|
Network.HTTP.Base | Portability | non-portable (not tested) | Stability | experimental | Maintainer | Sigbjorn Finne <sigbjorn.finne@gmail.com> |
|
|
|
|
|
Description |
Definitions of Request and Response types along with functions
for normalizing them. It is assumed to be an internal module; user
code should, if possible, import Network.HTTP to access the functionality
that this module provides.
Additionally, the module exports internal functions for working with URLs,
and for handling the processing of requests and responses coming back.
|
|
Synopsis |
|
httpVersion :: String | | data Request a = Request {} | | data Response a = Response {} | | | | type Request_String = Request String | | type Response_String = Response String | | type HTTPRequest a = Request a | | type HTTPResponse a = Response a | | urlEncode :: String -> String | | urlDecode :: String -> String | | urlEncodeVars :: [(String, String)] -> String | | data URIAuthority = URIAuthority {} | | parseURIAuthority :: String -> Maybe URIAuthority | | uriToAuthorityString :: URI -> String | | uriAuthToString :: URIAuth -> String | | uriAuthPort :: Maybe URI -> URIAuth -> Int | | reqURIAuth :: Request ty -> URIAuth | | parseResponseHead :: [String] -> Result ResponseData | | parseRequestHead :: [String] -> Result RequestData | | | | matchResponse :: RequestMethod -> ResponseCode -> ResponseNextStep | | type ResponseData = (ResponseCode, String, [Header]) | | type ResponseCode = (Int, Int, Int) | | type RequestData = (RequestMethod, URI, [Header]) | | data NormalizeRequestOptions ty = NormalizeRequestOptions {} | | defaultNormalizeRequestOptions :: NormalizeRequestOptions ty | | type RequestNormalizer ty = NormalizeRequestOptions ty -> Request ty -> Request ty | | normalizeRequest :: NormalizeRequestOptions ty -> Request ty -> Request ty | | splitRequestURI :: URI -> (String, URI) | | getAuth :: Monad m => Request ty -> m URIAuthority | | normalizeRequestURI :: Bool -> String -> Request ty -> Request ty | | normalizeHostHeader :: Request ty -> Request ty | | findConnClose :: [Header] -> Bool | | linearTransfer :: (Int -> IO (Result a)) -> Int -> IO (Result ([Header], a)) | | hopefulTransfer :: BufferOp a -> IO (Result a) -> [a] -> IO (Result ([Header], a)) | | chunkedTransfer :: BufferOp a -> IO (Result a) -> (Int -> IO (Result a)) -> IO (Result ([Header], a)) | | uglyDeathTransfer :: String -> IO (Result ([Header], a)) | | readTillEmpty1 :: BufferOp a -> IO (Result a) -> IO (Result [a]) | | readTillEmpty2 :: BufferOp a -> IO (Result a) -> [a] -> IO (Result [a]) | | defaultGETRequest :: URI -> Request_String | | defaultGETRequest_ :: BufferType a => URI -> Request a | | mkRequest :: BufferType ty => RequestMethod -> URI -> Request ty | | defaultUserAgent :: String | | libUA :: String | | catchIO :: IO a -> (IOException -> IO a) -> IO a | | catchIO_ :: IO a -> IO a -> IO a | | responseParseError :: String -> String -> Result a | | getRequestVersion :: Request a -> Maybe String | | getResponseVersion :: Response a -> Maybe String | | setRequestVersion :: String -> Request a -> Request a | | setResponseVersion :: String -> Response a -> Response a |
|
|
|
Constants
|
|
httpVersion :: String |
|
HTTP
|
|
data Request a |
An HTTP Request.
The Show instance of this type is used for message serialisation,
which means no body data is output.
| Constructors | Request | | rqURI :: URI | might need changing in future
1) to support * uri in OPTIONS request
2) transparent support for both relative
& absolute uris, although this should
already work (leave scheme & host parts empty).
| rqMethod :: RequestMethod | | rqHeaders :: [Header] | | rqBody :: a | |
|
| Instances | |
|
|
data Response a |
An HTTP Response.
The Show instance of this type is used for message serialisation,
which means no body data is output, additionally the output will
show an HTTP version of 1.1 instead of the actual version returned
by a server.
| Constructors | | Instances | |
|
|
data RequestMethod |
The HTTP request method, to be used in the Request object.
We are missing a few of the stranger methods, but these are
not really necessary until we add full TLS.
| Constructors | HEAD | | PUT | | GET | | POST | | DELETE | | OPTIONS | | TRACE | | CONNECT | | Custom String | |
| Instances | |
|
|
type Request_String = Request String |
|
type Response_String = Response String |
|
type HTTPRequest a = Request a |
|
type HTTPResponse a = Response a |
|
URL Encoding
|
|
urlEncode :: String -> String |
|
urlDecode :: String -> String |
|
urlEncodeVars :: [(String, String)] -> String |
|
URI authority parsing
|
|
data URIAuthority |
Constructors | | Instances | |
|
|
parseURIAuthority :: String -> Maybe URIAuthority |
Parse the authority part of a URL.
RFC 1732, section 3.1:
//<user>:<password>@<host>:<port>/<url-path>
Some or all of the parts "<user>:<password>@", ":<password>",
":<port>", and "/<url-path>" may be excluded.
|
|
uriToAuthorityString :: URI -> String |
|
uriAuthToString :: URIAuth -> String |
|
uriAuthPort :: Maybe URI -> URIAuth -> Int |
|
reqURIAuth :: Request ty -> URIAuth |
|
parseResponseHead :: [String] -> Result ResponseData |
|
parseRequestHead :: [String] -> Result RequestData |
|
data ResponseNextStep |
Constructors | Continue | | Retry | | Done | | ExpectEntity | | DieHorribly String | |
|
|
|
matchResponse :: RequestMethod -> ResponseCode -> ResponseNextStep |
|
type ResponseData = (ResponseCode, String, [Header]) |
ResponseData contains the head of a response payload;
HTTP response code, accompanying text description + header
fields.
|
|
type ResponseCode = (Int, Int, Int) |
For easy pattern matching, HTTP response codes xyz are
represented as (x,y,z).
|
|
type RequestData = (RequestMethod, URI, [Header]) |
RequestData contains the head of a HTTP request; method,
its URL along with the auxillary/supporting header data.
|
|
data NormalizeRequestOptions ty |
|
|
defaultNormalizeRequestOptions :: NormalizeRequestOptions ty |
|
type RequestNormalizer ty = NormalizeRequestOptions ty -> Request ty -> Request ty |
RequestNormalizer is the shape of a (pure) function that rewrites
a request into some normalized form.
|
|
normalizeRequest :: NormalizeRequestOptions ty -> Request ty -> Request ty |
normalizeRequest opts req is the entry point to use to normalize your
request prior to transmission (or other use.) Normalization is controlled
via the NormalizeRequestOptions record.
|
|
splitRequestURI :: URI -> (String, URI) |
|
getAuth :: Monad m => Request ty -> m URIAuthority |
getAuth req fishes out the authority portion of the URL in a request's Host
header.
|
|
normalizeRequestURI :: Bool -> String -> Request ty -> Request ty |
|
normalizeHostHeader :: Request ty -> Request ty |
|
findConnClose :: [Header] -> Bool |
|
linearTransfer :: (Int -> IO (Result a)) -> Int -> IO (Result ([Header], a)) |
Used when we know exactly how many bytes to expect.
|
|
hopefulTransfer :: BufferOp a -> IO (Result a) -> [a] -> IO (Result ([Header], a)) |
Used when nothing about data is known,
Unfortunately waiting for a socket closure
causes bad behaviour. Here we just
take data once and give up the rest.
|
|
chunkedTransfer :: BufferOp a -> IO (Result a) -> (Int -> IO (Result a)) -> IO (Result ([Header], a)) |
A necessary feature of HTTP/1.1
Also the only transfer variety likely to
return any footers.
|
|
uglyDeathTransfer :: String -> IO (Result ([Header], a)) |
Maybe in the future we will have a sensible thing
to do here, at that time we might want to change
the name.
|
|
readTillEmpty1 :: BufferOp a -> IO (Result a) -> IO (Result [a]) |
Remove leading crlfs then call readTillEmpty2 (not required by RFC)
|
|
readTillEmpty2 :: BufferOp a -> IO (Result a) -> [a] -> IO (Result [a]) |
Read lines until an empty line (CRLF),
also accepts a connection close as end of
input, which is not an HTTP/1.1 compliant
thing to do - so probably indicates an
error condition.
|
|
defaultGETRequest :: URI -> Request_String |
|
defaultGETRequest_ :: BufferType a => URI -> Request a |
|
mkRequest :: BufferType ty => RequestMethod -> URI -> Request ty |
'mkRequest method uri' constructs a well formed
request for the given HTTP method and URI. It does not
normalize the URI for the request _nor_ add the required
Host: header. That is done either explicitly by the user
or when requests are normalized prior to transmission.
|
|
defaultUserAgent :: String |
|
libUA :: String |
|
catchIO :: IO a -> (IOException -> IO a) -> IO a |
catchIO a h handles IO action exceptions throughout codebase; version-specific
tweaks better go here.
|
|
catchIO_ :: IO a -> IO a -> IO a |
|
responseParseError :: String -> String -> Result a |
|
getRequestVersion :: Request a -> Maybe String |
getRequestVersion req returns the HTTP protocol version of
the request req. If Nothing, the default httpVersion can be assumed.
|
|
getResponseVersion :: Response a -> Maybe String |
getResponseVersion rsp returns the HTTP protocol version of
the response rsp. If Nothing, the default httpVersion can be
assumed.
|
|
setRequestVersion :: String -> Request a -> Request a |
setRequestVersion v req returns a new request, identical to
req, but with its HTTP version set to v.
|
|
setResponseVersion :: String -> Response a -> Response a |
setResponseVersion v rsp returns a new response, identical to
rsp, but with its HTTP version set to v.
|
|
Produced by Haddock version 2.5.0 |