Portability | non-portable (not tested) |
---|---|
Stability | experimental |
Maintainer | bjorn@bringert.net |
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
tothrow
- Added simpleHTTP_, which takes a stream argument. - Changes from 0.1
- change
openHTTP
toopenTCP
, removedcloseTCP
- useclose
fromStream
class. - added use of inet_addr to openHTTP, allowing use of IP dot notation addresses. - reworking of the use of Stream, including alterations to makesendHTTP
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).
- module Happstack.Server.HTTPClient.Stream
- module Happstack.Server.HTTPClient.TCP
- httpVersion :: String
- data Request = Request {}
- data Response = Response {}
- data RequestMethod
- simpleHTTP :: Request -> IO (Result Response)
- simpleHTTP_ :: Stream s => s -> Request -> IO (Result Response)
- sendHTTP :: Stream s => s -> Request -> IO (Result Response)
- sendHTTPPipelined :: Stream s => s -> [Request] -> IO ([Response], Maybe ConnError)
- 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
Documentation
Constants
HTTP
An HTTP Request.
The Show
instance of this type is used for message serialisation,
which means no body data is output.
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.
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.
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.
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
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.
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
urlEncodeVars :: [(String, String)] -> StringSource