-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A ByteString based library for writing HTTP(S) servers and clients.
--   
--   A ByteString based HTTP(S) library
@package network-minihttp
@version 0.2


-- | This module contains a structure for representing web URLs. We don't
--   try to be a fully general URI parser (so no <tt>mailto:</tt> etc), but
--   it's a lot better than <a>Network.URI</a> for dealing with HTTP(S)
module Network.MiniHTTP.URL

-- | A web URL
data URL
URL :: Scheme -> Maybe ByteString -> Maybe ByteString -> Host -> Int -> ByteString -> Map ByteString ByteString -> Maybe ByteString -> URL
urlScheme :: URL -> Scheme
urlUser :: URL -> Maybe ByteString
urlPassword :: URL -> Maybe ByteString
urlHost :: URL -> Host

-- | defaults based on the scheme
urlPort :: URL -> Int

-- | does not include leading <a>/</a>
urlPath :: URL -> ByteString
urlArguments :: URL -> Map ByteString ByteString

-- | doesn't include '#'
urlFragment :: URL -> Maybe ByteString

-- | This is a relative URL. It just copies (and renames) the last three
--   members of URL. However, it's good to keep these two different types
--   of URL apart in the type system.
data RelativeURL
RelativeURL :: ByteString -> Map ByteString ByteString -> Maybe ByteString -> RelativeURL

-- | does not include leading <a>/</a>
rurlPath :: RelativeURL -> ByteString
rurlArguments :: RelativeURL -> Map ByteString ByteString
rurlFragment :: RelativeURL -> Maybe ByteString

-- | The transport layer to be used
data Scheme
HTTP :: Scheme
HTTPS :: Scheme

-- | The host where the resource can be found
data Host
IPv4Literal :: HostAddress -> Host
IPv6Literal :: HostAddress6 -> Host
Hostname :: ByteString -> Host

-- | Extract a relative URL from a URL
toRelative :: URL -> RelativeURL

-- | Parse a URL
parse :: ByteString -> Maybe URL

-- | Parse a relative URL
parseRelative :: ByteString -> Maybe RelativeURL

-- | Parse just an arguments map. Can be useful for POST requests. Warning:
--   it occurs to be that the arguments in a POST request might include
--   unescaped '#' symbols. In a URL that would be illegal, but the parser
--   may need to be reworked for that.
parseArguments :: ByteString -> Maybe (Map ByteString ByteString)

-- | Convert a URL to a ByteString. It's the same as <a>show</a>, except
--   for the type of the return.
serialise :: URL -> ByteString
serialiseRelative :: RelativeURL -> ByteString

-- | Serialise just an arguments map. Can be useful for POST requests.
serialiseArguments :: Map ByteString ByteString -> ByteString
instance Show Host
instance Eq Host
instance Show Scheme
instance Eq Scheme
instance Show RelativeURL
instance Eq RelativeURL
instance Eq URL
instance Show URL


-- | This module serialises and deserialises HTTP headers. It contains
--   Haskell representations of request and replies and can transform them
--   to, and from, the HTTP wire format.
module Network.MiniHTTP.Marshal

-- | A HTTP request
data Request
Request :: Method -> RelativeURL -> Int -> Int -> Headers -> Request
reqMethod :: Request -> Method
reqUrl :: Request -> RelativeURL
reqMajor :: Request -> Int
reqMinor :: Request -> Int
reqHeaders :: Request -> Headers

-- | A HTTP reply
data Reply
Reply :: Int -> Int -> Int -> String -> Headers -> Reply
replyMajor :: Reply -> Int
replyMinor :: Reply -> Int
replyStatus :: Reply -> Int
replyMessage :: Reply -> String
replyHeaders :: Reply -> Headers

-- | A HTTP range
data Range

-- | everything from the given byte onwards
RangeFrom :: Int64 -> Range

-- | the bytes in the given range, inclusive
RangeOf :: Int64 -> Int64 -> Range

-- | the final n bytes
RangeSuffix :: Int64 -> Range

