-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A library for client-side HTTP -- -- The HTTP package supports client-side web programming in Haskell. It -- lets you set up HTTP connections, transmitting requests and processing -- the responses coming back, all from within the comforts of Haskell. -- It's dependent on the network package to operate, but other than that, -- the implementation is all written in Haskell. -- -- A basic API for issuing single HTTP requests + receiving responses is -- provided. On top of that, a session-level abstraction is also on offer -- (the BrowserAction monad); it taking care of handling the -- management of persistent connections, proxies, state (cookies) and -- authentication credentials required to handle multi-step interactions -- with a web server. -- -- The representation of the bytes flowing across is extensible via the -- use of a type class, letting you pick the representation of requests -- and responses that best fits your use. Some pre-packaged, common -- instances are provided for you (ByteString, String.) -- -- Here's an example use: -- -- 
--   do
--     rsp <- Network.HTTP.simpleHTTP (getRequest "http://www.haskell.org/")
--             -- fetch document and return it (as a 'String'.)
--     fmap (take 100) (getResponseBody rsp)
--   
--   do
--     rsp <- Network.Browser.browse $ do
--              setAllowRedirects True -- handle HTTP redirects
--              request $ getRequest "http://google.com/"
--     fmap (take 100) (getResponseBody rsp)
--
-- -- Git repository available at git://github.com/haskell/HTTP.git @package HTTP @version 4000.1.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 () closeOnEnd :: Stream x => x -> Bool -> 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 fmapE :: (a -> Result b) -> IO (Result a) -> IO (Result b) failParse :: String -> Result a failWith :: ConnError -> Result a failMisc :: String -> Result a instance Show ConnError instance Eq ConnError instance Error ConnError -- | This module provides the data types for representing HTTP headers, and -- operations for looking up header values and working with sequences of -- header values in Requests and Responses. To avoid -- having to provide separate set of operations for doing so, we -- introduce a type class HasHeaders to facilitate writing such -- processing using overloading instead. module Network.HTTP.Headers -- | HasHeaders is a type class for types containing HTTP headers, -- allowing you to write overloaded header manipulation functions for -- both Request and Response data types, for instance. 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 -- | Header constructor as a function, hiding above rep. mkHeader :: HeaderName -> String -> Header hdrName :: Header -> HeaderName hdrValue :: Header -> String -- | HTTP HeaderName type, a Haskell data constructor for each -- specification-defined header, prefixed with Hdr and -- CamelCased, (i.e., eliding the - in the process.) Should you -- require using a custom header, there's the HdrCustom -- constructor which takes a String argument. -- -- Encoding HTTP header names differently, as Strings perhaps, is an -- equally fine choice..no decidedly clear winner, but let's stick with -- data constructors here. 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 HdrTE :: HeaderName HdrTrailer :: 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 hdr val x inserts a header with the given header -- name and value. Does not check for existing headers with same name, -- allowing duplicates to be introduce (use replaceHeader if you -- want to avoid this.) insertHeader :: HasHeaders a => HeaderSetter a -- | insertHeaderIfMissing hdr val x adds the new header only if -- no previous header with name hdr exists in x. insertHeaderIfMissing :: HasHeaders a => HeaderSetter a -- | insertHeaders hdrs x appends multiple headers to x's -- existing set. insertHeaders :: HasHeaders a => [Header] -> a -> a -- | retrieveHeaders hdrNm x gets a list of headers with -- HeaderName hdrNm. retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header] -- | replaceHeader hdr val o replaces the header hdr with -- the value val, dropping any existing replaceHeader :: HasHeaders a => HeaderSetter a -- | findHeader hdrNm x looks up hdrNm in x, -- returning the first header that matches, if any. findHeader :: HasHeaders a => HeaderName -> a -> Maybe String -- | lookupHeader hdr hdrs locates the first header matching -- hdr in the list hdrs. lookupHeader :: HeaderName -> [Header] -> Maybe String -- | parseHeader headerNameAndValueString tries to unscramble a -- header: value pairing and returning it as a Header. parseHeader :: String -> Result Header -- | parseHeaders hdrs takes a sequence of strings holding header -- information and parses them into a set of headers (preserving their -- order in the input argument.) Handles header values split up over -- multiple lines. parseHeaders :: [String] -> Result [Header] -- | headerMap is a straight assoc list for translating between -- header names and values. headerMap :: [(String, HeaderName)] type HeaderSetter a = HeaderName -> String -> a -> a instance Eq HeaderName instance Show HeaderName instance Show Header -- | This module provides the data types and functions for working with -- HTTP cookies. Right now, it contains mostly functionality needed by -- Network.Browser. module Network.HTTP.Cookie -- | Cookie is the Haskell representation of HTTP cookie values. -- See its relevant specs for authoritative details. data Cookie MkCookie :: String -> String -> String -> Maybe String -> Maybe String -> Maybe String -> Cookie ckDomain :: Cookie -> String ckName :: Cookie -> String ckValue :: Cookie -> String ckPath :: Cookie -> Maybe String ckComment :: Cookie -> Maybe String ckVersion :: Cookie -> Maybe String -- | cookieMatch (domain,path) ck performs the standard cookie -- match wrt the given domain and path. cookieMatch :: (String, String) -> Cookie -> Bool -- | cookieToHeader ck serialises a Cookie to an HTTP -- request header. cookieToHeader :: Cookie -> Header -- | 
--   processCookieHeaders dom hdrs
--
processCookieHeaders :: String -> [Header] -> ([String], [Cookie]) instance Show Cookie instance Read Cookie instance Eq Cookie -- | In order to give the user freedom in how request and response content -- is represented, a sufficiently abstract representation is needed of -- these internally. The Network.BufferType module provides this, -- defining the BufferType class and its ad-hoc representation of -- buffer operations via the BufferOp record. -- -- This module provides definitions for the standard buffer types that -- the package supports, i.e., for String and -- ByteString (strict and lazy.) 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 the dicts themselves. class BufferType bufType bufferOps :: BufferType bufType => BufferOp bufType -- | BufferOp encodes the I/O operations of the underlying buffer -- over a Handle in an (explicit) dictionary type. May not be needed, but -- gives us flexibility in explicit overriding and wrapping up of these -- methods. -- -- Along with IO operations is an ad-hoc collection of functions for -- working with these abstract buffers, as needed by the internals of the -- code that processes requests and responses. -- -- We supply three default BufferOp values, for String -- along with the strict and lazy versions of ByteString. To add -- others, provide BufferOp definitions for data BufferOp a BufferOp :: (Handle -> Int -> IO a) -> (Handle -> IO a) -> (Handle -> a -> IO ()) -> (Handle -> IO a) -> a -> (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_concat :: BufferOp 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 is the BufferOp definition over -- ByteStrings, the non-lazy kind. strictBufferOp :: BufferOp ByteString -- | lazyBufferOp is the BufferOp definition over -- ByteStrings, the non-strict kind. lazyBufferOp :: BufferOp ByteString -- | stringBufferOp is the BufferOp definition over -- Strings. It is defined in terms of strictBufferOp -- operations, unpacking/converting to String when needed. stringBufferOp :: BufferOp String instance Eq (BufferOp a) instance BufferType String instance BufferType ByteString instance BufferType ByteString -- | 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. module Network.HTTP.Base httpVersion :: String -- | An HTTP Request. The Show instance of this type is used for -- message serialisation, which means no body data is output. data Request a Request :: URI -> RequestMethod -> [Header] -> a -> Request 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 :: Request a -> URI rqMethod :: Request a -> RequestMethod rqHeaders :: Request a -> [Header] rqBody :: Request 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 Response a Response :: ResponseCode -> String -> [Header] -> a -> Response a rspCode :: Response a -> ResponseCode rspReason :: Response a -> String rspHeaders :: Response a -> [Header] rspBody :: Response a -> a -- | 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 CONNECT :: RequestMethod Custom :: String -> RequestMethod 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 :: 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 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 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]) -- | NormalizeRequestOptions brings together the various -- defaulting/normalization options over Requests. Use -- defaultNormalizeRequestOptions for the standard selection of -- option data NormalizeRequestOptions ty NormalizeRequestOptions :: Bool -> Bool -> Maybe String -> [RequestNormalizer ty] -> NormalizeRequestOptions ty normDoClose :: NormalizeRequestOptions ty -> Bool normForProxy :: NormalizeRequestOptions ty -> Bool normUserAgent :: NormalizeRequestOptions ty -> Maybe String normCustoms :: NormalizeRequestOptions ty -> [RequestNormalizer ty] defaultNormalizeRequestOptions :: NormalizeRequestOptions ty -- | RequestNormalizer is the shape of a (pure) function that -- rewrites a request into some normalized form. type RequestNormalizer ty = 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. normalizeRequest :: NormalizeRequestOptions ty -> Request ty -> Request ty splitRequestURI :: URI -> (String, URI) -- | getAuth req fishes out the authority portion of the URL in a -- request's Host header. getAuth :: Monad m => Request ty -> m URIAuthority normalizeRequestURI :: Bool -> String -> Request ty -> Request ty normalizeHostHeader :: Request ty -> Request 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 :: String -> 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]) defaultGETRequest :: URI -> Request_String defaultGETRequest_ :: BufferType a => URI -> Request a -- | '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. mkRequest :: BufferType ty => RequestMethod -> URI -> Request ty defaultUserAgent :: String libUA :: String -- | 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 responseParseError :: String -> String -> Result a -- | getRequestVersion req returns the HTTP protocol version of -- the request req. If Nothing, the default -- httpVersion can be assumed. getRequestVersion :: Request a -> Maybe String -- | getResponseVersion rsp returns the HTTP protocol version of -- the response rsp. If Nothing, the default -- httpVersion can be assumed. getResponseVersion :: Response a -> Maybe String -- | setRequestVersion v req returns a new request, identical to -- req, but with its HTTP version set to v. setRequestVersion :: String -> Request a -> Request a -- | setResponseVersion v rsp returns a new response, identical to -- rsp, but with its HTTP version set to v. setResponseVersion :: String -> Response a -> Response a instance Eq RequestMethod instance Eq URIAuthority instance Show URIAuthority instance HasHeaders (Response a) instance Show (Response a) instance HasHeaders (Request a) instance Show (Request a) instance Show RequestMethod -- | Some utility functions for working with the Haskell network -- package. Mostly for internal use by the Network.HTTP code, -- but 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 -- | openTCPPort uri port establishes a connection to a remote -- host, using getHostByName which possibly queries 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) -- | socketConnection, like openConnection but using a -- pre-existing Socket. socketConnection :: BufferType ty => String -> Socket -> IO (HandleStream ty) isTCPConnectedTo :: HandleStream ty -> String -> IO Bool data HandleStream a -- | HStream overloads the use of HandleStreams, letting -- you overload the handle operations over the type that is communicated -- across the handle. It comes in handy for Network.HTTP -- Request and Responses as the payload representation -- isn't fixed, but overloaded. -- -- The library comes with instances for ByteStrings and -- String, but should you want to plug in your own payload -- representation, defining your own HStream instance _should_ -- be all that it takes. class BufferType bufType => HStream bufType openStream :: HStream bufType => String -> Int -> IO (HandleStream bufType) openSocketStream :: HStream bufType => String -> Socket -> 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 () closeQuick :: HStream bufType => HandleStream bufType -> IO () closeOnEnd :: HStream bufType => HandleStream bufType -> Bool -> IO () data StreamHooks ty StreamHooks :: ((ty -> String) -> Result ty -> IO ()) -> ((ty -> String) -> Int -> Result ty -> IO ()) -> ((ty -> String) -> ty -> Result () -> IO ()) -> IO () -> String -> 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 () hook_name :: StreamHooks ty -> String nullHooks :: StreamHooks ty setStreamHooks :: HandleStream ty -> StreamHooks ty -> IO () getStreamHooks :: HandleStream ty -> IO (Maybe (StreamHooks ty)) hstreamToConnection :: HandleStream String -> Connection 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 -- | Representing HTTP Auth values in Haskell. Right now, it contains -- mostly functionality needed by Network.Browser. module Network.HTTP.Auth -- | Authority specifies the HTTP Authentication method to use for -- a given domain/realm; Basic or Digest. 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] -- | Algorithm controls the digest algorithm to, MD5 or -- MD5Session. data Algorithm AlgMD5 :: Algorithm AlgMD5sess :: Algorithm data Challenge ChalBasic :: String -> Challenge chRealm :: Challenge -> String ChalDigest :: String -> [URI] -> String -> Maybe String -> Bool -> Maybe Algorithm -> [Qop] -> Challenge chRealm :: Challenge -> String chDomain :: Challenge -> [URI] chNonce :: Challenge -> String chOpaque :: Challenge -> Maybe String chStale :: Challenge -> Bool chAlgorithm :: Challenge -> Maybe Algorithm chQop :: Challenge -> [Qop] data Qop QopAuth :: Qop QopAuthInt :: Qop -- | headerToChallenge base www_auth tries to convert the -- WWW-Authenticate header www_auth into a -- Challenge value. headerToChallenge :: URI -> Header -> Maybe Challenge -- | withAuthority auth req generates a credentials value from the -- auth Authority, in the context of the given request. -- -- If a client nonce was to be used then this function might need to be -- of type ... -> BrowserAction String withAuthority :: Authority -> Request ty -> String instance Eq Qop instance Show Qop instance Eq Algorithm instance Show Algorithm -- | Author : Eric Kow E.Y.Kow@brighton.ac.uk Stability : -- experimental Portability : non-portable (not tested) -- -- Handling proxy server settings and their resolution. module Network.HTTP.Proxy -- | HTTP proxies (or not) are represented via Proxy, specifying if -- a proxy should be used for the request (see -- Network.Browser.setProxy) 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. Additionally, an -- optional Authority for authentication with the proxy. Proxy :: String -> (Maybe Authority) -> Proxy noProxy :: Proxy -- | fetchProxy flg gets the local proxy settings and parse the -- string into a Proxy value. If you want to be informed of -- ill-formed proxy configuration strings, supply True for -- flg. Proxy settings are sourced from the HTTP_PROXY -- environment variable, and in the case of Windows platforms, by -- consulting IE/WinInet's proxy setting in the Registry. fetchProxy :: Bool -> IO Proxy -- | parseProxy str translates a proxy server string into a -- Proxy value; returns Nothing if not well-formed. parseProxy :: String -> Maybe Proxy -- | A HandleStream-based version of Network.HTTP interface. -- -- For more detailed information about what the individual exports do, -- please consult the documentation for Network.HTTP. -- Notice however that the functions here do not perform any kind -- of normalization prior to transmission (or receipt); you are -- responsible for doing any such yourself, or, if you prefer, just -- switch to using Network.HTTP function instead. module Network.HTTP.HandleStream -- | simpleHTTP transmits a resource across a non-persistent -- connection. simpleHTTP :: HStream ty => Request ty -> IO (Result (Response ty)) -- | Like simpleHTTP, but acting on an already opened stream. simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty)) -- | sendHTTP hStream httpRequest transmits httpRequest -- over hStream, but does not alter the status of the -- connection, nor request it to be closed upon receiving the response. sendHTTP :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty)) -- | sendHTTP_notify hStream httpRequest action behaves like -- sendHTTP, but lets you supply an IO action to execute -- once the request has been successfully transmitted over the -- connection. Useful when you want to set up tracing of request -- transmission and its performance. sendHTTP_notify :: HStream ty => HandleStream ty -> Request ty -> IO () -> IO (Result (Response ty)) -- | receiveHTTP hStream reads a Request from the -- HandleStream hStream receiveHTTP :: HStream bufTy => HandleStream bufTy -> IO (Result (Request bufTy)) -- | respondHTTP hStream httpResponse transmits an HTTP -- Response over the HandleStream hStream. It -- could be used to implement simple web server interactions, performing -- the dual role to sendHTTP. respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO () -- | simpleHTTP_debug debugFile req behaves like -- simpleHTTP, but logs the HTTP operation via the debug file -- debugFile. simpleHTTP_debug :: HStream ty => FilePath -> Request ty -> IO (Result (Response ty)) -- | The Network.HTTP module provides a simple interface for -- sending and receiving content over HTTP in Haskell. Here's how to -- fetch a document from a URL and return it as a String: -- -- 
--   simpleHTTP (getRequest "http://www.haskell.org/") >>= fmap (take 100) . getResponseBody
--       -- fetch document and return it (as a 'String'.)
--
-- -- Other functions let you control the submission and transfer of HTTP -- Requests and Responses more carefully, letting you -- integrate the use of Network.HTTP functionality into your -- application. -- -- The module also exports the main types of the package, Request -- and Response, along with Header and functions for -- working with these. -- -- The actual functionality is implemented by modules in the -- Network.HTTP.* namespace, letting you either use the default -- implementation here by importing Network.HTTP or, for more -- specific uses, selectively import the modules in -- Network.HTTP.*. To wit, more than one kind of representation -- of the bulk data that flows across a HTTP connection is supported. -- (see Network.HTTP.HandleStream.) -- -- NOTE: The Request send actions will normalize the -- Request prior to transmission. Normalization such as having -- the request path be in the expected form and, possibly, introduce a -- default Host: header if one isn't already present. If you do -- not want the requests tampered with, but sent as-is, please import and -- use the the Network.HTTP.HandleStream or -- Network.HTTP.Stream modules instead. They export the same -- functions, but leaves construction and any normalization of -- Requests to the user. module Network.HTTP -- | simpleHTTP req transmits the Request req by -- opening a direct, non-persistent connection to the HTTP server -- that req is destined for, followed by transmitting it and -- gathering up the response as a Result. Prior to sending the -- request, it is normalized (via normalizeRequest). If you have -- to mediate the request via an HTTP proxy, you will have to normalize -- the request yourself. Or switch to using Network.Browser -- instead. -- -- Examples: -- -- 
--   simpleHTTP (getRequest "http://hackage.haskell.org/")
--   simpleHTTP (getRequest "http://hackage.haskell.org:8012/")
--
simpleHTTP :: HStream ty => Request ty -> IO (Result (Response ty)) -- | Identical to simpleHTTP, but acting on an already opened -- stream. simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty)) -- | sendHTTP hStream httpRequest transmits httpRequest -- (after normalization) over hStream, but does not alter the -- status of the connection, nor request it to be closed upon receiving -- the response. sendHTTP :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty)) -- | sendHTTP_notify hStream httpRequest action behaves like -- sendHTTP, but lets you supply an IO action to execute -- once the request has been successfully transmitted over the -- connection. Useful when you want to set up tracing of request -- transmission and its performance. sendHTTP_notify :: HStream ty => HandleStream ty -> Request ty -> IO () -> IO (Result (Response ty)) -- | receiveHTTP hStream reads a Request from the -- HandleStream hStream receiveHTTP :: HStream ty => HandleStream ty -> IO (Result (Request ty)) -- | respondHTTP hStream httpResponse transmits an HTTP -- Response over the HandleStream hStream. It -- could be used to implement simple web server interactions, performing -- the dual role to sendHTTP. respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO () -- | getRequest urlString is convenience constructor for basic GET -- Requests. If urlString isn't a syntactically valid -- URL, the function raises an error. getRequest :: String -> Request_String -- | postRequest urlString is convenience constructor for POST -- Requests. If urlString isn't a syntactically valid -- URL, the function raises an error. postRequest :: String -> Request_String -- | getResponseBody response takes the response of a HTTP -- requesting action and tries to extricate the body of the -- Response response. If the request action returned an -- error, an IO exception is raised. getResponseBody :: Result (Response ty) -> IO ty -- | Transmitting HTTP requests and responses holding String in -- their payload bodies. This is one of the implementation modules for -- the Network.HTTP interface, representing request and response -- content as Strings and transmitting them in non-packed form -- (cf. Network.HTTP.HandleStream and its use of -- ByteStrings.) over Stream handles. It is mostly here -- for backwards compatibility, representing how requests and responses -- were transmitted up until the 4.x releases of the HTTP package. -- -- For more detailed information about what the individual exports do, -- please consult the documentation for Network.HTTP. -- Notice however that the functions here do not perform any kind -- of normalization prior to transmission (or receipt); you are -- responsible for doing any such yourself, or, if you prefer, just -- switch to using Network.HTTP function instead. module Network.HTTP.Stream -- | Simple way to transmit a resource across a non-persistent connection. simpleHTTP :: Request_String -> IO (Result Response_String) -- | Like simpleHTTP, but acting on an already opened stream. simpleHTTP_ :: Stream s => s -> Request_String -> IO (Result Response_String) sendHTTP :: Stream s => s -> Request_String -> IO (Result Response_String) sendHTTP_notify :: Stream s => s -> Request_String -> IO () -> IO (Result Response_String) -- | Receive and parse a HTTP request from the given Stream. Should be used -- for server side interactions. receiveHTTP :: Stream s => s -> IO (Result Request_String) -- | 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_String -> IO () -- | Session-level interactions over HTTP. -- -- The Network.Browser goes beyond the basic Network.HTTP -- functionality in providing support for more involved, and real, -- request/response interactions over HTTP. Additional features supported -- are: -- -- -- -- Example use: -- -- 
--   do 
--     rsp <- Network.Browser.browse $ do
--              setAllowRedirects True -- handle HTTP redirects
--              request $ getRequest "http://google.com/"
--     fmap (take 100) (getResponseBody rsp)
--
module Network.Browser -- | BrowserState is the (large) record type tracking the current -- settings of the browser. data BrowserState connection -- | BrowserAction is the IO monad, but carrying along a -- BrowserState. data BrowserAction conn a -- | HTTP proxies (or not) are represented via Proxy, specifying if -- a proxy should be used for the request (see -- Network.Browser.setProxy) 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. Additionally, an -- optional Authority for authentication with the proxy. Proxy :: String -> (Maybe Authority) -> Proxy -- | browse act is the toplevel action to perform a -- BrowserAction. Example use: browse (request (getRequest -- yourURL)). browse :: BrowserAction conn a -> IO a -- | request httpRequest tries to submit the Request -- httpRequest to some HTTP server (possibly going via a -- proxy, see setProxy.) Upon successful delivery, the URL -- where the response was fetched from is returned along with the -- Response itself. request :: HStream ty => Request ty -> BrowserAction (HandleStream ty) (URI, Response ty) -- | getBrowserState returns the current browser config. Useful -- for restoring state across BrowserActions. getBrowserState :: BrowserAction t (BrowserState t) -- | withBrowserAction st act performs act with -- BrowserState st. withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t a -- | setAllowRedirects onOff toggles the willingness to follow -- redirects (HTTP responses with 3xx status codes). setAllowRedirects :: Bool -> BrowserAction t () -- | getAllowRedirects returns current setting of the -- do-chase-redirects flag. getAllowRedirects :: BrowserAction t Bool -- | setMaxRedirects maxCount sets the maxiumum number of -- forwarding hops we are willing to jump through. A no-op if the count -- is negative; if zero, the max is set to whatever default applies. -- Notice that setting the max redirects count does not enable -- following of redirects itself; use setAllowRedirects to do so. setMaxRedirects :: Maybe Int -> BrowserAction t () -- | getMaxRedirects returns the current setting for the -- max-redirect count. If Nothing, the Network.Browser's -- default is used. getMaxRedirects :: BrowserAction t (Maybe Int) -- | Authority specifies the HTTP Authentication method to use for -- a given domain/realm; Basic or Digest. 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] -- | getAuthorities return the current set of Authoritys -- known to the browser. getAuthorities :: BrowserAction t [Authority] setAuthorities :: [Authority] -> BrowserAction t () addAuthority :: Authority -> BrowserAction t () data Challenge ChalBasic :: String -> Challenge chRealm :: Challenge -> String ChalDigest :: String -> [URI] -> String -> Maybe String -> Bool -> Maybe Algorithm -> [Qop] -> Challenge chRealm :: Challenge -> String chDomain :: Challenge -> [URI] chNonce :: Challenge -> String chOpaque :: Challenge -> Maybe String chStale :: Challenge -> Bool chAlgorithm :: Challenge -> Maybe Algorithm chQop :: Challenge -> [Qop] data Qop QopAuth :: Qop QopAuthInt :: Qop -- | Algorithm controls the digest algorithm to, MD5 or -- MD5Session. data Algorithm AlgMD5 :: Algorithm AlgMD5sess :: Algorithm -- | getAuthorityGen returns the current authority generator getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String))) -- | setAuthorityGen genAct sets the auth generator to -- genAct. setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t () -- | setAllowBasicAuth onOff enables/disables HTTP Basic -- Authentication. setAllowBasicAuth :: Bool -> BrowserAction t () getAllowBasicAuth :: BrowserAction t Bool -- | setMaxErrorRetries mbMax sets the maximum number of attempts -- at transmitting a request. If Nothing, rever to default max. setMaxErrorRetries :: Maybe Int -> BrowserAction t () -- | getMaxErrorRetries returns the current max number of error -- retries. getMaxErrorRetries :: BrowserAction t (Maybe Int) -- | setMaxAuthAttempts mbMax sets the maximum number of -- authentication attempts to do. If Nothing, rever to default -- max. setMaxAuthAttempts :: Maybe Int -> BrowserAction t () -- | getMaxAuthAttempts returns the current max auth attempts. If -- Nothing, the browser's default is used. getMaxAuthAttempts :: BrowserAction t (Maybe Int) -- | setCookieFilter fn sets the cookie acceptance filter to -- fn. setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t () -- | getCookieFilter returns the current cookie acceptance filter. getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool) -- | defaultCookieFilter is the initial cookie acceptance filter. -- It welcomes them all into the store :-) defaultCookieFilter :: URI -> Cookie -> IO Bool -- | userCookieFilter is a handy acceptance filter, asking the -- user if he/she is willing to accept an incoming cookie before adding -- it to the store. userCookieFilter :: URI -> Cookie -> IO Bool -- | Cookie is the Haskell representation of HTTP cookie values. -- See its relevant specs for authoritative details. data Cookie MkCookie :: String -> String -> String -> Maybe String -> Maybe String -> Maybe String -> Cookie ckDomain :: Cookie -> String ckName :: Cookie -> String ckValue :: Cookie -> String ckPath :: Cookie -> Maybe String ckComment :: Cookie -> Maybe String ckVersion :: Cookie -> Maybe String -- | getCookies returns the current set of cookies known to the -- browser. getCookies :: BrowserAction t [Cookie] -- | setCookies cookies replaces the set of cookies known to the -- browser to cookies. Useful when wanting to restore cookies -- used across browse invocations. setCookies :: [Cookie] -> BrowserAction t () -- | addCookie c adds a cookie to the browser state, removing -- duplicates. addCookie :: Cookie -> BrowserAction t () -- | setErrHandler sets the IO action to call when the browser -- reports running errors. To disable any such, set it to const -- (return ()). setErrHandler :: (String -> IO ()) -> BrowserAction t () -- | setErrHandler sets the IO action to call when the browser -- chatters info on its running. To disable any such, set it to const -- (return ()). setOutHandler :: (String -> IO ()) -> BrowserAction t () -- | setEventHandler onBrowserEvent configures event handling. If -- onBrowserEvent is Nothing, event handling is turned -- off; setting it to Just onEv causes the onEv IO -- action to be notified of browser events during the processing of a -- request by the Browser pipeline. setEventHandler :: Maybe (BrowserEvent -> BrowserAction ty ()) -> BrowserAction ty () -- | BrowserEvent is the event record type that a user-defined -- handler, set via setEventHandler, will be passed. It indicates -- various state changes encountered in the processing of a given -- RequestID, along with timestamps at which they occurred. data BrowserEvent BrowserEvent :: ClockTime -> RequestID -> String -> BrowserEventType -> BrowserEvent browserTimestamp :: BrowserEvent -> ClockTime browserRequestID :: BrowserEvent -> RequestID browserRequestURI :: BrowserEvent -> String browserEventType :: BrowserEvent -> BrowserEventType -- | BrowserEventType is the enumerated list of events that the -- browser internals will report to a user-defined event handler. data BrowserEventType OpenConnection :: BrowserEventType ReuseConnection :: BrowserEventType RequestSent :: BrowserEventType ResponseEnd :: ResponseData -> BrowserEventType ResponseFinish :: BrowserEventType type RequestID = Int -- | setProxy p will disable proxy usage if p is -- NoProxy. If p is Proxy proxyURL mbAuth, -- then proxyURL is interpreted as the URL of the proxy to use, -- possibly authenticating via Authority information in -- mbAuth. setProxy :: Proxy -> BrowserAction t () -- | getProxy returns the current proxy settings. If the -- auto-proxy flag is set to True, getProxy will -- perform the necessary getProxy :: BrowserAction t Proxy -- | setCheckForProxy flg sets the one-time check for proxy flag -- to flg. If True, the session will try to determine -- the proxy server is locally configured. See fetchProxy for -- details of how this done. setCheckForProxy :: Bool -> BrowserAction t () -- | getCheckForProxy returns the current check-proxy setting. -- Notice that this may not be equal to True if the session has -- set it to that via setCheckForProxy and subsequently performed -- some HTTP protocol interactions. i.e., the flag return represents -- whether a proxy will be checked for again before any future protocol -- interactions. getCheckForProxy :: BrowserAction t Bool -- | setDebugLog mbFile turns off debug logging iff -- mbFile is Nothing. If set to Just fStem, -- logs of browser activity is appended to files of the form -- fStem-url-authority, i.e., fStem is just the prefix -- for a set of log files, one per host/authority. setDebugLog :: Maybe String -> BrowserAction t () -- | getUserAgent returns the current User-Agent: default -- string. getUserAgent :: BrowserAction t String -- | setUserAgent ua sets the current User-Agent: string -- to ua. It will be used if no explicit user agent header is -- found in subsequent requests. setUserAgent :: String -> BrowserAction t () out :: String -> BrowserAction t () err :: String -> BrowserAction t () -- | Lifts an IO action into the BrowserAction monad. ioAction :: IO a -> BrowserAction t a defaultGETRequest :: URI -> Request_String defaultGETRequest_ :: BufferType a => URI -> Request a formToRequest :: Form -> Request_String -- | uriDefaultTo a b returns a URI that is consistent with the -- first argument URI a when read in the context of the second -- URI b. If the second argument is not sufficient context for -- determining a full URI then anarchy reins. uriDefaultTo :: URI -> URI -> URI data Form Form :: RequestMethod -> URI -> [FormVar] -> Form type FormVar = (String, String) instance Functor (BrowserAction conn) instance Monad (BrowserAction conn) instance Show (BrowserState t)