wireshark/doc/http3.md

# Supported features
The HTTP3 dissector is a work in progress.

At the moment, the following aspects of HTTP3 are supported:
- Diseciton of different HTTP3 stream types
- Dissection of different HTTP3 frame types
- Dissection of HTTP header fields
- Dissection of QPACK instructions

In addition, the dissector suports decoding of the HTTP3
header fields. This ability requires `nghttp3` third-party library.

## High-level overview
The HTTP3 dissector is invoked by the QUIC dissector.

The essential call tree:
-  `dissect_http3`
   Main entry point. Depending on the stream type, invokes one of the following:
   -  `dissect_http3_uni_stream`
      Processes unidirectional streams, including the control streams,
      the QPACK encoder/decoder streams, and the HTTP3 server push streams.
      NOTE: the HTTP3 server push streams support is rudimental.
      -  `dissect_http3_qpack_enc`
         Dissects the QPACK encoder stream.
         If Wireshark was built with the optional `nghttp3` library,
         this function is also responsible on updating the state
         of the QPACK decoder.
   -  `dissect_http3_frame`
      Processed HTTP3 frames from the client-initiated bidirectional stream.
      Determines the frame type, and dispatches the call to one of the
      sub-dissectors:
      -  `dissect_http3_data`
         Dissects the `HTTP3_DATA` frames.
      -  `dissect_http3_headers`
         Dissects the `HTTP3_HEADER` frames.
         If Wireshark was built with the optional `nghttp3` library,
         this function attempts to decode the header fields, using
         the QPACK decoder.
      -  `dissect_http3_settings`
         Dissects the `HTTP3_SETTINGS` frames.

### Overview of the HTTP3 header dissection
The QPACK implementation from `nghttp3` requires a separate QPACK decoder instance
for every HTTP3 connection. The different HTTP3 streams that constitute a single
HTTP3 conneciton are sharing the same QPACK decoder instance.

The HTTP3 dissector interacts with the QPACK decoder in 2 ways:
-  On the reception of QPACK encoder data (which is delivered on a dedicated unidirectional stream),
   the dissector updates the connection's decoder instance.
-  On the reception of compressed HTTP3 headers, the dissector uses the connection's decoder
   to uncompress the HTTP headers.

If decompression succeeds, the dissector adds tree items to the packet tree. Otherwise,
the dissector adds expert info items.

The decompression can fail due to several reasons:
-  If the instruction count required by the compressed HTTP3 headers
   exceeds the maximal instruction count that the QPACK decoder is aware of,
   the decoding becomes "blocked". This situation can occure when the QUIC packets
   that carry the QPACK encoder instructions are dropped/reordered.
-  If the state of the decoder becomes invalid, which may happen when a "garbage"
   data is received on the QUIC stream.
-  Lastly, the decoding can fail if the underlying QUIC desegmentation is
   not working correctly.

### Overview of HTTP3 data frames dissection
The higher-level dissectors that could use HTTP3 (e.g. WebTransport) need to be able
to access the contents of a single HTTP3 stream as a contiguous span of data.

For that purpose, the HTTP3 dissector is defining a custom conversation finder.
See functions `http3_find_inner_conversation` and `http3_reset_inner_conversation`.

## Essential data structures
### File-level state
#### `HTTP3_CONN_INFO_MAP`
The `HTTP3_CONN_INFO_MAP` contains session-level information for every HTTP3 connection
in a PCAP file. This map is lazily allocated, and is cleared upon exiting the file scope.

### HTTP3 header caches
The dissector attempts to conserve memory, by avoding allocating memory for
duplicate header names/values. Instead, the dissector keeps the decoded names/values
in two caches: `HTTP3_HEADER_CACHE` and `HTTP3_HEADER_DEF_CACHE`. The former stores
the decoded HTTP3 header values, and the latter stores the decoded HTTP3 header names.

### Connection-level state
#### `http3_session_info_t`
The `http3_session_info_t` keeps the state of the QPACK decoder. Every HTTP3 connection
corresponds to a single session. In the future, the session may be shared between multiple
connections, to support connection migration or multipath HTTP3.
At the moment, there are no shared sessions.

### Stream-level state
#### `http3_stream_info_t`
The `http3_stream_info_t` keeps the information about the individual HTTP3 streams,
as well as mapping to the underlying QUIC streams.

### Frame-level state
#### `http3_header_field_t`
The `http3_header_field_t` keeps the information about a single HTTP header.
It contains both the encoded and the decoded representation of the header.
The actual decoded strings are stored in `HTTP3_HEADER_CACHE`/`HTTP3_HEADER_DEF_CACHE`;
the individual `http3_header_field_t` instances contain pointers to the strings.