-- 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 <tt>BrowserAction</tt> 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 (<tt>ByteString</tt>, <tt>String</tt>).
--   
--   Here's an example use:
--   
--   <pre>
--   do
--     rsp &lt;- Network.HTTP.simpleHTTP (getRequest "http://www.haskell.org/")
--             -- fetch document and return it (as a 'String'.)
--     fmap (take 100) (getResponseBody rsp)
--   
--   do
--     (_, rsp)
--        &lt;- Network.Browser.browse $ do
--              setAllowRedirects True -- handle HTTP redirects
--              request $ getRequest "http://www.haskell.org/"
--     return (take 100 (rspBody rsp))
--   </pre>
@package HTTP
@version 4000.3.4


-- | An library for creating abstract streams. Originally part of
--   Gray's\/Bringert's HTTP module.
--   
--   <ul>
--   <li>Changes by Robin Bate Boerop <a>robin@bateboerop.name</a>:</li>
--   <li>Removed unnecessary import statements.</li>
--   <li>Moved Debug code to StreamDebugger.hs</li>
--   <li>Moved Socket-related code to StreamSocket.hs.</li>
--   <li>Changes by Simon Foster:</li>
--   <li>Split Network.HTTPmodule up into to separate
--   Network.[Stream,TCP,HTTP] modules</li>
--   </ul>
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 GHC.Classes.Eq Network.Stream.ConnError
instance GHC.Show.Show Network.Stream.ConnError
instance Control.Monad.Trans.Error.Error Network.Stream.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 <tt>Request</tt>s and <tt>Response</tt>s. To avoid
--   having to provide separate set of operations for doing so, we
--   introduce a type class <a>HasHeaders</a> to facilitate writing such
--   processing using overloading instead.
module Network.HTTP.Headers

-- | <tt>HasHeaders</tt> is a type class for types containing HTTP headers,
--   allowing you to write overloaded header manipulation functions for
--   both <tt>Request</tt> and <tt>Response</tt> data types, for instance.
class HasHeaders x
getHeaders :: HasHeaders x => x -> [Header]
setHeaders :: HasHeaders x => x -> [Header] -> x

-- | The <tt>Header</tt> data type pairs header names &amp; 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 <tt>HeaderName</tt> type, a Haskell data constructor for each
--   specification-defined header, prefixed with <tt>Hdr</tt> and
--   CamelCased, (i.e., eliding the <tt>-</tt> in the process.) Should you
--   require using a custom header, there's the <tt>HdrCustom</tt>
--   constructor which takes a <tt>String</tt> 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

-- | <tt>insertHeader hdr val x</tt> 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 <a>replaceHeader</a> if you
--   want to avoid this.)
insertHeader :: HasHeaders a => HeaderSetter a

-- | <tt>insertHeaderIfMissing hdr val x</tt> adds the new header only if
--   no previous header with name <tt>hdr</tt> exists in <tt>x</tt>.
insertHeaderIfMissing :: HasHeaders a => HeaderSetter a

-- | <tt>insertHeaders hdrs x</tt> appends multiple headers to <tt>x</tt>'s
--   existing set.
insertHeaders :: HasHeaders a => [Header] -> a -> a

-- | <tt>retrieveHeaders hdrNm x</tt> gets a list of headers with
--   <a>HeaderName</a> <tt>hdrNm</tt>.
retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header]

-- | <tt>replaceHeader hdr val o</tt> replaces the header <tt>hdr</tt> with
--   the value <tt>val</tt>, dropping any existing
replaceHeader :: HasHeaders a => HeaderSetter a

-- | <tt>findHeader hdrNm x</tt> looks up <tt>hdrNm</tt> in <tt>x</tt>,
--   returning the first header that matches, if any.
findHeader :: HasHeaders a => HeaderName -> a -> Maybe String

-- | <tt>lookupHeader hdr hdrs</tt> locates the first header matching
--   <tt>hdr</tt> in the list <tt>hdrs</tt>.
lookupHeader :: HeaderName -> [Header] -> Maybe String

-- | <tt>parseHeader headerNameAndValueString</tt> tries to unscramble a
--   <tt>header: value</tt> pairing and returning it as a <a>Header</a>.
parseHeader :: String -> Result Header

-- | <tt>parseHeaders hdrs</tt> 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]

-- | <tt>headerMap</tt> is a straight assoc list for translating between
--   header names and values.
headerMap :: [(String, HeaderName)]
type HeaderSetter a = HeaderName -> String -> a -> a
instance GHC.Classes.Eq Network.HTTP.Headers.HeaderName
instance GHC.Show.Show Network.HTTP.Headers.Header
instance GHC.Show.Show Network.HTTP.Headers.HeaderName


-- | This module provides the data types and functions for working with
--   HTTP cookies. Right now, it contains mostly functionality needed by
--   <a>Browser</a>.
module Network.HTTP.Cookie

