Safe Haskell	None
Language	Haskell2010

Network.HTTP2

Contents

Frame
Encoding
Decoding
Decoding payload
Frame type ID
Frame type
Priority
Stream identifier
Stream identifier related
Flags
SettingsList
Settings
Window
Error code
Error
Predefined values

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

Eq Frame Source #
Methods (==) :: Frame -> Frame -> Bool # (/=) :: Frame -> Frame -> Bool #
Read Frame Source #
Methods readsPrec :: Int -> ReadS Frame # readList :: ReadS [Frame] # readPrec :: ReadPrec Frame # readListPrec :: ReadPrec [Frame] #
Show Frame Source #
Methods showsPrec :: Int -> Frame -> ShowS # show :: Frame -> String # showList :: [Frame] -> ShowS #

data FrameHeader Source #

The data type for HTTP/2 frame headers.

Constructors

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

Instances

Eq FrameHeader Source #
Methods (==) :: FrameHeader -> FrameHeader -> Bool # (/=) :: FrameHeader -> FrameHeader -> Bool #
Read FrameHeader Source #
Methods readsPrec :: Int -> ReadS FrameHeader # readList :: ReadS [FrameHeader] # readPrec :: ReadPrec FrameHeader # readListPrec :: ReadPrec [FrameHeader] #
Show FrameHeader Source #
Methods showsPrec :: Int -> FrameHeader -> ShowS # show :: FrameHeader -> String # showList :: [FrameHeader] -> ShowS #

data FramePayload Source #

The data type for HTTP/2 frame payloads.

Instances

Eq FramePayload Source #
Methods (==) :: FramePayload -> FramePayload -> Bool # (/=) :: FramePayload -> FramePayload -> Bool #
Read FramePayload Source #
Methods readsPrec :: Int -> ReadS FramePayload # readList :: ReadS [FramePayload] # readPrec :: ReadPrec FramePayload # readListPrec :: ReadPrec [FramePayload] #
Show FramePayload Source #
Methods showsPrec :: Int -> FramePayload -> ShowS # show :: FramePayload -> String # showList :: [FramePayload] -> ShowS #

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

Read EncodeInfo Source #
Methods readsPrec :: Int -> ReadS EncodeInfo # readList :: ReadS [EncodeInfo] # readPrec :: ReadPrec EncodeInfo # readListPrec :: ReadPrec [EncodeInfo] #
Show EncodeInfo Source #
Methods showsPrec :: Int -> EncodeInfo -> ShowS # show :: EncodeInfo -> String # showList :: [EncodeInfo] -> ShowS #

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

Eq FrameTypeId Source #
Methods (==) :: FrameTypeId -> FrameTypeId -> Bool # (/=) :: FrameTypeId -> FrameTypeId -> Bool #
Ord FrameTypeId Source #
Methods compare :: FrameTypeId -> FrameTypeId -> Ordering # (<) :: FrameTypeId -> FrameTypeId -> Bool # (<=) :: FrameTypeId -> FrameTypeId -> Bool # (>) :: FrameTypeId -> FrameTypeId -> Bool # (>=) :: FrameTypeId -> FrameTypeId -> Bool # max :: FrameTypeId -> FrameTypeId -> FrameTypeId # min :: FrameTypeId -> FrameTypeId -> FrameTypeId #
Show FrameTypeId Source #
Methods showsPrec :: Int -> FrameTypeId -> ShowS # show :: FrameTypeId -> String # showList :: [FrameTypeId] -> ShowS #

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

Eq Priority Source #
Methods (==) :: Priority -> Priority -> Bool # (/=) :: Priority -> Priority -> Bool #
Read Priority Source #
Methods readsPrec :: Int -> ReadS Priority # readList :: ReadS [Priority] # readPrec :: ReadPrec Priority # readListPrec :: ReadPrec [Priority] #
Show Priority Source #
Methods showsPrec :: Int -> Priority -> ShowS # show :: Priority -> String # showList :: [Priority] -> ShowS #

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

