httlib_huffman/lib.rs
1//! This crate implements [canonical Huffman] functionality for handling [HPACK]
2//! format in [HTTP/2]. It exposes a simple API for performing the encoding and
3//! decoding of [HTTP/2] header string literals according to the [HPACK] spec.
4//!
5//! [](https://docs.rs/httlib-huffman)
6//! [](https://github.com/xpepermint/httlib-rs/tree/main/huffman)
7//!
8//! Header Compression format for [HTTP/2], known as [HPACK], foresees the use
9//! of the Huffman algorithm for encoding header literal values. This
10//! contributes to the additional decrease in the quantity of data, transferred
11//! with each web request and response.
12//!
13//! A [Huffman code] is a particular type of optimal prefix code that is
14//! commonly used for lossless data compression. The process of finding or using
15//! such a code proceeds by means of Huffman coding, an algorithm developed by
16//! David A. Huffman. The output from Huffman's algorithm can be viewed as a
17//! variable-length code table for encoding a source symbol (such as a character
18//! in a file). The algorithm derives this table from the estimated probability
19//! or frequency of occurrence (weight) for each possible value of the source
20//! symbol. As in other entropy encoding methods, more common symbols are
21//! generally represented using fewer bits than less common symbols. Huffman's
22//! method can be efficiently implemented, finding a code in time linear to the
23//! number of input weights if these weights are sorted.
24//!
25//! [HPACK] compression entails a pre-created [canonical Huffman] code table
26//! for encoding [ASCII] characters to the Huffman sequence. A
27//! [canonical Huffman] code is a particular type of [Huffman code] with unique
28//! properties that allow it to be described in a very compact manner. In the
29//! aforementioned table are the Huffman codes for each [ASCII] character with a
30//! length up to 32 bits (4x by 8 fields with value 0 or 1), in the form of
31//! base-2 integer, aligned on the most significant bit (MSB is the bit farthest
32//! to the left).
33//!
34//! Each module covers this topic in more details so check the rest of the code
35//! to learn more.
36//!
37//! ## Usage
38//!
39//! **Encoding example:**
40//!
41//! ```rust
42//! use httlib_huffman::encode;
43//!
44//! let mut dst = Vec::new();
45//! let text = "Hello world!".as_bytes();
46//! encode(&text, &mut dst).unwrap();
47//! ```
48//!
49//! **Decoding example:**
50//!
51//! ```rust
52//! use httlib_huffman::{DecoderSpeed, decode};
53//!
54//! let speed = DecoderSpeed::ThreeBits;
55//! let mut dst = Vec::new();
56//! let src = vec![135];
57//! decode(&src, &mut dst, speed).unwrap();
58//! ```
59//!
60//! ## Articles
61//!
62//! * [HPACK: Huffman encoder](https://dev.to/xpepermint/hpack-huffman-encoder-3i7c)
63//! * [HPACK: Huffman translation matrix](https://dev.to/xpepermint/hpack-huffman-translation-matrix-64c)
64//! * [HPACK: Huffman decoder](https://dev.to/xpepermint/hpack-huffman-decoder-52el)
65//!
66//! [ASCII]: https://en.wikipedia.org/wiki/ASCII
67//! [HPACK]: https://tools.ietf.org/html/rfc7541
68//! [HTTP/2]: https://tools.ietf.org/html/rfc7540
69//! [Huffman code]: https://en.wikipedia.org/wiki/Huffman_coding
70//! [canonical Huffman]: https://en.wikipedia.org/wiki/Canonical_Huffman_code
71
72pub mod decoder;
73pub mod encoder;
74pub mod flattener;
75pub mod parser;
76
77pub use decoder::*;
78pub use encoder::*;