This version fixes a serious issue in previous releases when using streaming RPCs (full-duplex bidirectional RPCs in particular). In previous versions, certain streaming usage patterns, including inadvertent misuse of the stream stub in an RPC client, could result in deadlock -- such that all RPCs over a tunnel effectively hang indefinitely.
This version introduces flow control to prevent that category of deadlock. This is a change to the tunneling protocol, but one that is backwards-compatible. When a newer peer (client or server) is connected to an older one (that does not support flow control), flow control will be skipped and the tunnel will operate as in previous versions. But when both peers are newer and support flow control, it will be used, and stream-heavy use of the tunnel should be safe and free from deadlocks.
Currently, flow control window sizes, the frequency of window updates, and the maximum "chunk" size (when a single message must be broken up for flow control or for multiplexing fairness reasons) are hard-coded. Future versions will likely allow customizing all three of these, which could improve throughput in some environments.
Note that future releases may drop support for peers that do not support flow control. So users are recommended to upgrade to this v0.3.0 as soon as possible (though users of v0.1.0 should first upgrade to v0.2.0; see more below).
Compatibility
NOTE: This release is NOT fully compatible with all previous releases. In particular, you should upgrade all clients and servers to v0.2.0 before trying to upgrade to this release. This release inter-operates with v0.2.0, but may not inter-operate with v0.1.0.
In particular, forward tunnel clients that are v0.3.0 (or later) will hang indefinitely if trying to create a tunnel using a server that is v0.1.0. Other combinations, including the use of reverse tunnels or the use of v0.1.0 clients with v0.3.0 servers, should work fine. However, it is still recommended to upgrade everything from v0.1.0 to v0.2.0 before trying to use this new release.
API Changes
In addition to the compatibility issues when combined with v0.1.0 described above, this release also includes a minor backwards-incompatible API change. The NewChannel function has a changed signature. This was necessary for two reasons: (1) to provide compatibility/interop with v0.2.0 via letting this package control the request headers that are sent in OpenTunnel RPCs, and (2) to provide support for adding variadic options in future iterations of this API.
The change is not significant and should be fairly easy to apply to existing codebases. The change you will need to make will resemble the following change:
tunnelStub := tunnelpb.NewTunnelServiceClient(cc)
- stream, err := tunnelStub.OpenTunnel(ctx, callOptions...)
+ ch, err := grpctunnel.NewChannel(tunnelStub).Start(ctx, callOptions...)
if err != nil {
return err
}
- ch := grpctunnel.NewChannel(stream)Also note that this module has not yet reached v1.0, so the API is still considered unstable, and there may be more backwards-incompatible API changes made in the future. Please check the release notes to learn about potentially incompatible changes and how to modify your code to upgrade to the new release.