Struct httlib_hpack::Encoder

pub struct Encoder<'a> { /* fields omitted */ }

An object for encoding HTTP/2 headers.

Since headers in HPACK can be encoded in multiple ways, the encoder provides multiple methods for encoding headers. A developer is responsible to carefully choose between them to achieve the best encoding performance.

Implementations

impl<'a> Encoder<'a>

pub const HUFFMAN_NAME: u8

A flag indicating to encode header name with Huffman algorithm (0x1).

pub const HUFFMAN_VALUE: u8

A flag indicating to encode header value with Huffman algorithm (0x2).

pub const WITH_INDEXING: u8

A flag indicating to index literal header field (0x4).

pub const NEVER_INDEXED: u8

A flag indicating to never index literal header field (0x8).

pub const BEST_FORMAT: u8

A flag indicating to find the best literal representation by searching the indexing table (0x10).

pub fn with_dynamic_size(max_dynamic_size: u32) -> Self

Returns a new encoder instance with the provided maximum allowed size of the dynamic table.

pub fn max_dynamic_size(&mut self) -> u32

Returns the maximum allowed size of the dynamic table.

pub fn encode<F>(
    &mut self,
    field: F,
    dst: &mut Vec<u8>
) -> Result<(), EncoderError> where
    F: Into<EncoderInput>, 

Encodes headers into the HPACK's header field representation format.

By default headers are represented without indexing and Huffman encoding is not enabled for literals. We can configure the encoder by providing byte flags:

• 0x1: Use Huffman to encode header name.
• 0x2: Use Huffman to encode header value.
• 0x4: Literal header field with incremental indexing (6.2.1.).
• 0x8: Literal header field never indexed (6.2.3.).
• 0x10: Encode literal as the best representation.

Example:

use httlib_hpack::Encoder;
 
let mut encoder = Encoder::default();
let mut dst = Vec::new();
let name = b":method".to_vec();
let value = b"PATCH".to_vec();
let flags = 0x2 | 0x4 | 0x10;
encoder.encode((name, value, flags), &mut dst).unwrap();

pub fn encode_indexed(
    &self,
    index: u32,
    dst: &mut Vec<u8>
) -> Result<(), EncoderError>

Encodes a header that exists at index in the indexing table.

The function converts the header index into HPACK's indexed header field representation and writes it into the dst buffer.

Indexed header field representation (6.1., figure 5):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 1 |        Index (7+)         |
+---+---------------------------+

pub fn encode_indexed_name(
    &mut self,
    index: u32,
    value: Vec<u8>,
    flags: u8,
    dst: &mut Vec<u8>
) -> Result<(), EncoderError>

Encodes a header where its name is represented with an index from the indexing table and the value is provided in bytes.

This function converts the header into HPACK's literal header field representation and writes it into the dst buffer.

Literal header field with incremental indexing (6.2.1., figure 6):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 1 |      Index (6+)       |
+---+---+-----------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

Literal header field without indexing (6.2.2., figure 8):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 0 |  Index (4+)   |
+---+---+-----------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

Literal header field never indexed (6.2.3., figure 10):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 1 |  Index (4+)   |
+---+---+-----------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

By default headers are represented as literals without indexing and header's value is encoded as a string. We can configure the encoder by providing byte flags:

• 0x2: Use Huffman to encode header value.
• 0x4: Literal header field with incremental indexing (6.2.1.).
• 0x8: Literal header field never indexed (6.2.3.).

pub fn encode_literal(
    &mut self,
    name: Vec<u8>,
    value: Vec<u8>,
    flags: u8,
    dst: &mut Vec<u8>
) -> Result<(), EncoderError>

Encodes a header where its name and value are provided in bytes.

This function converts the header into HPACK's literal header field representation and writes it into the dst buffer.

Literal header field with incremental indexing (6.2.1., figure 7):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 1 |           0           |
+---+---+-----------------------+
| H |     Name Length (7+)      |
+---+---------------------------+
|  Name String (Length octets)  |
+---+---------------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

Literal header field without indexing (6.2.2., figure 9):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 0 |       0       |
+---+---+-----------------------+
| H |     Name Length (7+)      |
+---+---------------------------+
|  Name String (Length octets)  |
+---+---------------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

Literal header field never indexed (6.2.3., figure 11):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 0 | 0 | 1 |       0       |
+---+---+-----------------------+
| H |     Name Length (7+)      |
+---+---------------------------+
|  Name String (Length octets)  |
+---+---------------------------+
| H |     Value Length (7+)     |
+---+---------------------------+
| Value String (Length octets)  |
+-------------------------------+

By default headers are represented as literals without indexing. Heder's name and value are encoded as a string. We can configure the encoder by providing byte flags:

• 0x1: Use Huffman to encode header name.
• 0x2: Use Huffman to encode header value.
• 0x4: Literal header field with incremental indexing (6.2.1.).
• 0x8: Literal header field never indexed (6.2.3.).

pub fn update_max_dynamic_size(
    &mut self,
    size: u32,
    dst: &mut Vec<u8>
) -> Result<(), EncoderError>

Updates the maximum size of the dynamic table and encodes the new size into a dynamic table size signal.

The new maximum size MUST be lower than or equal to the limit determined by the protocol using HPACK. In HTTP/2, this limit is the last value of the SETTINGS_HEADER_TABLE_SIZE received from the decoder and acknowledged by the encoder.

Maximum Dynamic table size change ([6.3.], figure 12):

  0   1   2   3   4   5   6   7
+---+---+---+---+---+---+---+---+
| 0 | 0 | 1 |   Max size (5+)   |
+---+---------------------------+

Trait Implementations

impl<'a> Debug for Encoder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Encoder<'a>

fn default() -> Self

Returns the "default value" for a type.