v1.59.0

gRPC Java 1.59.0 Release Notes

PLANNED ABI BREAKAGE!

This breaks the ABI of the @ExperimentalApi classes listed below.
This does not impact source code (API); it only impacts code compiled with a different version of gRPC than it runs with (ABI).

Users that recompiled their code using grpc-java v1.36.0 (released on Feb 23, 2021) and later, ARE NOT AFFECTED.
Users that compiled their source using grpc-java earlier than v1.36.0 may need to recompile when upgrading to grpc-java v1.59.0.

See details in #10406.

Affected classes

Class io.grpc.internal.AbstractManagedChannelImplBuilder is deleted, and no longer in the class hierarchy of the channel builders:

• io.grpc.netty.NettyChannelBuilder
• io.grpc.okhttp.OkhttpChannelBuilder
• io.grpc.cronet.CronetChannelBuilder

Class io.grpc.internal.AbstractServerImplBuilder is deleted, and no longer in the class hierarchy of the server builders:

• io.grpc.netty.NettyServerBuilder
• io.grpc.inprocess.InProcessServerBuilder

---

API Changes

• core: AbstractManagedChannelImplBuilder and AbstractServerImplBuilder are removed (#10530). This is ABI-breaking, see the warning above. (#10406)
• core: Removed .class file hack previously introduced in v1.36.0 to ease removal of internal ABIs. (#10406)
• api: Add ForwardingChannelBuilder2, an ABI-safe version of ForwardingChannelBuilder, which will be deprecated in the following release. (#10585, #10406)
• api: Add LoadBalancer.FixedResultPicker convenience class for load balancer implementations. It is a replacement for ErrorPicker and EMPTY_PICKER added in 1.58.0
• testing: Stabilize TestMethodDescriptors (#10530)

Behavior Changes

• core: de-expermentalize pick first config parsing (#10531)
• netty: Respect -Dio.netty.allocator.type=unpooled when getting Netty Allocator instead of ignoring it (#10543)
• netty: Use UNAVAILABLE for connections closed while writing. Previously this would result in UNKNOWN
• binder: Enable indirect addressing using s. (#10550)

Improvements

• core: only use reflection to resolve InternalCensusStatsAccessor once instead of once per channel
• core: enhance error message in the case of DEADLINE_EXCEEDED to indicate name resolution delay.
• netty: When creating a connection, use java.util.logging formatting instead of String.format to avoid work when not logged
• netty: Touch ByteBuf when message framing has been decoded. If the buffer is leaked, this helps narrow down the source of reference counting bug
• java_grpc_library.bzl: Disable Automatic Exec Groups inside grpc libraries (#10514). This improves compatibility with future Bazel versions while retaining Bazel 5.x compatibility

Bug Fixes

• netty: Avoid NettyAdaptiveCumulator incorrectly releasing its input ByteBuf twice when reading messages under certain error conditions (#10537)
• xds: Add fix for xdstp replacement for percent-encoded authorities (#10571)

Documentation

• API documentation (Javadoc) for Server and Channel builders now correctly displays inherited methods and the class hierarchy. (#10406)
• examples: add an example for OAuth (#10560)

Dependencies

• Upgrade Netty to 4.1.97.Final

Acknowledgements

John Cormie (@jdcormie)
Stephane Landelle (@slandelle)
@kotlaja

v1.58.0

API Changes

• xds: Add missing ExperimentalApi to OrcaServiceImpl
• stub: Removed deprecated methods attachHeaders and captureMetadata from MetadataUtils (#10443)
• api: Stabilized ServerCall.getAuthority() by removing experimental annotation (#10498)
• api: Stabilized ServerCall#setMessageCompression() and PartialForwardingServerCall#setMessageCompression() (#10393)
• protobuf: Stabilize ProtoUtils.setExtensionRegistry() and ProtoLiteUtils.setExtensionRegistry() (#10392)
• testing: Stabilize GrpcCleanupRule, GrpcServerRule (#10494)
• api: Stabilized ServerBuilder.handshakeTimeout (#10499)
• api: Removed Context.Storage deprecated method attach(), made doAttach() abstract (#10379)
• api: Stabilized methodDescriptor getRequestMarshaller, getResponseMarshaller (#10495)
• api, xds: Enabled pick first by default (GRPC_EXPERIMENTAL_PICKFIRST_LB_CONFIG env variable is true by default now) for xds leaf LB policy (#10475)

Behavior Changes

• rls: Have RLS's LRU Cache rely on cleanup process to remove expired entries (#10400)
• core, inprocess, util: 2 new artifacts grpc-inprocess and grpc-util have been created by moving code from grpc-core to facilitate Java module support (#10362, #10390)
• all: Automatic module name support added to all artifacts (#10413)
• xds: Encode the service authority in XdsNameResolver (#10207)
• stub: When using BlockingServerStream, in some cases the request will be sent to the server when the RPC is created where previously it always waited until next() or hasNext() had been called to send the request.

Improvements

• api: In Javadoc, link to gRFCs A8/A9 for keepalive and related settings
• okhttp: Enable support for being returned by Grpc.newServerBuilderForPort(). At present, Netty always has higher priority than OkHttp, if they are both available, because ServerBuilder.forPort() is not supported in the OkHttp transport but is supported in the Netty transport
• bazel: Enhance java_grpc_library.bzl to allow toolchain to use annotation processors
• examples: Add pre-serialized-message example (#10112)
• examples: Android examples to use AGP 7.4.0 (#10497)

Bug Fixes

• Fix compatibility with Java 8. This fixes the NoSuchMethodError for ByteBuffer methods present in 1.57.0 (#10441)
• xds: Remove debug assert in WeightedRoundRobinLoadBalancer. The assert was to detect breakages in the static stride algorithm causing too much looping. However, with multithreading it is possible to trigger even in legitimate scenarios (#10437)
• util: Outlier detection tracer delegation (#10459)
• Handle header with errors and endStream = true. Was filling logs with NPEs. (#10384)
• core: Fix a retriablestream bug that may cause deadlock with OkHttp (#10386)
• stub: Remove ThreadlessExecutor from BlockingServerStream to eliminate the problem where sometimes the iterator’s next() method would get stuck. (#10496)
• compiler: Fix aarch_64 macs not being able to build the compiler module. (#10516)
• okhttp: Use padded length for flow control in both client and server transport (#10422)
• xds: Fix locality logging information in bootstrap (#10423)

Dependencies

• Upgraded protobuf to 3.24.0
• android: Min SDK level to 21 (#10505)
• Various dependency upgrades (#10359):

   androidx.core:core 1.10.0 -> 1.10.1
   com.google.api.grpc:proto-google-common-protos 2.17.0 -> 2.22.0
   com.google.cloud:google-cloud-logging 3.14.5 -> 3.15.5
   com.google.errorprone:error_prone_annotations 2.18.0 -> 2.20.0
   com.squareup.okio:okio 1.17.5 -> 2.10.0
  

Acknowledgements

Halvard Skogsrud

v1.57.2

Bug Fixes

• util: Outlier detection tracer delegation (#10459) (#10483)

v1.57.1

Bug fixes

• Fix compatibility with Java 8. This fixes the NoSuchMethodError for ByteBuffer methods present in 1.57.0 (#10441)
• xds: Remove debug assert in WeightedRoundRobinLoadBalancer. The assert was to detect breakages in the static stride algorithm causing too much looping. However, with multithreading it is possible to trigger even in legitimate scenarios (#10437)

v1.57.0

gRPC Java 1.57.0 Release Notes

This release accidentally broke Java 8: NoSuchMethodError for some ByteBuffer methods. The issue is tracked in #10432 and fixed in 1.57.1.

API Changes

• Use fully qualified java.lang.String in all cases in generated code. This fixes compilation if a protobuf message is named “String”.
• Stabilize io.grpc.Status.asRuntimeException(Metadata) and trailersFromThrowable
• Stabilize io.grpc.ManagedChannelBuilder.useTransportSecurity (#10244)
• Stabilize io.grpc.util.MutableHandlerRegistry (#10348)

Behavior Changes

• api: CheckedForwardingClientCall now passes trailers from the caught exception
• context, api: Package io.grpc is now consolidated into a single artifact grpc-api by moving classes from grpc-context to grpc-api. grpc-context now has a dependency on grpc-api (but excludes other dependencies of grpc-api) so any application previously using only grpc-context will now also bring in grpc-api. This fixes #3522 which was the major issue preventing support of Java modules. We are not done fixing support, as some artifacts need to be split and Automatic-Module-Name needs to be added. The next release is likely to be more stable for modules.
• core: Change delay for hedging retry after a non-fatal error to be 0 to match the gRFC (A6).
• core: Wrap other name resolver types in a RetryingNameResolver . Previously, if authority was not overridden, then some name resolvers (such as grpclb) had no retry.
• xds: Handle loops and duplicates in xds Aggregate clusters
• xds: require EDS service name in CDS resources with an xdstp name
• xds: Use Rule order instead of RuleChain
• xds: Environment variable "GRPC_XDS_EXPERIMENTAL_SECURITY_SUPPORT" is no longer respected, so xDS security cannot be disabled any more (#10243)

New Features

• binder: Add UserHandle and BinderChannelCredentials to support cross-user communication (#10197)
• xds,orca: LRS named metrics support

Improvements

• core: Resolve isAndroid only once on class loading. This can improve channel creation performance on Android.
• xds: Pick a subchannel with new static stride scheduler in WeightedRoundRobinLoadBalancer

Bug Fixes

• xds: Fix the server sending a GOAWAY when an LDS update with no changes other than ordering is received.
• netty: Fix NPE when a header with errors is received with endStream=true. This was causing logs to be filled with errors when health checkers didn’t specify a content type.
• okhttp: Fix the Socket data race when shutdown/closed during connecting that was causing a significant delay

Dependencies

• Upgraded Netty to 4.1.93-Final
• Update guava dependency to 32.0.1 to address CVE-2023-2976

Acknowledgements

• Benjamin Peterson
• Masakuni Oishi
• Philip K. Warren
• Stephane Landelle

v1.56.1

Bug fixes

• core: Fix regression in 1.54.0 where polling NameResolvers would not refresh after a resolution error (#10328). The symptom is a transient failure like "UNAVAILABLE: Unable to resolve host" continuing potentially forever. This did not impact DnsNameResolver, but it did impacted GrpclbNameResolver which is the dns name resolver used when grpc-grpclb is in the classpath. So even users that think "I don't use grpclb" may have been impacted. round_robin is mainly impacted on startup, but if the error happened afterward it would commonly fix itself for short transient DNS failures. pick_first is impacted at all times; any failed DNS resolution could cause all future RPCs on the channel to fail.

v1.55.3

Bug fixes

• core: Fix regression in 1.54.0 where polling NameResolvers would not refresh after a resolution error (#10328). The symptom is a transient failure like "UNAVAILABLE: Unable to resolve host" continuing potentially forever. This did not impact DnsNameResolver, but it did impacted GrpclbNameResolver which is the dns name resolver used when grpc-grpclb is in the classpath. So even users that think "I don't use grpclb" may have been impacted. round_robin is mainly impacted on startup, but if the error happened afterward it would commonly fix itself for short transient DNS failures. pick_first is impacted at all times; any failed DNS resolution could cause all future RPCs on the channel to fail.

v1.54.2

Bug Fixes

• core: Fix regression in 1.54.0 where polling NameResolvers would not refresh after a resolution error (#10328). The symptom is a transient failure like "UNAVAILABLE: Unable to resolve host" continuing potentially forever. This did not impact DnsNameResolver, but it did impacted GrpclbNameResolver which is the dns name resolver used when grpc-grpclb is in the classpath. So even users that think "I don't use grpclb" may have been impacted. round_robin is mainly impacted on startup, but if the error happened afterward it would commonly fix itself for short transient DNS failures. pick_first is impacted at all times; any failed DNS resolution could cause all future RPCs on the channel to fail.
• xds: Avoid using the default locale for case insensitive path matching (#10149)
• xds: Avoid potential channel panic when control plane changes the field used to configure load balancing (#10103)
• core: Allow transparent retries after a retry attempt and the configured max retries was 1 (#10080)

v1.56.0

API Changes

• api: Stabilize the SynchronizationContext class (#10130).
• api: Stabilize io.grpc.CallCredentials (#10208, #10211). thisUsesUnstableApi() is @Deprecated and has a default implementation. CallCredentials implementations should delete their implementation or remove @Overrides, as the method will be deleted in the future.
• api: Stabilize the ProxyDetector hierarchy and ManagedChannelBuilder.proxyDetector method.

Behavior Changes

• core: Sticky TRANSIENT_FAILURE in PickFirstLoadBalancer (#10106). See gRFC A62. If it can't connect, pick-first will now immediately fail RPCs until after it successfully connects. RPCs will no longer be delayed while it performs those attempts, which previously could cause significant (error) latency. It now also performs reconnect attempts after failure and backoff without prompting; previously it required an RPC to trigger the reconnect. ManagedChannel.idleTimeout (defaults to 30 minutes) still applies and forces the channel idle after a period of no RPCs.
• stub: Add a null check for responseObserver into the methods for initiating a call that takes a responseObserver argument. This ensures a fail fast with a clearer cause instead of an NPE when the observer is first used.
• xds: Flip default for RLS being enabled to true for XDS (#10248) (#10252). If there are no RLS configurations in your XDS or you already enabled it with the environment variable this will have no effect. To disable it, set the flag GRPC_EXPERIMENTAL_XDS_RLS_LB to false.
• xds: Rename weighted_round_robin_experimental LB Policy to weighted_round_robin (#10162).

New Features

• protobuf,protobuf-lite: Allow to configure protobuf recursion limit (#10094).
• core: Optional address shuffle in PickFirstLoadBalancer (#10110).
• xds: pick_first LB configuration (#10181).

Improvements

• xds: Add error-per-second in weight formula for client-side WRR (#10177).
• xds: Use application_utilization and fallback to cpu_utilization if unset in weight formula for client-side WRR. (#10256).
• bazel: The README now mentions Bazel and where to find the example. (#10217).

Bug Fixes

• binder: Handle unexpected exceptions on binder threads. (#10092.
• ​​android,binder,cronet: .aar file when publishing. (#10138).
• api: Fix boundary check in Status.fromCodeValue(). (#10155).
• core: Don't use system Locale for content-type matching. (#10097).
• okhttp: Fix signed-byte comparison in server when checking for ASCII in header (#10151). Without fix, authority could contain utf-8.

Dependencies

• Version pinning (e.g., [1.56.0] instead of 1.56.0) has been removed from POMs, for both Netty and gRPC dependencies. The pinning was unreliable in Maven and ignored in Gradle, yet caused downloads during the build to fetch the version list. For a while we've had a BOM that helps reduce version skew. (#10175).
• bazel: Add java toolchain type to all rules using java_common. (#10225).
• Upgraded netty-tcnative-boringssl-static in grpc-netty-shaded to 2.0.61.Final (#10260). Netty itself was not updated.
• Upgraded AndroidX Annotation to 1.6.0 (#10178).
• Upgraded AndroidX Core to 1.10.0 (#10178).
• Upgraded AndroidX Lifecycle-Common to 2.6.1 (#10178).
• Upgraded OpenCensus to 0.31.1 (#10178).
• Upgraded Cronet API to 108.5359.79 (#10178).
• Upgraded proto-google-common-protos to 2.17.0 (#10178).
• Upgraded Gson to 2.10.1 (#10178).
• Upgraded PerfMark API to 0.26.0 (#10178).
• Upgraded RE2/J to 1.7 (#10178).

Acknowledgements

• @chenwei321
• @cushon
• @kloyan
• @kotlaja
• @vorburger

v1.55.1

The 1.55.0 release failed. There were no artifacts published for it.

API Changes

• services: Rename MetricRecorder.setQps/clearQps to setQpsMetric/clearQpsMetric (#10031)

Behavior Changes

• gcp-observability: Remove monitored resource detection for logging (#10020). The cloud libraries will fill in these details instead
• protoc-gen-grpc-java: binaries for Linux ARM and PPC are now built using Ubuntu 18.04. They will no longer work on Ubuntu 16.04 and Debian 9

New Features

• api: Stabilize the frequently used compression APIs (#9942): CallOptions.withCompression, CallOptions.getCompressor, AbstractStub.withCompression, ServerCall.setCompression, ServerCall.setMessageCompression
• api: Stabilize Detachable and HasByteBuffer
• gcp-observability: Stabilize GcpObservability (#10024). The GcpObservability API provides a simple way to export logging, tracing, and metrics to Google Cloud Operations. See the Google Cloud blog post.
• census: Add new tracer annotation to indicate the time when name resolution completed for those RPCs that experienced name resolution delay, or the time when picking subchannel completed for those RPCs that experienced picking subchannel delay. (#10014, #10044)
• protoc-gen-grpc-java: binary for s390x is now published (#9455). The glibc version used is available in Ubuntu 20.04, Debian 11, and CentOS 9 and later
• authz: Added FileWatcherAuthorizationServerInterceptor (#9775)
• services: Added OrcaMetricReportingServerInterceptor.create(MetricRecorder) which adds common metrics per-RPC (#9902)
• android: Add UdsChannelBuilder for using LocalSocket an Android (#8418)
• alts: Observe the GRPC_ALTS_MAX_CONCURRENT_HANDSHAKES environment variable user to adjust the max number of concurrent ALTS handshakes (#10016)
• binder: Expose client identity via PeerUid and PeerUids (#9952)
• binder: Add BindServiceFlags.setAllowActivityStarts() for BIND_ALLOW_ACTIVITY_STARTS added in Android U (#10008)

Bug Fixes

• core: Fix NPE race during hedging (#10007), fixing a Netty buffer memory leak for cancelled RPCs
• core: Allow transparent retries after a retry attempt and the configured max retries was 1 (#10066)
• okhttp: properly implement OkHttpServerBuilder.maxConnectionAgeGrace() (#9968)
• xds: Enable federation support. See gRFC A47
• xds: Enable Weighted Round Robin LB policy support. See gRFC A58
• xds: Avoid ClassCastException if the control plane changes the top-level policy (#10091). This is expected to be unlikely, but is possible
• xds: Fix java.util.NoSuchElementException: SecurityProtocolNegotiators$ClientSdsHandler#0 (#10118). This error did not cause any problems, other than unnecessary logging
• xds: Avoid using the default locale for case insensitive path matching (#10148)
• googleapis: Enable ignore_resource_deletion for google-c2p: resolver’s default xds bootstrap (#10121)
• rls: Refresh name resolution on rejected addresses (#10032)

New Examples

• Keepalive (#9956)
• Cancellation (#9962)
• Deadline (#9958)
• Using waitForReady (#9960)
• Client and Server sharing (#9969)
• Reflection (#9955)
• Doing debug (#9957)
• Health service (#9991)
• Error details (#9997)
• Custom load balancing (#9951)
• gRPC-level reverse proxy (#10059)

Dependencies

• protobuf-java and protobuf-java-util upgraded to 3.22.3 (#10045)

Acknowledgements

• @carl-mastrangelo
• @haubenr
• @jpd236
• @kenk42292