Lines Matching refs:a
3 This tutorial, adapted from [grpc-go], provides a basic introduction to working with gRPC
6 - Define a service in a `.proto` file.
8 - Write a simple client and server for your service.
20 Our example is a simple route mapping application that lets clients get information about features
21 on their route, create a summary of their route, and exchange route information such as traffic
24 With gRPC we can define our service once in a `.proto` file and implement clients and servers in
28 protocol buffers, including efficient serialization, a simple IDL, and easy interface updating.
33 [rustup] is a convenient tool to install it, if you haven't already.
55 In a separate shell, run the client
74 We will develop our example from scratch in a new crate:
85 [protocol buffers]. We will keep our `.proto` files in a directory in our crate's root.
96 To define a service, you specify a named `service` in your `.proto` file:
108 - A *simple RPC* where the client sends a request to the server and waits for a response to come
109 back, just like a normal function call.
111 // Obtains the feature at a given position.
115 - A *server-side streaming RPC* where the client sends a request to the server and gets a stream
116 to read a sequence of messages back. The client reads from the returned stream until there are
117 no more messages. As you can see in our example, you specify a server-side streaming method by
121 // streamed rather than returned at once (e.g. in a response message with a
122 // repeated field), as the rectangle may cover a large area and contain a
127 - A *client-side streaming RPC* where the client writes a sequence of messages and sends them to
129 all and return its response. You specify a client-side streaming method by placing the `stream`
132 // Accepts a stream of Points on a route being traversed, returning a
137 - A *bidirectional streaming RPC* where both sides send a sequence of messages. The two streams
140 writing its responses, or it could alternately read a message then write a message, or some other
144 // Accepts a stream of RouteNotes sent while a route is being traversed,
191 Create a `build.rs` file at the root of your crate:
217 First let's look at how we create a `RouteGuide` server. If you're only interested in creating gRPC
224 - Running a gRPC server to listen for requests from clients.
233 We can start by defining a struct to represent our service, we can do this on `main.rs` for now:
241 The generated code is placed inside our target directory, in a location defined by the `OUT_DIR`
243 code in a path similar to `target/debug/build/routeguide/out/routeguide.rs`.
259 the package declared in our `.proto` file, not a filename, e.g "routeguide.rs".
315 deserialize them from a json file and keep them around as our only piece of shared state:
324 Create the json data file and a helper module to read and deserialize our features.
368 All our service methods receive a `tonic::Request<T>` and return a
372 - A single value, e.g `Point`, `Rectangle`, or even a message type that includes a repeated field.
376 Let's look at the simplest method first, `get_feature`, which just gets a `tonic::Request<Point>`
377 from the client and tries to find a feature at the given `Point`. If no feature is found, it returns
394 Now let's look at one of our streaming RPCs. `list_features` is a server-side streaming RPC, so we
419 Like `get_feature`, `list_features`'s input is a single message, a `Rectangle` in this
420 case. This time, however, we need to return a stream of values, rather than a single one.
421 We create a channel and spawn a new asynchronous task where we perform a lookup, sending
424 The `Stream` half of the channel is returned to the caller, wrapped in a `tonic::Response`.
428 Now let's look at something a little more complicated: the client-side streaming method
429 `record_route`, where we get a stream of `Point`s from the client and return a single `RouteSummary`
430 with information about their trip. As you can see, this time the method receives a
472 `record_route` is conceptually simple: we get a stream of `Points` and fold it into a `RouteSummary…
473 In other words, we build a summary value as we process each `Point` in our stream, one by one.
474 When there are no more `Points` in our stream, we return the `RouteSummary` wrapped in a
478 Finally, let's look at our bidirectional streaming RPC `route_chat`, which receives a stream
479 of `RouteNote`s and returns a stream of `RouteNote`s.
520 inserted into the notes map, yielding a clone of the original `RouteNote`. The resulting stream
523 **Note**: The funky `as` cast is needed due to a limitation in the rust compiler. This is expected
530 Once we've implemented all our methods, we also need to start up a gRPC server so that clients can
556 among other things, is that we have a flexible and composable stack we can build on top of. We can,
565 <a name="client"></a>
568 In this section, we'll look at creating a Tonic client for our `RouteGuide` service. You can see our
584 Rename `main.rs` to `server.rs` and create a new file `client.rs`.
591 To call service methods, we first need to create a gRPC *client* to communicate with the server. Li…
612 create a client in our main function, passing the server's full URL to `RouteGuideClient::connect`.
624 Calling the simple RPC `get_feature` is as straightforward as calling a local method:
640 We call the `get_feature` client method, passing a single `Point` value wrapped in a
641 `tonic::Request`. We get a `Result<tonic::Response<Feature>, tonic::Status>` back.
644 Here's where we call the server-side streaming method `list_features`, which returns a stream of
678 As in the simple RPC, we pass a single value request. However, instead of getting a
679 single value back, we get a stream of `Features`.
682 server's responses to a response protocol buffer object (in this case a `Feature`) until there are
686 The client-side streaming method `record_route` takes a stream of `Point`s and returns a single
727 We build a vector of a random number of `Point` values (between 2 and 100) and then convert
728 it into a `Stream` using the `tokio_stream::iter` function. This is a cheap an easy way to get
729 a stream suitable for passing into our service method. The resulting stream is then wrapped in a
735 Finally, let's look at our bidirectional streaming RPC. The `route_chat` method takes a stream
792 <a name="tonic-build"></a>
796 projects. However, there are some cases when we need a slightly different workflow. For example:
799 - When building a rust client or server (or both) as part of a larger, multi-language project.
803 More generally, whenever we want to keep our `.proto` definitions in a central place and generate
809 1) We can keep our `.proto` definitions in a separate crate and generate our code on demand, as
827 2) Similarly, we could also keep the `.proto` definitions in a separate crate and then use that
828 crate as a direct dependency wherever we need it.