1.1.1 Release

I am pleased to announce availability of gRPC Java 1.1.1, the next minor release of gRPC. This includes several months of changes made since 1.0.3. There are many bug fixes, API improvements, and performance changes in this release.

Major Changes

• Preview of New Load Balancer API The previous API for implementing a new load balancer had several structural issues (#1600 #2209 #2301 #2302) that made it difficult to assign load intelligently to backends. The V2 API is available for trial use in this release. The classes are suffixed with a "2". They will be renamed in the next release of gRPC, and the the current implementations will be removed. Note that these APIs are still considered experimental and not guaranteed to be stable yet. See the notice.
• Server Reflection It is now possible to enable server side reflection when using Protobuf generated stubs. This allows remote clients to inquire as to which supported services and methods the server can process. It is currently opt in, by adding ProtoReflectionService to an existing server.
• New Context Artifact Context, the means by which deadlines and cancellation are propagated across API boundaries is now in its own package in grpc-context. It can (and will) be used for implementing cross RPC state, such as for stats and tracing.
• Wait For Ready Also known as "fail fast", wait for ready has been implemented as an option in gRPC stubs. This can be used to indicate that an RPC should fail immediately if there are no healthy servers available.
• Proxy Support It is now possible to use basic HTTP CONNECT style proxy support (23f5a6f)
• _Service_ImplBase.bindService() is now final. The grpc-io mailing list was notified of our intentions and reasoning. This is a breaking change but is not expected to impact production code. If a test breaks, typically you can just remove the line resembling Mockito.when(service.bindService()).thenCallRealMethod();. If this change causes you pain, please file an issue and we may revisit it.

Minor Changes

• Many classes have been made final. These classes were previously uninstantiable due to having private constructors, but were possible to use with a mocking framework (such as Mockito). These classes have been made final, and special testing utility classes have been provided for use instead.
• The generated stub classes have several new methods for indicating max message size.
• Stub classes also lazily load classes whenever possible. If a stub is generated from a very large proto file, or has many dependencies, this avoids loading them all when possible.
• Many more examples have been added and clarified. See the examples/ directory.
• Multiple performance optimizations. gRPC is now more memory efficient, less lock contentious, and less CPU overhead. (24de243, 35c3f81, ca5a402, f78644d, 6d28a93, ea3f506, 8c18a0d, 8b745d9, 6907d81, 1623063, 141eed5, ef4e0f4, 8702185, 496a621, cb1ba5b)
• Guava collection classes are removed from the library, making it easier for Android users to lower their method count and binary size.
• Dependencies are upgraded to Guava 20, Netty 4.1.8, and Protobuf 3.1.0
• Status error messages have been made more clear, and should be easier to diagnose.
• Numerous small bug fixes
• Numerous small API changes.

Note that all classes marked @ExperimentalApi and @Internal aren't guaranteed to be API stable, and may be changed without notice. Classes and methods marked @Deprecated should be avoided and may be removed in a later release. Of note is ClientAuthInterceptor, which should be avoided in favor of MoreCallCredentials.

v1.0.3 Release

The v1.0.3 release has a small bugfix and experimental support for forward proxies. Only users of InProcess transport in tests or users wanting to test the forward proxy support benefit from the update.

• Remove a usage of an executor which was just to avoid lock ordering issues. Now the work is done on the same thread, but after locks are released. This fixes non-determinism when "connecting" with the InProcess transport (#2444)
• Add experimental support for http forward proxies via CONNECT to both Netty and OkHttp transports. Proxy authentication is unsupported. To enable, use the GRPC_PROXY_EXP environment variable and set to a host:port-formatted string. Error handling is known to be weak when negotiating with the proxy; most proxy failures will result in a generic error. Errors after negotiation completes are unaffected.

v1.0.2 Release

The v1.0.2 release is a bug fix release with no new features. The following specific fixes were backported from the master branch:

• Make the OkHTTP transport AppEngine friendly f52b4e5
• core: Fix a bug for exception handling at messageRead abb4a2a
• netty: Upgrade to 4.1.6 and tcnative Fork23 6fa63a6
• core: Update HTTP status to gRPC status mapping 78107a6
• core: fix bug when stream listener not set before stream closed 0e27eef
• core,netty: quick patch for setListener regression 0d694c8

v1.0.1 Release

• Moved io.grpc.Context and io.grpc.Deadline from grpc-core to its own artifact, grpc-context. This is to allow wider usage of the API and avoid circular dependencies. grpc-core depends on the new artifact. (#2226)
• Avoid creating unnecessary threads in InProcess transport, which improves performance for short-lived channels and prevents non-determinism when using direct executor in tests. (#2108)
• Fix bug where Errors could end up being wrapped in RuntimeException (#2131)
• Fix a deadlock in TransportSet (#2258)

v1.0.0 Release

APIs and codegen are guaranteed stable, excluding APIs marked with @ExperimentalApi or @Internal, APIs within an internal package, and utilities like grpc-benchmarks and grpc-interop-testing. APIs marked @Deprecated in this release are not covered. Mocking frameworks purposefully break API assumptions, so we can't guarantee stability with them.

Changes since v1.0.0-pre2

• Fix a deadlock when scheduling connection reestablishment backoff
• Benchmarks: Swap to ForkJoinPool, as the executor is the bottleneck for high CPU (16+ core), high QPS benchmarks. On smaller workloads using normal ThreadPoolExecutor is faster
• Android: New "route guide" example
• Android: helloworld example now prints full stacktrace on failure, which easies debugging
• Android: encourage using new protobuf-gradle-plugin v0.8.0 to slightly simplify protobuf-lite usage
• Minor documentation tweaks

v1.0.0-pre2 Release

Changes

• Update protobuf to v3.0.0
• grpc-protobuf-lite now depends on protobuf-lite. Since grpc-protobuf depends on grpc-protobuf-lite, grpc-protobuf explicitly excludes the protobuf-lite dependency and adds its own protobuf dependency. Everything should "just work" for most varieties of protobuf users, as both Maven and Gradle handle the dependencies correctly.
• Update README to every-so-slightly encourage lite instead of nano. We generally prefer lite as it is a more similar API to full protobuf, and it is the most actively maintained
• Fix a blocking unary stub bug introduced in v1.0.0-pre1 that wrapped the status in an additional status
• Minor fixes

v1.0.0-pre1 Release

API Changes

• Generated interfaces and methods that were deprecated in v0.15.0 are now removed. To ease migration, the grpc protoc plugin supports the option enable_deprecated=true which will re-enable the old generated APIs. This option will be removed in a later release.
  • Mocking stubs is no longer supported. Most tests should use the inprocess transport, which is fast and lightweight, especially when using directExecutor() for both the client and server. Some tests may need to use a ClientInterceptor to verify the CallOptions. We plan to improve convenience utilities over time; please file a bug for testing issues or suggested utilities.
• Reduced default max message size from 100 MiB to 4 MiB. ManagedChannelBuilder.maxMessageSize() and ServerBuilder.maxMessageSize() can override the default. Larger sizes are not a problem for grpc, but applications should be aware when they may receive large messages.

New Notables

• Update Netty to 4.1.3.Final. This resolves a flow-control accounting, off-by-one bug when interoperating with HTTP/2 implementations that use padding (netty/netty#5434). The off-by-one accumulates over time, which could eventually hang a long-lived TCP connection. gRPC implementations do not use padding today, nor do most HTTP/2 proxies. Google's GFE does use padding which impacts all Google-hosted APIs, but requires receiving GBs per connection before triggering a hang.
• Channel can now enter IDLE after a period of no RPCs, which can be enabled via ManagedChannelBuilder.idleTimeout(). IDLE disconnects the TCP connection and shuts down the name resolver and load balancer. This is generally useful for reducing resources, but can also be used on Android to avoid broken TCP connections on bad networks and "avoid" timeouts of NATs and load balancers.
• Keepalive support for OkHttp, which can be enabled via OkHttpChannelBuilder.enableKeepAlive(). Keepalive uses HTTP/2 PINGs while RPCs are in progress to monitor the TCP connection and signal activity to NATs and load balancers. Keepalive does nothing if no RPCs are in progress, thus is primarily useful when for long-lived streaming RPCs. This implementation preempts the design of keepalive being finalized, but was important enough for mobile networks to have something available sooner. This can be used on Android to detect broken TCP connections on bad networks and reset timeouts of NATs and load balancers.
• Revamped compilation of examples. Examples are now divorced from the rest of grpc-java's build process. Maven can now be used to build the examples, and the Gradle build file is simplified. Both builds are intended to be copyable for your own project.

Other

• Hard-code providers list for Android, moving away from ServiceLoader on the platform. If your application never calls Class.getResource(), this will reduce memory on some Android versions and speed construction of your first ManagedChannel. This also simplifies the necessary ProGuard configuration. General-purpose 3rd-party providers for NameResolver and ManagedChannel that may be used on Android should request to be added to the hard-coded list.
• ClientCall.cancel(String, Throwable) is now a required method and will log a warning when called with neither a message nor cause. This completes the migration from ClientCall.cancel(void) which was very difficult to debug where cancel was called.
• Bug fix: StatusRuntimeExceptions for blocking unary calls should now include trailers.
• Miscellaneous fixes.

v0.15.0 Release

Major Changes

• significant performance improvements around header processing
• generated AbstractService class and interfaces are now deprecated in favor of ServiceImplBase
• made Context is no longer experimental (#1705)

Generated Code / Stub

• static bindService() method is deprecated
• added ClientResponseObsever to interact with advanced features like flow-control

Core

• improved error messages when unable to find a name resolver
• fix onReady race by adding DelayedStreamListener
• added a RoundRobin Loadbalancer
• clarified and extended core documentation (#1479, #714, #986, #1962, #1805)
• fix race with exception in onMessage and onCompleted (#1652)
• made ServiceDescriptor final, and now accepts a collection of methods.
• made ServerInterceptor, BindableService, ServerCallHandler non experimental (#1711, #1701)
• promoted Deadline API no longer be experimental
• added a NameResolverProvider
• remove deprecated ClientCall.cancel overload
• new client calls no longer get their a new context (fixes a stack overflow, #1926)
• made CallOptions accept custom values
• enable per-message compression by default, if a compression method is set.
• added a fail-fast feature, which makes new RPCs fail if there are no connections
• added CallOptions.waitForReady to support fail-fast
• log exceptions from scheduled tasks (#1759)
• implemented ManagedChannel.shutdownNow (#448)
• made URI parsing for targets more robust (#1883)
• increased visibility of Code.status() and Status.fromCode (#1722)
• methodDescriptor argument moved from ServerInterceptor to ServerCall
• added a health checking service (not on by default) (#647)
• server call exception is saved when a message fails to close
• status exceptions can now hold additional metadata
• allow ClientCall.cancel before start. Fixes #1536
• split HandlerRegistry into an immutable default and a fallback for dynamic dispatch
• made Context.fork return a normal Context instead of CancellableContext (1626)
• reduced memory usage when cancelling calls by using the right executor

Examples

• stopped using deprecated generated classes
• added examples to show how to get error information from different stubs
• switch android example to use proto lite instead of nano proto
• moved json encoding examples to the "advanced" package (#1778)

Auth

• added a CallCredentials class for propagating credentials
• promote OAuth2 service accounts to JWT (#785)
• add MoreCallCredentials.from(Credentials) to work with the Google Auth Library
• made ClientAuthInterceptor deprecated

Netty

• fixed a bug when headers could get corrupted during decoding
• use boringssl uberjar
• detect when ALPN was not used. (#522)
• add tests for Netty bug where a channel would break after a RST_STREAM frame (#1682)
• added Trailiers to the Status for BlockingResponseStream (#1861)
• call transportShutdown immediately on ID exhaustion (#1819)

Protobuf

• bump dependency to 3.0.0-beta-3

OkHttp

• fix NPE when using CLEARTEXT connectionSpec (#1815)

Other

• deflake lots of tests based on finding an empty port
• disable flaky test in ClientCallsTest
• improve ClientCall test to fail more obviously
• add test for MessageDeframer closed exception (#1795)
• benchmark transport flag now works in AsyncClient
• always set message encoding in headers, even for the "identy" encoding.
• updated error codes returned to match the specification (#1605)
• added a log message for unknown client streams
• added more detail when recieving GOAWAY
• cause removed from InProcessTransport (#1716)
• setRemoveOnCancelPolicy

v0.14.1 Release

• Update Netty to v4.1.1.Final, which is the first stable release we've released with. gRPC-java v0.14.0 was already compatible with Netty v4.1.1. This fixes cancellation causing Channel to black hole received data and fixes a DoS bug in renegotiation when using OpenSSL-based tcnative (BoringSSL not impacted).
• The Netty version bump also supports the "fat" tcnative-boringssl-static JAR that has binaries for all platforms. Simply depend on 1.1.33.Fork17 without any OS-specific classifier
• Reworked shutdown handling for OkHttp. Fixes "IllegalStateException: Listener is still attached to activeTransport. Seems transportTerminated was not called."

v0.14.0 Release

New Features:

• It is now possible to use JSON-encoded protobufs.
• ClientCall can now be passed in cancellation details.
• Both Client and Server interceptors can now work in reverse order. See interceptForward().
• Stubs can now parse messages using an ExtensionRegistry.
• Server now has a getPort() method.
• Generated code now includes the version it was built at.
• Added more info for call cancellation.
  • It is now possible to tell if a call was cancelled client side vs. server side.
• CallOptions now uses Attributes for affinity routing.
• Added CallStreamObserver and ServerCallStreamObserver as specialized Stub observers.
• CallOptions and stubs now uses Deadline instead of a long of nanoseconds.

Major bugs fixed:

• Fixed a memory leak involving TransportSets.
• Netty based transports now shutdown upon GOAWAY.
• DNS Resolution is retried on error.

Other Changes:

• The grpc-all release artifact no longer repackages source and classes from other grpc artifacts, and instead depends on them
• Statuses and their exceptions now have a lot more detail about where they came from.
• Split Protobuf into Protobuf-lite specific parts.
• Status messages now use a URL encoding for messages.
  • It is now possible to send newlines as well as non-ASCII charcacters in Status messages.
• Stubs now use an an abstract base class, which allows for easier stub binding.