-- | HTTP headers, see RFC 2616 section 14
data Headers
Headers :: Maybe [(MediaType, Int)] -> Maybe [(String, Int)] -> Maybe [(String, Int)] -> Maybe [(String, Int)] -> Bool -> Maybe Int64 -> Maybe [Method] -> Maybe ByteString -> [Cookie] -> Bool -> [String] -> [String] -> Maybe [String] -> Maybe Int64 -> Maybe ByteString -> Maybe (Maybe (Int64, Int64), Maybe Int64) -> Maybe MediaType -> Maybe UTCTime -> Maybe (Bool, ByteString) -> Maybe UTCTime -> Maybe ByteString -> Maybe (Either () [ByteString]) -> Maybe UTCTime -> Maybe (Either () [(Bool, ByteString)]) -> Maybe (Either ByteString UTCTime) -> Maybe UTCTime -> Maybe Int -> Maybe UTCTime -> Maybe ByteString -> Maybe [(String, Maybe String)] -> Maybe ByteString -> Maybe ByteString -> Maybe [Range] -> Maybe ByteString -> Maybe Int64 -> Maybe ByteString -> [Cookie] -> Maybe [String] -> [String] -> Maybe ByteString -> Maybe ByteString -> Map ByteString ByteString -> Headers
httpAccept :: Headers -> Maybe [(MediaType, Int)]
httpAcceptCharset :: Headers -> Maybe [(String, Int)]
httpAcceptEncoding :: Headers -> Maybe [(String, Int)]
httpAcceptLanguage :: Headers -> Maybe [(String, Int)]
httpAcceptRanges :: Headers -> Bool
httpAge :: Headers -> Maybe Int64
httpAllow :: Headers -> Maybe [Method]
httpAuthorization :: Headers -> Maybe ByteString
httpCookie :: Headers -> [Cookie]
httpConnectionClose :: Headers -> Bool
httpConnection :: Headers -> [String]
httpContentEncodings :: Headers -> [String]
httpContentLanguage :: Headers -> Maybe [String]
httpContentLength :: Headers -> Maybe Int64
httpContentLocation :: Headers -> Maybe ByteString
httpContentRange :: Headers -> Maybe (Maybe (Int64, Int64), Maybe Int64)
httpContentType :: Headers -> Maybe MediaType
httpDate :: Headers -> Maybe UTCTime
httpETag :: Headers -> Maybe (Bool, ByteString)
httpExpires :: Headers -> Maybe UTCTime
httpHost :: Headers -> Maybe ByteString
httpIfMatch :: Headers -> Maybe (Either () [ByteString])
httpIfModifiedSince :: Headers -> Maybe UTCTime
httpIfNoneMatch :: Headers -> Maybe (Either () [(Bool, ByteString)])
httpIfRange :: Headers -> Maybe (Either ByteString UTCTime)
httpIfUnmodifiedSince :: Headers -> Maybe UTCTime
httpKeepAlive :: Headers -> Maybe Int
httpLastModified :: Headers -> Maybe UTCTime
httpLocation :: Headers -> Maybe ByteString
httpPragma :: Headers -> Maybe [(String, Maybe String)]
httpProxyAuthenticate :: Headers -> Maybe ByteString
httpProxyAuthorization :: Headers -> Maybe ByteString
httpRange :: Headers -> Maybe [Range]
httpReferer :: Headers -> Maybe ByteString
httpRetryAfter :: Headers -> Maybe Int64
httpServer :: Headers -> Maybe ByteString
httpSetCookie :: Headers -> [Cookie]
httpTrailer :: Headers -> Maybe [String]
httpTransferEncoding :: Headers -> [String]
httpUserAgent :: Headers -> Maybe ByteString
httpWWWAuthenticate :: Headers -> Maybe ByteString
httpOtherHeaders :: Headers -> Map ByteString ByteString

-- | A HTTP Cookie. See <a>http://en.wikipedia.org/wiki/HTTP_cookie</a>
data Cookie
Cookie :: ByteString -> ByteString -> Maybe String -> Maybe String -> Maybe UTCTime -> Bool -> Cookie
cookieName :: Cookie -> ByteString
cookieValue :: Cookie -> ByteString
cookiePath :: Cookie -> Maybe String
cookieDomain :: Cookie -> Maybe String
cookieExpires :: Cookie -> Maybe UTCTime
cookieSecure :: Cookie -> Bool
emptyHeaders :: Headers
emptyCookie :: Cookie

