1[![Build Status](https://travis-ci.org/litespeedtech/ls-qpack.svg?branch=master)](https://travis-ci.org/litespeedtech/ls-qpack)
2[![Build status](https://ci.appveyor.com/api/projects/status/kat31lt42ds0rmom?svg=true)](https://ci.appveyor.com/project/litespeedtech/ls-qpack)
3[![Build Status](https://api.cirrus-ci.com/github/litespeedtech/ls-qpack.svg)](https://cirrus-ci.com/github/litespeedtech/ls-qpack)
4
5# ls-qpack
6QPACK compression library for use with HTTP/3
7
8## Introduction
9
10QPACK is the compression mechanism used by
11[HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) to compress HTTP headers.
12It is in the process of being standardazed by the QUIC Working Group.  The
13[QPACK Internet-Draft](https://tools.ietf.org/html/draft-ietf-quic-qpack-11)
14is has been stable for some time and we don't expect functional changes to
15it before the final RFC is released.
16
17## Functionality
18
19ls-qpack is a full-featured, tested, and fast QPACK library.  The QPACK encoder
20produces excellent compression results based on an [innovative mnemonic technique](https://blog.litespeedtech.com/2021/04/05/qpack-mnemonic-technique/).  It boasts the fastest Huffman
21[encoder](https://blog.litespeedtech.com/2019/10/03/fast-huffman-encoder/) and
22[decoder](https://blog.litespeedtech.com/2019/09/16/fast-huffman-decoder/).
23
24The library is production quality.  It is used in
25[OpenLiteSpeed](https://openlitespeed.org/),
26LiteSpeed [Web Server](https://www.litespeedtech.com/products#lsws),
27and LiteSpeed [Web ADC](https://www.litespeedtech.com/products#wadc).
28
29The library is robust:
301. The encoder does not assume anything about usual HTTP headers such as `Server`
31   or `User-Agent`.  Instead, it uses its mnemonic compression technique to
32   achieve good compression results for any input.
331. The decoder uses modulo arithmetic to track dynamic table insertions.  This is
34   in contrast to all other QPACK implementations, which use an integer counter,
35   meaning that at some point, the decoder will break.
361. The decoder processes input in streaming fashion.  The caller does not have to
37   buffer the contents of HTTP/3 `HEADERS` frame.  Instead, the decoder can be
38   supplied input byte-by-byte.
39
40## Other Languages
41
42The ls-qpack library is implemented in vanilla C99.  It makes it a good candidate
43for wrapping into a library for a higher-level language.  As of this writing, we
44know of the following wrappers:
45- Go: [ls-qpack-go](https://github.com/mpiraux/ls-qpack-go)
46- Python: [pylsqpack](https://github.com/aiortc/pylsqpack)
47- TypeScript: [quicker](https://github.com/rmarx/quicker/tree/draft-20/lib/ls-qpack)
48
49## Versioning
50
51Before the QPACK RFC is released, the three parts of the version are:
52- MAJOR: set to zero;
53- MINOR: set to the number of QPACK Internet-Draft the lirbary supports; and
54- PATCH: set to the patch number
55
56Once the RFC is released, MAJOR will be set to 1 and the version will follow
57the usual MAJOR.MINOR.PATCH pattern.
58
59## API
60
61The API is documented in the header file, [lsqpack.h](lsqpack.h).
62One example how it is used in real code can be seen in
63[lsquic](https://github.com/litespeedtech/lsquic), a QUIC and HTTP/3 library
64developed by LiteSpeed Technologies.
65
66A different API, without the use of `struct lsxpack_header`, is available
67on branch-v1.
68