-- | <tt>Cookie</tt> 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

-- | <tt>cookieMatch (domain,path) ck</tt> performs the standard cookie
--   match wrt the given domain and path.
cookieMatch :: (String, String) -> Cookie -> Bool

-- | <tt>cookieToHeaders ck</tt> serialises <tt>Cookie</tt>s to an HTTP
--   request header.
cookiesToHeader :: [Cookie] -> Header

-- | <pre>
--   processCookieHeaders dom hdrs
--   </pre>
processCookieHeaders :: String -> [Header] -> ([String], [Cookie])
instance GHC.Read.Read Network.HTTP.Cookie.Cookie
instance GHC.Show.Show Network.HTTP.Cookie.Cookie
instance GHC.Classes.Eq Network.HTTP.Cookie.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 <a>Network.BufferType</a> module provides this,
--   defining the <a>BufferType</a> class and its ad-hoc representation of
--   buffer operations via the <a>BufferOp</a> record.
--   
--   This module provides definitions for the standard buffer types that
--   the package supports, i.e., for <tt>String</tt> and
--   <tt>ByteString</tt> (strict and lazy.)
module Network.BufferType

-- | The <tt>BufferType</tt> 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

-- | <tt>BufferOp</tt> 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 <tt>BufferOp</tt> values, for <tt>String</tt>
--   along with the strict and lazy versions of <tt>ByteString</tt>. To add
--   others, provide <tt>BufferOp</tt> 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

-- | <tt>strictBufferOp</tt> is the <a>BufferOp</a> definition over
--   <tt>ByteString</tt>s, the non-lazy kind.
strictBufferOp :: BufferOp ByteString

-- | <tt>lazyBufferOp</tt> is the <a>BufferOp</a> definition over
--   <tt>ByteString</tt>s, the non-strict kind.
lazyBufferOp :: BufferOp ByteString

-- | <tt>stringBufferOp</tt> is the <a>BufferOp</a> definition over
--   <tt>String</tt>s. It is defined in terms of <tt>strictBufferOp</tt>
--   operations, unpacking/converting to <tt>String</tt> when needed.
stringBufferOp :: BufferOp String
instance Network.BufferType.BufferType Data.ByteString.Lazy.Internal.ByteString
instance Network.BufferType.BufferType Data.ByteString.Internal.ByteString
instance Network.BufferType.BufferType GHC.Base.String
instance GHC.Classes.Eq (Network.BufferType.BufferOp a)


-- | Definitions of <tt>Request</tt> and <tt>Response</tt> types along with
--   functions for normalizing them. It is assumed to be an internal
--   module; user code should, if possible, import <tt>Network.HTTP</tt> 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 <a>Show</a> 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 <a>*</a> uri in OPTIONS
--   request 2) transparent support for both relative &amp; absolute uris,
--   although this should already work (leave scheme &amp; host parts
--   empty).
[rqURI] :: Request a -> URI
[rqMethod] :: Request a -> RequestMethod
[rqHeaders] :: Request a -> [Header]
[rqBody] :: Request a -> a

-- | An HTTP Response. The <a>Show</a> 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 <a>Request</a> 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.
--   
--   <pre>
--   RFC 1732, section 3.1:
--   
--         //&lt;user&gt;:&lt;password&gt;@&lt;host&gt;:&lt;port&gt;/&lt;url-path&gt;
--    Some or all of the parts "&lt;user&gt;:&lt;password&gt;@", ":&lt;password&gt;",
--    ":&lt;port&gt;", and "/&lt;url-path&gt;" may be excluded.
--   </pre>
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

-- | <tt>ResponseData</tt> 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 <tt>xyz</tt> are
--   represented as <tt>(x,y,z)</tt>.
type ResponseCode = (Int, Int, Int)

-- | <tt>RequestData</tt> contains the head of a HTTP request; method, its
--   URL along with the auxillary/supporting header data.
type RequestData = (RequestMethod, URI, [Header])

-- | <tt>NormalizeRequestOptions</tt> brings together the various
--   defaulting/normalization options over <a>Request</a>s. Use
--   <a>defaultNormalizeRequestOptions</a> 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

-- | <tt>RequestNormalizer</tt> is the shape of a (pure) function that
--   rewrites a request into some normalized form.
type RequestNormalizer ty = NormalizeRequestOptions ty -> Request ty -> Request ty

-- | <tt>normalizeRequest opts req</tt> is the entry point to use to
--   normalize your request prior to transmission (or other use.)
--   Normalization is controlled via the <tt>NormalizeRequestOptions</tt>
--   record.
normalizeRequest :: NormalizeRequestOptions ty -> Request ty -> Request ty
splitRequestURI :: URI -> (String, URI)

