http2-1.4.3: HTTP/2.0 library including frames and HPACK

Safe HaskellNone
LanguageHaskell2010

Network.HTTP2

Contents

Description

Framing in HTTP/2(https://tools.ietf.org/html/rfc7540).

Synopsis

Frame

data Frame Source

The data type for HTTP/2 frames.

Constructors

Frame 

Fields

frameHeader :: !FrameHeader
 
framePayload :: !FramePayload
 

Instances

data FrameHeader Source

The data type for HTTP/2 frame headers.

Constructors

FrameHeader 

Fields

payloadLength :: !Int
 
flags :: !FrameFlags
 
streamId :: !StreamId
 

Instances

data FramePayload Source

The data type for HTTP/2 frame payloads.

Constructors

DataFrame !ByteString 
HeadersFrame !(Maybe Priority) !HeaderBlockFragment 
PriorityFrame !Priority 
RSTStreamFrame !ErrorCodeId 
SettingsFrame !SettingsList 
PushPromiseFrame !StreamId !HeaderBlockFragment 
PingFrame !ByteString 
GoAwayFrame !StreamId !ErrorCodeId !ByteString 
WindowUpdateFrame !WindowSize 
ContinuationFrame !HeaderBlockFragment 
UnknownFrame !FrameType !ByteString 

Instances

type HeaderBlockFragment = ByteString Source

The type for fragments of a header encoded with HPACK.

type Padding = ByteString Source

The type for padding in payloads.

isPaddingDefined :: FramePayload -> Bool Source

Checking if padding is defined in this frame type.

>>> isPaddingDefined $ DataFrame ""
True
>>> isPaddingDefined $ PingFrame ""
False

Encoding

encodeFrame :: EncodeInfo -> FramePayload -> ByteString Source

Encoding an HTTP/2 frame to ByteString. This function is not efficient enough for high performace program because of the concatenation of ByteString.

>>> encodeFrame (encodeInfo id 1) (DataFrame "body")
"\NUL\NUL\EOT\NUL\NUL\NUL\NUL\NUL\SOHbody"

encodeFrameChunks :: EncodeInfo -> FramePayload -> [ByteString] Source

Encoding an HTTP/2 frame to [ByteString]. This is suitable for sendMany.

encodeFrameHeader :: FrameTypeId -> FrameHeader -> ByteString Source

Encoding an HTTP/2 frame header. The frame header must be completed.

encodeFrameHeaderBuf :: FrameTypeId -> FrameHeader -> Ptr Word8 -> IO () Source

Writing an encoded HTTP/2 frame header to the buffer. The length of the buffer must be larger than or equal to 9 bytes.

encodeFramePayload :: EncodeInfo -> FramePayload -> (FrameHeader, [ByteString]) Source

Encoding an HTTP/2 frame payload. This returns a complete frame header and chunks of payload.

data EncodeInfo Source

Auxiliary information for frame encoding.

Constructors

EncodeInfo 

Fields

encodeFlags :: !FrameFlags

Flags to be set in a frame header

encodeStreamId :: !StreamId

Stream id to be set in a frame header

encodePadding :: !(Maybe Padding)

Padding if any. In the case where this value is set but the priority flag is not set, this value gets preference over the priority flag. So, if this value is set, the priority flag is also set.

Instances

encodeInfo Source

Arguments

:: (FrameFlags -> FrameFlags) 
-> Int

stream identifier

-> EncodeInfo 

A smart builder of EncodeInfo.

>>> encodeInfo setAck 0
EncodeInfo {encodeFlags = 1, encodeStreamId = 0, encodePadding = Nothing}

Decoding

decodeFrame Source

Arguments

:: Settings

HTTP/2 settings

-> ByteString

Input byte-stream

-> Either HTTP2Error Frame

Decoded frame

Decoding an HTTP/2 frame to ByteString. The second argument must be include the entire of frame. So, this function is not useful for real applications but useful for testing.

decodeFrameHeader :: ByteString -> (FrameTypeId, FrameHeader) Source

Decoding an HTTP/2 frame header. Must supply 9 bytes.

checkFrameHeader :: Settings -> (FrameTypeId, FrameHeader) -> Either HTTP2Error (FrameTypeId, FrameHeader) Source

Checking a frame header and reporting an error if any.

>>> checkFrameHeader defaultSettings (FrameData,(FrameHeader 100 0 0))
Left (ConnectionError ProtocolError "cannot used in control stream")

Decoding payload

decodeFramePayload :: FrameTypeId -> FramePayloadDecoder Source

Decoding an HTTP/2 frame payload. This function is considered to return a frame payload decoder according to a frame type.

type FramePayloadDecoder = FrameHeader -> ByteString -> Either HTTP2Error FramePayload Source

The type for frame payload decoder.

decodeDataFrame :: FramePayloadDecoder Source

Frame payload decoder for DATA frame.

decodeHeadersFrame :: FramePayloadDecoder Source

Frame payload decoder for HEADERS frame.

decodePriorityFrame :: FramePayloadDecoder Source

Frame payload decoder for PRIORITY frame.

decoderstStreamFrame :: FramePayloadDecoder Source

Frame payload decoder for RST_STREAM frame.

decodeSettingsFrame :: FramePayloadDecoder Source

Frame payload decoder for SETTINGS frame.

decodePushPromiseFrame :: FramePayloadDecoder Source

Frame payload decoder for PUSH_PROMISE frame.

decodePingFrame :: FramePayloadDecoder Source

Frame payload decoder for PING frame.

decodeGoAwayFrame :: FramePayloadDecoder Source

Frame payload decoder for GOAWAY frame.

decodeWindowUpdateFrame :: FramePayloadDecoder Source

Frame payload decoder for WINDOW_UPDATE frame.

decodeContinuationFrame :: FramePayloadDecoder Source

Frame payload decoder for CONTINUATION frame.

Frame type ID

data FrameTypeId Source

The type for frame type.

Constructors

FrameData 
FrameHeaders 
FramePriority 
FrameRSTStream 
FrameSettings 
FramePushPromise 
FramePing 
FrameGoAway 
FrameWindowUpdate 
FrameContinuation 
FrameUnknown FrameType 

Instances

framePayloadToFrameTypeId :: FramePayload -> FrameTypeId Source

Getting FrameType from FramePayload.

>>> framePayloadToFrameTypeId (DataFrame "body")
FrameData

Frame type

type FrameType = Word8 Source

The type for raw frame type.

fromFrameTypeId :: FrameTypeId -> FrameType Source

Converting FrameTypeId to FrameType.

>>> fromFrameTypeId FrameData
0
>>> fromFrameTypeId FrameContinuation
9
>>> fromFrameTypeId (FrameUnknown 10)
10

toFrameTypeId :: FrameType -> FrameTypeId Source

Converting FrameType to FrameTypeId.

>>> toFrameTypeId 0
FrameData
>>> toFrameTypeId 9
FrameContinuation
>>> toFrameTypeId 10
FrameUnknown 10

Priority

data Priority Source

Type for stream priority

Constructors

Priority 

Fields

exclusive :: !Bool
 
streamDependency :: !StreamId
 
weight :: !Weight
 

Instances

type Weight = Int Source

The type for weight in priority. Its values are from 1 to 256.

defaultPriority :: Priority Source

Default priority which depends on stream 0.

>>> defaultPriority
Priority {exclusive = False, streamDependency = 0, weight = 16}

highestPriority :: Priority Source

Highest priority which depends on stream 0.

>>> highestPriority
Priority {exclusive = False, streamDependency = 0, weight = 256}

Stream identifier

type StreamId = Int Source

The type for stream identifier

isControl :: StreamId -> Bool Source

Checking if the stream identifier for control.

>>> isControl 0
True
>>> isControl 1
False

isRequest :: StreamId -> Bool Source

Checking if the stream identifier for request.

>>> isRequest 0
False
>>> isRequest 1
True

isResponse :: StreamId -> Bool Source

Checking if the stream identifier for response.

>>> isResponse 0
False
>>> isResponse 2
True

Stream identifier related

testExclusive :: StreamId -> Bool Source

Checking if the exclusive flag is set.

setExclusive :: StreamId -> StreamId Source

Setting the exclusive flag.

clearExclusive :: StreamId -> StreamId Source

Clearing the exclusive flag.

Flags

type FrameFlags = Word8 Source

The type for flags.

defaultFlags :: FrameFlags Source

The initial value of flags. No flags are set.

>>> defaultFlags
0

testEndStream :: FrameFlags -> Bool Source

Checking if the END_STREAM flag is set. >>> testEndStream 0x1 True

testAck :: FrameFlags -> Bool Source

Checking if the ACK flag is set. >>> testAck 0x1 True

testEndHeader :: FrameFlags -> Bool Source

Checking if the END_HEADERS flag is set.

>>> testEndHeader 0x4
True

testPadded :: FrameFlags -> Bool Source

Checking if the PADDED flag is set.

>>> testPadded 0x8
True

testPriority :: FrameFlags -> Bool Source

Checking if the PRIORITY flag is set.

>>> testPriority 0x20
True

setEndStream :: FrameFlags -> FrameFlags Source

Setting the END_STREAM flag.

>>> setEndStream 0
1

setAck :: FrameFlags -> FrameFlags Source

Setting the ACK flag.

>>> setAck 0
1

setEndHeader :: FrameFlags -> FrameFlags Source

Setting the END_HEADERS flag.

>>> setEndHeader 0
4

setPadded :: FrameFlags -> FrameFlags Source

Setting the PADDED flag.

>>> setPadded 0
8

setPriority :: FrameFlags -> FrameFlags Source

Setting the PRIORITY flag.

>>> setPriority 0
32

SettingsList

type SettingsList = [(SettingsKeyId, SettingsValue)] Source

Association list of SETTINGS.

data SettingsKeyId Source

The type for SETTINGS key.

Constructors

SettingsHeaderTableSize 
SettingsEnablePush 
SettingsMaxConcurrentStreams 
SettingsInitialWindowSize 
SettingsMaxFrameSize 
SettingsMaxHeaderBlockSize 

Instances

type SettingsValue = Int Source

The type for raw SETTINGS value.

fromSettingsKeyId :: SettingsKeyId -> Word16 Source

Converting SettingsKeyId to raw value.

>>> fromSettingsKeyId SettingsHeaderTableSize
1
>>> fromSettingsKeyId SettingsMaxHeaderBlockSize
6

toSettingsKeyId :: Word16 -> Maybe SettingsKeyId Source

Converting raw value to SettingsKeyId.

>>> toSettingsKeyId 0
Nothing
>>> toSettingsKeyId 1
Just SettingsHeaderTableSize
>>> toSettingsKeyId 6
Just SettingsMaxHeaderBlockSize
>>> toSettingsKeyId 7
Nothing

checkSettingsList :: SettingsList -> Maybe HTTP2Error Source

Checking SettingsList and reporting an error if any.

>>> checkSettingsList [(SettingsEnablePush,2)]
Just (ConnectionError ProtocolError "enable push must be 0 or 1")

Settings

data Settings Source

Cooked version of settings. This is suitable to be stored in a HTTP/2 context.

Constructors

Settings 

Fields

headerTableSize :: !Int
 
enablePush :: !Bool
 
maxConcurrentStreams :: !(Maybe Int)
 
initialWindowSize :: !WindowSize
 
maxFrameSize :: !Int
 
maxHeaderBlockSize :: !(Maybe Int)
 

Instances

defaultSettings :: Settings Source

The default settings.

>>> defaultSettings
Settings {headerTableSize = 4096, enablePush = True, maxConcurrentStreams = Nothing, initialWindowSize = 65535, maxFrameSize = 16384, maxHeaderBlockSize = Nothing}

updateSettings :: Settings -> SettingsList -> Settings Source

Updating settings.

>>> updateSettings defaultSettings [(SettingsEnablePush,0),(SettingsMaxHeaderBlockSize,200)]
Settings {headerTableSize = 4096, enablePush = False, maxConcurrentStreams = Nothing, initialWindowSize = 65535, maxFrameSize = 16384, maxHeaderBlockSize = Just 200}

Window

type WindowSize = Int Source

The type for window size.

defaultInitialWindowSize :: WindowSize Source

The default initial window size.

>>> defaultInitialWindowSize
65535

maxWindowSize :: WindowSize Source

The maximum window size.

>>> maxWindowSize
2147483647

isWindowOverflow :: WindowSize -> Bool Source

Checking if a window size exceeds the maximum window size.

>>> isWindowOverflow 10
False
>>> isWindowOverflow maxWindowSize
False
>>> isWindowOverflow (maxWindowSize + 1)
True

Error code

type ErrorCode = Word32 Source

The type for raw error code.

data ErrorCodeId Source

The type for error code. See https://tools.ietf.org/html/rfc7540#section-7.

Constructors

NoError 
ProtocolError 
InternalError 
FlowControlError 
SettingsTimeout 
StreamClosed 
FrameSizeError 
RefusedStream 
Cancel 
CompressionError 
ConnectError 
EnhanceYourCalm 
InadequateSecurity 
HTTP11Required 
UnknownErrorCode ErrorCode 

Instances

fromErrorCodeId :: ErrorCodeId -> ErrorCode Source

Converting ErrorCodeId to ErrorCode.

>>> fromErrorCodeId NoError
0
>>> fromErrorCodeId InadequateSecurity
12

toErrorCodeId :: ErrorCode -> ErrorCodeId Source

Converting ErrorCode to ErrorCodeId.

>>> toErrorCodeId 0
NoError
>>> toErrorCodeId 0xc
InadequateSecurity
>>> toErrorCodeId 0xe
UnknownErrorCode 14

Error

data HTTP2Error Source

The connection error or the stream error.

Constructors

ConnectionError !ErrorCodeId !ByteString 
StreamError !ErrorCodeId !StreamId 

Instances

errorCodeId :: HTTP2Error -> ErrorCodeId Source

Obtaining ErrorCodeId from HTTP2Error.

Predefined values

connectionPreface :: ByteString Source

The preface of HTTP/2.

>>> connectionPreface
"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"

connectionPrefaceLength :: Int Source

Length of the preface.

>>> connectionPrefaceLength
24

frameHeaderLength :: Int Source

The length of HTTP/2 frame header.

>>> frameHeaderLength
9

maxPayloadLength :: Int Source

The maximum length of HTTP/2 payload.

>>> maxPayloadLength
16384

recommendedConcurrency :: Int Source

Default concurrency.

>>> recommendedConcurrency
100