nhttp_qpack_encoder (nhttp_lib v1.1.1)

View Source

QPACK encoder state machine (RFC 9204 Section 2.1).

Converts field sections into compressed representations using the QPACK header compression format for HTTP/3. The encoder maintains a dynamic table, generates encoder stream instructions for table modifications, and produces encoded field section data for request streams.

Field names

encode_field_section/3 writes every field name in lowercase. RFC 9114 §4.2 requires that characters in field names are converted to lowercase before their encoding, and RFC 9114 §4.1.2 makes an uppercase name malformed. The conversion is silent: the return type does not change, and the caller reads no report of it.

A name that already holds no octet in 0x41-0x5A costs one scan and no allocation. The lowercase name is what the static table lookup reads, what the literal representation writes, what the encoder stream instruction carries and what the dynamic table holds. All four name the same octets.

The implementation uses a conservative encoding strategy following Appendix C of RFC 9204: static table lookups are always preferred, dynamic table entries are only referenced when safely below the Known Received Count (no risk of blocking), and new entries are inserted eagerly when table capacity allows.

Usage

{ok, Enc0} = nhttp_qpack_encoder:new(#{
    max_table_capacity => 4096,
    max_blocked_streams => 100
}),

Headers = [{<<":method">>, <<"GET">>}, {<<":path">>, <<"/">>}],
{ok, Enc1, EncStreamData, FieldData} =
    nhttp_qpack_encoder:encode_field_section(Enc0, 0, Headers),


DecoderData = ...,
{ok, Enc2} = nhttp_qpack_encoder:feed_decoder_stream(Enc1, DecoderData).

Summary

Types

config()
state()

Functions

encode_field_section(State0, StreamId, Headers)

Encode a field section for the given stream.

feed_decoder_stream(State, Data)

Process decoder instructions received on the decoder stream. Handles section acknowledgments, stream cancellations, and insert count increments. Partial instructions are buffered (returns the current state unchanged).

new(Config)

Create a new encoder with the given configuration.

reconcile_peer_limits(PeerMaxCap, PeerMaxBlocked, State)

Reconcile the encoder against the peer's advertised QPACK limits (RFC 9204 Section 3.2.3). The peer is the decoder of the field sections this encoder produces, so the effective dynamic-table capacity is bounded by min(configured ceiling, peer advertised), and the encoder must never reference more than the peer's advertised blocked-stream budget. max_entries for the field-section prefix is fixed by the peer's advertised capacity (Section 4.5.1.1), independent of how much of the table this encoder chooses to use. Arms the Set Dynamic Table Capacity instruction so the next encode announces the effective capacity on the encoder stream before any reference to a dynamic entry. Capacity 0 (the QPACK default, e.g. a peer that does not advertise the setting) leaves the encoder dormant: all field lines stay static-or-literal and no encoder-stream instructions are emitted.

Types

config()

-type config() ::
          #{max_table_capacity => non_neg_integer(),
            configured_max_capacity => non_neg_integer(),
            max_blocked_streams => non_neg_integer(),
            configured_max_blocked => non_neg_integer(),
            huffman => boolean()}.

state()

-opaque state()

Functions

encode_field_section(State0, StreamId, Headers)

-spec encode_field_section(state(), nhttp_lib:stream_id(), [{binary(), binary()}]) ->
                              {ok, state(), iodata(), iodata()}.

Encode a field section for the given stream.

Returns encoder stream data (instructions for the decoder's dynamic table) and field section data (the prefix plus encoded representations to send on the request stream).

feed_decoder_stream(State, Data)

-spec feed_decoder_stream(state(), binary()) -> {ok, state()} | {error, term()}.

Process decoder instructions received on the decoder stream. Handles section acknowledgments, stream cancellations, and insert count increments. Partial instructions are buffered (returns the current state unchanged).

new(Config)

-spec new(config()) -> {ok, state()}.

Create a new encoder with the given configuration.

reconcile_peer_limits(PeerMaxCap, PeerMaxBlocked, State)

-spec reconcile_peer_limits(non_neg_integer(), non_neg_integer(), state()) -> state().

Reconcile the encoder against the peer's advertised QPACK limits (RFC 9204 Section 3.2.3). The peer is the decoder of the field sections this encoder produces, so the effective dynamic-table capacity is bounded by min(configured ceiling, peer advertised), and the encoder must never reference more than the peer's advertised blocked-stream budget. max_entries for the field-section prefix is fixed by the peer's advertised capacity (Section 4.5.1.1), independent of how much of the table this encoder chooses to use. Arms the Set Dynamic Table Capacity instruction so the next encode announces the effective capacity on the encoder stream before any reference to a dynamic entry. Capacity 0 (the QPACK default, e.g. a peer that does not advertise the setting) leaves the encoder dormant: all field lines stay static-or-literal and no encoder-stream instructions are emitted.