HTTP-3001.0.0Source codeContentsIndex
Network.HTTP
Portabilitynon-portable (not tested)
Stabilityexperimental
Maintainer[email protected]
Contents
Constants
HTTP
Header Functions
URL Encoding
URI authority parsing
Description

An easy HTTP interface enjoy.

  • Changes by Simon Foster: - Split module up into to sepearate Network.[Stream,TCP,HTTP] modules - Created functions receiveHTTP and responseHTTP to allow server side interactions (although 100-continue is unsupported and I haven't checked for standard compliancy). - Pulled the transfer functions from sendHTTP to global scope to allow access by above functions.
  • Changes by Graham Klyne: - export httpVersion - use new URI module (similar to old, but uses revised URI datatype)
  • Changes by Bjorn Bringert:
  • handle URIs with a port number - added debugging toggle - disabled 100-continue transfers to get HTTP/1.0 compatibility - change ioError to throw - Added simpleHTTP_, which takes a stream argument.
  • Changes from 0.1 - change openHTTP to openTCP, removed closeTCP - use close from Stream class. - added use of inet_addr to openHTTP, allowing use of IP dot notation addresses. - reworking of the use of Stream, including alterations to make sendHTTP generic and the addition of a debugging stream. - simplified error handling.
  • TODO - request pipelining - https upgrade (includes full TLS, i.e. SSL, implementation) - use of Stream classes will pay off - consider C implementation of encryption/decryption - comm timeouts - MIME & entity stuff (happening in separate module) - support "*" uri-request-string for OPTIONS request method
  • Header notes:
Host
Required by HTTP/1.1, if not supplied as part of a request a default Host value is extracted from the request-uri.
Connection
If this header is present in any request or response, and it's value is close, then the current request/response is the last to be allowed on that connection.
Expect
Should a request contain a body, an Expect header will be added to the request. The added header has the value "100-continue". After a 417 "Expectation Failed" response the request is attempted again without this added Expect header.
TransferEncoding,ContentLength,...
if request is inconsistent with any of these header values then you may not receive any response or will generate an error response (probably 4xx).
  • Response code notes Some response codes induce special behaviour:
1xx
"100 Continue" will cause any unsent request body to be sent. "101 Upgrade" will be returned. Other 1xx responses are ignored.
417
The reason for this code is "Expectation failed", indicating that the server did not like the Expect "100-continue" header added to a request. Receipt of 417 will induce another request attempt (without Expect header), unless no Expect header had been added (in which case 417 response is returned).
Synopsis
module Network.Stream
module Network.TCP
httpVersion :: String
data Request = Request {
rqURI :: URI
rqMethod :: RequestMethod
rqHeaders :: [Header]
rqBody :: String
}
data Response = Response {
rspCode :: ResponseCode
rspReason :: String
rspHeaders :: [Header]
rspBody :: String
}
data RequestMethod
= HEAD
| PUT
| GET
| POST
| DELETE
| OPTIONS
| TRACE
type ResponseCode = (Int, Int, Int)
simpleHTTP :: Request -> IO (Result Response)
simpleHTTP_ :: Stream s => s -> Request -> IO (Result Response)
sendHTTP :: Stream s => s -> Request -> IO (Result Response)
receiveHTTP :: Stream s => s -> IO (Result Request)
respondHTTP :: Stream s => s -> Response -> IO ()
class HasHeaders x
data Header = Header HeaderName String
data HeaderName
= HdrCacheControl
| HdrConnection
| HdrDate
| HdrPragma
| HdrTransferEncoding
| HdrUpgrade
| HdrVia
| HdrAccept
| HdrAcceptCharset
| HdrAcceptEncoding
| HdrAcceptLanguage
| HdrAuthorization
| HdrCookie
| HdrExpect
| HdrFrom
| HdrHost
| HdrIfModifiedSince
| HdrIfMatch
| HdrIfNoneMatch
| HdrIfRange
| HdrIfUnmodifiedSince
| HdrMaxForwards
| HdrProxyAuthorization
| HdrRange
| HdrReferer
| HdrUserAgent
| HdrAge
| HdrLocation
| HdrProxyAuthenticate
| HdrPublic
| HdrRetryAfter
| HdrServer
| HdrSetCookie
| HdrVary
| HdrWarning
| HdrWWWAuthenticate
| HdrAllow
| HdrContentBase
| HdrContentEncoding
| HdrContentLanguage
| HdrContentLength
| HdrContentLocation
| HdrContentMD5
| HdrContentRange
| HdrContentType
| HdrETag
| HdrExpires
| HdrLastModified
| HdrContentTransferEncoding
| HdrCustom String
insertHeader :: HasHeaders a => HeaderName -> String -> a -> a
insertHeaderIfMissing :: HasHeaders a => HeaderName -> String -> a -> a
insertHeaders :: HasHeaders a => [Header] -> a -> a
retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header]
replaceHeader :: HasHeaders a => HeaderName -> String -> a -> a
findHeader :: HasHeaders a => HeaderName -> a -> Maybe String
urlEncode :: String -> String
urlDecode :: String -> String
urlEncodeVars :: [(String, String)] -> String
data URIAuthority = URIAuthority {
user :: Maybe String
password :: Maybe String
host :: String
port :: Maybe Int
}
parseURIAuthority :: String -> Maybe URIAuthority
Documentation
module Network.Stream
module Network.TCP
Constants
httpVersion :: StringSource
HTTP
data Request Source
An HTTP Request. The Show instance of this type is used for message serialisation, which means no body data is output.
Constructors
Request
rqURI :: URImight 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 :: String
show/hide Instances
data Response Source
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
Response
rspCode :: ResponseCode
rspReason :: String
rspHeaders :: [Header]
rspBody :: String
show/hide Instances
data RequestMethod Source
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
show/hide Instances
type ResponseCode = (Int, Int, Int)Source
simpleHTTP :: Request -> IO (Result Response)Source
Simple way to get a resource across a non-persistant connection. Headers that may be altered: Host Altered only if no Host header is supplied, HTTP/1.1 requires a Host header. Connection Where no allowance is made for persistant connections the Connection header will be set to close
simpleHTTP_ :: Stream s => s -> Request -> IO (Result Response)Source
Like simpleHTTP, but acting on an already opened stream.
sendHTTP :: Stream s => s -> Request -> IO (Result Response)Source
receiveHTTP :: Stream s => s -> IO (Result Request)Source
Receive and parse a HTTP request from the given Stream. Should be used for server side interactions.
respondHTTP :: Stream s => s -> Response -> IO ()Source
Very simple function, send a HTTP response over the given stream. This could be improved on to use different transfer types.
Header Functions
class HasHeaders x Source
This class allows us to write generic header manipulation functions for both Request and Response data types.
show/hide Instances
data Header Source
The Header data type pairs header names & values.
Constructors
Header HeaderName String
show/hide Instances
data HeaderName Source

