Migration from Apache Pekko gRPC 1.x to 2.x

Apache Pekko gRPC 2.x requires Apache Pekko 2.x and Apache Pekko HTTP 2.x. See the Pekko 1.x to 2.x migration guide and the Pekko HTTP 1.x to 2.x migration guide for the changes in those libraries.

See the 2.0 release notes for the full list of changes.

General changes

  • Java 17 is the minimum Java version.
  • The runtime library is built for Scala 2.13 and Scala 3. Scala 2.12 is no longer supported, except by the sbt plugin for sbt 1.x.
  • Deprecated code has been removed, including GrpcClientSettings.withGrpcLoadBalancingType, the deprecated constructors of the request builders, ClientState and the japiFunction/javaFunction helpers (PR502). Before upgrading, build against the latest Pekko gRPC 1.x release and fix any deprecation warnings.
  • Pekko gRPC 2.x is not binary compatible with 1.x. Regenerate all generated gRPC code with the 2.x build plugin; code generated by a 1.x plugin, or by a 2.0.0 milestone, does not work with the 2.x runtime. Libraries that ship generated Pekko gRPC code need to be rebuilt and released for 2.x.

Protobuf and ScalaPB

  • Pekko gRPC 2.x uses protobuf-java 4.x and protoc 4.x, up from 3.25.x (PR610). Java classes generated by older protoc releases may not work with the protobuf-java 4.x runtime: regenerate your own code, and check any third-party libraries that ship generated protobuf classes.
  • Scala code is generated with ScalaPB 1.0.0. ScalaPB plugins and libraries built for ScalaPB 0.11.x, such as scalapb-validate, may not be compatible with it.

Build tools

sbt

  • The sbt plugin supports sbt 1.x and sbt 2.x (PR710).
  • The plugin is published in the non-legacy Maven style (PR736), which needs sbt 1.9.0 or later.

Maven

  • The Maven plugin uses io.github.blackrock:protoc-jar 3.0.0 instead of the unmaintained com.github.os72:protoc-jar (PR709).

Scala 3 sources

  • With the scala3_sources generator option, the generated Scala sources use Scala 3 syntax (using/given and * wildcard imports) (PR597, PR770). The Gradle plugin has a new scala3Sources option.
  • This is not source compatible with code that passes an implicit argument to the generated code explicitly. For example, the generated client factories take the actor system in a using clause, so a call such as GreeterServiceClient(settings)(system) fails to compile on Scala 3 with No given instance of type ClassicActorSystemProvider was found.

Bring the actor system into implicit scope instead, which compiles on both Scala 2.13 and Scala 3:

implicit val sys: ClassicActorSystemProvider = system
val client = GreeterServiceClient(settings)

In Scala 3-only code, GreeterServiceClient(settings)(using system) also works.

API changes

  • Java DSL APIs, including the generated Java handler factories, take org.apache.pekko.japi.function.Function instead of the deprecated org.apache.pekko.japi.Function (PR484).
  • Java API collection parameters accept Iterables and wildcard generic types (PR935). This is source compatible for most callers, but not binary compatible:
    • GrpcServiceException.create takes an Iterable<? extends GeneratedMessage> (was List<GeneratedMessage>)
    • WebHandler.grpcWebHandler takes an Iterable of handlers (was List)
    • MetadataBuilder.fromHeaders takes an Iterable<? extends HttpHeader>
    • ServerReflection.create takes an Iterable<? extends ServiceDescription> (was Collection<ServiceDescription>)
    • ServiceHandler.handler and ServiceHandler.concatOrNotFound have Iterable overloads next to the varargs ones
  • GrpcMarshalling.negotiated (scaladsl and javadsl) has an overload that takes GrpcServerSettings, so that settings such as the maximum inbound message size reach the handler (PR877). Hand-written handlers that use the overload without settings get the defaults.
  • GrpcMarshalling.handleUnary (scaladsl) and GrpcMarshalling.handleUnaryResponse and GrpcMarshalling.handleUnaryFailure (javadsl), which were added in 2.0.0-M2 for the generated handlers, have been removed in favour of GrpcExceptionHandler.recover and the existing marshalling methods (PR905). Handlers generated by 2.0.0-M2 fail with NoSuchMethodError on the first call to a unary method until they are regenerated.

Behavior changes

Server

  • HTTP/2 is enabled with pekko.http.server.enable-http2 instead of the pekko.http.server.preview.enable-http2 setting used with Pekko HTTP 1.x (PR601). See the Pekko HTTP 2.x migration guide for its defaults.
  • Server reflection implements the grpc.reflection.v1 protocol instead of grpc.reflection.v1alpha (PR599). Reflection clients that only speak v1alpha need to be upgraded. Server reflection also sends the transitive dependencies of the requested files (PR643).
  • Inbound messages larger than pekko.grpc.server.max-inbound-message-size (4 MiB by default, measured after decompression) are rejected with RESOURCE_EXHAUSTED (PR818). Pekko gRPC 1.x had no limit.
  • The server honours the grpc-timeout request header (PR872).
  • NotImplementedError (for example from ???) and UnsupportedOperationException thrown by a service implementation are logged and answered with UNIMPLEMENTED, without the exception message (PR874). Throw a GrpcServiceException to send a description to the caller.

gRPC-Web

  • WebHandler.defaultCorsSettings allows any origin, and no longer allows credentials together with unrestricted origins (PR871). Browsers then withhold cookies on cross-origin calls. To use credentials, restrict the allowed origins, or set pekko.grpc.server.grpc-web.allow-credentials-from-any-origin = true to keep the unsafe 1.x behavior.

Client

  • The pekko-http client backend verifies the server hostname against its TLS certificate (RFC 2818) (PR820, PR830). Pekko gRPC 1.x did not, while the netty backend always did. Set verify-hostname = false in the client settings only for testing.
  • Inbound messages larger than the client max-inbound-message-size (4 MiB by default) are rejected with RESOURCE_EXHAUSTED (PR818).
  • The pekko-http client backend applies the configured deadline and sends it to the server as grpc-timeout (PR824, PR872).
  • The pekko-http client backend percent-decodes grpc-message (PR869), and reports malformed grpc-status and binary headers in a response as a StatusRuntimeException instead of a raw JVM exception (PR870).
  • A mismatch between the host to resolve and the configured override-authority fails with an IllegalArgumentException instead of an AssertionError (PR873).

Configuration changes in Pekko gRPC 2.x

Changed default values

  • pekko.grpc.server.grpc-web.allow-credentials-from-any-origin = false (new setting): the default gRPC-Web CORS settings no longer allow credentials from any origin.
  • pekko.grpc.client."*".verify-hostname = true (new setting): the pekko-http client backend now verifies the server hostname.
  • max-inbound-message-size = 4194304 (new client and server setting): inbound messages were unbounded in 1.x.

New configuration

Client settings (pekko.grpc.client."*"):

  • verify-hostname: verify the server hostname against its TLS certificate (pekko-http backend only) (PR820)
  • minimum-tls-version: the minimum TLS protocol version to negotiate (PR823)
  • max-inbound-message-size: the maximum size of an inbound message (PR818)
  • compression: the message encoding to compress requests with, off by default (PR927)

Server settings (pekko.grpc.server):

  • max-inbound-message-size: the maximum size of an inbound message (PR818)
  • grpc-web.allow-credentials-from-any-origin: whether the default gRPC-Web CORS settings may allow credentials together with unrestricted origins (PR871)