-- | Convert a status code to a message (e.g. 200 -&gt; <a>OK</a>)
statusToMessage :: Int -> String

-- | The list of valid methods, see RFC 2616 section 5.1
data Method
OPTIONS :: Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
CONNECT :: Method
type MediaType = ((String, String), [(String, String)])
putRequest :: Request -> Put
putReply :: Reply -> Put
parseRequest :: (BinaryParser m) => m Request
parseReply :: (BinaryParser m) => m Reply
parseChunkHeader :: (BinaryParser m) => m Int64
instance Ord Method
instance Enum Method
instance Show Method
instance Eq Method
instance Show Cookie
instance Eq Cookie
instance Ord Cookie
instance Show Headers
instance Show Range
instance Show Reply
instance Show Request


-- | This module contains many helper functions, as well the code for
--   <a>Source</a>, which is a pretty important structure
module Network.MiniHTTP.HTTPConnection

-- | A source is a stream of data, like a lazy data structure, but without
--   some of the dangers that such entail. A source returns a
--   <a>SourceResult</a> each time you evaluate it.
type Source = IO SourceResult
data SourceResult

-- | error - please don't read this source again
SourceError :: SourceResult

-- | end of data
SourceEOF :: SourceResult

-- | some data
SourceData :: ByteString -> SourceResult

-- | Construct a source from a ByteString
bsSource :: ByteString -> IO Source

-- | Construct a source from a Handle
hSource :: (Int64, Int64) -> Handle -> IO Source

-- | A source with no data (e.g. <tt><i>dev</i>null</tt>)
nullSource :: Source

-- | Convert a source to a lazy ByteString
sourceToLBS :: Source -> IO ByteString

-- | Take, at most, the first n bytes from a Source and return a strict
--   ByteString. Returns Nothing on error. (A short read is not an error)
sourceToBS :: Int -> Source -> IO (Maybe ByteString)

-- | A source which reads from a <a>Connection</a>
connSource :: Int64 -> ByteString -> Connection -> IO Source

-- | A source which reads an HTTP chunked reply from a <a>Connection</a>
connChunkedSource :: Connection -> IO Source

-- | A source which reads from the given <tt>Connection</tt> until the
--   connection signals end-of-file.
connEOFSource :: Connection -> IO Source

-- | Read a source until it returns <a>SourceEOF</a>
sourceDrain :: Source -> IO ()

-- | Stream a source to a connection while not enqueuing more than lowWater
--   bytes in the outbound queue (not inc the kernel buffer)
streamSource :: Int -> Connection -> Source -> IO Bool

-- | Stream a source to a connection, with chunked encoding, while not
--   enqueuing more than lowWater bytes in the outbound queue (not inc the
--   kernel buffer)
streamSourceChunked :: Int -> Connection -> Source -> IO Bool

-- | Run an incremental parser from the network
readIG :: Connection -> Int -> Int -> Get a a -> IO (Maybe a)

-- | Run an incremental parser from a <a>Source</a>
sourceIG :: Source -> Int -> Get a a -> IO (Maybe a)
maybeRead :: (Read a) => ByteString -> Maybe a

-- | Convert an SSL connection to a BaseConnection for Network.Connection
sslToBaseConnection :: SSL -> BaseConnection
instance Show SourceResult


-- | This module contains a very basic HTTP client. At the moment, it
--   doesn't even handle redirects for you.
--   
--   Note that, in order to use SSL, you need to have the root CA
--   certificates in a PEM file in <tt><i>etc</i>ssh/certs.pem</tt> and you
--   need to have wrapped your main function in
--   <tt>OpenSSL.withOpenSSL</tt>
module Network.MiniHTTP.Client

-- | Fetch an HTTP(S) entity.
fetchBasic :: Headers -> URL -> IO (Connection, Reply, Maybe Source)

-- | Construct a connection to the correct host for the given URL. (i.e.
--   resolve the hostname and create a TCP connection to the correct port).
--   
--   Note that the DNS resolution (if any) doesn't block the whole process.
connection :: URL -> IO Socket

