v0.3.0

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.

v0.2.0

This release fixes concurrency bugs that were present in v0.1.0. It is highly recommended for anyone using this module to upgrade to this version ASAP.

In v0.1.0, it was possible to observe deadlocks or spurious failures of the form "cannot create stream ID XX: that ID has already been used". These were caused by multiple goroutines using the same tunnel, due to incorrect synchronization when interacting with the underlying gRPC stream.

This release also prepares for an upcoming v0.3.0. In both v0.1.0 and in this release, certain usage patterns of streaming RPCs can cause deadlocks, where all operations on a tunnel are effectively frozen. This is due to the way backpressure works on the gRPC stream underlying a tunnel combined with head-of-line blocking that happens when multiple RPCs are multiplexed over a single gRPC stream. This will be fixed in v0.3.0 via the introduction of flow control for RPCs sent over the tunnel. However, in order for this fix to correctly inter-operate with previous versions (that do not implement flow control), a very slight change is required in the server implementation. That change is present in this v0.2.0 release.

NOTE: The above means that users of this library must upgrade all clients and servers to this v0.2.0 version before they can safely upgrade to future versions to be released after this one.

v0.1.0

Initial Release

This is the first release for this module. It is not yet v0.1.0 since some APIs may need more iteration before "sealing" them with a v1.0. But the tests are reasonably thorough and the documentation hopefully is, too.

---

Note

This release has a bug that prevents direct upgrades to version v0.3.0 or later. Anyone using this release should update all tunnel clients and servers to v0.2.0 as soon as possible. After that, it will subsequently be safe to update to v0.3.0 or later versions.