Network.HTTP

An easy HTTP interface enjoy.

• Changes by Robin Bate Boerop [e-mail]: - Made dependencies explicit in import statements. - Removed false dependencies in import statements. - Added missing type signatures. - Moved Header-related code to Network.HTTP.Headers module.
• 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).

Documentation

module Network.Stream

module Network.TCP

Constants

httpVersion :: String

HTTP

data Request

An HTTP Request. The Show instance of this type is used for message serialisation, which means no body data is output.

Constructors

Request

Fields

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 :: String

Instances

Show Request

Typeable Request

HasHeaders Request

type RequestData = (RequestMethod, URI, [Header])

data Response

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

Fields

rspCode :: ResponseCode

rspReason :: String

rspHeaders :: [Header]

rspBody :: String

Instances

Show Response

Typeable Response

HasHeaders Response

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

Custom String

Instances

Eq RequestMethod

Show RequestMethod

type ResponseCode = (Int, Int, Int)

simpleHTTP :: Request -> IO (Result Response)

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)

Like simpleHTTP, but acting on an already opened stream.

sendHTTP :: Stream s => s -> Request -> IO (Result Response)

receiveHTTP :: Stream s => s -> IO (Result Request)

Receive and parse a HTTP request from the given Stream. Should be used for server side interactions.

processRequest :: Stream s => s -> RequestData -> IO (Result Request)

Process request body (called after successful getRequestHead)

getRequestHead :: Stream s => s -> IO (Result RequestData)

Reads and parses request headers.

respondHTTP :: Stream s => s -> Response -> IO ()

Very simple function, send a HTTP response over the given stream. This could be improved on to use different transfer types.

Header Functions

module Network.HTTP.Headers

URL Encoding

urlEncode :: String -> String

Converts a single value to the application/x-www-form-urlencoded encoding.

urlDecode :: String -> String

Converts a single value from the application/x-www-form-urlencoded encoding.

urlEncodeVars :: [(String, String)] -> String

Formats name-value pairs as application/x-www-form-urlencoded.

URI authority parsing

data URIAuthority

Constructors

URIAuthority

Fields

user :: Maybe String

password :: Maybe String

host :: String

port :: Maybe Int

Instances

Eq URIAuthority

Show URIAuthority

getAuth :: Monad m => Request -> m URIAuthority

parseURIAuthority :: String -> Maybe URIAuthority

Parse the authority part of a URL.

 RFC 1738, 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.