-- | <tt>getAuth req</tt> fishes out the authority portion of the URL in a
--   request's <tt>Host</tt> header.
getAuth :: Monad m => Request ty -> m URIAuthority

-- | <i>Deprecated: Please use Network.HTTP.Base.normalizeRequest
--   instead</i>
normalizeRequestURI :: Bool -> String -> Request ty -> Request ty

-- | <i>Deprecated: Please use Network.HTTP.Base.normalizeRequest
--   instead</i>
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
setRequestBody :: Request_String -> (String, String) -> Request_String

-- | A default user agent string. The string is
--   <tt>"haskell-HTTP/$version"</tt> where <tt>$version</tt> is the
--   version of this HTTP package.
defaultUserAgent :: String

-- | The version of this HTTP package as a string, e.g.
--   <tt>"4000.1.2"</tt>. This may be useful to include in a user agent
--   string so that you can determine from server logs what version of this
--   package HTTP clients are using. This can be useful for tracking down
--   HTTP compatibility quirks.
httpPackageVersion :: String

-- | Deprecated. Use <a>defaultUserAgent</a>

-- | <i>Deprecated: Use defaultUserAgent instead (but note the user agent
--   name change)</i>
libUA :: String

-- | <tt>catchIO a h</tt> 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

-- | <tt>getRequestVersion req</tt> returns the HTTP protocol version of
--   the request <tt>req</tt>. If <tt>Nothing</tt>, the default
--   <a>httpVersion</a> can be assumed.
getRequestVersion :: Request a -> Maybe String

-- | <tt>getResponseVersion rsp</tt> returns the HTTP protocol version of
--   the response <tt>rsp</tt>. If <tt>Nothing</tt>, the default
--   <a>httpVersion</a> can be assumed.
getResponseVersion :: Response a -> Maybe String

-- | <tt>setRequestVersion v req</tt> returns a new request, identical to
--   <tt>req</tt>, but with its HTTP version set to <tt>v</tt>.
setRequestVersion :: String -> Request a -> Request a

-- | <tt>setResponseVersion v rsp</tt> returns a new response, identical to
--   <tt>rsp</tt>, but with its HTTP version set to <tt>v</tt>.
setResponseVersion :: String -> Response a -> Response a
failHTTPS :: Monad m => URI -> m ()
instance GHC.Classes.Eq Network.HTTP.Base.RequestMethod
instance GHC.Show.Show Network.HTTP.Base.URIAuthority
instance GHC.Classes.Eq Network.HTTP.Base.URIAuthority
instance GHC.Show.Show Network.HTTP.Base.RequestMethod
instance GHC.Show.Show (Network.HTTP.Base.Request a)
instance Network.HTTP.Headers.HasHeaders (Network.HTTP.Base.Request a)
instance GHC.Show.Show (Network.HTTP.Base.Response a)
instance Network.HTTP.Headers.HasHeaders (Network.HTTP.Base.Response a)


-- | Some utility functions for working with the Haskell <tt>network</tt>
--   package. Mostly for internal use by the <tt>Network.HTTP</tt> code.
module Network.TCP

-- | The <a>Connection</a> 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
data EndPoint
EndPoint :: String -> Int -> EndPoint
[epHost] :: EndPoint -> String
[epPort] :: EndPoint -> Int

-- | <tt>openTCPPort uri port</tt> establishes a connection to a remote
--   host, using <tt>getHostByName</tt> 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 -> EndPoint -> IO Bool
openTCPConnection :: BufferType ty => String -> Int -> IO (HandleStream ty)

-- | <tt>socketConnection</tt>, like <tt>openConnection</tt> but using a
--   pre-existing <a>Socket</a>.
socketConnection :: BufferType ty => String -> Int -> Socket -> IO (HandleStream ty)
isTCPConnectedTo :: HandleStream ty -> EndPoint -> IO Bool
data HandleStream a

-- | <tt>HStream</tt> overloads the use of <a>HandleStream</a>s, letting
--   you overload the handle operations over the type that is communicated
--   across the handle. It comes in handy for <tt>Network.HTTP</tt>
--   <tt>Request</tt> and <tt>Response</tt>s as the payload representation
--   isn't fixed, but overloaded.
--   
--   The library comes with instances for <tt>ByteString</tt>s and
--   <tt>String</tt>, but should you want to plug in your own payload
--   representation, defining your own <tt>HStream</tt> instance _should_
--   be all that it takes.
class BufferType bufType => HStream bufType
openStream :: HStream bufType => String -> Int -> IO (HandleStream bufType)
openSocketStream :: HStream bufType => String -> Int -> 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 GHC.Classes.Eq a => GHC.Classes.Eq (Network.TCP.Conn a)
instance GHC.Classes.Eq Network.TCP.EndPoint
instance GHC.Classes.Eq ty => GHC.Classes.Eq (Network.TCP.StreamHooks ty)
instance Network.TCP.HStream Data.ByteString.Internal.ByteString
instance Network.TCP.HStream Data.ByteString.Lazy.Internal.ByteString
instance Network.Stream.Stream Network.TCP.Connection
instance Network.TCP.HStream GHC.Base.String


