Network.HTTP.Toolkit

Exceptions

• All functions that consume input fail with UnexpectedEndOfInput if the input ends before the function can completely successfully.
• All cases where a function may fail with an exception other than UnexpectedEndOfInput are documented thoroughly on a per function level.

data ToolkitError

Constructors

UnexpectedEndOfInput

The input ended unpexpectedly while reading a message.

InvalidRequestLine ByteString

The request-line of the message is malformed.

InvalidStatusLine ByteString

The status-line of the message is malformed.

InvalidHeader

A header field is malformed.

HeaderTooLarge

The start-line of the message and all header fields together exceed the specified size Limit.

ChunkTooLarge

The size of a body chunk exceeds maxChunkSize.

InvalidChunk

A body chunk is malformed.

Instances

Eq ToolkitError

Show ToolkitError

Typeable ToolkitError

Exception ToolkitError

Input handling

data InputStream

An abstraction for input streams that allows to read and unread input.

makeInputStream :: IO ByteString -> IO InputStream

Create an InputStream from provided IO action.

inputStreamFromHandle :: Handle -> IO InputStream

Create an InputStream from provided Handle.

Handling requests

type RequestPath = ByteString

data Request a

Constructors

Request

Fields

requestMethod :: Method

requestPath :: RequestPath

requestHeaders :: [Header]

requestBody :: a

Instances

Functor Request

Foldable Request

Traversable Request

Eq a => Eq (Request a)

Show a => Show (Request a)

readRequestWithLimit :: Limit -> Bool -> InputStream -> IO (Request BodyReader)

Read request from provided InputStream.

The second argument is passed to makeChunkedReader.

Throws:

• InvalidRequestLine if request-line is malformed.
• HeaderTooLarge if request-line and headers together exceed the specified size Limit
• InvalidHeader if request-line is missing or a header is malformed

readRequest :: Bool -> InputStream -> IO (Request BodyReader)

Same as readRequestWithLimit with a Limit of defaultHeaderSizeLimit.

sendRequest :: (ByteString -> IO ()) -> Request BodyReader -> IO ()

Send an HTTP request.

Note: The first argument to this function is used to send the data. For space efficiency it may be called multiple times.

Handling responses

data Response a

Constructors

Response

Fields

responseStatus :: Status

responseHeaders :: [Header]

responseBody :: a

Instances

Functor Response

Foldable Response

Traversable Response

Eq a => Eq (Response a)

Show a => Show (Response a)

readResponseWithLimit :: Limit -> Bool -> Method -> InputStream -> IO (Response BodyReader)

Read response from provided InputStream.

The second argument is passed to makeChunkedReader.

The corresponding request Method has to be specified so that the body length can be determined (see RFC 2616, Section 4.4).

Throws:

• InvalidStatusLine if status-line is malformed.
• HeaderTooLarge if status-line and headers together exceed the specified size Limit
• InvalidHeader if status-line is missing or a header is malformed

readResponse :: Bool -> Method -> InputStream -> IO (Response BodyReader)

Same as readResponseWithLimit with a Limit of defaultHeaderSizeLimit.

sendResponse :: (ByteString -> IO ()) -> Response BodyReader -> IO ()

Send an HTTP response.

Note: The first argument to this function is used to send the data. For space efficiency it may be called multiple times.

simpleResponse :: (ByteString -> IO ()) -> Status -> [Header] -> ByteString -> IO ()

Send a simple HTTP response. The provided ByteString is used as the message body. A suitable Content-Length header is added to the specified list of headers.

Note: The first argument to this function is used to send the data. For space efficiency it may be called multiple times.

Handling message bodies

type BodyReader = IO ByteString

A reader for HTTP bodies. It returns chunks of the body as long as there is more data to consume. When the body has been fully consumed, it returns empty.

sendBody :: (ByteString -> IO ()) -> BodyReader -> IO ()

Read input from provided BodyReader and wirte it to provided sink until all input has been consumed.

Note: The first argument to this function is used to send the data. For space efficiency it may be called multiple times.

consumeBody :: BodyReader -> IO ByteString

Strictly consume all input from provided BodyReader.

Deprecated types and functions

type Connection = InputStream

makeConnection :: IO ByteString -> IO Connection

connectionFromHandle :: Handle -> IO Connection