Details
Accessing request metadata
By default the generated service interfaces don’t provide access to the request metadata, only to the request body (via the RPC method input parameter). If your methods require access to the request MetadataMetadata, you can configure Pekko gRPC to generate server “power APIs” that extend the base service interfaces to provide an additional request metadata parameter to each service method. See the detailed chapters on sbt, Gradle and Maven for how to set this build option. Note that this option doesn’t effect the generated client stubs.
Notice: you need to change GreeterServiceHandlerFactory to GreeterServiceHandlerFactoryPowerApiHandlerFactory.
Notice: you need to change GreeterServiceHandler to GreeterServicePowerApiHandler.
Here’s an example implementation of these server power APIs:
- Scala
-
source
package example.myapp.helloworld import org.apache.pekko import pekko.NotUsed import pekko.actor.ActorSystem import pekko.grpc.scaladsl.Metadata import pekko.stream.scaladsl.{ Sink, Source } import example.myapp.helloworld.grpc._ import scala.concurrent.Future class PowerGreeterServiceImpl(implicit system: ActorSystem) extends GreeterServicePowerApi { import system.dispatcher override def sayHello(in: HelloRequest, metadata: Metadata): Future[HelloReply] = { val greetee = authTaggedName(in, metadata) println(s"sayHello to $greetee") Future.successful(HelloReply(s"Hello, $greetee")) } override def itKeepsTalking(in: Source[HelloRequest, NotUsed], metadata: Metadata): Future[HelloReply] = { println(s"sayHello to in stream...") in.runWith(Sink.seq) .map(elements => HelloReply(s"Hello, ${elements.map(authTaggedName(_, metadata)).mkString(", ")}")) } override def itKeepsReplying(in: HelloRequest, metadata: Metadata): Source[HelloReply, NotUsed] = { val greetee = authTaggedName(in, metadata) println(s"sayHello to $greetee with stream of chars...") Source(s"Hello, $greetee".toList).map(character => HelloReply(character.toString)) } override def streamHellos(in: Source[HelloRequest, NotUsed], metadata: Metadata): Source[HelloReply, NotUsed] = { println(s"sayHello to stream...") in.map(request => HelloReply(s"Hello, ${authTaggedName(request, metadata)}")) } // Bare-bones just for GRPC metadata demonstration purposes private def isAuthenticated(metadata: Metadata): Boolean = metadata.getText("authorization").nonEmpty private def authTaggedName(in: HelloRequest, metadata: Metadata): String = { val authenticated = isAuthenticated(metadata) s"${in.name} (${if (!authenticated) "not " else ""}authenticated)" } } - Java
-
source
package example.myapp.helloworld; import example.myapp.helloworld.grpc.GreeterServicePowerApi; import example.myapp.helloworld.grpc.HelloReply; import example.myapp.helloworld.grpc.HelloRequest; import java.util.List; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import org.apache.pekko.NotUsed; import org.apache.pekko.grpc.javadsl.Metadata; import org.apache.pekko.stream.Materializer; import org.apache.pekko.stream.javadsl.Sink; import org.apache.pekko.stream.javadsl.Source; public class PowerGreeterServiceImpl implements GreeterServicePowerApi { private final Materializer mat; public PowerGreeterServiceImpl(Materializer mat) { this.mat = mat; } @Override public CompletionStage<HelloReply> sayHello(HelloRequest in, Metadata metadata) { String greetee = authTaggedName(in, metadata); System.out.println("sayHello to " + greetee); HelloReply reply = HelloReply.newBuilder().setMessage("Hello, " + greetee).build(); return CompletableFuture.completedFuture(reply); } @Override public CompletionStage<HelloReply> itKeepsTalking( Source<HelloRequest, NotUsed> in, Metadata metadata) { System.out.println("sayHello to in stream..."); return in.runWith(Sink.<HelloRequest>seq(), mat) .thenApply( elements -> { String elementsStr = elements.stream().map(elem -> authTaggedName(elem, metadata)).toList().toString(); return HelloReply.newBuilder().setMessage("Hello, " + elementsStr).build(); }); } @Override public Source<HelloReply, NotUsed> itKeepsReplying(HelloRequest in, Metadata metadata) { String greetee = authTaggedName(in, metadata); System.out.println("sayHello to " + greetee + " with stream of chars"); List<Character> characters = ("Hello, " + greetee).chars().mapToObj(c -> (char) c).toList(); return Source.from(characters) .map(character -> HelloReply.newBuilder().setMessage(String.valueOf(character)).build()); } @Override public Source<HelloReply, NotUsed> streamHellos( Source<HelloRequest, NotUsed> in, Metadata metadata) { System.out.println("sayHello to stream..."); return in.map( request -> HelloReply.newBuilder() .setMessage("Hello, " + authTaggedName(request, metadata)) .build()); } // Bare-bones just for GRPC metadata demonstration purposes private boolean isAuthenticated(Metadata metadata) { return metadata.getText("authorization").isPresent(); } private String authTaggedName(HelloRequest in, Metadata metadata) { return "%s (%sauthenticated)".formatted(in.getName(), isAuthenticated(metadata) ? "" : "not "); } }
Status codes
To signal an error, you can fail the FutureCompletionStage or Source you are returning with a GrpcServiceExceptionGrpcServiceException containing the status code you want to return.
For an overview of gRPC status codes and their meaning see statuscodes.md.
For unary responses:
- Scala
-
source
import pekko.grpc.GrpcServiceException import io.grpc.Status val exceptionMetadata = new MetadataBuilder() .addText("test-text", "test-text-data") .addBinary("test-binary-bin", ByteString("test-binary-data")) .build() // ... def sayHello(in: HelloRequest): Future[HelloReply] = { if (in.name.isEmpty) Future.failed( new GrpcServiceException(Status.INVALID_ARGUMENT.withDescription("No name found"), exceptionMetadata)) else Future.successful(HelloReply(s"Hi ${in.name}!")) } - Java
-
source
import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; import io.grpc.Status; import org.apache.pekko.grpc.GrpcServiceException; // ... @Override public CompletionStage<HelloReply> sayHello(HelloRequest in) { if (in.getName().isEmpty()) { CompletableFuture<HelloReply> future = new CompletableFuture<>(); future.completeExceptionally( new GrpcServiceException(Status.INVALID_ARGUMENT.withDescription("No name found"))); return future; } else { return CompletableFuture.completedFuture( HelloReply.newBuilder().setMessage("Hi, " + in.getName()).build()); } }
For streaming responses:
- Scala
-
source
import org.apache.pekko import pekko.NotUsed import pekko.stream.scaladsl.Source import pekko.grpc.GrpcServiceException import io.grpc.Status val exceptionMetadata = new MetadataBuilder() .addText("test-text", "test-text-data") .addBinary("test-binary-bin", ByteString("test-binary-data")) .build() def itKeepsReplying(in: HelloRequest): Source[HelloReply, NotUsed] = { if (in.name.isEmpty) Source.failed( new GrpcServiceException(Status.INVALID_ARGUMENT.withDescription("No name found"), exceptionMetadata)) else myResponseSource } - Java
-
source
import org.apache.pekko.NotUsed; import org.apache.pekko.stream.javadsl.Source; import io.grpc.Status; import org.apache.pekko.grpc.GrpcServiceException; // ... @Override public Source<HelloReply, NotUsed> itKeepsReplying(HelloRequest in) { if (in.getName().isEmpty()) { return Source.failed( new GrpcServiceException(Status.INVALID_ARGUMENT.withDescription("No name found"))); } else { return myResponseSource; } }
Rich error model
Beyond status codes you can also use the Rich error model.
This example uses an error model taken from common protobuf but every class that is based on scalapb.GeneratedMessage can be used. Build and return the error as a PekkoGrpcException:
- Scala
-
source
def sayHello(in: HelloRequest): Future[HelloReply] = { Future.failed( GrpcServiceException( Code.INVALID_ARGUMENT, "What is wrong?", Seq(new LocalizedMessage("EN", "The password!")))) } - Java
-
source
@Override public CompletionStage<HelloReply> sayHello(HelloRequest in) { List<LocalizedMessage> details = List.of(LocalizedMessage.of("EN", "The password!")); GrpcServiceException exception = GrpcServiceException.create(Code.INVALID_ARGUMENT, "What is wrong?", details); CompletableFuture<HelloReply> future = new CompletableFuture<>(); future.completeExceptionally(exception); return future; }
Please look here how to handle this on the client.
Message compression
The server supports the gzip and deflate message encodings of the gRPC compression spec, as well as identity.
- Requests compressed with a supported encoding (
grpc-encoding) are decompressed. Other encodings are rejected with anUNIMPLEMENTEDstatus. - Responses are compressed with the first supported encoding in the order the client lists them in its
grpc-accept-encodingheaders, or not compressed when the client lists none. For example,grpc-accept-encoding: deflate, gzipgivesdeflateresponses, andidentity, deflate, gzipgives uncompressed responses.
Maximum inbound message size
Inbound gRPC messages are limited to 4 MiB by default, matching the grpc-java default. A frame whose declared length exceeds the limit is rejected before its payload is read, and a compressed frame that inflates past the limit is rejected while it is being decompressed, so neither an oversized frame nor a decompression bomb needs to be buffered in full. In both cases the peer sees a RESOURCE_EXHAUSTED status.
The limit is read from pekko.grpc.server:
reference.conf-
source
pekko.grpc.server { # Maximum allowed size for inbound gRPC messages (in bytes). # Applies to the decompressed message size. Messages exceeding this limit # will be rejected with RESOURCE_EXHAUSTED status. # Default is 4 MiB, matching grpc-java's default. max-inbound-message-size = 4194304 # Whether generated handlers honour the deadline a client sends in the `grpc-timeout` header. # When on, a call still running at the deadline is completed with DEADLINE_EXCEEDED, and a # streamed response is ended and its Source cancelled, as grpc-java does. # Set to off to ignore the header and let every call run to completion. enforce-deadline = on }
To raise it for every service in the actor system, override the setting in your application.conf:
pekko.grpc.server {
max-inbound-message-size = 8388608 # 8 MiB
}
To use a different limit for a single service, pass GrpcServerSettingsGrpcServerSettings to the generated handler’s partial method:
- Scala
-
val settings = GrpcServerSettings(system).withMaxInboundMessageSize(8 * 1024 * 1024) val handler = GreeterServiceHandler.partial( new GreeterServiceImpl(), settings = Some(settings)) - Java
-
GrpcServerSettings settings = GrpcServerSettings.create(system).withMaxInboundMessageSize(8 * 1024 * 1024); Function<HttpRequest, CompletionStage<HttpResponse>> handler = GreeterServiceHandlerFactory.partial( new GreeterServiceImpl(), GreeterService.name, SystemMaterializer.get(system).materializer(), GrpcExceptionHandler.defaultMapper(), settings, system);
The limit did not exist before 2.0.0, so a server that previously accepted messages larger than 4 MiB will start rejecting them after upgrading. Raise pekko.grpc.server.max-inbound-message-size to keep the old behaviour.
Handlers generated before 2.0.0 call an entry point that has no access to the actor system’s configuration, so they fall back on the 4 MiB default and pekko.grpc.server.max-inbound-message-size has no effect on them. Regenerate your sources against 2.0.0 to make the setting apply.
Deadlines
A client can tell the server how long it is prepared to wait by sending the grpc-timeout request header. Generated handlers honour it: when the deadline passes before the service has replied, the call is completed with DEADLINE_EXCEEDED — the same status the client reports for the same call. For a streamed response, the stream is ended with DEADLINE_EXCEEDED trailers once the deadline passes, and the Source the service returned is cancelled.
Both clients send the header when a call has a deadline:
- Scala
-
val settings = GrpcClientSettings.connectToServiceAt("localhost", 8080) .withDeadline(5.seconds)
A Future cannot be cancelled, so for a unary or client-streaming call the deadline bounds the reply, not the work behind it: a service that has already started an expensive operation keeps running it, and only its result is discarded. A streamed response is different, because its Source is cancelled at the deadline.
A request that carries no grpc-timeout, or one whose value is malformed, is served without a deadline. A malformed value is deliberately ignored rather than rejected: the timeout is a hint from the peer, and refusing the request outright would be a worse outcome than serving it.
Turning deadline enforcement off
Handlers before 2.0.0 ignored grpc-timeout and always ran a call to completion. To keep that behaviour, for example for a service that relies on a streamed response running to its end, turn enforcement off for every service in application.conf:
pekko.grpc.server.enforce-deadline = off
or for a single service by passing GrpcServerSettingsGrpcServerSettings to the generated handler:
- Scala
-
val settings = GrpcServerSettings(system).withEnforceDeadline(false) val handler = GreeterServiceHandler.partial( new GreeterServiceImpl(), settings = Some(settings)) - Java
-
GrpcServerSettings settings = GrpcServerSettings.create(system).withEnforceDeadline(false); Function<HttpRequest, CompletionStage<HttpResponse>> handler = GreeterServiceHandlerFactory.partial( new GreeterServiceImpl(), GreeterService.name, SystemMaterializer.get(system).materializer(), GrpcExceptionHandler.defaultMapper(), settings, system);
With enforcement off, the grpc-timeout header is ignored: a call that outlives the client’s deadline is not answered with DEADLINE_EXCEEDED and a streamed response is not cancelled. The client still stops waiting at its own deadline.