Skip to content

Latest commit

 

History

History
108 lines (89 loc) · 6.42 KB

README.md

File metadata and controls

108 lines (89 loc) · 6.42 KB
Raw

HTTP/2 Handler

Included in this folder is a complete ThousandIsland.Handler based implementation of HTTP/2 as defined in RFC 9110 & RFC 9113

Process model

Within a Bandit server, an HTTP/2 connection is modeled as a set of processes:

  • 1 process per connection, a Bandit.HTTP2.Handler module implementing the ThousandIsland.Handler behaviour, and;
  • 1 process per stream (i.e.: per HTTP request) within the connection, implemented as a Bandit.HTTP2.StreamProcess process

Each of these processes model the majority of their state via a Bandit.HTTP2.Connection & Bandit.HTTP2.Stream struct, respectively.

The lifetimes of these processes correspond to their role; a connection process lives for as long as a client is connected, and a stream process lives only as long as is required to process a single stream request within a connection.

Connection processes are the 'root' of each connection's process group, and are supervised by Thousand Island in the same manner that ThousandIsland.Handler processes are usually supervised (see the project README for details).

Stream processes are not supervised by design. The connection process starts new stream processes as required, via a standard start_link call, and manages the termination of the resultant linked stream processes by handling {:EXIT,...} messages as described in the Elixir documentation. Each stream process stays alive long enough to fully model an HTTP/2 stream, beginning its life in the :init state and ending it in the :closed state (or else by a stream or connection error being raised). This approach is aligned with the realities of the HTTP/2 model, insofar as if a connection process terminates there is no reason to keep its constituent stream processes around, and if a stream process dies the connection should be able to handle this without itself terminating. It also means that our process model is very lightweight - there is no extra supervision overhead present because no such supervision is required for the system to function in the desired way.

Reading client data

The overall structure of the implementation is managed by the Bandit.HTTP2.Handler module, and looks like the following:

  1. Bytes are asynchronously received from ThousandIsland via the Bandit.HTTP2.Handler.handle_data/3 function
  2. Frames are parsed from these bytes by calling the Bandit.HTTP2.Frame.deserialize/2 function. If successful, the parsed frame(s) are returned. We retain any unparsed bytes in a buffer in order to attempt parsing them upon receipt of subsequent data from the client
  3. Parsed frames are passed into the Bandit.HTTP2.Connection module along with a struct of same module. Frames are processed via the Bandit.HTTP2.Connection.handle_frame/3 function. Connection-level frames are handled within the Bandit.HTTP2.Connection struct, and stream-level frames are passed along to the corresponding stream process, which is wholly responsible for managing all aspects of a stream's state (which is tracked via the Bandit.HTTP2.Stream struct). The one exception to this is the handling of frames sent to streams which have already been closed (and whose corresponding processes have thus terminated). Any such frames are discarded without effect.
  4. This process is repeated every time we receive data from the client until the Bandit.HTTP2.Connection module indicates that the connection should be closed, either normally or due to error. Note that frame deserialization may end up returning a connection error if the parsed frames fail specific criteria (generally, the frame parsing modules are responsible for identifying errors as described in section 6 of RFC 9113). In these cases, the failure is passed through to the connection module for processing in order to coordinate an orderly shutdown or client notification as appropriate

Processing requests

The state of a particular stream are contained within a Bandit.HTTP2.Stream struct, maintained within a Bandit.HTTP2.StreamProcess process. As part of the stream's lifecycle, the server's configured Plug is called, with an instance of the Bandit.Adapter struct being used to interface with the Plug. There is a separation of concerns between the aspect of HTTP semantics managed by Bandit.Adapter (roughly, those concerns laid out in RFC9110) and the more transport-specific HTTP/2 concerns managed by Bandit.HTTP2.Stream (roughly the concerns specified in RFC9113).

Testing

All of this is exhaustively tested. Tests are broken up primarily into protocol_test.exs, which is concerned with aspects of the implementation relating to protocol conformance and client-facing concerns, while plug_test.exs is concerned with aspects of the implementation having to do with the Plug API and application-facing concerns. There are also more unit-style tests covering frame serialization and deserialization.

In addition, the h2spec conformance suite is run via a System wrapper & executes the entirety of the suite (in strict mode) against a running Bandit server.

Limitations and Assumptions

Some limitations and assumptions of this implementation:

  • This handler assumes that the HTTP/2 connection preface has already been consumed from the client. The Bandit.InitialHandler module uses this preface to discriminate between various HTTP versions when determining which handler to use
  • Priority frames are parsed and validated, but do not induce any action on the part of the server. There is no priority assigned to respective streams in terms of processing; all streams are run in parallel as soon as they arrive
  • While flow control is completely implemented here, the specific values used for upload flow control (that is, the end that we control) are fixed. Specifically, we attempt to maintain fairly large windows in order to not restrict client uploads (we 'slow-start' window changes upon receipt of first byte, mostly to retain parity between connection and stream window management since connection windows cannot be changed via settings). The majority of flow control logic has been encapsulated in the Bandit.HTTP2.FlowControl module should future refinement be required