gRPC Examples

The grpc folder contains examples for the gRPC application protocol. We provide implementations for the examples proto services provided by gRPC.

Hello World

Implementation for the gRPC hello world example.

Asynchronous

This example demonstrates asynchronous request processing for the hello world API using the HelloWorldServer and a HelloWorldClient

Blocking

This example demonstrates blocking request processing for the hello world API using the BlockingHelloWorldServer and a BlockingHelloWorldClient

Route guide

Implementation for the gRPC route guide example.

Asynchronous

Asynchronous processing for different APIs in the route guide service are demonstrated using the RouteGuideServer and the following clients:

Blocking

Blocking processing for different APIs in the route guide service are demonstrated using the BlockingRouteGuideServer and the following clients:

Compression

Extends the async "Hello World" example to demonstrate compression of the response body.

Deadlines

Extends the async "Hello World" example to demonstrate gRPC deadlines (aka timeout).

  • DeadlineServer – Waits for hello request from the client and, after 5 seconds of delay, responds with a greeting response.

  • DeadlineClient – Sends hello requests to the server with 1 minute deadline and 3 second deadline and receives a greeting response within that time or cancels the request.

Keep Alive

Demonstrates how to use HTTP/2 keep alive for gRPC server and client. Keep alive uses transport control frames to ensure the peer is still able to read and write to open connections. If the peer is not able to respond to the control frame within the configured amount of time, the connection is closed. This is useful if your environment doesn’t provide other forms of connection keep alive (e.g. SO_KEEPALIVE, and maybe preferred to lower level keep alive because it is closer the application logic (more likely if this check works, that your application is able to read/write). Keep alive can be helpful to detect scenarios such as non-graceful disconnects (e.g. power outage, ethernet cable pulled, buggy middle box) and general network disconnects.

Debugging

Extends the blocking "Hello World" example to demonstrate configuration of debugging features.

  • DebuggingServer – Waits for hello request from the client and responds with a greeting response.

  • DebuggingClient – Sends hello requests to the server and receives a greeting response.

Observer

This example demonstrates the following: - Use of GrpcLifecycleObserver to log a summary of each request/response.

Using the following classes:

Health Checking

This example demonstrates the following: - Use of DefaultHealthService which implements gRPC health checking paired with a simple "hello world" service.

Using the following classes: * HealthServerExample a server that installs DefaultHealthService in addition to a simple "hello world" service. * HealthClientExample a client that calls the "hello world" server, the "health check" server, and prints results.

Application Errors

The gRPC protocol supports propagating application level errors, and also provides serialization/deserialization of these objects. This example demonstrates a server returning an application level error to the client via the gRPC transport. The client intentionally omits the token field which is required, and the server returns an application level error. In this case the application level error type happens to be defined in error_details.proto, but it could be any protobuf object.

  • ErrorExampleServer - Requires each request has a non-empty token field or else returns an error.

  • ErrorExampleClient - Sends a request with missing token field to simulate an error condition on the server.

Execution Strategy

The gRPC implementation can be configured to execute all or some of the routes for a server without offloading. Using the IoExecutor for executing routes is appropriate only if there is no possibility that the route implementation will block.

The example demonstrates the impact of different route execution strategy configuration mechanisms.

  • ExecutionStrategyServer - Starts multiple servers configured using a variety of modes and techniques to specify the execution strategy to be used.

  • ExecutionStrategyClient - Sends requests to each of the differently configured servers and reports execution details.

Protoc Options

This example demonstrates how options for the servicetalk-grpc-protoc plugin can be used. See protoc-options for more details.

Request Response Context

This example demonstrates how request and response context can be used to access HTTP meta-data.

Asynchronous

This example demonstrates context with asynchronous request processing using the RequestResponseContextClient and a RequestResponseContextServer.

Blocking

This example demonstrates context with blocking request processing using the BlockingRequestResponseContextClient and a BlockingRequestResponseContextServer.