README
¶
HPACK library
This library implements RFC7541, HPACK: Header Compression for HTTP/2, which includes:
- Primitive Type Representations
- Variable integer sizes (with prefix lengths)
- String literals (incl. Huffman decoding)
- Static & Dynamic indexes
- Dynamic Table evictions
- Header block parsing
You can read about HPACK and this implementation here.
Usage
Most users of this library will be implementing HTTP/2.
decoder := hpack.NewDecoder(negotiatedDynamicTableSizeMax)
headerBlock := recvHeaderBlockAndContinuations()
headers, err := decoder.Decode(headerBlock)
The Decode function expects a complete header block. HTTP/2 specifies that a header block can be split across multiple frames, in a HEADER or PUSH_PROMISE frame plus optional CONTINUATION frames.
Users should concatenate the header block fragments together and only call Decode when a frame with the END_HEADERS flag is received.
Development
Generating Huffman lookup tables
The lookup tables are code generated from the Huffman codes in the HPACK specification. This ensures the lookup tables are available at runtime with no initialization required.
Run the following command to generate the lookup tables used for Huffman decoding:
go run cmd/generate_huffman_tables/main.go | gofmt > huffman_tables.go
License
Copyright 2016 Chris Moos
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Documentation
¶
Overview ¶
Implements the HPACK Header Compression specification https://tools.ietf.org/html/rfc7541
The Huffman decoding is implemented with multi-level lookup tables for high performance.
Index ¶
- Variables
- func HuffmanDecode(encoded []byte) ([]byte, error)
- func HuffmanEncode(data []byte) []byte
- type Decoder
- func (decoder *Decoder) Decode(block []byte) ([]Header, error)
- func (decoder *Decoder) DecodeInteger(buf []byte, prefixLength int) (remainingBuf []byte, maskedFirstOctet int, number int, err error)
- func (decoder *Decoder) SetDynamicTableMaxSize(newMaxSize int)
- func (decoder *Decoder) SetMaxIntegerEncodedLength(length int)
- func (decoder *Decoder) SetMaxIntegerValue(value int)
- func (decoder *Decoder) SetMaxStringLiteralLength(length int)
- type Encoder
- func (encoder *Encoder) Encode(headers []Header) ([]byte, error)
- func (encoder *Encoder) EncodeIndexed(header Header, huffman bool) ([]byte, error)
- func (encoder *Encoder) EncodeInteger(number int, prefixLength int) []byte
- func (encoder *Encoder) EncodeNoDynamicIndexing(header Header, huffman bool) ([]byte, error)
- func (encoder *Encoder) SetDynamicTableMaxSize(newMaxSize int)
- type Header
Constants ¶
This section is empty.
Variables ¶
var DefaultMaxIntegerEncodedLength = 6
var DefaultMaxIntegerValue = ((1 << 32) - 1)
var DefaultMaxStringLiteralLength = 1024 * 64
var ErrHuffmanDecodeFailure = errors.New("invalid huffman code encountered")
var ErrIntegerEncodedLengthTooLong = errors.New("integer encoded length is too long")
var ErrIntegerValueTooLarge = errors.New("integer value larger than max value")
var ErrStringLiteralLengthTooLong = errors.New("string literal length is too long")
Functions ¶
func HuffmanDecode ¶
Decodes the huffman encoded data
func HuffmanEncode ¶
Encodes the specified data with Huffman codes in HPACK
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
A decoder is stateful and updates the internal compression context during processing of header blocks.
If HTTP/2 is used, a single decoder instance must be used during the lifetime of a connection, see: https://tools.ietf.org/html/rfc7540#section-4.3
func NewDecoder ¶
func (*Decoder) Decode ¶
Parsers the HPACK header block and returns list of headers with the order preserved from the order in the block.
func (*Decoder) DecodeInteger ¶
func (decoder *Decoder) DecodeInteger(buf []byte, prefixLength int) (remainingBuf []byte, maskedFirstOctet int, number int, err error)
Decodes an integer from buf with the specified prefix length in number of bits.
This function returns the remaining buffer after fully parsing the integer, the first octet with a mask applied to remove the prefix, the decoded number, and an error if an error occurred while parsing.
func (*Decoder) SetDynamicTableMaxSize ¶
Updates the decoder's dynamic table maximum size and evicts any headers if more space is needed to resize to newMaxSize.
func (*Decoder) SetMaxIntegerEncodedLength ¶
Sets the maximum bytes allowed for encoding a single integer
func (*Decoder) SetMaxIntegerValue ¶
Sets the largest integer that is allowed, anything > value will result in an error
func (*Decoder) SetMaxStringLiteralLength ¶
Sets the maximum length of a string literal For compressed string literals the length check will be against the compressed length, not the uncompressed length
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
func NewEncoder ¶
func (*Encoder) Encode ¶
This is a convenience function that encodes a list of headers into a header block using Huffman compression and with incremental indexing enabled.
If a header is marked as Sensitive it will be encoded as a never indexed header field
func (*Encoder) EncodeIndexed ¶
Encodes a header with Indexing and returns the encoded header field
func (*Encoder) EncodeInteger ¶
Encodes number with the specified prefix length in number of bits.
func (*Encoder) EncodeNoDynamicIndexing ¶
Encodes a header without Indexing and returns the encoded header field
func (*Encoder) SetDynamicTableMaxSize ¶
Updates the encoder's dynamic table maximum size and evicts any headers if more space is needed to resize to newMaxSize.
After this call the next header field that is encoded will include a dynamic table size update
Source Files
Directories