httlib_hpack/
lib.rs

1//! This crate implements [HPACK], a compression format for efficiently
2//! representing HTTP header fields in [HTTP/2]. It exposes a simple API for
3//! performing the encoding and decoding of HTTP headers.
4//! 
5//! [![Documentation](https://img.shields.io/badge/-Documentation-blue?style=for-the-badge&logo=Rust)](https://docs.rs/httlib-hpack)
6//! [![Source](https://img.shields.io/badge/-Source-lightgrey?style=for-the-badge&logo=GitHub)](https://github.com/xpepermint/httlib-rs/tree/main/hpack)
7//! 
8//! ## About
9//! 
10//! [HPACK] is a compression format that eliminates redundant header fields in
11//! requests and responses. This is one of the features based on which the
12//! [HTTP/2] protocol significantly reduces the amount of transferred data from
13//! one entity to another.
14//! 
15//! A significant shift in thinking is required from the implementer of the
16//! [HTTP/2] protocol. A connection in [HTTP/2] does not represent a single
17//! request/response session. We can start multiple simultaneous streams in one
18//! connection, representing multiple request/response sessions, which was not
19//! possible in the previous versions of the HTTP protocol. The [HPACK]
20//! compressor uses this characteristic of [HTTP/2] by indexing headers
21//! considering the whole connection and not per stream.
22//! 
23//! The implementation of [HPACK] contains three main parts of the process:
24//! 
25//! * `Indexing table` is a list, to which the HPACK saves the commonly used
26//! headers. Each entity indexes headers per connection, separately for incoming
27//! (decoding) and for outgoing (encoding) data.
28//! 
29//! * `Encoder` performs the task of data compression. It converts the data from
30//! its original readable form into an optimized byte sequence by applying the
31//! rules defined in the HPACK specification.
32//! 
33//! * `Decoder` takes over the task of the decompressor. It executes the
34//! commands inversely to the encoder. It converts the data back into its
35//! readable form.
36//! 
37//! ## Usage
38//!
39//! **Encoding example:**
40//! 
41//! ```rust
42//! use httlib_hpack::Encoder;
43//! 
44//! let mut encoder = Encoder::default();
45//! 
46//! let name = b":method".to_vec();
47//! let value = b"PATCH".to_vec();
48//! let flags = Encoder::HUFFMAN_VALUE | Encoder::WITH_INDEXING | Encoder::BEST_FORMAT;
49//! 
50//! let mut dst = Vec::new();
51//! encoder.encode((name, value, flags), &mut dst).unwrap();
52//! ```
53//! 
54//! **Decoding example:**
55//! 
56//! ```rust
57//! use httlib_hpack::Decoder;
58//!
59//! let mut decoder = Decoder::default();
60//! let mut buf = vec![0x80 | 2];
61//! 
62//! let mut dst = Vec::new();
63//! decoder.decode(&mut buf, &mut dst).unwrap();
64//! 
65//! for (name, value, flags) in dst {
66//!     if flags & Decoder::NEVER_INDEXED == Decoder::NEVER_INDEXED {
67//!         // sensitive header
68//!     } else {
69//!         // common header
70//!     }
71//! }
72//! ```
73//! 
74//! ## Articles
75//! 
76//! * [HPACK: The secret ingredient of HTTP/2](https://dev.to/xpepermint/hpack-the-secret-ingredient-of-http-2-4np6)
77//! 
78//! [HPACK]: https://tools.ietf.org/html/rfc7541
79//! [HTTP/2]: https://tools.ietf.org/html/rfc7540
80
81pub mod decoder;
82pub mod encoder;
83pub mod table;
84
85pub use decoder::*;
86pub use encoder::*;
87use table::*;
httlib_hpack/lib.rs

httlib_hpack/
lib.rs
