-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A library for client-side HTTP, version 2. Rewrite of existing HTTP -- package to allow overloaded representation of HTTP request bodies and -- responses. Provides three such instances: lazy and strict -- ByteString, along with the good old String. Inspired -- in part by Jonas Aadahl et al's work on ByteString'ifying HTTP a -- couple of years ago. Git repository available at -- http://code.galois.com/HTTPbis.git @package HTTP @version 4000.0.0 -- | An library for creating abstract streams. Originally part of -- Gray's\/Bringert's HTTP module. -- -- module Network.Stream -- | Streams should make layering of TLS protocol easier in future, they -- allow reading/writing to files etc for debugging, they allow use of -- protocols other than TCP/IP and they allow customisation. -- -- Instances of this class should not trim the input in any way, e.g. -- leave LF on line endings etc. Unless that is exactly the behaviour you -- want from your twisted instances ;) class Stream x readLine :: (Stream x) => x -> IO (Result String) readBlock :: (Stream x) => x -> Int -> IO (Result String) writeBlock :: (Stream x) => x -> String -> IO (Result ()) close :: (Stream x) => x -> IO () data ConnError ErrorReset :: ConnError ErrorClosed :: ConnError ErrorParse :: String -> ConnError ErrorMisc :: String -> ConnError -- | This is the type returned by many exported network functions. type Result a = Either ConnError a bindE :: Result a -> (a -> Result b) -> Result b instance Show ConnError instance Eq ConnError -- | -- -- See changes history and TODO list in Network.HTTP module. -- -- -- -- module Network.HTTP.Headers -- | This class allows us to write generic header manipulation functions -- for both Request and Response data types. class HasHeaders x getHeaders :: (HasHeaders x) => x -> [Header] setHeaders :: (HasHeaders x) => x -> [Header] -> x -- | The Header data type pairs header names & values. data Header Header :: HeaderName -> String -> Header -- | 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. -- -- Long discussions can be had on this topic! data HeaderName HdrCacheControl :: HeaderName HdrConnection :: HeaderName HdrDate :: HeaderName HdrPragma :: HeaderName HdrTransferEncoding :: HeaderName HdrUpgrade :: HeaderName HdrVia :: HeaderName HdrAccept :: HeaderName HdrAcceptCharset :: HeaderName HdrAcceptEncoding :: HeaderName HdrAcceptLanguage :: HeaderName HdrAuthorization :: HeaderName HdrCookie :: HeaderName HdrExpect :: HeaderName HdrFrom :: HeaderName HdrHost :: HeaderName HdrIfModifiedSince :: HeaderName HdrIfMatch :: HeaderName HdrIfNoneMatch :: HeaderName HdrIfRange :: HeaderName HdrIfUnmodifiedSince :: HeaderName HdrMaxForwards :: HeaderName HdrProxyAuthorization :: HeaderName HdrRange :: HeaderName HdrReferer :: HeaderName HdrUserAgent :: HeaderName HdrAge :: HeaderName HdrLocation :: HeaderName HdrProxyAuthenticate :: HeaderName HdrPublic :: HeaderName HdrRetryAfter :: HeaderName HdrServer :: HeaderName HdrSetCookie :: HeaderName HdrVary :: HeaderName HdrWarning :: HeaderName HdrWWWAuthenticate :: HeaderName HdrAllow :: HeaderName HdrContentBase :: HeaderName HdrContentEncoding :: HeaderName HdrContentLanguage :: HeaderName HdrContentLength :: HeaderName HdrContentLocation :: HeaderName HdrContentMD5 :: HeaderName HdrContentRange :: HeaderName HdrContentType :: HeaderName HdrETag :: HeaderName HdrExpires :: HeaderName HdrLastModified :: HeaderName -- | MIME entity headers (for sub-parts) HdrContentTransferEncoding :: HeaderName -- | Allows for unrecognised or experimental headers. HdrCustom :: String -> HeaderName insertHeader :: (HasHeaders a) => HeaderName -> String -> a -> a insertHeaderIfMissing :: (HasHeaders a) => HeaderName -> String -> a -> a -- | 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. insertHeaders :: (HasHeaders a) => [Header] -> a -> a -- | Gets a list of headers with a particular HeaderName. retrieveHeaders :: (HasHeaders a) => HeaderName -> a -> [Header] replaceHeader :: (HasHeaders a) => HeaderName -> String -> a -> a -- | Lookup presence of specific HeaderName in a list of Headers Returns -- the value from the first matching header. findHeader :: (HasHeaders a) => HeaderName -> a -> Maybe String lookupHeader :: HeaderName -> [Header] -> Maybe String parseHeaders :: [String] -> Result [Header] instance Eq HeaderName instance Show HeaderName instance Show Header -- | Operations over wire-transmitted values. module Network.BufferType -- | The BufferType class encodes, in a mixed-mode way, the -- interface that the library requires to operate over data embedded in -- HTTP requests and responses. That is, we use explicit dictionaries for -- the operations, but overload the name of these dicts. class BufferType bufType bufferOps :: (BufferType bufType) => BufferOp bufType data BufferOp a BufferOp :: (Handle -> Int -> IO a) -> (Handle -> IO a) -> (Handle -> a -> IO ()) -> (Handle -> IO a) -> a -> (a -> a -> a) -> (String -> a) -> (a -> String) -> (a -> Word8 -> a) -> (Int -> a -> (a, a)) -> ((Char -> Bool) -> a -> (a, a)) -> (a -> Bool) -> (a -> Bool) -> BufferOp a buf_hGet :: BufferOp a -> Handle -> Int -> IO a buf_hGetContents :: BufferOp a -> Handle -> IO a buf_hPut :: BufferOp a -> Handle -> a -> IO () buf_hGetLine :: BufferOp a -> Handle -> IO a buf_empty :: BufferOp a -> a buf_append :: BufferOp a -> a -> a -> a buf_fromStr :: BufferOp a -> String -> a buf_toStr :: BufferOp a -> a -> String buf_snoc :: BufferOp a -> a -> Word8 -> a buf_splitAt :: BufferOp a -> Int -> a -> (a, a) buf_span :: BufferOp a -> (Char -> Bool) -> a -> (a, a) buf_isLineTerm :: BufferOp a -> a -> Bool buf_isEmpty :: BufferOp a -> a -> Bool strictBufferOp :: BufferOp ByteString lazyBufferOp :: BufferOp ByteString stringBufferOp :: BufferOp String instance Eq (BufferOp a) instance BufferType String instance BufferType ByteString instance BufferType ByteString -- | An easy HTTP interface; base types. module Network.HTTP.Base httpVersion :: String type Request = HTTPRequest String type Response = HTTPResponse String -- | 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. data RequestMethod HEAD :: RequestMethod PUT :: RequestMethod GET :: RequestMethod POST :: RequestMethod DELETE :: RequestMethod OPTIONS :: RequestMethod TRACE :: RequestMethod -- | An HTTP Request. The Show instance of this type is used for -- message serialisation, which means no body data is output. data HTTPRequest a Request :: URI -> RequestMethod -> [Header] -> a -> HTTPRequest a -- | 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). rqURI :: HTTPRequest a -> URI rqMethod :: HTTPRequest a -> RequestMethod rqHeaders :: HTTPRequest a -> [Header] rqBody :: HTTPRequest a -> 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. data HTTPResponse a Response :: ResponseCode -> String -> [Header] -> a -> HTTPResponse a rspCode :: HTTPResponse a -> ResponseCode rspReason :: HTTPResponse a -> String rspHeaders :: HTTPResponse a -> [Header] rspBody :: HTTPResponse a -> a urlEncode :: String -> String urlDecode :: String -> String urlEncodeVars :: [(String, String)] -> String data URIAuthority URIAuthority :: Maybe String -> Maybe String -> String -> Maybe Int -> URIAuthority user :: URIAuthority -> Maybe String password :: URIAuthority -> Maybe String host :: URIAuthority -> String port :: URIAuthority -> Maybe Int -- | 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.
--
parseURIAuthority :: String -> Maybe URIAuthority crlf :: String sp :: String uriToAuthorityString :: URI -> String uriAuthToString :: URIAuth -> String parseResponseHead :: [String] -> Result ResponseData parseRequestHead :: [String] -> Result RequestData data ResponseNextStep Continue :: ResponseNextStep Retry :: ResponseNextStep Done :: ResponseNextStep ExpectEntity :: ResponseNextStep DieHorribly :: String -> ResponseNextStep matchResponse :: RequestMethod -> ResponseCode -> ResponseNextStep -- | ResponseData contains the head of a response payload; HTTP -- response code, accompanying text description + header fields. type ResponseData = (ResponseCode, String, [Header]) -- | For easy pattern matching, HTTP response codes xyz are -- represented as (x,y,z). type ResponseCode = (Int, Int, Int) -- | RequestData contains the head of a HTTP request; method, its -- URL along with the auxillary/supporting header data. type RequestData = (RequestMethod, URI, [Header]) -- | getAuth req fishes out the authority portion of the URL in a -- request's Host header. getAuth :: (Monad m) => HTTPRequest ty -> m URIAuthority normalizeRequestURI :: URIAuthority -> HTTPRequest ty -> HTTPRequest ty normalizeHostHeader :: HTTPRequest ty -> HTTPRequest ty findConnClose :: [Header] -> Bool -- | Used when we know exactly how many bytes to expect. linearTransfer :: (Int -> IO (Result a)) -> Int -> 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. hopefulTransfer :: BufferOp a -> IO (Result a) -> [a] -> IO (Result ([Header], a)) -- | A necessary feature of HTTP/1.1 Also the only transfer variety likely -- to return any footers. chunkedTransfer :: BufferOp a -> IO (Result a) -> (Int -> IO (Result a)) -> 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. uglyDeathTransfer :: IO (Result ([Header], a)) -- | Remove leading crlfs then call readTillEmpty2 (not required by RFC) readTillEmpty1 :: BufferOp a -> IO (Result 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. readTillEmpty2 :: BufferOp a -> IO (Result a) -> [a] -> IO (Result [a]) -- | catchIO a h handles IO action exceptions throughout codebase; -- version-specific tweaks better go here. catchIO :: IO a -> (IOException -> IO a) -> IO a catchIO_ :: IO a -> IO a -> IO a instance Show RequestMethod instance Eq RequestMethod instance Eq URIAuthority instance Show URIAuthority instance HasHeaders (HTTPResponse a) instance Show (HTTPResponse a) instance HasHeaders (HTTPRequest a) instance Show (HTTPRequest a) -- | An easy access TCP library. Makes the use of TCP in Haskell much -- easier. This was originally part of Gray's\/Bringert's HTTP module. -- -- module Network.TCP -- | The Connection newtype is a wrapper that allows us to make -- connections an instance of the Stream class, without ghc extensions. -- While this looks sort of like a generic reference to the transport -- layer it is actually TCP specific, which can be seen in the -- implementation of the 'Stream Connection' instance. data Connection -- | This function establishes a connection to a remote host, it uses -- getHostByName which interrogates the DNS system, hence may -- trigger a network connection. openTCPPort :: String -> Int -> IO Connection -- | Checks both that the underlying Socket is connected and that the -- connection peer matches the given host name (which is recorded -- locally). isConnectedTo :: Connection -> String -> IO Bool openTCPConnection :: (BufferType ty) => String -> Int -> IO (HandleStream ty) isTCPConnectedTo :: HandleStream ty -> String -> IO Bool data HandleStream a class (BufferType bufType) => HStream bufType openStream :: (HStream bufType) => String -> Int -> IO (HandleStream bufType) readLine :: (HStream bufType) => HandleStream bufType -> IO (Result bufType) readBlock :: (HStream bufType) => HandleStream bufType -> Int -> IO (Result bufType) writeBlock :: (HStream bufType) => HandleStream bufType -> bufType -> IO (Result ()) close :: (HStream bufType) => HandleStream bufType -> IO () data StreamHooks ty StreamHooks :: ((ty -> String) -> Result ty -> IO ()) -> ((ty -> String) -> Int -> Result ty -> IO ()) -> ((ty -> String) -> ty -> Result () -> IO ()) -> IO () -> StreamHooks ty hook_readLine :: StreamHooks ty -> (ty -> String) -> Result ty -> IO () hook_readBlock :: StreamHooks ty -> (ty -> String) -> Int -> Result ty -> IO () hook_writeBlock :: StreamHooks ty -> (ty -> String) -> ty -> Result () -> IO () hook_close :: StreamHooks ty -> IO () nullHooks :: StreamHooks ty setStreamHooks :: HandleStream ty -> StreamHooks ty -> IO () instance (Eq a) => Eq (Conn a) instance HStream String instance Stream Connection instance HStream ByteString instance HStream ByteString instance (Eq ty) => Eq (StreamHooks ty) -- | Implements debugging of Streams. Originally part of -- Gray's\/Bringert's HTTP module. -- -- module Network.StreamDebugger -- | Allows stream logging. Refer to debugStream below. data StreamDebugger x -- | Wraps a stream with logging I/O. The first argument is a filename -- which is opened in AppendMode. debugStream :: (Stream a) => FilePath -> a -> IO (StreamDebugger a) debugByteStream :: (HStream ty) => FilePath -> HandleStream ty -> IO (HandleStream ty) instance (Stream x) => Stream (StreamDebugger x) -- | Socket Stream instance. Originally part of Gray's\/Bringert's HTTP -- module. -- -- module Network.StreamSocket -- | Exception handler for socket operations. handleSocketError :: Socket -> IOException -> IO (Result a) myrecv :: Socket -> Int -> IO String instance Stream Socket -- | A HandleStream version of Network.HTTP.Stream's public offerings. module Network.HTTP.HandleStream -- | 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 :: (HStream ty) => HTTPRequest ty -> IO (Result (HTTPResponse ty)) -- | Like simpleHTTP, but acting on an already opened stream. simpleHTTP_ :: (HStream ty) => HandleStream ty -> HTTPRequest ty -> IO (Result (HTTPResponse ty)) sendHTTP :: (HStream ty) => HandleStream ty -> HTTPRequest ty -> IO (Result (HTTPResponse ty)) -- | Receive and parse a HTTP request from the given Stream. Should be used -- for server side interactions. receiveHTTP :: (HStream bufTy) => HandleStream bufTy -> IO (Result (HTTPRequest bufTy)) -- | Very simple function, send a HTTP response over the given stream. This -- could be improved on to use different transfer types. respondHTTP :: (HStream ty) => HandleStream ty -> HTTPResponse ty -> IO () simpleHTTP_debug :: (HStream ty) => FilePath -> HTTPRequest ty -> IO (Result (HTTPResponse ty)) -- | An easy HTTP interface enjoy. -- -- -- -- -- -- -- -- module Network.HTTP -- | An easy HTTP interface enjoy. -- -- -- -- -- -- -- -- module Network.HTTP.Stream -- | 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 :: Request -> IO (Result Response) -- | Like simpleHTTP, but acting on an already opened stream. simpleHTTP_ :: (Stream s) => s -> Request -> IO (Result Response) sendHTTP :: (Stream s) => s -> Request -> IO (Result Response) -- | Receive and parse a HTTP request from the given Stream. Should be used -- for server side interactions. receiveHTTP :: (Stream s) => s -> IO (Result Request) -- | Very simple function, send a HTTP response over the given stream. This -- could be improved on to use different transfer types. respondHTTP :: (Stream s) => s -> Response -> IO () -- | An HTTP/1.1 compatible wrapper for the HTTP module. module Network.Browser data BrowserState connection data BrowserAction conn a data Cookie data Form Form :: RequestMethod -> URI -> [FormVar] -> Form -- | Specifies if a proxy should be used for the request. data Proxy -- | Don't use a proxy. NoProxy :: Proxy -- | Use the proxy given. Should be of the form http://host:port, -- host, host:port, or http://host Proxy :: String -> (Maybe Authority) -> Proxy -- | Apply a browser action to a state. browse :: BrowserAction conn a -> IO a request :: (HStream ty) => HTTPRequest ty -> BrowserAction (HandleStream ty) (URI, HTTPResponse ty) setAllowRedirects :: Bool -> BrowserAction t () getAllowRedirects :: BrowserAction t Bool data Authority AuthBasic :: String -> String -> String -> URI -> Authority auRealm :: Authority -> String auUsername :: Authority -> String auPassword :: Authority -> String auSite :: Authority -> URI AuthDigest :: String -> String -> String -> String -> Maybe Algorithm -> [URI] -> Maybe String -> [Qop] -> Authority auRealm :: Authority -> String auUsername :: Authority -> String auPassword :: Authority -> String auNonce :: Authority -> String auAlgorithm :: Authority -> Maybe Algorithm auDomain :: Authority -> [URI] auOpaque :: Authority -> Maybe String auQop :: Authority -> [Qop] -- | Interacting with browser state: getAuthorities :: BrowserAction t [Authority] setAuthorities :: [Authority] -> BrowserAction t () addAuthority :: Authority -> BrowserAction t () getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String))) setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t () setAllowBasicAuth :: Bool -> BrowserAction t () setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t () defaultCookieFilter :: URI -> Cookie -> IO Bool userCookieFilter :: URI -> Cookie -> IO Bool getCookies :: BrowserAction t [Cookie] setCookies :: [Cookie] -> BrowserAction t () -- | Adds a cookie to the browser state, removing duplicates. addCookie :: Cookie -> BrowserAction t () setErrHandler :: (String -> IO ()) -> BrowserAction t () setOutHandler :: (String -> IO ()) -> BrowserAction t () setProxy :: Proxy -> BrowserAction t () setDebugLog :: Maybe String -> BrowserAction t () out :: String -> BrowserAction t () err :: String -> BrowserAction t () -- | Do an io action ioAction :: IO a -> BrowserAction t a defaultGETRequest :: URI -> Request formToRequest :: Form -> Request -- | Returns a URI that is consistent with the first argument uri when read -- in the context of a second. If second argument is not sufficient -- context for determining a full URI then anarchy reins. uriDefaultTo :: URI -> URI -> URI uriTrimHost :: URI -> URI instance Eq Qop instance Show Qop instance Eq Algorithm instance Show Cookie instance Read Cookie instance Functor (BrowserAction conn) instance Monad (BrowserAction conn) instance Show (BrowserState t) instance Show Algorithm instance Eq Cookie