An open API service indexing awesome lists of open source software.

https://github.com/sollimann/grpc_routeguide

routeguide grpc example
https://github.com/sollimann/grpc_routeguide

Last synced: 9 days ago
JSON representation

routeguide grpc example

Awesome Lists containing this project

README

          

# grpc_routeguide

## to run

```bash
$ cargo run --bin routeguide-server
```

```bash
$ cargo run --bin routeguide-client
```

### gRPC lets you define four kinds of service methods, all of which are used in the `RouteGuide` service:

**1. `simple RPC (unary)`**

A `simple RPC (unary)` where the clients sends a request to the server and waits for a response to come back, just like
a normal function call.
```proto
// Obstains the feature at a given position
rpc GetFeature(Point) returns (Feature) {}
```

**2. `server-side streaming`**

A `server-side` streaming RPC where the client sends a request to the server and gets a stream to read
a sequence of messages back. The client reads from the returned stream until there are no more messages.
As you can see in our example, you specify a server-side streaming method by placing the `stream` keyword
before the *response* type.

```proto
// Obstains the Features available within the given Rectangle. Results are streamed rather than returned at once
// (e.g. in a reponse message with a repeated field), as the rectangle may cover a large area and contain a
// huge number of features
rpc ListFeatures(Rectangle) returns (stream Feature) {}
```

**3. `client-side streaming`**

A `client-side` streaming RPC where the client writes a sequence of messages and sends them to the server. Once th client
has finished writing the messages, it wait for the server to read them all and return it's response. You specify a client-side
streaming method by placing the `stream` keyword before the `request` type.

```proto
// Accepts a stream of Points on a route being traversed, returning a RouteSummary
// when the traversal is completed
rpc RecordRoute(stream Point) returns (RouteSummary) {}
```

**4. `bidirectional streaming`**

A `bidirectional streaming RPC` where both sides send a sequence of messages. The two streams operate independently, so clients
and servers can read and write in whater order they like: for example, the server could wait to receice all the client messages
before writing its responses, or it could alternatively read a message then write a message, or some other
combination of reads and writes. The order messages in each stream is preserved. You specify this type of method by placing the `stream`
keyword before both the request and the response.

```proto
// Accepts a stream of RouteNotes sent while a route is being traversed,
// while receiving other RouteNotes (e.g from other users)
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
```

our `.proto` file also contains protocol buffer message of type definitions for all the request and response
types used in our service methods - for example, here's the `Point` message type:

```proto
// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
int32 latitude = 1;
int32 longitude = 2;
}
```

### To generate gRPC stubs for Rust

Create a `build.rs` in the root of the crate:

```rust
fn main() {
tonic_build::compile_protos("proto/route_guide.proto")
.unwrap_or_else(|e| panic!("Failed to compile protos {:?}", e));
}
```

That's it. The generated code contains:
* Struct definitions for messages types `Point`, `Rectangle`, `Feature`, `RouteNote`, `RouteSummary`
* A service trait we'll need to implement: `route_guide_server::RouteGuide`
* A client type we'll use to call the server: `route_guide_client::RouteGuideClient`

The generated code is placed inside our target directory, in a location defined by the `OUT_DIR` environment variable
that is set by cargo. For our example, this means you can find the generated code in a path similar
to `target/debug/build/grpc_routeguide-***/out/routeguide.rs`.

### Creating a server

There are two parts of making our `RouteGuide` service do its job:
* Implementing the service trait generated from our service definition.
* Running a gRPC server to listen for requests from clients.