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
sourcepackage 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
sourcepackage 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
sourceimport 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
sourceimport 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
sourceimport 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
sourceimport 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
sourcedef 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 an UNIMPLEMENTED status.
  • Responses are compressed with the first supported encoding in the order the client lists them in its grpc-accept-encoding headers, or not compressed when the client lists none. For example, grpc-accept-encoding: deflate, gzip gives deflate responses, and identity, deflate, gzip gives 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
sourcepekko.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);
Note

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)
Note

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.