-- | Setup the transport (i.e. SSL) for the given URL. In the case of a
--   HTTP scheme, this just wraps the socket in a Connection.
transport :: URL -> Socket -> IO Connection

-- | A lower level HTTP client, but it allows you to perform POSTs etc
request :: Connection -> Request -> Maybe Source -> IO (Maybe (Reply, Maybe Source))


-- | This module contains support for the OpenID authentication standard.
--   See <a>http://www.openid.net</a> for details of the protocol. At the
--   moment, only the basic v2 authentication is supported. Also, we only
--   support OpenID 2.0 HTML discovery, not Yadis nor XRI.
--   
--   Only DH-SHA1 is used for the cryptography. This used to be SHA256, but
--   Yahoo doesn't support it (boo!)
--   
--   References in this module are to the OpenID v2 spec
--   <a>http://openid.net/specs/openid-authentication-2_0.html</a>
module Network.MiniHTTP.OpenID

-- | This is the result of Discovery: the OP local identity and the server
--   HTTP endpoint.
data OpenIDDiscovery
OpenIDDiscovery :: URL -> Maybe String -> OpenIDDiscovery
discoveryProvider :: OpenIDDiscovery -> URL
discoveryLocalID :: OpenIDDiscovery -> Maybe String

-- | There are two types of checkid calls.
data CheckIDType
CheckIDSetup :: CheckIDType
CheckIDImmediate :: CheckIDType

-- | The type of an OpenID handle. Handles are used to identify sessions
--   between the consumer and OP.
data Handle

-- | The type of a key.
data Key

-- | Lookup a key given the hostname of the OP and the handle. Generally
--   used after an indirect request to check a signature from an OP.
findKey :: ByteString -> Handle -> STM (Maybe Key)

-- | Use HTML discovery to find the OpenID information for a given URL
discover :: URL -> IO OpenIDDiscovery

-- | Perform an association with a discovered OP and return either an error
--   message or a handle, a key and the number of seconds from now when the
--   handle will expire.
--   
--   Internally this uses a cache so <a>associate</a> may not actually
--   involve an HTTP request to the OP.
associate :: OpenIDDiscovery -> IO (Handle, Key)

-- | Construct a checkid call
checkID :: CheckIDType -> URL -> OpenIDDiscovery -> Handle -> ByteString -> Maybe ByteString -> URL
processCheckIDReply :: Map ByteString ByteString -> IO (Either String ByteString)
instance Show CheckIDType
instance Eq CheckIDType
instance Show Key
instance Eq Key
instance Show Handle
instance Eq Handle
instance Show OpenIDDiscovery
instance Eq OpenIDDiscovery


-- | This module contains functions for writing webservers. These servers
--   process requests in a state monad pipeline and several useful actions
--   are provided herein.
--   
--   See <tt>examples/test.hs</tt> for an example of how to use this
--   module.
module Network.MiniHTTP.Server

-- | The processing monad
type WebMonad = StateT WebState IO

-- | Processing a request involves running a number of actions in a StateT
--   monad where the state for that monad is this record. This contains
--   both a <tt>Source</tt> and a <a>Handle</a> element. Often something
--   will fill in the <a>Handle</a> and expect later processing to convert
--   it to a <a>Source</a>. Somehow, you have to end up with a
--   <a>Source</a>, however.
data WebState
WebState :: Request -> Maybe Source -> Map ByteString MediaType -> Reply -> Maybe Source -> Maybe Handle -> Maybe (IO ()) -> WebState

-- | the original request
wsRequest :: WebState -> Request

-- | the client's payload
wsBody :: WebState -> Maybe Source

-- | the system mime types db, mapping file extensions
wsMimeTypes :: WebState -> Map ByteString MediaType

-- | the current reply
wsReply :: WebState -> Reply

-- | the current source
wsSource :: WebState -> Maybe Source

-- | the current handle
wsHandle :: WebState -> Maybe Handle

-- | an action to be performed before sending the reply
wsAction :: WebState -> Maybe (IO ())

-- | Return the request
getRequest :: WebMonad Request

