Releases: grpc/grpc-java
V1.81.0
In this release we drop support for Android API level 22 or lower (Lollipop or earlier), following Google Play Service’s discontinued updates for Lollipop (API levels 21 & 22) and now requires a minimum of API level 23 (Android 6.0 Marshmallow).
API Changes
- api: Deprecate LoadBalancer.handleResolvedAddresses(). Developers maintaining custom LoadBalancer implementations should transition to using LoadBalancer.acceptResolvedAddresses(). Unlike the deprecated method, acceptResolvedAddresses() returns a Status object, allowing the load balancer to explicitly report success or reject the update if the provided addresses or configuration are invalid. (#11623)
Behavior Changes
- core: Enable dns "caching" on Android for 30 seconds to reduce CPU impact of a refresh loop with an LB policy (0675f70). DnsNameResolver ignores re-resolution requests on OpenJDK-like platforms if it has been too soon since the last DNS query because InetAddress.getAllByName() has a cache with a fixed entry lifetime, but this logic was disabled for Android which does not have that style of cache. Android’s cache uses the result TTL, which will rarely be less than 30 seconds. This change would probably be most noticeable when 1) changing to a different network (e.g., from wifi to mobile), 2) the server has different addresses for different networks, and 3) the app is not using AndroidChannelBuilder with an
android.context.Context. For reference, it seems Chrome caches for 1 minute
Bug Fixes
- opentelemetry: Fix baggage propagation, the baggage propagation for opentelemetry introduced in #12389 was broken. The context is decided once and used for all recording for the call, thus guaranteeing all record()s have consistent information.
- core: Address a race condition where
ManagedChannelOrphanWrappercould incorrectly log a "not shutdown properly" warning during garbage collection when using directExecutor(). (#12705) (d459338) - xds: Fix xDS HTTP CONNECT's transport socket name bug which is now corrected to use
typeUrl. (#12740) (eac9fe9) - xds: Fix an issue where subchannel metrics were dropping their association with the
backend_service. This ensures xDS load balancing metrics are reported accurately. (#12735)
New Features
- netty: Add tcp metrics, by implementing a few of the metrics defined in A80.
- api: Add a CallOption for a custom label on per-RPC metrics (0e39b29). This CallOption is copied by grpc-opentelemetry to the
grpc.client.call.customlabel as defined by gRFC A108. See also the gRPC OpenTelemetry Metrics guide (update in-progress) - xds: Add support for Weighted Round Robin (WRR) load balancing driven by custom backend metrics, implementing the behavior defined in gRFC A114. (#12645)
- utils: Update
AdvancedTlsX509KeyManagerso that developers can now preserve and use key aliases when dynamically reloading TLS certificates. (#12686)
Documentation
- Update the "Outgoing Flow Control" section in the Manual Flow Control example to say onNext() does not block, but rather queues the messages in memory and advises developers to use CallStreamObserver.isReady() to prevent this memory exhaustion (#12700) (a3a9ffc) (#12726) (65ae2ef)
- examples: Clean up Health example, and document need for grpc-services (3ed732f)
Dependencies
- Upgrade Dependencies (#12719) (16e17ab). Google-auth-library: 1.42.1, animal-sniffer: 1.27, assertj-core:3.27.7, error_prone_annotations:2.48.0, proto-google-common-protos:2.64.1, google-cloud-logging:3.23.10, jetty-http2-server:12.1.7, jetty-ee10-servlet:12.1.7, lincheck:3.4, opentelemetry-api:1.60.1, opentelemetry-exporter-prometheus:1.60.1-alpha, opentelemetry-gcp-resources:1.54.0-alpha, opentelemetry-sdk-extension-autoconfigure:1.60.1, opentelemetry-sdk-testing:1.60.1, robolectric:4.16.1, tomcat-embed-core:10.1.52, tomcat-embed-core9: 9.0.115,
- Upgrade Netty to 4.1.132 and netty-tcnative to 2.0.75 (1528f80)
Thanks to
V1.80.0
API Changes
- core: Added PickResult.copyWithSubchannel() and PickResult.copyWithStreamTracerFactory() to simplify updating PickResult while preserving metadata. Load balancing policies should now ensure ForwardingSubchannel decorators are unwrapped before being returned in a pick result. (#12658) (eae16b2)
Bug Fixes
- core: Fixed the retry backoff jitter range to [0.8, 1.2] to align with the gRPC A6 specification. Retries will now occur more consistently around the calculated backoff interval. (#12639) (024fdd0)
core: Fixed a race condition in RetriableStream where inFlightSubStreams counting could become inconsistent during concurrent retry and deadline events. This ensures that client calls (such as blockingUnaryCall) do not hang indefinitely and correctly receive a close signal. (#12649) (73abb48)
Improvements
- api: Trigger R8's ServiceLoader optimization to reduce necessary configuration when using R8 Full Mode (470219f). This allows gRPC to avoid reflection, and the need to specify -keeps for various class’s constructors.
Upgrade to protobuf 33.4 (#12615) (50c18f1) - cronet: Introduced CRONET_READ_BUFFER_SIZE_KEY to allow customizing the read buffer size per-stream via CallOptions. Increasing the buffer size from the 4KB default can significantly improve performance for large messages by reducing JNI and context-switching overhead. (31fdb6c)
- api: Moved FlagResetRule to api/testFixtures and updated ManagedChannelRegistry to honor the GRPC_ENABLE_RFC3986_URIS feature flag. This ensures that target parsing is consistent across the library when the new URI parser is enabled. (#12608)
- api: Updated NameResolverRegistry to natively support io.grpc.Uri. This is a foundational change that allows gRPC's name resolution system to handle URIs parsed with the new RFC 3986-compliant parser, ensuring more robust target handling. (#12609) (9903488)
- xds: Removed the GRPC_EXPERIMENTAL_XDS_SNI feature flag. SNI determination via xDS is now always enabled and follows gRFC A101, where SNI is derived from xDS configurations like auto_host_sni or UpstreamTlsContext.sni. This ensures that no SNI is sent if not explicitly configured, unless the legacy channel authority fallback is enabled. (#12625) (ac44e96)
New Features
- core: pick_first shuffling now a weighted shuffle and observes weights from EDS (34dd290). This finishes the gRFC A113 pick_first: Weighted Random Shuffling support
- netty: Added RFC 3986 support to the unix: name resolver. This enables proper parsing of Unix domain socket URIs, including correct handling of query and fragment components in both hierarchical (e.g., unix:///path) and opaque (e.g., unix:/path) formats. (#12659)
Thanks to
v1.79.0
API Changes
-
core: Delete the never-used io.grpc.internal.ReadableBuffer.readBytes(ByteBuffer) (#12580) (738782f). This is deeply internal and not accessible, so shouldn’t impact anything. However, Apache Arrow Java uses reflection to access private fields; GH-939: Remove reflection for gRPC buffers is swapping to gRPC’s public zero-copy APIs
-
opentelemetry: Add target attribute filter for metrics (#12587). Introduce an optional Predicate targetAttributeFilter to control how grpc.target is recorded in OpenTelemetry client metrics. When a filter is provided, targets rejected by the predicate are normalized to "other" to reduce grpc.target metric cardinality, while accepted targets are recorded as-is. If no filter is set, existing behavior is preserved. This change adds a new Builder API on GrpcOpenTelemetry to allow applications to configure the filter.
Behavior Changes
-
core: Convert AutoConfiguredLB to an actual LB (4bbf8ee). This is an internal refactoring, but it does improve how errors are handled for broken binaries. Previously, not being able to load pick_first would result in a channel panic. Now it is handled as a regular load balancing error
-
okhttp: Assert no pending streams before transport READY (#12566) (ed6d175). No pending streams should exist when the transport transitions to READY. This PR adds an assertion to help verify this invariant.
Bug Fixes
-
core: PickFirstLB should not return a subchannel during CONNECTING (228fc8e). Pick-first in grpc-java has behaved this way since it was created, and it was of no consequence. However, now there are some load balancing policies (mainly RLS) that will do a pick() and hope the result to be reasonably accurate for metrics.
-
xds: Endpoint weights are now normalized within localities, so that when using rish_hash the locality weights are preserved (f6d140f). Previously, localities with many endpoints or high endpoint weights could receive excess traffic. This is one part of gRFC A113 pick_first: Weighted Random Shuffle
Improvements
-
core: Improve DEADLINE_EXCEEDED message for CallCreds delays (ead532b). Previously the error message contained “buffered_nanos” and “waiting_for_connection” for connection delays. However, we discovered the same strings were also used if waiting on CallCredentials. Now you’ll see details like “connecting_and_lb_delay”, “call_credentials_delay”, and “was_still_waiting”.
-
opentelemetry: Add Android API checking (a9f73f4). Previously we assumed OpenTelemetry support would not be used on Android. It did happen to be compatible with Android, but since OpenTelemetry does have some Android support, we now have a check that it remains compatible
-
core: Catch Errors when calling complex config parsing code (a535ed7). Error (and any other Throwable) is now caught and handled when parsing configuration (e.g., service config, xds). This will cause such failures to be handled gracefully instead of panicking the channel
-
core: Implement LoadBalancer.Helper.createOobChannel() with the internals of createResolvingOobChannel() (3915d02). This API is only expected to be relevant to the gRPC-LB lookaside load balancer, and is not believed to have behavior changes. Out-of-band channel had been implemented with its own stripped-down Channel without load balancing. Reimplementing using the resolving oob channel makes it a full-fledged channel and reduces the burden when integrating new features and allows us to have a ManagedChannelBuilder to use with efforts like gRFC A110: Child Channel Options.
-
xds: Implement the proactive connection logic in RingHashLoadBalancer as outlined in gRFC A61 (#12596). Previously, the Java implementation only initialized child balancers when a ring-chosen endpoint was in TRANSIENT_FAILURE during a picker's pickSubchannel call. This PR adds the missing logic: when a child balancer reports TRANSIENT_FAILURE, the LoadBalancer now proactively initializes the first available IDLE child if no other children are currently connecting or ready.
This ensures a backup subchannel starts warming up immediately outside the RPC flow, reducing failover latency and improving overall resilience. This behavior was previously present but was inadvertently lost after #10610.
- api: Add RFC 3986 support to DnsNameResolverProvider (#12602) (f65127c) Experimental RFC 3986 target URI parsing mode (disabled by default)
New Features
- opentelemetry: Actual reason for the disconnects in subchannel metrics(6b2f758), completing the remaining work in gRFC A96: OTel metrics for Subchannels
Dependencies
-
protobuf: Upgrade Bazel protobuf to 33.1 (#12553) (b61a8f4) and load java_proto_library from the protobuf repo (c7f3cdb)
-
protobuf: Fix build with Bazel 9 by upgrading bazel_jar_jar and grpc-proto versions (#12569)
-
Upgrade dependencies (#12588) (6422092) Netty to 4.1.130, error-prone annotations to 2.45.0, google-auth-library to 1.41.0, tomcat-embed-core9 to 9.0.113, tomcat-embed-core to 10.1.50, opentelemetry to 1.57.0, jetty-ee10-servlet to 12.1.5, jetty-http2-server to 12.1.5, google-cloud-logging to 3.23.9, google-auth to 1.41.0, proto-google-common-protos to 2.63.2.
Thanks to
v1.76.3
Dependencies
- Downgrade OpenTelemetry to 1.51.0 to make it easier for people dealing with the OkHttp 4.x → 5.x upgrade of some OpenTelemetry modules (354d8b4). gRPC is not using the impacted OpenTelemetry modules. Users are still free to upgrade to newer versions of OpenTelemetry of their choosing.
V1.78.0
Bug Fixes
- core: Fix shutdown failing accepted RPCs during channel startup (02e98a8). This fixes a race where RPCs could fail with "UNAVAILABLE: Channel shutdown invoked" even though they were created before channel.shutdown()
- okhttp: Fix race condition overwriting MAX_CONCURRENT_STREAMS (#12548) (8d49dc1)
- binder: Stop leaking
thisfrom BinderServerTransport's ctor (#12453) (89d77e0) - rls: Avoid missed config update from reentrancy (55ae1d0). This fixes a regression since 1.75.0 triggered by CdsLb being converted to XdsDepManager. Without this fix, a second channel to the same target may hang when starting, causing DEADLINE_EXCEEDED, and unhang when the control plane delivers an update (e.g., endpoint address update)
Improvements
- xds: gRFC A88 - Changes to XdsClient Watcher APIs (#12446) (f385add). We now have improved xDS error handling and this provides a clearer mechanism for the xDS server to report per-resource errors to the client, resulting in better error messages for debugging and faster detection of non-existent resources. This also improves the handling of all xDS-related data errors and the behavior of the xDS resource timer.
- rls: Control plane channel monitor state and back off handling (#12460) (26c1c13). Resets RLS request backoff timers when the Control plane channel state transitions to READY. Also when the backoff timer expires, instead of making a RLS request immediately, it just causes a picker update to allow making rpc again to the RLS target.
- core: simplify DnsNameResolver.resolveAddresses() (4843256)
- netty: Run handshakeCompleteRunnable in success cases (283f103)
- api,netty: Add custom header support for HTTP CONNECT proxy (bbc0aa3)
- binder: Pre-factor out the guts of the BinderClientTransport handshake. (9313e87)
- compiler: Add RISC-V 64-bit architecture support to compiler build configuration (725ab22)
- core: Release lock before closing shared resource (cb73f21). Shared resources are internal to gRPC for sharing expensive objects across channels and servers, like threads. This reduces the chances of forming a deadlock, like seen with s2a in d50098f
- Upgrade gson to 2.12.1 (6dab2ce)
- Upgrade dependencies (f36defa). proto-google-common-protos to 2.63.1, google-auth-library to 1.40.0, error-prone annotations to 2.44.0, guava to 33.5.0-android, opentelemetry to 1.56.0
- compiler: Update maximum supported protobuf edition to EDITION_2024 (2f64092)
- binder: Introduce server authorization strategy v2 (d971072). Adds support for
android:isolatedProcessServices and moves all security checks to the handshake, making subsequent transactions more efficient.
New Features
- compiler: Upgrade to C++ protobuf 33.1 (#12534) (58ae5f8).
- util: Add gRFC A68 random subsetting LB (48a4288). The policy uses the name
random_subsetting_experimental. If it is working for you, tell us so we can gauge marking it stable. While the xDS portions haven’t yet landed, it is possible to use with xDS with JSON-style Structs as supported by gRFC A52 - xds: Support for System Root Certs (#12499) (51611ba). Most service mesh workloads use mTLS, as described in gRFC A29. However, there are cases where it is useful for applications to use normal TLS rather than using certificates for workload identity, such as when a mesh wants to move some workloads behind a reverse proxy. The xDS
CertificateValidationContextmessage (see envoyproxy/envoy#34235) has asystem_root_certsfield. In the gRPC client, if this field is present and theca_certificate_provider_instancefield is unset, system root certificates will be used for validation. This implements gRFC A82. - xds: Support for GCP Authentication Filter (#12499) (51611ba). In service mesh environments, there are cases where intermediate proxies make it impossible to rely on mTLS for end-to-end authentication. These cases can be addressed instead by the use of service account identity JWT tokens. The xDS GCP Authentication filter provides a mechanism for attaching such JWT tokens as gRPC call credentials on GCP. gRPC already supports a framework for xDS HTTP filters, as described in gRFC A39. This release supports the GCP Authentication filter under this framework as described in gRFC A83.
- xds: Support for xDS-based authority rewriting (#12499) (51611ba). gRPC supports getting routing configuration from an xDS server, as described in gRFCs A27 and A28. The xDS configuration can configure the client to rewrite the authority header on requests. This functionality can be useful in cases where the server is using the authority header to make decisions about how to process the request, such as when multiple hosts are handled via a reverse proxy. Note that this feature is solely about rewriting the authority header on data plane RPCs; it does not affect the authority used in the TLS handshake.
As mentioned in gRFC A29, there are use-cases for gRPC that prohibit trusting the xDS server to control security-centric configuration. The authority rewriting feature falls under the same umbrella as mTLS configuration. As a result, the authority rewriting feature will only be enabled when the bootstrap config for the xDS server hastrusted_xds_serverin theserver_featuresfield. - xds: xDS based SNI setting and SAN validation (#12378) (0567531). When using xDS credentials make SNI for the Tls handshake to be configured via xDS, rather than use the channel authority as the SNI, and make SAN validation to be able to use the SNI sent when so instructed via xDS. Implements gRFC A101.
Documentation
- api: Document gRFC A18 TCP_USER_TIMEOUT handling for keepalive (da70387)
- core: Fix AbstractClientStream Javadoc (28a6130)
- examples: Document how to preserve META-INF/services in uber jars (97695d5)
Thanks to
v1.77.1
Bug Fixes
- rls: Avoid missed config update from reentrancy (#12549). This fixes a regression since 1.75.0 triggered by CdsLb being converted to XdsDepManager. Without this fix, a second channel to the same target may hang when starting, causing DEADLINE_EXCEEDED, and unhang when the control plane delivers an update (e.g., endpoint address update)
v1.76.2
Bug Fixes
- rls: Avoid missed config update from reentrancy (#12550). This fixes a regression since 1.75.0 triggered by CdsLb being converted to XdsDepManager. Without this fix, a second channel to the same target may hang when starting, causing DEADLINE_EXCEEDED, and unhang when the control plane delivers an update (e.g., endpoint address update)
v1.77.0
API Changes
- binder: Remove experimental
BinderChannelBuilder.bindAsUser()method, deprecated since 1.69 (#12401) (f96ce06)
Bug Fixes
- api: Fix name resolver bridge listener handling for address resolution errors for custom name resolvers (#12441) (acbbf86). This fixes regression introduced in v1.68.1 causing a “IllegalStateException: No value present.” exception
- core: Fix NullPointerException during address update with Happy Eyeballs (5e8af56). This should not impact many people as the code is disabled by default, behind two experimental environment variables
- okhttp: Fix bidirectional keep-alive causing spurious GOAWAY (6fc3fd0). This fixes the grpc-okhttp server incorrectly closing the connection with
GOAWAY: too_many_pings - xds: SslContext updates handling when using system root certs (#12340) (63fdaac). Since
FileWatcherCertificateProviderisn't used when using system root trust store, the SslContext update for the handshake that depended on it wasn't happening. This fix creates a separateCertificateProviderfor handling system root certs that doesn't rely on theFileWatcherCertificateProvider. - xds: Make cluster selection interceptor run before other filters (#12381) (82f9b8e). This is needed when there is
GcpAuthenticationFilterin the filter chain to make available the cluster resource inCallOptions. - xds: Handle wildcards in DNS SAN exact matching (#12345) (5b876cc)
- android: Fix UdsChannelBuilder with WiFi Proxy (349a35a)
- binder: Avoid potential deadlock when canceling AsyncSecurityPolicy futures (#12283) (4725ced)
- binder: Fix a BinderServerTransport crash in the rare shutdown-before-start case (#12440) (91f3f4d)
Improvements
- Improve status messages by including causal error details in config parsing errors for outlier detection and xds’s wrr locality policies (86e8b56)
- xds: Detect negative ref count for xds client (21696cd). A negative reference count could cause NullPointerExceptions, so when too many unrefs are detected it produces a SEVERE warning and prevents the reference count from going negative
- xds: Support deprecated xDS TLS fields for Istio compat (#12435) (53cd1a2). This fixes a regression with Istio introduced in v1.73.0. This gives time for Istio’s new xDS field support to roll out
- googleapis: Allow wrapping NameResolver to inject XdsClient (#12450) (27d1508). This allows googleapis to inject an xDS bootstrap to use with its channels even if one is already specified in the environment variable or system property. When the code was originally written there was a single global XdsClient, but since gRFC A71 Xds Fallback each target string has its own XdsClient and thus can have its own bootstrap
- alts: Allow overriding metadata server address with env variable (9ac12ef) (498f717)
- binder: Let the server know when the client fails to authorize it. (#12445) (599a0a1) This avoids the server needing to wait for the handshake timeout before realizing the handshake failed
New Features
- opentelemetry: Implement otel retry metrics from gRFC A96 (#12064) (d380191)
- opentelemetry: propagate baggage to server metrics for custom attributes (#12389) (155308d)
- xds: Allow EC Keys in SPIFFE Bundle Map parsing (#12399) (559e3ba)
- xds: Enable authority rewriting (gRFC A81), system root cert support (gRFC A82), GCP authentication filter (gRFC A83), and SNI (gRFC A101) (#12499) (246c2b1). Authority rewriting requires the control plane to be labeled
trusted_xds_serverin the bootstrap. System root cert support and SNI require using XdsChannelCredentials - rls: Add route lookup reason to request whether it is due to a cache miss or stale cache entry (#12442) (795ce02)
Dependencies
- compiler: C++ protobuf used by codegen upgraded to 26.1 (#12330) (55aefd5)
- alts: Remove dep on grpclb (b769f96). ALTS is no longer used with grpclb, so this removes dead code
- Upgrade netty to 4.1.127.Final (b37ee67)
Thanks to
@panchenko
@benjaminp
@HyunsangHan
@becomeStar
@ZachChuba
@oliviamariacodes
@kssumin
@laz-canva
v1.76.1
v1.76.0
Bug Fixes
- xds: ClusterResolverLb has been converted to use XdsDepManager, which finishes the changes for gRFC A74 xDS Config Tears. This change should resolve some unnecessary reconnections introduced in v1.75.0 when using weighted_round_robin and maybe other policies.
- netty: Remove Netty version detection since grpc-netty-shaded can't reliably determine its Netty version when multiple copies of Netty are present (even when shaded). This fixes the resurfacing of the Netty 4.1.111 corruption fixed in 1.65.0. That version fixed grpc-netty, but v1.75.0 upgraded grpc-netty-shaded to Netty 4.1.111 and exposed the Netty version detection problem. This fixes corruption, so the error messages range wildly, but one of them is "RESOURCE_EXHAUSTED: gRPC message exceeds maximum size"
- compiler: A fix has been implemented for the blockingV2 stub to mangle generated method names that conflict with java.lang.Object methods.
- servlet: A race condition in AsyncServletOutputStreamWriter has been fixed to prevent threads from getting stuck.
- servlet: An issue where AsyncContext.complete() was called multiple times, causing an IllegalStateException, has been resolved.
- binder: The REMOTE_UID is now required to hold the exact UID passed to the SecurityPolicy.
- binder: The server will now only accept post-setup transactions from the authorized server UID.
- util: AdvancedTlsX509TrustManager now errors with a message to say that files don’t exist instead of the previous “Files were unmodified before their initial update. Probably a bug.”
- android: A fix has been implemented for network change handling on API levels below 24.
Improvements
- api: Allocations of Attributes.Builder have been reduced. This mostly benefits attributes.toBuilder(), but that’s not expected to be visible in regular workloads.
- api: An empty array allocation in LoadBalancer.CreateSubchannelArgs.Builder has been avoided. It is a small optimization and is not expected to have any performance impact.
- servlet: A configurable methodNameResolver has been added to configure the mapping from servlet request paths to gRPC method name
- servlet: Avoid a race by increasing the AsyncContext timeout by 5 seconds. The gRPC Context timeout should trigger first
- xds: Pretty-print envoy.service.discovery.v3.Resource in debug logs
- bazel: The java/proto rules from rules_java/rules_proto are now used instead of native rules.
- bazel: Unnecessary direct build dependencies were removed from some targets
- netty: Support for the BCJSSE provider has been added in GrpcSslContexts.
- netty: Huffman coding in server response headers has been disabled; it was already disabled for client request headers
- netty: Include allow header for HTTP response code 405
- okhttp: Include allow header for HTTP response code 405
- binder: Error descriptions for ServiceConnection callbacks have been improved
- binder: Apps can now call SecurityPolicy.checkAuthorization() by PeerUid.
New Features
- stub: Trailers are now propagated in StatusException when thrown by BlockingClientCall.
- compiler: Support for macOS aarch64 with a universal binary has been added.
- opentelemetry: grpc.subchannel.* metrics as described in gRFC A94 OTel metrics for Subchannels have been added. grpc.disconnect_error will show as “unknown” until transports implement support
- binder: A NameResolver for Android's intent: URIs has been introduced.
- binder: A basic SocketStats with just the local and remote addresses has been added for channelz.
Documentation
- SECURITY.md: The documentation now describes how to use gcompat with LD_PRELOAD for Alpine.
- examples: The documentation now explains Bazel BCR releases and the git_override option.
Dependencies
- Upgraded Guava version to 33.4.8.
- The org.apache.tomcat:annotations-api dependency has been removed from the examples.
Thanks to
@JoeCqupt
@Sangamesh1997
@benjaminp
@camelcc
@dmytroreutov
@duckladydinh
@jirkafm
@kilink
@panchenko
@umairk79
@vimanikag
@werkt
@xuhongxu96
@zrlw