*** HTTP/2 frame processing overview ***
The HTTP/2 inspector (H2I) converts HTTP/2 frames into HTTP/1.1 message sections and feeds them
to the new HTTP inspector (NHI) for further processing.

The Http2StreamSplitter splits HTTP/2 traffic on frame boundaries with two exceptions. First, any
Continuation frames following a Headers frame are aggregated and sent through detection as a single
header block. Second, long Data frames are split into 16kb chunks for inspection as message bodies
are in NHI. The Http2StreamSplitter strips the frame headers from the frame data and stores them in
separate buffers. In the case of a Headers frame followed by Continuation frames, the Headers frame
header is stored and the Continuation frame headers are discarded.

*** HTTP/2 Frame Classes ***
HTTP/2 frames are stored in frame objects for processing.
1. Http2Frame - top level class
2. Http2HeadersFrame : Http2Frame - common elements of frames containing headers
3. Htt2HeadersFrameWithStartline : Http2HeadersFrame - common elements of headers with start lines
4. Http2HeadersFrameHeader : Htt2HeadersFrameWithStartline - regular request/response headers
5. Http2PushPromiseFrame : Htt2HeadersFrameWithStartline - server push headers
6. Http2HeadersFrameTrailer : Http2HeadersFrame - headers frame containing trailers
7. Http2DataFrame : Http2Frame
8. Http2SettingsFrame : Http2Frame
9. Http2RstStreamFrame : Http2Frame
10. Http2WindowUpdateFrame: Http2Frame
11. Http2PriorityFrame: Http2Frame
12. Http2GoAwayFrame: Http2Frame

Http2Frame virtual methods:
1. bool valid_sequence(Http2Enums::StreamState state) - Returns if the current frame has been sent
   on a valid stream in a valid state for the frame.
2. void analyze_http1() - Contains the interface with http_inspect if necessary for the frame type
3. void clear() - Cleanup after processing is complete
4. const Field& get_buf(unsigned id) - Returns any buffers associated with this frame type
5. void update_stream_state() - Updates the state of the current stream based on the contents of 
   the current packet.
6. bool is_detection_required() - Returns if the data in this frame be sent through the detection
   engine.

*** HTTP/2 Stream States ***
Http2 stream states are directional and take the form {<C2S state>, <S2C state>}. States can have
the following values:
1. STREAM_EXPECT_HEADERS - No frames have yet been seen on this stream in this direction. A stream
   with state {STREAM_EXPECT_HEADERS, STREAM_EXPECT_HEADERS} is what the HTTP/2 RFC refers to as
   "idle."
2. STREAM_EXPECT_BODY - Headers are complete and we are expecting to see a Data frame
3. STREAM_BODY - There has been at least one Data frame in this direction already, but we have not
   yet seen the END_STREAM flag so are still expecting more Data or Headers frames.
4. STREAM_COMPLETE - The END_STREAM flag has been seen. No more Data or Headers frames are
   expected.
5. STREAM_ERROR - An error has occurred processing this stream. This is a terminal stream state.
   Further frames on this stream in this direction may be checked for proper formatting, but will
   not impact the stream state or interact with http_inspect. For information on error processing
   see the section below.

*** HTTP/2 Header Decoding ***
HTTP/2 headers frames can come at the start of a stream and contain the header block, or at the end
of a stream and contain trailers. H2I contains headers frame subclasses Http2HeadersFrameHeader and
Http2HeadersFrameTrailer to support these two types of headers frames. Http2PushPromise frames begin
server pushed streams and also contain the header block. Headers frames containing the header block
will contain pseudo-headers that must be converted into an HTTP/1.1 start line in addition to
regular HTTP/1.1 headers. The two Http2StartLine subclasses, Http2RequestLine and Http2ResponseLine
perform this translation and generate the start-line, which is stored in a new buffer inside the
Http2StartLine object. Trailers may only contain regular headers.

Both headers and trailers must undergo HPACK decoding before being sent to NHI for processing. To
perform decoding, reassemble() makes a first copy of the encoded headers, which is stored in the
frame_data buffer. The frame_data buffer is passed to the function decode_headers(), which is the
main loop driving HPACK decoding. Each decoded header line is progressively written to a second
decoded_headers buffer that will ultimately be sent to NHI.