HTTP Header Name type: Why include this at all? I have some reasons 1) prevent spelling errors of header names, 2) remind everyone of what headers are available, 3) might speed up searches for specific headers.

Arguments against: 1) makes customising header names laborious 2) increases code volume.

Constructors
HdrCacheControl
HdrConnection
HdrDate
HdrPragma
HdrTransferEncoding
HdrUpgrade
HdrVia
HdrAccept
HdrAcceptCharset
HdrAcceptEncoding
HdrAcceptLanguage
HdrAuthorization
HdrCookie
HdrExpect
HdrFrom
HdrHost
HdrIfModifiedSince
HdrIfMatch
HdrIfNoneMatch
HdrIfRange
HdrIfUnmodifiedSince
HdrMaxForwards
HdrProxyAuthorization
HdrRange
HdrReferer
HdrUserAgent
HdrAge
HdrLocation
HdrProxyAuthenticate
HdrPublic
HdrRetryAfter
HdrServer
HdrSetCookie
HdrVary
HdrWarning
HdrWWWAuthenticate
HdrAllow
HdrContentBase
HdrContentEncoding
HdrContentLanguage
HdrContentLength
HdrContentLocation
HdrContentMD5
HdrContentRange
HdrContentType
HdrETag
HdrExpires
HdrLastModified
HdrContentTransferEncoding
HdrCustom StringAllows for unrecognised or experimental headers.
show/hide Instances
insertHeader :: HasHeaders a => HeaderName -> String -> a -> aSource
insertHeaderIfMissing :: HasHeaders a => HeaderName -> String -> a -> aSource
insertHeaders :: HasHeaders a => [Header] -> a -> aSource

Inserts a header with the given name and value. Allows duplicate header names.

Adds the new header only if no previous header shares the same name.

Removes old headers with duplicate name.

Inserts multiple headers.

retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header]Source
Gets a list of headers with a particular HeaderName.
replaceHeader :: HasHeaders a => HeaderName -> String -> a -> aSource
findHeader :: HasHeaders a => HeaderName -> a -> Maybe StringSource
Lookup presence of specific HeaderName in a list of Headers Returns the value from the first matching header.
URL Encoding
urlEncode :: String -> StringSource
urlDecode :: String -> StringSource
urlEncodeVars :: [(String, String)] -> StringSource
URI authority parsing
data URIAuthority Source
Constructors
URIAuthority
user :: Maybe String
password :: Maybe String
host :: String
port :: Maybe Int
show/hide Instances
parseURIAuthority :: String -> Maybe URIAuthoritySource

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.
Produced by Haddock version 2.6.0