-- | Implements debugging of <tt>Stream</tt>s. Originally part of
--   Gray's\/Bringert's HTTP module.
--   
--   <ul>
--   <li>Changes by Robin Bate Boerop <a>robin@bateboerop.name</a>:</li>
--   <li>Created. Made minor formatting changes.</li>
--   </ul>
module Network.StreamDebugger

-- | Allows stream logging. Refer to <a>debugStream</a> below.
data StreamDebugger x

-- | Wraps a stream with logging I/O. The first argument is a filename
--   which is opened in <tt>AppendMode</tt>.
debugStream :: (Stream a) => FilePath -> a -> IO (StreamDebugger a)
debugByteStream :: HStream ty => FilePath -> HandleStream ty -> IO (HandleStream ty)
instance Network.Stream.Stream x => Network.Stream.Stream (Network.StreamDebugger.StreamDebugger x)


-- | Socket Stream instance. Originally part of Gray's\/Bringert's HTTP
--   module.
--   
--   <ul>
--   <li>Changes by Robin Bate Boerop <a>robin@bateboerop.name</a>:</li>
--   <li>Made dependencies explicit in import statements.</li>
--   <li>Removed false dependencies in import statements.</li>
--   <li>Created separate module for instance Stream Socket.</li>
--   <li>Changes by Simon Foster:</li>
--   <li>Split module up into to sepearate Network.[Stream,TCP,HTTP]
--   modules</li>
--   </ul>
module Network.StreamSocket

-- | Exception handler for socket operations.
handleSocketError :: Socket -> IOException -> IO (Result a)
myrecv :: Socket -> Int -> IO String
instance Network.Stream.Stream Network.Socket.Types.Socket


-- | Representing HTTP Auth values in Haskell. Right now, it contains
--   mostly functionality needed by <a>Browser</a>.
module Network.HTTP.Auth

-- | <tt>Authority</tt> specifies the HTTP Authentication method to use for
--   a given domain/realm; <tt>Basic</tt> or <tt>Digest</tt>.
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]

-- | <tt>Algorithm</tt> controls the digest algorithm to, <tt>MD5</tt> or
--   <tt>MD5Session</tt>.
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

-- | <tt>headerToChallenge base www_auth</tt> tries to convert the
--   <tt>WWW-Authenticate</tt> header <tt>www_auth</tt> into a
--   <a>Challenge</a> value.
headerToChallenge :: URI -> Header -> Maybe Challenge

-- | <tt>withAuthority auth req</tt> generates a credentials value from the
--   <tt>auth</tt> <a>Authority</a>, in the context of the given request.
--   
--   If a client nonce was to be used then this function might need to be
--   of type ... -&gt; BrowserAction String
withAuthority :: Authority -> Request ty -> String
instance GHC.Show.Show Network.HTTP.Auth.Qop
instance GHC.Classes.Eq Network.HTTP.Auth.Qop
instance GHC.Classes.Eq Network.HTTP.Auth.Algorithm
instance GHC.Show.Show Network.HTTP.Auth.Algorithm


-- | Handling proxy server settings and their resolution.
module Network.HTTP.Proxy

-- | HTTP proxies (or not) are represented via <a>Proxy</a>, specifying if
--   a proxy should be used for the request (see <a>setProxy</a>)
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
--   <a>Authority</a> for authentication with the proxy.
Proxy :: String -> (Maybe Authority) -> Proxy
noProxy :: Proxy

-- | <tt>fetchProxy flg</tt> gets the local proxy settings and parse the
--   string into a <tt>Proxy</tt> value. If you want to be informed of
--   ill-formed proxy configuration strings, supply <tt>True</tt> for
--   <tt>flg</tt>. Proxy settings are sourced from the <tt>HTTP_PROXY</tt>
--   environment variable, and in the case of Windows platforms, by
--   consulting IE/WinInet's proxy setting in the Registry.
fetchProxy :: Bool -> IO Proxy

-- | <tt>parseProxy str</tt> translates a proxy server string into a
--   <tt>Proxy</tt> value; returns <tt>Nothing</tt> if not well-formed.
parseProxy :: String -> Maybe Proxy


-- | A <a>HandleStream</a>-based version of <a>Network.HTTP</a> interface.
--   
--   For more detailed information about what the individual exports do,
--   please consult the documentation for <a>Network.HTTP</a>.
--   <i>Notice</i> 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 <a>Network.HTTP</a> function instead.
module Network.HTTP.HandleStream

