Struct hpack::encoder::Encoder

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

Represents an HPACK encoder. Allows clients to encode arbitrary header sets and tracks the encoding context. That is, encoding subsequent header sets will use the context built by previous encode calls.

This is the main API for performing HPACK encoding of headers.

Examples

Encoding a header two times in a row produces two different representations, due to the utilization of HPACK compression.

use hpack::Encoder;

let mut encoder = Encoder::new();

let headers = vec![
    (b"custom-key".to_vec(), b"custom-value".to_vec()),
];
// First encoding...
let result = encoder.encode(headers.iter().map(|h| (&h.0[..], &h.1[..])));
// The result is a literal encoding of the header name and value, with an
// initial byte representing the type of the encoding
// (incremental indexing).
assert_eq!(
    vec![0x40,
         10, b'c', b'u', b's', b't', b'o', b'm', b'-', b'k', b'e', b'y',
         12, b'c', b'u', b's', b't', b'o', b'm', b'-', b'v', b'a', b'l',
         b'u', b'e'],
    result);

// Encode the same headers again!
let result = encoder.encode(headers.iter().map(|h| (&h.0[..], &h.1[..])));
// The result is simply the index of the header in the header table (62),
// with a flag representing that the decoder should use the index.
assert_eq!(vec![0x80 | 62], result);

Implementations

impl<'a> Encoder<'a>

pub fn new() -> Encoder<'a>

Creates a new Encoder with a default static table, as defined by the HPACK spec (Appendix A).

pub fn encode<'b, I>(&mut self, headers: I) -> Vec<u8> where
    I: IntoIterator<Item = (&'b [u8], &'b [u8])>, 

Encodes the given headers using the HPACK rules and returns a newly allocated Vec containing the bytes representing the encoded header set.

The encoder so far supports only a single, extremely simple encoding strategy, whereby each header is represented as an indexed header if already found in the header table and a literal otherwise. When a header isn't found in the table, it is added if the header name wasn't found either (i.e. there are never two header names with different values in the produced header table). Strings are always encoded as literals (Huffman encoding is not used).

pub fn encode_into<'b, I, W>(
    &mut self,
    headers: I,
    writer: &mut W
) -> Result<()> where
    I: IntoIterator<Item = (&'b [u8], &'b [u8])>,
    W: Write, 

Encodes the given headers into the given io::Write instance. If the io::Write raises an Error at any point, this error is propagated out. Any changes to the internal state of the encoder will not be rolled back, though, so care should be taken to ensure that the paired decoder also ends up seeing the same state updates or that their pairing is cancelled.

pub fn encode_header_into<W: Write>(
    &mut self,
    header: (&[u8], &[u8]),
    writer: &mut W
) -> Result<()>

Encodes a single given header into the given io::Write instance.

Any errors are propagated, similarly to the encode_into method, and it is the callers responsiblity to make sure that the paired encoder sees them too.