v1.38.0

gRPC Java 1.38.0 Release Notes

API Changes

• services: move classes with protobuf dependency into io.grpc.protobuf.services. Users currently using BinaryLogging, HealthChecking, Channelz should migrate to use the corresponding classes in io.grpc.protobuf.services. (#8056)
• ChannelCredentials and ServerCredentials and are now stable. Notably, this also includes TlsChannelCredentials and TlsServerCredentials that allow mTLS configuration without a direct dependency on Netty. The description of the new API can be found in gRFC L74. These APIs are intended to “replace” the implicit security defaults of channels/servers as well as the usePlaintext() and useTransportSecurity() methods on the channel and server builders. The previous APIs are stable so will not be removed. Over time, documentation and examples will be migrated to the new API

Bug Fixes

• xds: Fixed a bug that xDS users may experience null pointer exception in rare cases (#8087)
• netty: Fixed a bug that client RPCs may fail with a wrong exception with message "Maximum active streams violated for this endpoint" when receiving GOAWAY while MAX_CONCURRENT_STREAMS is reached. After the fix the client RPC should fail with UNAVAILABLE status in such a scenario. (#8020)
• xds: Fixed a bug that xDS LB policies may process and propagate load balancing state update from its child LB policy after itself being shut down. This can be cascaded and result in hard-to-reason behaviors if any one layer of the LB policies does not clean up its internal state after shutdown.

Behavior Changes

• core, grpclb, xds: let leaf LB policies explicitly refresh name resolution when subchannel connection is broken. Custom LoadBalancer implementations should refresh name resolution (with Helper.refreshNameResolution()) when seeing its created subchannel becomes IDLE or TRANSIENT_FAILURE. Currently the Channel will do it for you and log a warning. But this operation will be removed in the future releases. (#8048)
• netty: Added support for OpenJSSE

Dependencies

• Upgrade Guava to 30.1 (#8100). As part of #4671 grpc-java will drop support for Java 7, with no impact to Android API levels supported. Guava is going through the same process and in this Guava release it warns when used on Java 7. If you are using Java 7 and are impacted, please comment on #4671. The Java 7 check may be noticed by Android builds and fail without language-level desugaring. We expect most users have already enabled language-level desugaring, but if not it would be necessary to add to your build.gradle:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

• auth: Allow pre- and post-0.25.0 behavior from google-auth-library-java, for Bazel users. google-auth-library-java 0.25.0 changed its behavior for JWT that caused a gRPC test to fail. The failure was benign but prevented Bazel users from using newer versions of the library

v1.37.1

Bug Fixes

• netty: fixed a bug that client RPCs may fail with a wrong exception with message "Maximum active streams violated for this endpoint" when receiving GOAWAY while MAX_CONCURRENT_STREAMS is reached. After the fix the client RPC should fail with UNAVAILABLE status in such a scenario.
• grpclb, xds: fixed a day-one issue that the control plane RPC are using the same Context as the inbound application RPC, which can cause control plane RPC aborted when the inbound application RPC completes.
• xds: fixed a bug that xDS LB policies may process and propagate load balancing state update from its child LB policy after itself being shut down. This can be cascaded and result in hard-to-reason behaviors if any one layer of the LB policies does not clean up its internal state after shutdown.

v1.37.0

Behavior Changes

• alts: make both GoogleDefaultChannelCredentials and ComputeEngineChannelCredentials choose ALTS for backends given by xDS TD. Changes for ComputeEngineChannelCredentials were missing, but they really should be the same.
• api: added a convenient ServerBuilder.addServices() API that allows adding a list of services instead of iterating through list and calling addService().
• api: deleted some NameResolver APIs that have been marked as deprecated since 1.21 release.
• api: implemented admin interface API, which automatically loads available admin services in a given binary. Currently, it only includes Channelz and CSDS with dependencies required at runtime.
• context: move pendingDeadline.cancel out of synchronized block.
• netty: allow connection handshakes (e.g., TCP, TLS) to be interrupted by channel.shutdown(). Previously shutdownNow() was required for prompt shutdown if a connection was handshaking.
• xds: change in parsing ADS responses for LDS, RDS, CDS, and EDS resources. Before this release, gRPC parsing logic for ADS response containing multiple resources was to stop resource processing on the first encountered error, followed by NACK with the details of this single error. With this change, the parsing logic processes all resources and collects all processing errors. If any error occurred, a NACK is issued with concatenated error messages of all errors encountered. The rationale and the detailed design can be found in gRFC A40 — ADS Parsing Logic Update: Continue After First Error.
• xds: change system property name for reading bootstrap config from io.grpc.xds.bootstrapValue to io.grpc.xds.bootstrapConfig.
• xds: circuit breaking, timeout and fault injection are enabled by default. Previously they were protected by environment variables.
• xds: use the new server_listener_resource_name_template property from the bootstrap file for server side xDS processing as per the gRFC A36-xds-for-servers.md.

New Features

• api: TlsChannelCredentials and TlsServerCredentials now support client certificates and custom KeyManagers/TrustManagers. grpc-netty fully supports these options. grpc-okhttp does not support keyfile-based configuration; you’d need to use a KeyManager. Most users of Netty’s SslContext and GrpcSslContexts should be able to migrate and are encouraged to do so, because this API does not have a Netty dependency and so is planned to become stable.
• netty: added support for OpenJSSE.
• okhttp: support compiling with okio 2.x API for Bazel users. grpc-okhttp was already compatible with okio 2 at runtime.
• xds: XdsServingStatusListener has been implemented as per the gRFC A36-xds-for-servers.md.
• xds: add proto leakage check at gradle build. Create a new Gradle task depends on shadowJar. It examines the outputs of shadowJar package prefix to make sure it is inside within the package.
• xds: added CsdsService. It is safe for production but are Experimental APIs to resolve issues discovered as they see usage. The rationale and description of the new API can be found in gRFC A40: xDS Configuration Dump via Client Status Discovery Service in gRPC.
• xds: implement gRPC server side validations and filterChain match of xDS configuration as per the gRFC A36-xds-for-servers.md.
• xds: WeightedTargetLoadBalancer collect all failure child pickers to log more error details.

Bug Fixes

• grpclb: gRPCLB would buffer RPCs indefinitely if failing to fallback because the resolver provides no fallback addresses. Now it turns into TRANSIENT_FAILURE for such cases.
• xds: fix CdsLoadBalancer2 childLb shutdown behavior. Previously these childLbs are not properly shutdown, which might cause channel panic as client channel is referenced by those childLbs.
• Fixed an UnsupportedOperationException incompatibility with Netty 4.1.60.Final (#7953). This allows users of grpc-netty that may be using Netty elsewhere in their application to upgrade their Netty version to avoid exposure to recent Netty CVEs. gRPC itself is not impacted by those CVEs.
• grpclb: fixed a race between address update and LB stream recreation, which would cause channel panic if the resolver refreshes the result while gRPCLB is in LB stream backoff.
• grpclb: gRPCLB ignored CONNECTING subchannels when aggregating the overall LB state, which would cause RPCs to fail prematurely if there are subchannels in its initial connection.
• grpclb: now we allow multiple authorities in lb backends instead of flattening to the first authority.
• interop-testing: fix alts handshaking race: add proper synchronization on the AltsTestServer object lock, this way, alts client and alts server won’t race on the AltsTestServer during Alts handshake negotiation.
• xds: fixed a bug that would drop some node information (e.g., user-agent) when reporting to LRS (#7964).
• xds: the xDS resolver did not clear its state when control plane resources were revoked before offloading the xDS LB plugin. It would treat the next update as duplicate if the control plane recovers and never comes back to use those resources. Now this is fixed.

Documentation

• example-tls: ported to TlsChannelCredentials/TlsServerCredentials and no longer depends on Netty at compile time.
• examples: add ALTS example README.md.

Dependencies

• gradle: bumped protobuf-gradle-plugin version to 0.8.15
• xds: envoy proto updated to commit ac9a26373. Added xDS v3 csds.proto with dependencies.

Acknowledgements

@spkrka Kristofer Karlsson
@njhill Nick Hill
@ulfjack Ulf Adams

v1.36.1

• Fix an UnsupportedOperationException incompatibility with Netty 4.1.60.Final (#7953). This allows users of grpc-netty that may be using Netty elsewhere in their application to upgrade their Netty version to avoid exposure to recent Netty CVEs. gRPC is not impacted by those CVEs so a Netty upgrade for gRPC itself is not necessary
• xds: Fixed a bug that would drop some node information (e.g., user-agent) when reporting to LRS (#7964)
• xds: Renamed io.grpc.xds.bootstrapValue system property to io.grpc.xds.bootstrapConfig. This more closely matches the environment variable (GRPC_XDS_BOOTSTRAP_CONFIG) and avoids future confusion (#7968)
• xds: Fixed a possible IllegalStateException causing Channel panic during LB shutdown (#7942). The bug was introduced in v1.36.0. The issue likely most impacts xDS users that may leave a channel unused (no RPCs) for 30 minutes since idle timeout triggers LB shutdown

v1.35.1

• Fix an UnsupportedOperationException incompatibility with Netty 4.1.60.Final (#7953). This allows users of grpc-netty that may be using Netty elsewhere in their application to upgrade their Netty version to avoid exposure to recent Netty CVEs. gRPC is not impacted by those CVEs so a Netty upgrade for gRPC itself is not necessary
• xds: Fixed a bug that would drop some node information (e.g., user-agent) when reporting to LRS (#7964)

v1.32.3

Bug Fixes

• xds: Fixed JSON number types in internally generated service config for header matching (more specifically, range matching for numerical headers) (#7880).

v1.31.2

Bug Fixes

• xds: Fixed JSON number types in internally generated service config for header matching (more specifically, range matching for numerical headers) (#7884).

v1.36.0

API Changes

• Added .class file hack to ease removal of internal ABIs (#7834). This does not impact source code (API); it only impacts code compiled with a different version of gRPC than it runs with (ABI). Users of the transport-specific and experimental channel/server builders (NettyChannelBuilder, NettyServerBuilder, OkHttpChannelBuilder, InProcessChannelBuilder, CronetChannelBuilder) are commonly referencing internal ABIs due to overly-specific generics in gRPC. There is now a .class file hack in place which preserves ABI compatibility for old builds while causing javac to use the intended public API for new builds. In a future release we will remove the internal ABI for these experimental APIs (#7211) which may cause runtime failures. Recompiling with this release or later will prevent your code from using those ABIs and so you will not be impacted by the ABI removal. This is related to the temporary ABI breakage in v1.33.0.
• Deleted deprecated LoadBalancer.Helper APIs as they had been deprecated since v1.22 release (#7793).
• Deprecated LoadBalancer.Helper.createResolvingOobChannelBuilder(String target) in favor of the new experimental API createResolvingOobChannelBuilder(String target, ChannelCredentials creds). The two APIs differ not only in signature but also in the default authority of the returned builder. See their javadoc for more detail.

Behavior Changes

• ManagedChannelBuilder.overrideAuthority() is now used even if the NameResolver uses EquivalentAddressGroup.ATTR_AUTHORITY_OVERRIDE. Previously the NameResolver’s override would be used
• grpclb: keep RR Subchannel state in TRANSIENT_FAILURE until becoming READY (#7816). This enhancement was previously made to the round_robin policy, but now also applies to grpclb
• netty: On server-side, stop logging expected STREAM_CLOSED exceptions. This reduces log pollution

New Features

• services: Add support for grpc.channelz.v1.Channelz.GetServer, as defined in channelz.proto
• xds: support reading bootstrap config directly from env var (GRPC_XDS_BOOTSTRAP_CONFIG) or system property (io.grpc.xds.bootstrapValue) values
• alts: Introduce AltsContext to allow outside packages access to ALTS peer information

Bug Fixes

• core: Fixed a bug where RPCs queued waiting for a connection can use user-provided executors after the ManagedChannel is terminated (#6283)
• core: Fixed a bug where RPCs queued waiting on CallCredentials can use user-provided executors after the ManagedChannel is terminated (#7813)

Documentation

• api: add nullable annotation to Status.trailersFromThrowable (#7856). The annotation doesn’t change behavior, it just makes the behavior more clear

Dependencies

• alts: Remove dependency on Apache Commons Lang

Acknowledgements

@elharo Elliotte Rusty Harold
@lriuui0x0 Rui Liu
@martin-schaub Martin Schaub
@njhill Nick Hill
@ReginFell Serhii Zabelnykov

v1.35.0

Bug Fixes

• core: Fix CompositeChannelCredentials to no longer use CallCredentials for OOB channels. OOB channels are available for load balancing policies to use to communicate with an LB server. It is mainly used by gRPC-LB. This resolves the incompatibility of the 1.34.0 release with googleapis.com.
• alts: Limit number of concurrent handshakes to 32. ALTS uses blocking RPCs for handshakes. If the handshake server has a limit to number of concurrent handshakes this can produce a deadlock. Limiting to 32 should workaround the problem for the majority of the cases. A later fix will allow handshake RPCs to be asynchronous
• xds: Fix missed class relocations for generated code. grpc-xds previously exposed generated code for multiple 3rd-party protobuf generated code classes outside of the io.grpc package. They are now shaded to avoid colliding with other users of the classes
• xds: Fix a user visible stack trace showing java.util.NoSuchElementException when the environment variable GRPC_XDS_EXPERIMENTAL_SECURITY_SUPPORT was set and the application contains an xDS configured gRPC server. The exception was benign and was seen when the connection was dropped before an SslContextProvider was available.
• xds: Decouple xds channel creation and bootstrapping. This fixes the bug caused by the lifecycle mismatch between XdsClient and its channel to the xDS server. Creating a new XdsClient (previous one shutdown due to no Channel using it) would create and use a new xDS channel.
• xds: Fix races between creating subchannls and Channel shutdown caused by delaying address/config propagation between LB policies. An exception will be thrown if Channel's shutdown() has been called and receiving an EDS update while the Channel has not completely shutdown.

Dependencies

• Guava updated to 30.0-android
• Animal Sniffer annotations updated to 1.19
• Error Prone annotations updated to 2.4.0
• Perfmark updated to 0.23.0
• compiler: Linux artifacts now built using CentOS 7. Previously CentOS 6 was used, but that distribution is discontinued and no longer available in our build infrastructure
• netty: Upgrade to Netty 4.1.52 and tcnative 2.0.34. Note that this Netty release enables TLSv1.3 support. mTLS failures with TLSv1.3 will have different error messages than in TLSv1.2
• auth,alts: google-auth-library-java updated to 0.22.2
• census: OpenCensus updated to 0.28.0
• protobuf: googleapi’s common protos updated to 2.0.1
• okhttp: Okio updated to 1.17.5
• xds: re2j updated to 1.5
• xds: bouncycastle updated to 1.67
• gradle: bumped protobuf-gradle-plugin version to 0.8.14
• android, cronet: upgraded the latest support Android version to 29

Acknowledgments

@amnox
@horizonzy
@wanyingd1996

v1.34.1

Bug Fixes

• core: Fix CompositeChannelCredentials to no longer use CallCredentials for OOB channels. OOB channels are available for load balancing policies to use to communicate with an LB server. It is mainly used by gRPC-LB. This resolves the incompatibility of the 1.34.0 release with googleapis.com.
• alts: Limit number of concurrent handshakes to 32. ALTS uses blocking RPCs for handshakes. If the handshake server has a limit to number of concurrent handshakes this can produce a deadlock. Limiting to 32 should workaround the problem for the majority of the cases. A later fix will allow handshake RPCs to be asynchronous
• xds: Relocate (shade) all generated code; a few classes had previously been missed
• xds: Fixed an issue when GRPC_XDS_EXPERIMENTAL_NEW_SERVER_API=true where gRPC would request non-existent resources