Network.HPACK

HPACK(https://tools.ietf.org/html/rfc7541) encoding and decoding a header list.

Encoding and decoding

encodeHeader

Arguments

:: EncodeStrategy

-> Size

The size of a temporary buffer.

-> DynamicTable

-> [Header]

-> IO ByteString

An HPACK format

Converting '[Header]' to the HPACK format. This function has overhead of allocating/freeing a temporary buffer. BufferOverrun will be thrown if the temporary buffer is too small.

decodeHeader

Arguments

:: DynamicTable

-> ByteString

An HPACK format

-> IO [Header]

Converting the HPACK format to '[Header]'.

• Headers are decoded as is.
• DecodeError would be thrown if the HPACK format is broken.
• BufferOverrun will be thrown if the temporary buffer for Huffman decoding is too small.

type Header = (HeaderName, ByteString)

A full HTTP header field with the name and value separated.

E.g. "Content-Length: 28" parsed into a Header would turn into ("Content-Length", "28")

original :: CI s -> s

Retrieve the original string-like value.

foldedCase :: CI s -> s

Retrieve the case folded string-like value. (Also see foldCase).

mk :: FoldCase s => s -> CI s

Make the given string-like value case insensitive.

Encoding and decoding with token

encodeTokenHeader

Arguments

:: Buffer

-> BufferSize

-> EncodeStrategy

-> Bool

True at the first time, False when continued.

-> DynamicTable

-> TokenHeaderList

-> IO (TokenHeaderList, Int)

Leftover, filled length

Converting TokenHeaderList to the HPACK format directly in the buffer.

When calling this function for a new TokenHeaderList, 4th argument must be True.

The return value is a pair of leftover TokenHeaderList and how many bytes are filled in the buffer. If the leftover is empty, the encoding is finished. Otherwise, this function should be called with it again. 4th argument must be False.

4th argument is relating to dynamic table size update. If True and the limit is set by setLimitForEncoding, dynamic table size update is generated at the beginning of the HPACK format.

decodeTokenHeader

Arguments

:: DynamicTable

-> ByteString

An HPACK format

-> IO TokenHeaderTable

Converting the HPACK format to TokenHeaderList and ValueTable.

• Multiple values of Cookie: are concatenated.
• If a pseudo header appears multiple times, IllegalHeaderName is thrown.
• If unknown pseudo headers appear, IllegalHeaderName is thrown.
• If pseudo headers are found after normal headers, IllegalHeaderName is thrown.
• If a header key contains capital letters, IllegalHeaderName is thrown.
• DecodeError would be thrown if the HPACK format is broken.
• BufferOverrun will be thrown if the temporary buffer for Huffman decoding is too small.

DynamicTable

data DynamicTable

Type for dynamic table.

defaultDynamicTableSize :: Int

Default dynamic table size. The value is 4,096 bytes: an array has 128 entries.

>>> defaultDynamicTableSize
4096

newDynamicTableForEncoding

Arguments

:: Size

The dynamic table size

-> IO DynamicTable

Creating DynamicTable for encoding.

newDynamicTableForDecoding

Arguments

:: Size

The dynamic table size

-> Size

The size of temporary buffer for Huffman decoding

-> IO DynamicTable

Creating DynamicTable for decoding.

withDynamicTableForEncoding

Arguments

:: Size

The dynamic table size

-> (DynamicTable -> IO a)

-> IO a

Creating DynamicTable for encoding, performing the action and clearing the DynamicTable.

withDynamicTableForDecoding

Arguments

:: Size

The dynamic table size

-> Size

The size of temporary buffer for Huffman

-> (DynamicTable -> IO a)

-> IO a

Creating DynamicTable for decoding, performing the action and clearing the DynamicTable.

setLimitForEncoding :: Size -> DynamicTable -> IO ()

When SETTINGS_HEADER_TABLE_SIZE is received from a peer, its value should be set by this function.

Strategy for encoding

data CompressionAlgo

Compression algorithms for HPACK encoding.

Constructors

Naive

No compression

Static

Using indices in the static table only

Linear

Using indices

Instances

Show CompressionAlgo

Defined in Network.HPACK.Types

Methods

showsPrec :: Int -> CompressionAlgo -> ShowS

show :: CompressionAlgo -> String

showList :: [CompressionAlgo] -> ShowS

Eq CompressionAlgo

Defined in Network.HPACK.Types

Methods

(==) :: CompressionAlgo -> CompressionAlgo -> Bool

(/=) :: CompressionAlgo -> CompressionAlgo -> Bool

data EncodeStrategy

Strategy for HPACK encoding.

Constructors

EncodeStrategy

Fields

• compressionAlgo :: CompressionAlgo

  Which compression algorithm is used.

• useHuffman :: Bool

  Whether or not to use Huffman encoding for strings.

Instances

Show EncodeStrategy

Defined in Network.HPACK.Types

Methods

showsPrec :: Int -> EncodeStrategy -> ShowS

show :: EncodeStrategy -> String

showList :: [EncodeStrategy] -> ShowS

Eq EncodeStrategy

Defined in Network.HPACK.Types

Methods

(==) :: EncodeStrategy -> EncodeStrategy -> Bool

(/=) :: EncodeStrategy -> EncodeStrategy -> Bool

defaultEncodeStrategy :: EncodeStrategy

Default EncodeStrategy.

>>> defaultEncodeStrategy
EncodeStrategy {compressionAlgo = Linear, useHuffman = False}

Errors

data DecodeError

Errors for decoder.

Constructors

IndexOverrun Index

Index is out of range

EosInTheMiddle

Eos appears in the middle of huffman string

IllegalEos

Non-eos appears in the end of huffman string

TooLongEos

Eos of huffman string is more than 7 bits

TooSmallTableSize

A peer set the dynamic table size less than 32

TooLargeTableSize

A peer tried to change the dynamic table size over the limit

IllegalTableSizeUpdate

Table size update at the non-beginning

HeaderBlockTruncated

IllegalHeaderName

TooLargeHeader

Instances

Exception DecodeError

Defined in Network.HPACK.Types

Methods

toException :: DecodeError -> SomeException

fromException :: SomeException -> Maybe DecodeError

displayException :: DecodeError -> String

Show DecodeError

Defined in Network.HPACK.Types

Methods

showsPrec :: Int -> DecodeError -> ShowS

show :: DecodeError -> String

showList :: [DecodeError] -> ShowS

Eq DecodeError

Defined in Network.HPACK.Types

Methods

(==) :: DecodeError -> DecodeError -> Bool

(/=) :: DecodeError -> DecodeError -> Bool

data BufferOverrun

Buffer overrun exception.

Constructors

BufferOverrun

The buffer size is not enough

Instances

Exception BufferOverrun

Defined in Network.ByteOrder

Methods

toException :: BufferOverrun -> SomeException

fromException :: SomeException -> Maybe BufferOverrun

displayException :: BufferOverrun -> String

Show BufferOverrun

Defined in Network.ByteOrder

Methods

showsPrec :: Int -> BufferOverrun -> ShowS

show :: BufferOverrun -> String

showList :: [BufferOverrun] -> ShowS

Eq BufferOverrun

Defined in Network.ByteOrder

Methods

(==) :: BufferOverrun -> BufferOverrun -> Bool

(/=) :: BufferOverrun -> BufferOverrun -> Bool

Token header

type FieldValue = ByteString

Field value.

type TokenHeader = (Token, FieldValue)

TokenBased header.

type TokenHeaderList = [TokenHeader]

TokenBased header list.

toTokenHeaderTable :: [Header] -> IO TokenHeaderTable

Converting a header list of the http-types style to TokenHeaderList and ValueTable.

Value table

type ValueTable = Array Int (Maybe FieldValue)

An array to get FieldValue quickly. getHeaderValue should be used. Internally, the key is tokenIx.

type TokenHeaderTable = (TokenHeaderList, ValueTable)

A pair of token list and value table.

getFieldValue :: Token -> ValueTable -> Maybe FieldValue

Accessing FieldValue with Token.

getHeaderValue :: Token -> ValueTable -> Maybe FieldValue

Accessing FieldValue with Token.

Basic types

type Size = Int

Size in bytes.

type Index = Int

Index for table.

type Buffer = Ptr Word8

A pointer to Word8.

type BufferSize = Int

Size of a buffer.