-- | <tt>simpleHTTP</tt> transmits a resource across a non-persistent
--   connection.
simpleHTTP :: HStream ty => Request ty -> IO (Result (Response ty))

-- | Like <a>simpleHTTP</a>, but acting on an already opened stream.
simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))

-- | <tt>sendHTTP hStream httpRequest</tt> transmits <tt>httpRequest</tt>
--   over <tt>hStream</tt>, 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))

-- | <tt>sendHTTP_notify hStream httpRequest action</tt> behaves like
--   <a>sendHTTP</a>, but lets you supply an IO <tt>action</tt> 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))

-- | <tt>receiveHTTP hStream</tt> reads a <a>Request</a> from the
--   <a>HandleStream</a> <tt>hStream</tt>
receiveHTTP :: HStream bufTy => HandleStream bufTy -> IO (Result (Request bufTy))

-- | <tt>respondHTTP hStream httpResponse</tt> transmits an HTTP
--   <a>Response</a> over the <a>HandleStream</a> <tt>hStream</tt>. It
--   could be used to implement simple web server interactions, performing
--   the dual role to <a>sendHTTP</a>.
respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO ()

-- | <tt>simpleHTTP_debug debugFile req</tt> behaves like
--   <a>simpleHTTP</a>, but logs the HTTP operation via the debug file
--   <tt>debugFile</tt>.
simpleHTTP_debug :: HStream ty => FilePath -> Request ty -> IO (Result (Response ty))


-- | The <a>HTTP</a> 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:
--   
--   <pre>
--   simpleHTTP (getRequest "http://www.haskell.org/") &gt;&gt;= fmap (take 100) . getResponseBody
--       -- fetch document and return it (as a 'String'.)
--   </pre>
--   
--   Other functions let you control the submission and transfer of HTTP
--   <a>Request</a>s and <a>Response</a>s more carefully, letting you
--   integrate the use of <a>HTTP</a> functionality into your application.
--   
--   The module also exports the main types of the package, <a>Request</a>
--   and <a>Response</a>, along with <a>Header</a> and functions for
--   working with these.
--   
--   The actual functionality is implemented by modules in the
--   <tt>Network.HTTP.*</tt> namespace, letting you either use the default
--   implementation here by importing <tt>Network.HTTP</tt> or, for more
--   specific uses, selectively import the modules in
--   <tt>Network.HTTP.*</tt>. To wit, more than one kind of representation
--   of the bulk data that flows across a HTTP connection is supported.
--   (see <a>Network.HTTP.HandleStream</a>.)
--   
--   <i>NOTE:</i> The <a>Request</a> send actions will normalize the
--   <tt>Request</tt> prior to transmission. Normalization such as having
--   the request path be in the expected form and, possibly, introduce a
--   default <tt>Host:</tt> header if one isn't already present.
--   Normalization also takes the <tt>"user:pass@"</tt> portion out of the
--   the URI, if it was supplied, and converts it into <tt>Authorization:
--   Basic$ header. If you do not want the requests tampered with, but sent
--   as-is, please import and use the the <a>Network.HTTP.HandleStream</a>
--   or <a>Network.HTTP.Stream</a> modules instead. They export the same
--   functions, but leaves construction and any normalization of
--   </tt>Request@s to the user.
--   
--   <i>NOTE:</i> This package only supports HTTP; it does not support
--   HTTPS. Attempts to use HTTPS result in an error.
module Network.HTTP

-- | <tt>simpleHTTP req</tt> transmits the <a>Request</a> <tt>req</tt> by
--   opening a <i>direct</i>, non-persistent connection to the HTTP server
--   that <tt>req</tt> is destined for, followed by transmitting it and
--   gathering up the response as a <a>Result</a>. Prior to sending the
--   request, it is normalized (via <a>normalizeRequest</a>). If you have
--   to mediate the request via an HTTP proxy, you will have to normalize
--   the request yourself. Or switch to using <a>Browser</a> instead.
--   
--   Examples:
--   
--   <pre>
--   simpleHTTP (getRequest "http://hackage.haskell.org/")
--   simpleHTTP (getRequest "http://hackage.haskell.org:8012/")
--   </pre>
simpleHTTP :: (HStream ty) => Request ty -> IO (Result (Response ty))

-- | Identical to <a>simpleHTTP</a>, but acting on an already opened
--   stream.
simpleHTTP_ :: HStream ty => HandleStream ty -> Request ty -> IO (Result (Response ty))

-- | <tt>sendHTTP hStream httpRequest</tt> transmits <tt>httpRequest</tt>
--   (after normalization) over <tt>hStream</tt>, 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))

-- | <tt>sendHTTP_notify hStream httpRequest action</tt> behaves like
--   <a>sendHTTP</a>, but lets you supply an IO <tt>action</tt> 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))

