nghttp3 Documentation

To decode QPACK encoded data, follow these steps:

1. Initialize the decoder: Call nghttp3_qpack_decoder_new. It requires hard_max_dtable_size and max_blocked parameters (e.g., 4096 and 0 respectively).
2. Process encoder stream: Call nghttp3_qpack_decoder_read_encoder to read the encoder stream. This may update the dynamic table but does not emit header fields.
3. Process request stream: Call nghttp3_qpack_decoder_read_request to emit header fields. This requires a per-stream decoder state (sctx) created via nghttp3_qpack_stream_context_new.
   • The fin parameter must be non-zero if and only if the provided data contains the last part of the encoded header block.
   • If the function returns, you may need to call it repeatedly by adjusting the data pointer and length until all data is consumed or the NGHTTP3_QPACK_DECODE_FLAG_BLOCKED flag is set.
4. Manage stream context: The nghttp3_qpack_stream_context is scoped to a single header block. You can reuse it for another header block in the same stream by calling nghttp3_qpack_stream_context_reset, typically when the NGHTTP3_QPACK_DECODE_FLAG_FINAL flag is detected.
5. Handle emitted headers: If *pflags has the NGHTTP3_QPACK_DECODE_FLAG_EMIT flag set, header fields are stored in the buffer pointed to by nv.
   • Memory Management: If nv is assigned, the nv->name and nv->value members are reference counted. Once finished processing them, you must call nghttp3_rcbuf_decref(nv->name) and nghttp3_rcbuf_decref(nv->value) to prevent leaks.
6. Cancel streams: If you do not need to decode headers for a specific stream, call nghttp3_qpack_decoder_cancel_stream.
7. Provide feedback to encoder: Call nghttp3_qpack_decoder_write_decoder to write the decoder stream, informing the encoder of the decoding state.
8. Cleanup: Call nghttp3_qpack_decoder_del to free the decoder's memory and nghttp3_qpack_stream_context_del to free individual stream contexts.

To encode HTTP header fields using QPACK, follow these steps:

1. Initialize the encoder: Call nghttp3_qpack_encoder_new. You must provide a hard_max_dtable_size parameter (e.g., 4096).
2. Configure capacity (Optional):
   • Use nghttp3_qpack_encoder_set_max_dtable_capacity to set the maximum size of the dynamic table.
   • Use nghttp3_qpack_encoder_set_max_blocked_streams to set the maximum number of streams that can be blocked.
3. Encode headers: Prepare an array of nghttp3_nv structures containing the header fields. Call nghttp3_qpack_encoder_encode. This function populates three buffers:
   • pbuf: Header block prefix.
   • rbuf: Request stream data.
   • ebuf: Encoder stream data.
   • Note: You must send the header block prefix (pbuf) and the request stream (rbuf) in that order to the stream_id provided. The encoder stream data (ebuf) must be sent to the dedicated encoder stream you have established.
4. Handle decoder feedback: Call nghttp3_qpack_encoder_read_decoder to read data from the decoder stream.
5. Cleanup: Call nghttp3_qpack_encoder_del to free the encoder's memory.

An nghttp3_conn object is the core building block for an HTTP/3 connection. You must create one per connection using either nghttp3_conn_client_new (for clients) or nghttp3_conn_server_new (for servers).

Both functions require:

1. nghttp3_callbacks: A structure of callback functions. While optional, most transactions require several callbacks to function correctly.
2. nghttp3_settings: Options to tweak HTTP/3 connection settings. Use nghttp3_settings_default to populate these with default values.
3. user_data: An opaque pointer passed to all callback functions, allowing you to associate application-specific state with the connection.

/* Example initialization concept */
nghttp3_conn *conn;
nghttp3_callbacks callbacks = { ... };
nghttp3_settings settings;
nghttp3_settings_default(&settings);

if (is_client) {
    conn = nghttp3_conn_client_new(&callbacks, &settings, user_data);
} else {
    conn = nghttp3_conn_server_new(&callbacks, &settings, user_data);
}

To perform standard HTTP/3 transactions, you should implement the following callbacks in nghttp3_callbacks:

Use nghttp3_conn_writev_stream to generate HTTP stream data for a particular stream.

Workflow:

1. Call nghttp3_conn_writev_stream. It populates *pstream_id with the stream ID, vec with the data pointers, and *pfin with a non-zero value if it is the final part of the stream.
2. Pass the produced data to your QUIC stack.
3. Call nghttp3_conn_add_write_offset with the number of bytes accepted by the QUIC stack. Note: You must call this even if 0 bytes were written but *pfin was non-zero (signaling the end of the stream).

Handling Flow Control and Stream State:

• Stream Blocked: If the QUIC stack indicates a stream-level flow control limit, call nghttp3_conn_block_stream. Resume by calling nghttp3_conn_unblock_stream when the limit increases.
• Stream Closed: If the QUIC stack indicates the write side of a stream is closed, call nghttp3_conn_shutdown_stream_write instead of blocking it. This ensures the stream is never scheduled again.