attr_dissector_fn_t
[wireshark-sm.git] / doc / http3.md
blob9fc10851ee7901b201a2868125bf858acfbe20e1
2 # Supported features
3 The HTTP3 dissector is a work in progress.
5 At the moment, the following aspects of HTTP3 are supported:
6 - Diseciton of different HTTP3 stream types
7 - Dissection of different HTTP3 frame types
8 - Dissection of HTTP header fields
9 - Dissection of QPACK instructions
11 In addition, the dissector suports decoding of the HTTP3
12 header fields. This ability requires `nghttp3` third-party library.
14 ## High-level overview
15 The HTTP3 dissector is invoked by the QUIC dissector.
17 The essential call tree:
18 -  `dissect_http3`
19    Main entry point. Depending on the stream type, invokes one of the following:
20    -  `dissect_http3_uni_stream`
21       Processes unidirectional streams, including the control streams,
22       the QPACK encoder/decoder streams, and the HTTP3 server push streams.
23       NOTE: the HTTP3 server push streams support is rudimental.
24       -  `dissect_http3_qpack_enc`
25          Dissects the QPACK encoder stream.
26          If Wireshark was built with the optional `nghttp3` library,
27          this function is also responsible on updating the state
28          of the QPACK decoder.
29    -  `dissect_http3_frame`
30       Processed HTTP3 frames from the client-initiated bidirectional stream.
31       Determines the frame type, and dispatches the call to one of the
32       sub-dissectors:
33       -  `dissect_http3_data`
34          Dissects the `HTTP3_DATA` frames.
35       -  `dissect_http3_headers`
36          Dissects the `HTTP3_HEADER` frames.
37          If Wireshark was built with the optional `nghttp3` library,
38          this function attempts to decode the header fields, using
39          the QPACK decoder.
40       -  `dissect_http3_settings`
41          Dissects the `HTTP3_SETTINGS` frames.
43 ### Overview of the HTTP3 header dissection
44 The QPACK implementation from `nghttp3` requires a separate QPACK decoder instance
45 for every HTTP3 connection. The different HTTP3 streams that constitute a single
46 HTTP3 conneciton are sharing the same QPACK decoder instance.
48 The HTTP3 dissector interacts with the QPACK decoder in 2 ways:
49 -  On the reception of QPACK encoder data (which is delivered on a dedicated unidirectional stream),
50    the dissector updates the connection's decoder instance.
51 -  On the reception of compressed HTTP3 headers, the dissector uses the connection's decoder
52    to uncompress the HTTP headers.
54 If decompression succeeds, the dissector adds tree items to the packet tree. Otherwise,
55 the dissector adds expert info items.
57 The decompression can fail due to several reasons:
58 -  If the instruction count required by the compressed HTTP3 headers
59    exceeds the maximal instruction count that the QPACK decoder is aware of,
60    the decoding becomes "blocked". This situation can occure when the QUIC packets
61    that carry the QPACK encoder instructions are dropped/reordered.
62 -  If the state of the decoder becomes invalid, which may happen when a "garbage"
63    data is received on the QUIC stream.
64 -  Lastly, the decoding can fail if the underlying QUIC desegmentation is
65    not working correctly.
67 ### Overview of HTTP3 data frames dissection
68 The higher-level dissectors that could use HTTP3 (e.g. WebTransport) need to be able
69 to access the contents of a single HTTP3 stream as a contiguous span of data.
71 For that purpose, the HTTP3 dissector is defining a custom conversation finder.
72 See functions `http3_find_inner_conversation` and `http3_reset_inner_conversation`.
74 ## Essential data structures
75 ### File-level state
76 #### `HTTP3_CONN_INFO_MAP`
77 The `HTTP3_CONN_INFO_MAP` contains session-level information for every HTTP3 connection
78 in a PCAP file. This map is lazily allocated, and is cleared upon exiting the file scope.
80 ### HTTP3 header caches
81 The dissector attempts to conserve memory, by avoding allocating memory for
82 duplicate header names/values. Instead, the dissector keeps the decoded names/values
83 in two caches: `HTTP3_HEADER_CACHE` and `HTTP3_HEADER_DEF_CACHE`. The former stores
84 the decoded HTTP3 header values, and the latter stores the decoded HTTP3 header names.
86 ### Connection-level state
87 #### `http3_session_info_t`
88 The `http3_session_info_t` keeps the state of the QPACK decoder. Every HTTP3 connection
89 corresponds to a single session. In the future, the session may be shared between multiple
90 connections, to support connection migration or multipath HTTP3.
91 At the moment, there are no shared sessions.
93 ### Stream-level state
94 #### `http3_stream_info_t`
95 The `http3_stream_info_t` keeps the information about the individual HTTP3 streams,
96 as well as mapping to the underlying QUIC streams.
98 ### Frame-level state
99 #### `http3_header_field_t`
100 The `http3_header_field_t` keeps the information about a single HTTP header.
101 It contains both the encoded and the decoded representation of the header.
102 The actual decoded strings are stored in `HTTP3_HEADER_CACHE`/`HTTP3_HEADER_DEF_CACHE`;
103 the individual `http3_header_field_t` instances contain pointers to the strings.