-- | <tt>receiveHTTP hStream</tt> reads a <a>Request</a> from the
--   <a>HandleStream</a> <tt>hStream</tt>
receiveHTTP :: HStream ty => HandleStream ty -> IO (Result (Request ty))

-- | <tt>respondHTTP hStream httpResponse</tt> transmits an HTTP
--   <a>Response</a> over the <a>HandleStream</a> <tt>hStream</tt>. It
--   could be used to implement simple web server interactions, performing
--   the dual role to <a>sendHTTP</a>.
respondHTTP :: HStream ty => HandleStream ty -> Response ty -> IO ()

-- | A convenience constructor for a GET <a>Request</a>.
--   
--   If the URL isn't syntactically valid, the function raises an error.
getRequest :: String -> Request_String

-- | A convenience constructor for a HEAD <a>Request</a>.
--   
--   If the URL isn't syntactically valid, the function raises an error.
headRequest :: String -> Request_String

-- | A convenience constructor for a POST <a>Request</a>.
--   
--   If the URL isn't syntactically valid, the function raises an error.
postRequest :: String -> Request_String

-- | A convenience constructor for a POST <a>Request</a>.
--   
--   It constructs a request and sets the body as well as the Content-Type
--   and Content-Length headers. The contents of the body are forced to
--   calculate the value for the Content-Length header.
--   
--   If the URL isn't syntactically valid, the function raises an error.
postRequestWithBody :: String -> String -> String -> Request_String

-- | <tt>getResponseBody response</tt> takes the response of a HTTP
--   requesting action and tries to extricate the body of the
--   <a>Response</a> <tt>response</tt>. If the request action returned an
--   error, an IO exception is raised.
getResponseBody :: Result (Response ty) -> IO ty

-- | <tt>getResponseBody response</tt> takes the response of a HTTP
--   requesting action and tries to extricate the status code of the
--   <a>Response</a> <tt>response</tt>. If the request action returned an
--   error, an IO exception is raised.
getResponseCode :: Result (Response ty) -> IO ResponseCode


-- | Transmitting HTTP requests and responses holding <tt>String</tt> in
--   their payload bodies. This is one of the implementation modules for
--   the <a>Network.HTTP</a> interface, representing request and response
--   content as <tt>String</tt>s and transmitting them in non-packed form
--   (cf. <a>Network.HTTP.HandleStream</a> and its use of
--   <tt>ByteString</tt>s.) over <a>Stream</a> 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 <a>Network.HTTP</a>.
--   <i>Notice</i> 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 <a>Network.HTTP</a> 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 <a>simpleHTTP</a>, 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 <a>Network.Browser</a> goes beyond the basic <a>Network.HTTP</a>
--   functionality in providing support for more involved, and real,
--   request/response interactions over HTTP. Additional features supported
--   are:
--   
--   <ul>
--   <li>HTTP Authentication handling</li>
--   <li>Transparent handling of redirects</li>
--   <li>Cookie stores + transmission.</li>
--   <li>Transaction logging</li>
--   <li>Proxy-mediated connections.</li>
--   </ul>
--   
--   Example use:
--   
--   <pre>
--   do
--     (_, rsp)
--        &lt;- Network.Browser.browse $ do
--              setAllowRedirects True -- handle HTTP redirects
--              request $ getRequest "http://www.haskell.org/"
--     return (take 100 (rspBody rsp))
--   </pre>
module Network.Browser

-- | <tt>BrowserState</tt> is the (large) record type tracking the current
--   settings of the browser.
data BrowserState connection

-- | <tt>BrowserAction</tt> is the IO monad, but carrying along a
--   <a>BrowserState</a>.
data BrowserAction conn a

-- | HTTP proxies (or not) are represented via <a>Proxy</a>, specifying if
--   a proxy should be used for the request (see <a>setProxy</a>)
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
--   <a>Authority</a> for authentication with the proxy.
Proxy :: String -> (Maybe Authority) -> Proxy

-- | <tt>browse act</tt> is the toplevel action to perform a
--   <a>BrowserAction</a>. Example use: <tt>browse (request (getRequest
--   yourURL))</tt>.
browse :: BrowserAction conn a -> IO a

-- | <tt>request httpRequest</tt> tries to submit the <a>Request</a>
--   <tt>httpRequest</tt> to some HTTP server (possibly going via a
--   <i>proxy</i>, see <a>setProxy</a>.) Upon successful delivery, the URL
--   where the response was fetched from is returned along with the
--   <a>Response</a> itself.
request :: HStream ty => Request ty -> BrowserAction (HandleStream ty) (URI, Response ty)

-- | <tt>getBrowserState</tt> returns the current browser config. Useful
--   for restoring state across <a>BrowserAction</a>s.

-- | <i>Deprecated: Use Control.Monad.State.get instead.</i>
getBrowserState :: BrowserAction t (BrowserState t)

