nhttp_qpack (nhttp_lib v1.1.1)

View Source

QPACK header compression for HTTP/3 (RFC 9204).

Public API facade that delegates to the encoder and decoder state machines. Provides a symmetric interface for encoding and decoding field sections on request/push streams, and feeding control stream data in both directions.

Encoder usage

{ok, Enc0} = nhttp_qpack:new_encoder(#{
    max_table_capacity => 4096,
    max_blocked_streams => 100
}),
Headers = [{<<":method">>, <<"GET">>}, {<<":path">>, <<"/">>}],
{ok, Enc1, EncStreamData, FieldData} =
    nhttp_qpack:encode_field_section(Enc0, 0, Headers).

Decoder usage

{ok, Dec0} = nhttp_qpack:new_decoder(#{
    max_table_capacity => 4096,
    max_blocked_streams => 100
}),
{ok, Dec1, DecStreamData, FieldLines} =
    nhttp_qpack:decode_field_section(Dec0, 0, FieldData).

Summary

Types

decoder()
decoder_config()
encoder()
encoder_config()
field_line()

Functions

decode_field_section(Decoder, StreamId, Data)

Decode an encoded field section from a request or push stream. Returns {ok, Decoder, DecoderStreamData, FieldLines} on success, {blocked, Decoder} when the field section references entries not yet received on the encoder stream, or {error, Reason} on failure. A field name or a field value that breaks the rule of RFC 9113 §8.2.1, which RFC 9114 §4.1.2 repeats, is refused as the nhttp_qpack_decoder:field_error/0 shape. RFC 9114 §4.1.2 makes that a stream error of type H3_MESSAGE_ERROR, where every other error here is a connection error.

encode_field_section(Encoder, StreamId, Headers)

Encode a field section for the given stream.

feed_decoder_stream(Encoder, Data)

Feed decoder stream data into the encoder. Processes section acknowledgments, stream cancellations, and insert count increments from the decoder.

feed_encoder_stream(Decoder, Data)

Feed encoder stream data into the decoder. Processes encoder instructions (table insertions, capacity changes, duplications) and unblocks any streams whose required insert count is now satisfied. Returns {ok, Decoder, UnblockedResults} where UnblockedResults is a list of {StreamId, DecoderStreamData, FieldLines} tuples for streams that became unblocked. An instruction that carries an invalid field name or an invalid field value is refused, and the entry does not enter the dynamic table. RFC 9204 §2.2.3 makes an error on the encoder stream a connection error of type QPACK_ENCODER_STREAM_ERROR.

new_decoder(Config)

Create a new QPACK decoder.

new_encoder(Config)

Create a new QPACK encoder.

reconcile_peer_limits(PeerMaxCap, PeerMaxBlocked, Encoder)

Reconcile the encoder against the peer's advertised QPACK limits (SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS). Call once when the peer's HTTP/3 SETTINGS are received. See nhttp_qpack_encoder:reconcile_peer_limits/3.

Types

decoder()

-type decoder() :: nhttp_qpack_decoder:state().

decoder_config()

-type decoder_config() :: nhttp_qpack_decoder:config().

encoder()

-type encoder() :: nhttp_qpack_encoder:state().

encoder_config()

-type encoder_config() :: nhttp_qpack_encoder:config().

field_line()

-type field_line() :: {binary(), binary()}.

Functions

decode_field_section(Decoder, StreamId, Data)

-spec decode_field_section(decoder(), nhttp_lib:stream_id(), binary()) ->
                              {ok, decoder(), iodata(), [field_line()]} |
                              {blocked, decoder()} |
                              {error, term()}.

Decode an encoded field section from a request or push stream. Returns {ok, Decoder, DecoderStreamData, FieldLines} on success, {blocked, Decoder} when the field section references entries not yet received on the encoder stream, or {error, Reason} on failure. A field name or a field value that breaks the rule of RFC 9113 §8.2.1, which RFC 9114 §4.1.2 repeats, is refused as the nhttp_qpack_decoder:field_error/0 shape. RFC 9114 §4.1.2 makes that a stream error of type H3_MESSAGE_ERROR, where every other error here is a connection error.

encode_field_section(Encoder, StreamId, Headers)

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

Encode a field section for the given stream.

Returns encoder stream data (to send on the encoder unidirectional stream) and field section data (to send on the request stream).

feed_decoder_stream(Encoder, Data)

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

Feed decoder stream data into the encoder. Processes section acknowledgments, stream cancellations, and insert count increments from the decoder.

feed_encoder_stream(Decoder, Data)

-spec feed_encoder_stream(decoder(), binary()) ->
                             {ok, decoder(), [{nhttp_lib:stream_id(), iodata(), [field_line()]}]} |
                             {error, term()}.

Feed encoder stream data into the decoder. Processes encoder instructions (table insertions, capacity changes, duplications) and unblocks any streams whose required insert count is now satisfied. Returns {ok, Decoder, UnblockedResults} where UnblockedResults is a list of {StreamId, DecoderStreamData, FieldLines} tuples for streams that became unblocked. An instruction that carries an invalid field name or an invalid field value is refused, and the entry does not enter the dynamic table. RFC 9204 §2.2.3 makes an error on the encoder stream a connection error of type QPACK_ENCODER_STREAM_ERROR.

new_decoder(Config)

-spec new_decoder(decoder_config()) -> {ok, decoder()}.

Create a new QPACK decoder.

new_encoder(Config)

-spec new_encoder(encoder_config()) -> {ok, encoder()}.

Create a new QPACK encoder.

reconcile_peer_limits(PeerMaxCap, PeerMaxBlocked, Encoder)

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

Reconcile the encoder against the peer's advertised QPACK limits (SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS). Call once when the peer's HTTP/3 SETTINGS are received. See nhttp_qpack_encoder:reconcile_peer_limits/3.