The main loop in decode_headers() finds the cut point for a single header line. The line is
passed to decode_header_line(), which parses the line and calls the appropriate decoding function
based on the header representation type. If the type is indexed, the full header line is looked up
in the table and copied to the decoded header buffer. The index may belong to either the static or
the dynamic table. The static table is 61-elements defined in the HPACK RFC. The dynamic table,
which starts at index 62, is specific to each direction of each flow. For the second type, literal
to be indexed, the header name may be indexed or a string literal, while the value is always a
literal. The resulting header line is then added to the dynamic table. The third representation type
is literal not to be indexed, which is the same as literal to be indexed, except the header line is
not added to the dynamic table.

*** Error Processing ***
H2I has two levels of failure for flow processing. Fatal errors include failures in frame splitting
and errors in header decoding that compromise the HPACK dictionary. A fatal error will trigger an
immediate EVENT_MISFORMATTED_HTTP2 and will cause scan() to return ABORT the next time it is called
in the same direction.

Stream errors affect HTTP/1 processing within a stream. They include errors in frame sequence
within a stream, errors that cause the HI stream splitter to abort, and errors that cause HI to be
unable to process a frame. The individual stream will transition to STREAM_ERROR state and HI
processing of that stream in that direction will end.

H2I supports the NHI test tool. See ../http_inspect/dev_notes.txt for usage instructions.

*** Memory requirements ***
Http2FlowData represents all H2I information in a flow. It does not account 
for the entries in the hpack dynamic table. The formula below estimates the size of an entry 
in the dynamic table:
name.length() + value.length() + RFC_ENTRY_OVERHEAD (32 as defined by the RFC)

Using the formula and some sample pcaps, the average size of the dynamic table is 1645 bytes.
Dynamically allocated objects related to http_inspect are considered separate and are not 
included. Temporary objects (frame_data and frame_header) are ignored. The remaining dynamically
allocated are Http2Infractions (8 bytes * 2) and Http2EventsGen(24 bytes * 2)
Therefore, the memory required by http2 per flow: sizeof(Http2FlowData) + 1645 + 16 + 48 

*** HTTP/2 Block Page Injection ***
During server-to-client scan(), H2I determines whether block page injection is structurally
possible for the current packet and sets PKT_HTTP_INJECT_BLOCKED or PKT_HTTP_INJECT_ALLOWED on the
packet flags. The injection status is tracked per stream in a thread-local cache that is reset at
the start of each scan call when no injection permission has been set yet (i.e., the first time
scan() is called for this packet). A global_injection_block flag short-circuits further checks
once the scan enters a state where injection is structurally impossible.

PKT_HTTP_INJECT_BLOCKED is set in the following cases:

Per-stream injection status (set via update_injection_status). Only the first frame for
each stream ID in a packet is checked:
1. Too many streams tracked - the per-thread injection status cache has reached
   MAX_STREAM_INJECTION_STATUS entries. Further streams are blocked to cap resource usage.
   This is a sanity check; usually one packet will have only 1-3 different HTTP/2 streams.
2. Frame type is not HEADERS - injection is only allowed when the server-to-client frame for the
   stream is a HEADERS frame. Data, settings, window update, and other frame types block injection
   because the client won't be able to interpret the block page.
3. Server stream state is not STREAM_EXPECT_HEADERS - even if the frame is HEADERS, the server
   direction of the stream must be expecting headers (i.e., no prior server frames on this stream).
   If the server has already sent headers or data (e.g., when processing trailers), injection is
   blocked.
4. Stream not found and no matching client stream - if the stream object does not exist and there
   is no unflushed client data for this stream ID, injection is blocked.

Structural injection block (global_injection_block is set to true, skipping all further
per-stream checks for the remainder of the scan call):

5. Packet starts with trailing frame padding - the scan is discarding padding that trails a
   previous frame.
6. Packet starts with padding length byte - the scan is reading the padding length field of a
   padded frame.
7. Packet starts with data frame body - the scan is processing frame data

Cases 5-7 all indicate that the server-to-client flow is in the middle of a frame, making
injection structurally impossible.
