New to Akka? Start with the Akka SDK.
Details
Client Lifecycle
Instances of the generated client may be long-lived and can be used concurrently. You can keep the client running until your system terminates, or close it earlier. To avoid leaking in the latter case, you should call .close() on the client.
When the connection breaks, the client will try reconnecting to the server automatically. On each reconnection attempt, If a connection the ServiceDiscovery will be used and a new host may be found.
When using client-side load balancing the reconnection loop will run indefinitely.
When using a direct client (not load balanced) when the connection breaks you can set up a maximum number of failed connection attempts. If that limit is reached, the client gives up. The default number of attempts is infinite and configurable via GrpcClientSettings’s connectionAttempts. Failed attempts are counted as follows:
- Each time the channel enters the
TRANSIENT_FAILUREstate counts as one failed attempt. The channel keeps retrying in the background while in that state, so for example a refused connection, a TLS failure or a name that does not resolve counts only once for as long as the problem lasts. - When the client stays in the
CONNECTINGstate for longer thanconnecting-timeout(Netty client only), for example because the TCP connection is accepted but the TLS/HTTP2 handshake never completes, the attempt is abandoned, counted as a failed attempt, and a new attempt is started. Since Netty’s own TCP connect timeout of 30 seconds is longer than the defaultconnecting-timeout, this also covers a TCP connection that is never answered. - The count is reset when the client becomes connected.
When the client gives up it is shut down, also if it had been connected before. Calls waiting for a connection fail with status UNAVAILABLE, later calls on the client fail with status UNAVAILABLE with the ClientConnectionException as cause, and a new client must be created to connect again.
The client offers a method closed() that returns a FutureCompletionStage that will complete once the client is explicitly closed after invoking close(). The returned FutureCompletionStage will instead complete with a ClientConnectionException failure when the client gives up because the maximum number of connectionAttempts was reached.
Shared Channels
By default, each instance of a generated client creates a separate HTTP connection to the server. If the server supports multiple services, you may want to allow multiple generated clients to share a single connection.
To do this, create a GrpcChannelGrpcChannel by passing GrpcClientSettingsGrpcClientSettings to the apply method. You can then use the GrpcChannel instance to create multiple generated clients; each client will use the provided channel to communicate with the server.
When using a shared channel, the client lifecycle changes slightly. Like the generated client, GrpcChannel offers close and closed methods; these can be used to explicitly close the connection to the server and detect when the connection has been closed or shutdown due to errors, respectively. When you are done communicating with the server, you should call close on the channel, rather than the individual clients. Calling close on a generated client that was created with a shared channel will throw a GrpcClientCloseExceptionGrpcClientCloseException.
Channel laziness
The Netty based channel backing a client will only actually connect once the client sees a first request. It is possible to configure it to eagerly connect as soon as the client, or channel, is created by setting eager-connection = true or programmatically through GrpcClientSettingsGrpcClientSettings withEagerConnection.
If the client does not see any traffic it will transition to an idle state, and close the connection, after 5 minutes. You can find some more details about the Netty channel behavior in the grpc connectivity-semantics-and-api docs.
The Akka HTTP backed client always connects eagerly.
Load balancing
When multiple endpoints are discovered for a gRPC client, currently one is selected and used for all outgoing calls.
This approach, while naïve, in fact works well in many cases: when there are multiple nodes available to handle requests, a server-side load balancer is better-positioned to make decisions than any single client, as it can take into account information from multiple clients, and sometimes even lifecycle information (e.g. not forward requests to nodes that are scheduled to shut down).
Client-side load balancing is desirable when you are using the default static or the grpc-dns discovery mechanism. You can set the load-balancing-policy client configuration option to round_robin to enable the round_robin client-side load balancing strategy provided by grpc-java.
Note that load balancing is marked as experimental in grpc-java.
Client-side load balancing for other discovery mechanisms is not yet supported.
Request Metadata
Default request metadata, for example for authentication, can be provided through the GrpcClientSettingsGrpcClientSettings passed to the client when it is created, it will be the base metadata used for each request.
In some cases you will want to provide specific metadata to a single request, this can be done through the “lifted” client API, each method of the service has an empty parameter list version (.sayHello()) on the client returning a SingleResponseRequestBuilderSingleResponseRequestBuilder or StreamResponseRequestBuilderStreamResponseRequestBuilder.
After adding the required metadata the request is done by calling invoke with the request parameters.
Notice: method addHeader return a new object, you should use it like String or use it in the chain structure.
- Scala
-
source
def singleRequestReply(): Unit = { sys.log.info("Performing request") val reply = client.sayHello().addHeader("key", "value").invoke(HelloRequest("Alice")) println(s"got single reply: ${Await.result(reply, 5.seconds).message}") } - Java
-
source
private static void singleRequestReply(GreeterServiceClient client) throws Exception { HelloRequest request = HelloRequest.newBuilder().setName("Alice").build(); CompletionStage<HelloReply> reply = client.sayHello() .addHeader("key", "value") .invoke(request); System.out.println("got single reply: " + reply.toCompletableFuture().get(5, TimeUnit.SECONDS)); }
Rich error model
Beyond status codes you can also use the Rich error model.
Extract the GrpcServiceException to access code, message and details.
- Scala
-
source
val richErrorResponse = client.sayHello(HelloRequest("Bob")).failed.futureValue richErrorResponse match { case status: GrpcServiceException => status.metadata match { case richMetadata: MetadataStatus => richMetadata.details(0).typeUrl should be("type.googleapis.com/google.rpc.LocalizedMessage") import LocalizedMessage.messageCompanion val localizedMessage = richMetadata.getParsedDetails[LocalizedMessage].head localizedMessage.message should be("The password!") localizedMessage.locale should be("EN") richMetadata.code should be(3) richMetadata.message should be("What is wrong?") case other => fail(s"This should be a RichGrpcMetadataImpl but it is ${other.getClass}") } case ex => fail(s"This should be a GrpcServiceException but it is ${ex.getClass}") } - Java
-
source
HelloRequest request = HelloRequest.newBuilder().setName("Alice").build(); CompletionStage<HelloReply> response = client.sayHello(request); StatusRuntimeException statusRuntimeException = response.toCompletableFuture().handle((res, ex) -> (StatusRuntimeException) ex ).get(); GrpcServiceException ex = GrpcServiceException.apply(statusRuntimeException); MetadataStatus meta = (MetadataStatus) ex.getMetadata(); assertEquals("type.googleapis.com/google.rpc.LocalizedMessage", meta.getDetails().get(0).typeUrl()); assertEquals(Status.INVALID_ARGUMENT.getCode().value(), meta.getCode()); assertEquals("What is wrong?", meta.getMessage()); LocalizedMessage details = meta.getParsedDetails(LocalizedMessage.getDefaultInstance()).get(0); Assert.assertEquals("The password!", details.getMessage()); Assert.assertEquals("EN", details.getLocale());
Please look here how to create errors with such details on the server side.