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,ClientStateand thejapiFunction/javaFunctionhelpers (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-jar3.0.0 instead of the unmaintainedcom.github.os72:protoc-jar(PR709).
Scala 3 sources
- With the
scala3_sourcesgenerator option, the generated Scala sources use Scala 3 syntax (using/givenand*wildcard imports) (PR597, PR770). The Gradle plugin has a newscala3Sourcesoption. - 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
usingclause, so a call such asGreeterServiceClient(settings)(system)fails to compile on Scala 3 withNo 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.Functioninstead of the deprecatedorg.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.createtakes anIterable<? extends GeneratedMessage>(wasList<GeneratedMessage>)WebHandler.grpcWebHandlertakes anIterableof handlers (wasList)MetadataBuilder.fromHeaderstakes anIterable<? extends HttpHeader>ServerReflection.createtakes anIterable<? extends ServiceDescription>(wasCollection<ServiceDescription>)ServiceHandler.handlerandServiceHandler.concatOrNotFoundhaveIterableoverloads next to the varargs ones
GrpcMarshalling.negotiated(scaladsl and javadsl) has an overload that takesGrpcServerSettings, 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) andGrpcMarshalling.handleUnaryResponseandGrpcMarshalling.handleUnaryFailure(javadsl), which were added in 2.0.0-M2 for the generated handlers, have been removed in favour ofGrpcExceptionHandler.recoverand the existing marshalling methods (PR905). Handlers generated by 2.0.0-M2 fail withNoSuchMethodErroron the first call to a unary method until they are regenerated.
Behavior changes
Server
- HTTP/2 is enabled with
pekko.http.server.enable-http2instead of thepekko.http.server.preview.enable-http2setting used with Pekko HTTP 1.x (PR601). See the Pekko HTTP 2.x migration guide for its defaults. - Server reflection implements the
grpc.reflection.v1protocol instead ofgrpc.reflection.v1alpha(PR599). Reflection clients that only speakv1alphaneed 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 withRESOURCE_EXHAUSTED(PR818). Pekko gRPC 1.x had no limit. - The server honours the
grpc-timeoutrequest header (PR872). NotImplementedError(for example from???) andUnsupportedOperationExceptionthrown by a service implementation are logged and answered withUNIMPLEMENTED, without the exception message (PR874). Throw aGrpcServiceExceptionto send a description to the caller.
gRPC-Web
WebHandler.defaultCorsSettingsallows 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 setpekko.grpc.server.grpc-web.allow-credentials-from-any-origin = trueto 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 = falsein the client settings only for testing. - Inbound messages larger than the client
max-inbound-message-size(4 MiB by default) are rejected withRESOURCE_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 malformedgrpc-statusand binary headers in a response as aStatusRuntimeExceptioninstead of a raw JVM exception (PR870). - A mismatch between the host to resolve and the configured
override-authorityfails with anIllegalArgumentExceptioninstead of anAssertionError(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):
2.0.0-M2