-- | Return the client's request payload (if any)
getPayload :: WebMonad (Maybe Source)

-- | Get the arguments to a POST request
getPOST :: Int -> WebMonad (Map ByteString ByteString)

-- | Get the arguments to a GET request
getGET :: WebMonad (Map ByteString ByteString)

-- | Return the current reply
getReply :: WebMonad Reply

-- | Set the current reply to be a reply with the given status code, the
--   default message for that status code, an empty body and an empty set
--   of headers.
setReply :: Int -> WebMonad ()

-- | Set a header in the current reply. Because of the way records work,
--   you use this function like this:
--   
--   <pre>
--   setHeader $ \h -&gt; h { httpSomeHeader = Just value }
--   </pre>
setHeader :: (Headers -> Headers) -> WebMonad ()
setCookie :: Cookie -> WebMonad ()
errorPage :: String -> WebMonad ()

-- | This handles the If-*Matches and If-*Modified conditional headers. It
--   takes its information from the Last-Modified and ETag headers of the
--   current reply. Note that, for the purposes of ETag matching, a reply
--   without an ETag header is considered not to exist from the point of
--   view of, say, If-Matches: *.
handleConditionalRequest :: WebMonad ()

-- | If the current state includes a Handle, this turns it into a Source
handleHandleToSource :: WebMonad ()

-- | This handles Range requests and also translates from Handles to
--   Sources. If the WebMonad has a Handle at this point, then we can
--   construct sources from any subrange of the file. (We also assume that
--   Content-Length is correctly set.)
--   
--   See RFC 2616, section 14.35
handleRangeRequests :: WebMonad ()

-- | At the moment, this just adds the header Server: Network.MiniHTTP
handleDecoration :: WebMonad ()

-- | This is a very simple handler which deals with requests by returning
--   the requested file from the filesystem. It sets a Handle in the state
--   and sets the Content-Type, Content-Length and Last-Modified headers
handleFromFilesystem :: FilePath -> WebMonad ()

-- | Start an IPv4 HTTP server
serveHTTP :: Int -> WebMonad () -> IO ()

-- | Start an IPv4 HTTPS server. Plese remember to have wrapped your main
--   function in <tt>OpenSSL.withOpenSSL</tt> otherwise you'll probably
--   crash the process.
serveHTTPS :: Int -> FilePath -> FilePath -> WebMonad () -> IO ()
data DispatchMatch
Exact :: ByteString -> DispatchMatch
Prefix :: ByteString -> DispatchMatch

-- | This is an, optional, helper function which you might find useful. The
--   serving fuctions both expect a <a>WebMonad</a> action which is called
--   to process each request. In general you have to write that and
--   dispatch based on the client's request.
--   
--   This might save you some work: it tries each of the elements in the
--   list in turn. As soon as one matches it runs the given action to
--   process the request.
dispatchOnURL :: [(DispatchMatch, WebMonad ())] -> WebMonad ()
instance Show DispatchMatch
instance Eq DispatchMatch


-- | Basic session support. Sessions are (currently) just maps of strings
--   to strings which are serialised and sent to the client using a Cookie.
--   Serialised, they should be less than 4K, so the sum of all your
--   strings in the map should be &lt; 3900 bytes to be safe.
--   
--   The cookies are HMACed and encrypted so that the client can't inspect
--   nor alter them. The key is, by default, generated randomly every time
--   the server starts. If you want the cookies to be reusable across
--   restarts or servers you need to set the key yourself.
--   
--   Also, by the default, the cookies are set to expire when the browser
--   session ends.
module Network.MiniHTTP.Session

-- | Return the current session. If the user didn't present a cookie, or
--   the cookie is invalid, an empty map is returned.
getSession :: WebMonad (Map ByteString ByteString)

-- | Set the current session. This alters the headers of the current
--   request, so future actions which reset the headers (like
--   <a>setReply</a>) will undo this.
putSession :: Map ByteString ByteString -> WebMonad ()

-- | Add a key value pair to the session
addSession :: ByteString -> ByteString -> WebMonad ()

-- | Set the secret key used to HMAC and encrypt the session cookies.
setSessionSecretKey :: ByteString -> STM ()