Bounded SettingsKeyId Source #
Methods minBound :: SettingsKeyId # maxBound :: SettingsKeyId #
Enum SettingsKeyId Source #
Methods succ :: SettingsKeyId -> SettingsKeyId # pred :: SettingsKeyId -> SettingsKeyId # toEnum :: Int -> SettingsKeyId # fromEnum :: SettingsKeyId -> Int # enumFrom :: SettingsKeyId -> [SettingsKeyId] # enumFromThen :: SettingsKeyId -> SettingsKeyId -> [SettingsKeyId] # enumFromTo :: SettingsKeyId -> SettingsKeyId -> [SettingsKeyId] # enumFromThenTo :: SettingsKeyId -> SettingsKeyId -> SettingsKeyId -> [SettingsKeyId] #
Eq SettingsKeyId Source #
Methods (==) :: SettingsKeyId -> SettingsKeyId -> Bool # (/=) :: SettingsKeyId -> SettingsKeyId -> Bool #
Ord SettingsKeyId Source #
Methods compare :: SettingsKeyId -> SettingsKeyId -> Ordering # (<) :: SettingsKeyId -> SettingsKeyId -> Bool # (<=) :: SettingsKeyId -> SettingsKeyId -> Bool # (>) :: SettingsKeyId -> SettingsKeyId -> Bool # (>=) :: SettingsKeyId -> SettingsKeyId -> Bool # max :: SettingsKeyId -> SettingsKeyId -> SettingsKeyId # min :: SettingsKeyId -> SettingsKeyId -> SettingsKeyId #
Read SettingsKeyId Source #
Methods readsPrec :: Int -> ReadS SettingsKeyId # readList :: ReadS [SettingsKeyId] # readPrec :: ReadPrec SettingsKeyId # readListPrec :: ReadPrec [SettingsKeyId] #
Show SettingsKeyId Source #
Methods showsPrec :: Int -> SettingsKeyId -> ShowS # show :: SettingsKeyId -> String # showList :: [SettingsKeyId] -> ShowS #

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

Show Settings Source #
Methods showsPrec :: Int -> Settings -> ShowS # show :: Settings -> String # showList :: [Settings] -> ShowS #

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

Eq ErrorCodeId Source #
Methods (==) :: ErrorCodeId -> ErrorCodeId -> Bool # (/=) :: ErrorCodeId -> ErrorCodeId -> Bool #
Ord ErrorCodeId Source #
Methods compare :: ErrorCodeId -> ErrorCodeId -> Ordering # (<) :: ErrorCodeId -> ErrorCodeId -> Bool # (<=) :: ErrorCodeId -> ErrorCodeId -> Bool # (>) :: ErrorCodeId -> ErrorCodeId -> Bool # (>=) :: ErrorCodeId -> ErrorCodeId -> Bool # max :: ErrorCodeId -> ErrorCodeId -> ErrorCodeId # min :: ErrorCodeId -> ErrorCodeId -> ErrorCodeId #
Read ErrorCodeId Source #
Methods readsPrec :: Int -> ReadS ErrorCodeId # readList :: ReadS [ErrorCodeId] # readPrec :: ReadPrec ErrorCodeId # readListPrec :: ReadPrec [ErrorCodeId] #
Show ErrorCodeId Source #
Methods showsPrec :: Int -> ErrorCodeId -> ShowS # show :: ErrorCodeId -> String # showList :: [ErrorCodeId] -> ShowS #

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

Eq HTTP2Error Source #
Methods (==) :: HTTP2Error -> HTTP2Error -> Bool # (/=) :: HTTP2Error -> HTTP2Error -> Bool #
Read HTTP2Error Source #
Methods readsPrec :: Int -> ReadS HTTP2Error # readList :: ReadS [HTTP2Error] # readPrec :: ReadPrec HTTP2Error # readListPrec :: ReadPrec [HTTP2Error] #
Show HTTP2Error Source #
Methods showsPrec :: Int -> HTTP2Error -> ShowS # show :: HTTP2Error -> String # showList :: [HTTP2Error] -> ShowS #
Exception HTTP2Error Source #
Methods toException :: HTTP2Error -> SomeException # fromException :: SomeException -> Maybe HTTP2Error # displayException :: HTTP2Error -> String #

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

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