-- | <tt>withBrowserAction st act</tt> performs <tt>act</tt> with
--   <a>BrowserState</a> <tt>st</tt>.
withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t a

-- | <tt>setAllowRedirects onOff</tt> toggles the willingness to follow
--   redirects (HTTP responses with 3xx status codes).
setAllowRedirects :: Bool -> BrowserAction t ()

-- | <tt>getAllowRedirects</tt> returns current setting of the
--   do-chase-redirects flag.
getAllowRedirects :: BrowserAction t Bool

-- | <tt>setMaxRedirects maxCount</tt> 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 <i>not</i> enable
--   following of redirects itself; use <a>setAllowRedirects</a> to do so.
setMaxRedirects :: Maybe Int -> BrowserAction t ()

-- | <tt>getMaxRedirects</tt> returns the current setting for the
--   max-redirect count. If <tt>Nothing</tt>, the <a>Network.Browser</a>'s
--   default is used.
getMaxRedirects :: BrowserAction t (Maybe Int)

-- | <tt>Authority</tt> specifies the HTTP Authentication method to use for
--   a given domain/realm; <tt>Basic</tt> or <tt>Digest</tt>.
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]

-- | <tt>getAuthorities</tt> return the current set of <tt>Authority</tt>s
--   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

-- | <tt>Algorithm</tt> controls the digest algorithm to, <tt>MD5</tt> or
--   <tt>MD5Session</tt>.
data Algorithm
AlgMD5 :: Algorithm
AlgMD5sess :: Algorithm

-- | <tt>getAuthorityGen</tt> returns the current authority generator
getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String)))

-- | <tt>setAuthorityGen genAct</tt> sets the auth generator to
--   <tt>genAct</tt>.
setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t ()

-- | <tt>setAllowBasicAuth onOff</tt> enables/disables HTTP Basic
--   Authentication.
setAllowBasicAuth :: Bool -> BrowserAction t ()
getAllowBasicAuth :: BrowserAction t Bool

-- | <tt>setMaxErrorRetries mbMax</tt> sets the maximum number of attempts
--   at transmitting a request. If <tt>Nothing</tt>, rever to default max.
setMaxErrorRetries :: Maybe Int -> BrowserAction t ()

-- | <tt>getMaxErrorRetries</tt> returns the current max number of error
--   retries.
getMaxErrorRetries :: BrowserAction t (Maybe Int)

-- | <tt>setMaxPoolSize maxCount</tt> sets the maximum size of the
--   connection pool that is used to cache connections between requests
setMaxPoolSize :: Maybe Int -> BrowserAction t ()

-- | <tt>getMaxPoolSize</tt> gets the maximum size of the connection pool
--   that is used to cache connections between requests. If
--   <tt>Nothing</tt>, the <a>Network.Browser</a>'s default is used.
getMaxPoolSize :: BrowserAction t (Maybe Int)

-- | <tt>setMaxAuthAttempts mbMax</tt> sets the maximum number of
--   authentication attempts to do. If <tt>Nothing</tt>, rever to default
--   max.
setMaxAuthAttempts :: Maybe Int -> BrowserAction t ()

-- | <tt>getMaxAuthAttempts</tt> returns the current max auth attempts. If
--   <tt>Nothing</tt>, the browser's default is used.
getMaxAuthAttempts :: BrowserAction t (Maybe Int)

-- | <tt>setCookieFilter fn</tt> sets the cookie acceptance filter to
--   <tt>fn</tt>.
setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t ()

-- | <tt>getCookieFilter</tt> returns the current cookie acceptance filter.
getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool)

-- | <tt>defaultCookieFilter</tt> is the initial cookie acceptance filter.
--   It welcomes them all into the store <tt>:-)</tt>
defaultCookieFilter :: URI -> Cookie -> IO Bool

-- | <tt>userCookieFilter</tt> 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

-- | <tt>Cookie</tt> 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

-- | <tt>getCookies</tt> returns the current set of cookies known to the
--   browser.
getCookies :: BrowserAction t [Cookie]

-- | <tt>setCookies cookies</tt> replaces the set of cookies known to the
--   browser to <tt>cookies</tt>. Useful when wanting to restore cookies
--   used across <a>browse</a> invocations.
setCookies :: [Cookie] -> BrowserAction t ()

-- | <tt>addCookie c</tt> adds a cookie to the browser state, removing
--   duplicates.
addCookie :: Cookie -> BrowserAction t ()

-- | <tt>setErrHandler</tt> sets the IO action to call when the browser
--   reports running errors. To disable any such, set it to <tt>const
--   (return ())</tt>.
setErrHandler :: (String -> IO ()) -> BrowserAction t ()

