A module adding support for gRPC over HTTP2.

This module provides helpers to encode gRPC queries on top of HTTP2 client.

The helpers we provide for streaming RPCs (streamReply, streamRequest, steppedBiDiStream) are a subset of what gRPC allows: the gRPC definition of streaming RPCs offers a large amount of valid behaviors regarding timing of headers, trailers, and end of streams.

The limitations of these functions should be clear from the type signatures. But in general, the design is to only allow synchronous state machines. Such state-machines cannot immediately react to server-sent messages but must wait for the client code to poll for some server-sent information. In short, these handlers prevents programs from observing intermediary steps which may be valid applications by gRPC standards. Simply put, it is not possibly to simultaneously wait for some information from the server and send some information. For instance, in a client-streaming RPC, the server is allowed to send trailers at any time, even before receiving any input message. The streamRequest functions disallows reading trailers until the client code is done sending requests. A result from this design choice is to offer a simple programming surface for the most common use cases. Further, these simple state-machines require little runtime overhead.

A more general handler generalHandler is provided which runs two thread in parallel. This handler allows to send an receive messages concurrently using one loop each, which allows to circumvent the limitations of the above handlers (but at a cost: complexity and threading overhead). It also means that a sending action may be stuck indefinitely on flow-control and cannot be cancelled without killing the RPC thread. You see where we are going: the more elaborate the semantics, the more a programmer has to think.

Though, all hope of expressing wacky application semantics is not lost: it is always possible to write its own RPC function. Writing one's own RPC function allows to leverage the specific semantics of the RPC call to save some overhead (much like the three above streaming helpers assume a simple behavior from the server). Hence, it is generally a good idea to take inspiration from the existing RPC functions and learn how to write one.