-- | <tt>setOutHandler</tt> sets the IO action to call when the browser
--   chatters info on its running. To disable any such, set it to <tt>const
--   (return ())</tt>.
setOutHandler :: (String -> IO ()) -> BrowserAction t ()

-- | <tt>setEventHandler onBrowserEvent</tt> configures event handling. If
--   <tt>onBrowserEvent</tt> is <tt>Nothing</tt>, event handling is turned
--   off; setting it to <tt>Just onEv</tt> causes the <tt>onEv</tt> 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 ()

-- | <tt>BrowserEvent</tt> is the event record type that a user-defined
--   handler, set via <a>setEventHandler</a>, will be passed. It indicates
--   various state changes encountered in the processing of a given
--   <a>RequestID</a>, along with timestamps at which they occurred.
data BrowserEvent
BrowserEvent :: UTCTime -> RequestID -> String -> BrowserEventType -> BrowserEvent
[browserTimestamp] :: BrowserEvent -> UTCTime
[browserRequestID] :: BrowserEvent -> RequestID
[browserRequestURI] :: BrowserEvent -> String
[browserEventType] :: BrowserEvent -> BrowserEventType

-- | <a>BrowserEventType</a> 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

-- | <tt>setProxy p</tt> will disable proxy usage if <tt>p</tt> is
--   <tt>NoProxy</tt>. If <tt>p</tt> is <tt>Proxy proxyURL mbAuth</tt>,
--   then <tt>proxyURL</tt> is interpreted as the URL of the proxy to use,
--   possibly authenticating via <a>Authority</a> information in
--   <tt>mbAuth</tt>.
setProxy :: Proxy -> BrowserAction t ()

-- | <tt>getProxy</tt> returns the current proxy settings. If the
--   auto-proxy flag is set to <tt>True</tt>, <tt>getProxy</tt> will
--   perform the necessary
getProxy :: BrowserAction t Proxy

-- | <tt>setCheckForProxy flg</tt> sets the one-time check for proxy flag
--   to <tt>flg</tt>. If <tt>True</tt>, the session will try to determine
--   the proxy server is locally configured. See <a>fetchProxy</a> for
--   details of how this done.
setCheckForProxy :: Bool -> BrowserAction t ()

-- | <tt>getCheckForProxy</tt> returns the current check-proxy setting.
--   Notice that this may not be equal to <tt>True</tt> if the session has
--   set it to that via <a>setCheckForProxy</a> 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

-- | <tt>setDebugLog mbFile</tt> turns off debug logging iff
--   <tt>mbFile</tt> is <tt>Nothing</tt>. If set to <tt>Just fStem</tt>,
--   logs of browser activity is appended to files of the form
--   <tt>fStem-url-authority</tt>, i.e., <tt>fStem</tt> is just the prefix
--   for a set of log files, one per host/authority.
setDebugLog :: Maybe String -> BrowserAction t ()

-- | <tt>getUserAgent</tt> returns the current <tt>User-Agent:</tt> default
--   string.
getUserAgent :: BrowserAction t String

-- | <tt>setUserAgent ua</tt> sets the current <tt>User-Agent:</tt> string
--   to <tt>ua</tt>. It will be used if no explicit user agent header is
--   found in subsequent requests.
--   
--   A common form of user agent string is <tt>"name/version
--   (details)"</tt>. For example <tt>"cabal-install/0.10.2 (HTTP
--   4000.1.2)"</tt>. Including the version of this HTTP package can be
--   helpful if you ever need to track down HTTP compatability quirks. This
--   version is available via <a>httpPackageVersion</a>. For more info see
--   <a>http://en.wikipedia.org/wiki/User_agent</a>.
setUserAgent :: String -> BrowserAction t ()
out :: String -> BrowserAction t ()
err :: String -> BrowserAction t ()

-- | Lifts an IO action into the <a>BrowserAction</a> monad.

-- | <i>Deprecated: Use Control.Monad.Trans.liftIO instead.</i>
ioAction :: IO a -> BrowserAction t a
defaultGETRequest :: URI -> Request_String
defaultGETRequest_ :: BufferType a => URI -> Request a
formToRequest :: Form -> Request_String

-- | <tt>uriDefaultTo a b</tt> returns a URI that is consistent with the
--   first argument URI <tt>a</tt> when read in the context of the second
--   URI <tt>b</tt>. 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 Control.Monad.State.Class.MonadState (Network.Browser.BrowserState conn) (Network.Browser.BrowserAction conn)
instance Control.Monad.IO.Class.MonadIO (Network.Browser.BrowserAction conn)
instance GHC.Base.Monad (Network.Browser.BrowserAction conn)
instance GHC.Base.Applicative (Network.Browser.BrowserAction conn)
instance GHC.Base.Functor (Network.Browser.BrowserAction conn)
instance GHC.Show.Show (Network.Browser.BrowserState t)
