libghc-happstack-server-doc 7.3.7-1 / usr / share / doc / libghc-happstack-server-doc / html / happstack-server.txt

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


-- | Web related tools and services.
--   
--   Happstack Server provides an HTTP server and a rich set of functions
--   for routing requests, handling query parameters, generating responses,
--   working with cookies, serving files, and more. For in-depth
--   documentation see the Happstack Crash Course
--   <a>http://happstack.com/docs/crashcourse/index.html</a>
@package happstack-server
@version 7.3.7

module Happstack.Server.Internal.Socket

-- | alternative implementation of accept to work around EAI_AGAIN errors
acceptLite :: Socket -> IO (Socket, HostName, PortNumber)
sockAddrToPeer :: SockAddr -> (HostName, PortNumber)

module Happstack.Server.Internal.LogFormat

-- | Format the time as describe in the Apache combined log format.
--   http:<i></i>httpd.apache.org<i>docs</i>2.2/logs.html#combined
--   
--   The format is: [day<i>month</i>year:hour:minute:second zone] day =
--   2*digit month = 3*letter year = 4*digit hour = 2*digit minute =
--   2*digit second = 2*digit zone = (<a>+</a> | <a>-</a>) 4*digit
formatTimeCombined :: FormatTime t => t -> String

-- | Format the request as describe in the Apache combined log format.
--   http:<i></i>httpd.apache.org<i>docs</i>2.2/logs.html#combined
--   
--   The format is: <a>%h - %u %t "%r" %&gt;s %b "%{Referer}i"
--   "%{User-agent}i"</a> %h: This is the IP address of the client (remote
--   host) which made the request to the server. %u: This is the userid of
--   the person requesting the document as determined by HTTP
--   authentication. %t: The time that the request was received. %r: The
--   request line from the client is given in double quotes. %&gt;s: This
--   is the status code that the server sends back to the client. %b: The
--   last part indicates the size of the object returned to the client, not
--   including the response headers. %{Referer}: The <a>Referer</a> (sic)
--   HTTP request header. %{User-agent}: The User-Agent HTTP request
--   header.
formatRequestCombined :: FormatTime t => String -> String -> t -> String -> Int -> Integer -> String -> String -> String

module Happstack.Server.Internal.TimeoutManager

-- | A timeout manager
data Manager
data Handle
initialize :: Int -> IO Manager
register :: Manager -> IO () -> IO Handle
registerKillThread :: Manager -> IO Handle
tickle :: Handle -> IO ()
pause :: Handle -> IO ()
resume :: Handle -> IO ()
cancel :: Handle -> IO ()
forceTimeout :: Handle -> IO ()

-- | terminate all threads immediately
forceTimeoutAll :: Manager -> IO ()

module Happstack.Server.Internal.TimeoutIO

-- | TimeoutIO is a record which abstracts out all the network IO functions
--   needed by the request handling loop. This allows use to use the same
--   event loop for handle both http:<i></i> and https:<i></i>.
data TimeoutIO
TimeoutIO :: Handle -> (ByteString -> IO ()) -> (ByteString -> IO ()) -> IO ByteString -> (FilePath -> Offset -> ByteCount -> IO ()) -> IO () -> Bool -> TimeoutIO
toHandle :: TimeoutIO -> Handle
toPutLazy :: TimeoutIO -> ByteString -> IO ()
toPut :: TimeoutIO -> ByteString -> IO ()
toGetContents :: TimeoutIO -> IO ByteString
toSendFile :: TimeoutIO -> FilePath -> Offset -> ByteCount -> IO ()
toShutdown :: TimeoutIO -> IO ()
toSecure :: TimeoutIO -> Bool


-- | <ul>
--   <li>- borrowed from snap-server. Check there periodically for
--   updates.</li>
--   </ul>
module Happstack.Server.Internal.TimeoutSocket
sPutLazyTickle :: Handle -> Socket -> ByteString -> IO ()
sPutTickle :: Handle -> Socket -> ByteString -> IO ()
sGetContents :: Handle -> Socket -> IO ByteString
sendFileTickle :: Handle -> Socket -> FilePath -> Offset -> ByteCount -> IO ()
iterTickle :: Handle -> IO Iter -> IO ()
timeoutSocketIO :: Handle -> Socket -> TimeoutIO


-- | A wrapper and type class so that functions like <tt>seeOther</tt> can
--   take a URI which is represented by a <a>String</a>, <a>URI</a>, or
--   other instance of <a>ToSURI</a>.
module Happstack.Server.SURI

-- | Retrieves the path component from the URI
path :: SURI -> String

-- | Retrieves the query component from the URI
query :: SURI -> String

-- | Retrieves the scheme component from the URI
scheme :: SURI -> String

-- | Modifies the scheme component of the URI using the provided function
u_scheme :: (String -> String) -> SURI -> SURI

-- | Modifies the path component of the URI using the provided function
u_path :: (String -> String) -> SURI -> SURI

-- | Sets the scheme component of the URI
a_scheme :: String -> SURI -> SURI

-- | Sets the path component of the URI
a_path :: String -> SURI -> SURI

-- | percent decode a String
--   
--   e.g. <tt>"hello%2Fworld"</tt> -&gt; <tt>"hello/world"</tt>
percentDecode :: String -> String
unEscape :: String -> String
unEscapeQS :: String -> String

-- | Returns true if the URI is absolute
isAbs :: SURI -> Bool
newtype SURI
SURI :: URI -> SURI
suri :: SURI -> URI

-- | Render should be used for prettyprinting URIs.
render :: ToSURI a => a -> String

-- | Parses a URI from a String. Returns Nothing on failure.
parse :: String -> Maybe SURI

-- | Convenience class for converting data types to URIs
class ToSURI x
toSURI :: ToSURI x => x -> SURI
class FromPath x
fromPath :: FromPath x => String -> x
instance [overlap ok] Typeable SURI
instance [overlap ok] Eq SURI
instance [overlap ok] Data SURI
instance [overlap ok] ToSURI Text
instance [overlap ok] ToSURI Text
instance [overlap ok] ToSURI String
instance [overlap ok] ToSURI URI
instance [overlap ok] ToSURI SURI
instance [overlap ok] Ord SURI
instance [overlap ok] Read SURI
instance [overlap ok] Show SURI

module Happstack.Server.Internal.Cookie

-- | a type for HTTP cookies. Usually created using <a>mkCookie</a>.
data Cookie
Cookie :: String -> String -> String -> String -> String -> Bool -> Bool -> Cookie
cookieVersion :: Cookie -> String
cookiePath :: Cookie -> String
cookieDomain :: Cookie -> String
cookieName :: Cookie -> String
cookieValue :: Cookie -> String
secure :: Cookie -> Bool
httpOnly :: Cookie -> Bool

-- | Specify the lifetime of a cookie.
--   
--   Note that we always set the max-age and expires headers because
--   internet explorer does not honor max-age. You can specific
--   <a>MaxAge</a> or <a>Expires</a> and the other will be calculated for
--   you. Choose which ever one makes your life easiest.
data CookieLife

-- | session cookie - expires when browser is closed
Session :: CookieLife

-- | life time of cookie in seconds
MaxAge :: Int -> CookieLife

-- | cookie expiration date
Expires :: UTCTime -> CookieLife

-- | cookie already expired
Expired :: CookieLife
calcLife :: CookieLife -> IO (Maybe (Int, UTCTime))

-- | Creates a cookie with a default version of 1, empty domain, a path of
--   <a>/</a>, secure == False and httpOnly == False
--   
--   see also: <tt>addCookie</tt>
mkCookie :: String -> String -> Cookie

-- | Set a Cookie in the Result. The values are escaped as per RFC 2109,
--   but some browsers may have buggy support for cookies containing e.g.
--   <tt>'"'</tt> or <tt>' '</tt>.
--   
--   Also, it seems that chrome, safari, and other webkit browsers do not
--   like cookies which have double quotes around the domain and
--   reject/ignore the cookie. So, we no longer quote the domain.
--   
--   internet explorer does not honor the max-age directive so we set both
--   max-age and expires.
--   
--   See <a>CookieLife</a> and <a>calcLife</a> for a convenient way of
--   calculating the first argument to this function.
mkCookieHeader :: Maybe (Int, UTCTime) -> Cookie -> String

-- | Get all cookies from the HTTP request. The cookies are ordered per RFC
--   from the most specific to the least specific. Multiple cookies with
--   the same name are allowed to exist.
getCookies :: Monad m => ByteString -> m [Cookie]

-- | Get the most specific cookie with the given name. Fails if there is no
--   such cookie or if the browser did not escape cookies in a proper
--   fashion. Browser support for escaping cookies properly is very
--   diverse.
getCookie :: Monad m => String -> ByteString -> m Cookie
getCookies' :: Monad m => ByteString -> m (Either String [Cookie])
getCookie' :: Monad m => String -> ByteString -> m (Either String Cookie)

-- | Not an supported api. Takes a cookie header and returns either a
--   String error message or an array of parsed cookies
parseCookies :: String -> Either String [Cookie]

-- | not a supported api. A parser for RFC 2109 cookies
cookiesParser :: GenParser Char st [Cookie]
instance [overlap ok] Typeable Cookie
instance [overlap ok] Typeable CookieLife
instance [overlap ok] Show Cookie
instance [overlap ok] Eq Cookie
instance [overlap ok] Read Cookie
instance [overlap ok] Data Cookie
instance [overlap ok] Eq CookieLife
instance [overlap ok] Ord CookieLife
instance [overlap ok] Read CookieLife
instance [overlap ok] Show CookieLife

module Happstack.Server.Internal.Types

-- | an HTTP request
data Request
Request :: Bool -> Method -> [String] -> String -> String -> [(String, Input)] -> MVar [(String, Input)] -> [(String, Cookie)] -> HttpVersion -> Headers -> MVar RqBody -> Host -> Request

-- | request uses https://
rqSecure :: Request -> Bool

-- | request method
rqMethod :: Request -> Method

-- | the uri, split on /, and then decoded
rqPaths :: Request -> [String]

-- | the raw rqUri
rqUri :: Request -> String

-- | the QUERY_STRING
rqQuery :: Request -> String

-- | the QUERY_STRING decoded as key/value pairs
rqInputsQuery :: Request -> [(String, Input)]

-- | the request body decoded as key/value pairs (when appropriate)
rqInputsBody :: Request -> MVar [(String, Input)]

-- | cookies
rqCookies :: Request -> [(String, Cookie)]

-- | HTTP version
rqVersion :: Request -> HttpVersion

-- | the HTTP request headers
rqHeaders :: Request -> Headers

-- | the raw, undecoded request body
rqBody :: Request -> MVar RqBody

-- | (hostname, port) of the client making the request
rqPeer :: Request -> Host

-- | an HTTP Response
data Response
Response :: Int -> Headers -> RsFlags -> ByteString -> Maybe (Response -> IO Response) -> Response
rsCode :: Response -> Int
rsHeaders :: Response -> Headers
rsFlags :: Response -> RsFlags
rsBody :: Response -> ByteString
rsValidator :: Response -> Maybe (Response -> IO Response)
SendFile :: Int -> Headers -> RsFlags -> Maybe (Response -> IO Response) -> FilePath -> Integer -> Integer -> Response
rsCode :: Response -> Int
rsHeaders :: Response -> Headers
rsFlags :: Response -> RsFlags
rsValidator :: Response -> Maybe (Response -> IO Response)

-- | file handle to send from
sfFilePath :: Response -> FilePath

-- | offset to start at
sfOffset :: Response -> Integer

-- | number of bytes to send
sfCount :: Response -> Integer

-- | The body of an HTTP <a>Request</a>
newtype RqBody
Body :: ByteString -> RqBody
unBody :: RqBody -> ByteString

-- | a value extract from the <tt>QUERY_STRING</tt> or <a>Request</a> body
--   
--   If the input value was a file, then it will be saved to a temporary
--   file on disk and <a>inputValue</a> will contain <tt>Left
--   pathToTempFile</tt>.
data Input
Input :: Either FilePath ByteString -> Maybe FilePath -> ContentType -> Input
inputValue :: Input -> Either FilePath ByteString
inputFilename :: Input -> Maybe FilePath
inputContentType :: Input -> ContentType

-- | an HTTP header
data HeaderPair
HeaderPair :: ByteString -> [ByteString] -> HeaderPair

-- | header name
hName :: HeaderPair -> ByteString

-- | header value (or values if multiple occurances of the header are
--   present)
hValue :: HeaderPair -> [ByteString]

-- | get the request body from the Request and replace it with Nothing
--   
--   IMPORTANT: You can really only call this function once. Subsequent
--   calls will return <a>Nothing</a>.
takeRequestBody :: MonadIO m => Request -> m (Maybe RqBody)

-- | read the request body inputs
--   
--   This will only work if the body inputs have already been decoded.
--   Otherwise it will return Nothing.
readInputsBody :: Request -> IO (Maybe [(String, Input)])

-- | Converts a Request into a String representing the corresponding URL
rqURL :: Request -> String

-- | Takes a list of (key,val) pairs and converts it into Headers. The keys
--   will be converted to lowercase
mkHeaders :: [(String, String)] -> Headers

-- | Lookup header value. Key is case-insensitive.
getHeader :: HasHeaders r => String -> r -> Maybe ByteString

-- | Lookup header value. Key is a case-insensitive bytestring.
getHeaderBS :: HasHeaders r => ByteString -> r -> Maybe ByteString

-- | Lookup header value with a case-sensitive key. The key must be
--   lowercase.
getHeaderUnsafe :: HasHeaders r => ByteString -> r -> Maybe ByteString

-- | Returns True if the associated key is found in the Headers. The lookup
--   is case insensitive.
hasHeader :: HasHeaders r => String -> r -> Bool

-- | Acts as <a>hasHeader</a> with ByteStrings
hasHeaderBS :: HasHeaders r => ByteString -> r -> Bool

-- | Acts as <a>hasHeaderBS</a> but the key is case sensitive. It should be
--   in lowercase.
hasHeaderUnsafe :: HasHeaders r => ByteString -> r -> Bool

-- | Associates the key/value pair in the headers. Forces the key to be
--   lowercase.
setHeader :: HasHeaders r => String -> String -> r -> r

-- | Acts as <a>setHeader</a> but with ByteStrings.
setHeaderBS :: HasHeaders r => ByteString -> ByteString -> r -> r

-- | Sets the key to the HeaderPair. This is the only way to associate a
--   key with multiple values via the setHeader* functions. Does not force
--   the key to be in lowercase or guarantee that the given key and the key
--   in the HeaderPair will match.
setHeaderUnsafe :: HasHeaders r => ByteString -> HeaderPair -> r -> r

-- | Add a key/value pair to the header. If the key already has a value
--   associated with it, then the value will be appended. Forces the key to
--   be lowercase.
addHeader :: HasHeaders r => String -> String -> r -> r

-- | Acts as addHeader except for ByteStrings
addHeaderBS :: HasHeaders r => ByteString -> ByteString -> r -> r

-- | Add a key/value pair to the header using the underlying HeaderPair
--   data type. Does not force the key to be in lowercase or guarantee that
--   the given key and the key in the HeaderPair will match.
addHeaderUnsafe :: HasHeaders r => ByteString -> HeaderPair -> r -> r

-- | Sets the Response status code to the provided Int and lifts the
--   computation into a Monad.
setRsCode :: Monad m => Int -> Response -> m Response

-- | function to log access requests (see also: <a>logMAccess</a>) type
--   LogAccess time = ( String -- ^ host -&gt; String -- ^ user -&gt; time
--   -- ^ time -&gt; String -- ^ requestLine -&gt; Int -- ^ responseCode
--   -&gt; Integer -- ^ size -&gt; String -- ^ referer -&gt; String -- ^
--   userAgent -&gt; IO ())
type LogAccess time = String -> String -> time -> String -> Int -> Integer -> String -> String -> IO ()

-- | log access requests using hslogger and apache-style log formatting
--   
--   see also: <a>Conf</a>
logMAccess :: FormatTime t => LogAccess t

-- | HTTP configuration
data Conf
Conf :: Int -> Maybe (Response -> IO Response) -> (forall t. FormatTime t => Maybe (LogAccess t)) -> Int -> Maybe ThreadGroup -> Conf

-- | Port for the server to listen on.
port :: Conf -> Int

-- | a function to validate the output on-the-fly
validator :: Conf -> Maybe (Response -> IO Response)

-- | function to log access requests (see also: <a>logMAccess</a>)
logAccess :: Conf -> forall t. FormatTime t => Maybe (LogAccess t)

-- | number of seconds to wait before killing an inactive thread
timeout :: Conf -> Int

-- | ThreadGroup for registering spawned threads for handling requests
threadGroup :: Conf -> Maybe ThreadGroup

-- | Default configuration contains no validator and the port is set to
--   8000
nullConf :: Conf

-- | Creates a Response with the given Int as the status code and the
--   provided String as the body of the Response
result :: Int -> String -> Response

-- | Acts as <a>result</a> but works with ByteStrings directly.
--   
--   By default, Transfer-Encoding: chunked will be used
resultBS :: Int -> ByteString -> Response

-- | Sets the Response's status code to the given Int and redirects to the
--   given URI
redirect :: ToSURI s => Int -> s -> Response -> Response

-- | <a>True</a> if <a>Request</a> is HTTP version <tt>1.0</tt>
isHTTP1_0 :: Request -> Bool

-- | <a>True</a> if <a>Request</a> is HTTP version <tt>1.1</tt>
isHTTP1_1 :: Request -> Bool

-- | Result flags
data RsFlags
RsFlags :: Length -> RsFlags
rsfLength :: RsFlags -> Length

-- | Default RsFlags: automatically use <tt>Transfer-Encoding:
--   Chunked</tt>.
nullRsFlags :: RsFlags

-- | Automatically add a Content-Length header. Do not use
--   Transfer-Encoding: Chunked
contentLength :: Response -> Response

-- | Do not automatically add a Content-Length header. Do automatically use
--   Transfer-Encoding: Chunked
chunked :: Response -> Response

-- | Do not automatically add a Content-Length field to the <a>Response</a>
noContentLength :: Response -> Response

-- | HTTP version
data HttpVersion
HttpVersion :: Int -> Int -> HttpVersion

-- | A flag value set in the <a>Response</a> which controls how the
--   <tt>Content-Length</tt> header is set, and whether *chunked* output
--   encoding is used.
--   
--   see also: <a>nullRsFlags</a>, <tt>notContentLength</tt>, and
--   <a>chunked</a>
data Length

-- | automatically add a <tt>Content-Length</tt> header to the
--   <a>Response</a>
ContentLength :: Length

-- | do not add a <tt>Content-Length</tt> header. Do use <tt>chunked</tt>
--   output encoding
TransferEncodingChunked :: Length

-- | do not set <tt>Content-Length</tt> or <tt>chunked</tt> output
--   encoding.
NoContentLength :: Length

-- | HTTP request method
data Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method

-- | a Map of HTTP headers
--   
--   the Map key is the header converted to lowercase
type Headers = Map ByteString HeaderPair

-- | Should the connection be used for further messages after this.
--   isHTTP1_0 &amp;&amp; hasKeepAlive || isHTTP1_1 &amp;&amp;
--   hasNotConnectionClose
--   
--   In addition to this rule All 1xx (informational), 204 (no content),
--   and 304 (not modified) responses MUST NOT include a message-body and
--   therefore are eligible for connection keep-alive.
continueHTTP :: Request -> Response -> Bool

-- | hostname &amp; port
type Host = (String, Int)

-- | A MIME media type value. The <a>Show</a> instance is derived
--   automatically. Use <a>showContentType</a> to obtain the standard
--   string representation. See <a>http://www.ietf.org/rfc/rfc2046.txt</a>
--   for more information about MIME media types.
data ContentType
ContentType :: String -> String -> [(String, String)] -> ContentType

-- | The top-level media type, the general type of the data. Common
--   examples are "text", "image", "audio", "video", "multipart", and
--   "application".
ctType :: ContentType -> String

-- | The media subtype, the specific data format. Examples include "plain",
--   "html", "jpeg", "form-data", etc.
ctSubtype :: ContentType -> String

-- | Media type parameters. On common example is the charset parameter for
--   the "text" top-level type, e.g. <tt>("charset","ISO-8859-1")</tt>.
ctParameters :: ContentType -> [(String, String)]
readDec' :: (Num a, Eq a) => String -> a

-- | convert a 'ReadS a' result to 'Maybe a'
fromReadS :: [(a, String)] -> Maybe a

-- | Read in any monad.
readM :: (Monad m, Read t) => String -> m t

-- | This class is used by <a>path</a> to parse a path component into a
--   value.
--   
--   The instances for number types (<a>Int</a>, <a>Float</a>, etc) use
--   <a>readM</a> to parse the path component.
--   
--   The instance for <a>String</a>, on the other hand, returns the
--   unmodified path component.
--   
--   See the following section of the Happstack Crash Course for detailed
--   instructions using and extending <a>FromReqURI</a>:
--   
--   
--   <a>http://www.happstack.com/docs/crashcourse/RouteFilters.html#FromReqURI</a>
class FromReqURI a
fromReqURI :: FromReqURI a => String -> Maybe a
instance [overlap ok] Typeable Method
instance [overlap ok] Typeable RsFlags
instance [overlap ok] Typeable Input
instance [overlap ok] Typeable Response
instance [overlap ok] Typeable RqBody
instance [overlap ok] Typeable Request
instance [overlap ok] Read HttpVersion
instance [overlap ok] Eq HttpVersion
instance [overlap ok] Show Method
instance [overlap ok] Read Method
instance [overlap ok] Eq Method
instance [overlap ok] Ord Method
instance [overlap ok] Data Method
instance [overlap ok] Read HeaderPair
instance [overlap ok] Show HeaderPair
instance [overlap ok] Eq Length
instance [overlap ok] Ord Length
instance [overlap ok] Read Length
instance [overlap ok] Show Length
instance [overlap ok] Enum Length
instance [overlap ok] Show RsFlags
instance [overlap ok] Read RsFlags
instance [overlap ok] Show Input
instance [overlap ok] Read Input
instance [overlap ok] Read RqBody
instance [overlap ok] Show RqBody
instance [overlap ok] FromReqURI Bool
instance [overlap ok] FromReqURI Double
instance [overlap ok] FromReqURI Float
instance [overlap ok] FromReqURI Word64
instance [overlap ok] FromReqURI Word32
instance [overlap ok] FromReqURI Word16
instance [overlap ok] FromReqURI Word8
instance [overlap ok] FromReqURI Word
instance [overlap ok] FromReqURI Integer
instance [overlap ok] FromReqURI Int64
instance [overlap ok] FromReqURI Int32
instance [overlap ok] FromReqURI Int16
instance [overlap ok] FromReqURI Int8
instance [overlap ok] FromReqURI Int
instance [overlap ok] FromReqURI Char
instance [overlap ok] FromReqURI Text
instance [overlap ok] FromReqURI Text
instance [overlap ok] FromReqURI String
instance [overlap ok] HasHeaders Headers
instance [overlap ok] HasHeaders Request
instance [overlap ok] HasHeaders Response
instance [overlap ok] Show Request
instance [overlap ok] Error Response
instance [overlap ok] Show Response
instance [overlap ok] Show HttpVersion

module Happstack.Server.Internal.Multipart

-- | similar to the normal <a>span</a> function, except the predicate gets
--   the whole rest of the lazy bytestring, not just one character.
--   
--   TODO: this function has not been profiled.
spanS :: (ByteString -> Bool) -> ByteString -> (ByteString, ByteString)
takeWhileS :: (ByteString -> Bool) -> ByteString -> ByteString
crlf :: ByteString
crlfcrlf :: ByteString
blankLine :: ByteString
dropWhileS :: (ByteString -> Bool) -> ByteString -> ByteString
data BodyPart

-- | headers body
BodyPart :: ByteString -> ByteString -> BodyPart
data Work
BodyWork :: ContentType -> [(String, String)] -> ByteString -> Work
HeaderWork :: ByteString -> Work
type InputWorker = Work -> IO InputIter
data InputIter
Failed :: (Maybe (String, Input)) -> String -> InputIter
BodyResult :: (String, Input) -> InputWorker -> InputIter
HeaderResult :: [Header] -> InputWorker -> InputIter
type FileSaver = FilePath -> Int64 -> FilePath -> ByteString -> IO (Bool, Int64, FilePath)
defaultFileSaver :: FilePath -> Int64 -> FilePath -> ByteString -> IO (Bool, Int64, FilePath)
defaultInputIter :: FileSaver -> FilePath -> Int64 -> Int64 -> Int64 -> Int64 -> Int64 -> Int64 -> Work -> IO InputIter
hPutLimit :: Int64 -> Handle -> ByteString -> IO (Bool, Int64)
hPutLimit' :: Int64 -> Handle -> Int64 -> ByteString -> IO (Bool, Int64)
bodyPartToInput :: InputWorker -> BodyPart -> IO InputIter
bodyPartsToInputs :: InputWorker -> [BodyPart] -> IO ([(String, Input)], Maybe String)
multipartBody :: InputWorker -> ByteString -> ByteString -> IO ([(String, Input)], Maybe String)

-- | Packs a string into an Input of type <a>text/plain</a>
simpleInput :: String -> Input

-- | The default content-type for variables.
defaultInputType :: ContentType
parseMultipartBody :: ByteString -> ByteString -> ([BodyPart], Maybe String)
dropPreamble :: ByteString -> ByteString -> (ByteString, Maybe String)
dropLine :: ByteString -> ByteString

-- | Check whether a string starts with two dashes followed by the given
--   boundary string.
isBoundary :: ByteString -> ByteString -> Bool

-- | Checks whether a string starts with two dashes.
startsWithDashes :: ByteString -> Bool
splitParts :: ByteString -> ByteString -> ([BodyPart], Maybe String)
splitPart :: ByteString -> ByteString -> (BodyPart, ByteString)
splitBlank :: ByteString -> (ByteString, ByteString)
splitBoundary :: ByteString -> ByteString -> (ByteString, ByteString)
splitAtEmptyLine :: ByteString -> Maybe (ByteString, ByteString)

-- | Split a string at the first CRLF. The CRLF is not included in any of
--   the returned strings.
splitAtCRLF :: ByteString -> Maybe (ByteString, ByteString)
instance [overlap ok] Eq BodyPart
instance [overlap ok] Ord BodyPart
instance [overlap ok] Read BodyPart
instance [overlap ok] Show BodyPart

module Happstack.Server.Internal.MessageWrap
queryInput :: SURI -> [(String, Input)]

-- | see <a>defaultBodyPolicy</a>
data BodyPolicy
BodyPolicy :: (Int64 -> Int64 -> Int64 -> InputWorker) -> Int64 -> Int64 -> Int64 -> BodyPolicy
inputWorker :: BodyPolicy -> Int64 -> Int64 -> Int64 -> InputWorker

-- | maximum bytes for files uploaded in this <a>Request</a>
maxDisk :: BodyPolicy -> Int64

-- | maximum bytes for all non-file values in the <a>Request</a> body
maxRAM :: BodyPolicy -> Int64

-- | maximum bytes of overhead for headers in <tt>multipart/form-data</tt>
maxHeader :: BodyPolicy -> Int64

-- | create a <a>BodyPolicy</a> for use with decodeBody
defaultBodyPolicy :: FilePath -> Int64 -> Int64 -> Int64 -> BodyPolicy
bodyInput :: MonadIO m => BodyPolicy -> Request -> m ([(String, Input)], Maybe String)

-- | Decodes application/x-www-form-urlencoded inputs. TODO: should any of
--   the [] be error conditions?
formDecode :: String -> [(String, Input)]

-- | Decodes application/x-www-form-urlencoded inputs. TODO: should any of
--   the [] be error conditions?
formDecodeBS :: ByteString -> [(String, Input)]
decodeBody :: BodyPolicy -> Maybe ContentType -> ByteString -> IO ([(String, Input)], Maybe String)

-- | Decodes multipart/form-data input.
multipartDecode :: InputWorker -> [(String, String)] -> ByteString -> IO ([(String, Input)], Maybe String)

-- | Get the path components from a String.
pathEls :: String -> [String]

-- | Repeadly splits a list by the provided separator and collects the
--   results
splitList :: Eq a => a -> [a] -> [[a]]

-- | Repeatedly splits a list and collects the results
splitListBy :: (a -> Bool) -> [a] -> [[a]]

-- | Split is like break, but the matching element is dropped.
split :: (a -> Bool) -> [a] -> ([a], [a])
defaultInputIter :: FileSaver -> FilePath -> Int64 -> Int64 -> Int64 -> Int64 -> Int64 -> Int64 -> Work -> IO InputIter

module Happstack.Server.Types

-- | an HTTP request
data Request
Request :: Bool -> Method -> [String] -> String -> String -> [(String, Input)] -> MVar [(String, Input)] -> [(String, Cookie)] -> HttpVersion -> Headers -> MVar RqBody -> Host -> Request

-- | request uses https://
rqSecure :: Request -> Bool

-- | request method
rqMethod :: Request -> Method

-- | the uri, split on /, and then decoded
rqPaths :: Request -> [String]

-- | the raw rqUri
rqUri :: Request -> String

-- | the QUERY_STRING
rqQuery :: Request -> String

-- | the QUERY_STRING decoded as key/value pairs
rqInputsQuery :: Request -> [(String, Input)]

-- | the request body decoded as key/value pairs (when appropriate)
rqInputsBody :: Request -> MVar [(String, Input)]

-- | cookies
rqCookies :: Request -> [(String, Cookie)]

-- | HTTP version
rqVersion :: Request -> HttpVersion

-- | the HTTP request headers
rqHeaders :: Request -> Headers

-- | the raw, undecoded request body
rqBody :: Request -> MVar RqBody

-- | (hostname, port) of the client making the request
rqPeer :: Request -> Host

-- | an HTTP Response
data Response
Response :: Int -> Headers -> RsFlags -> ByteString -> Maybe (Response -> IO Response) -> Response
rsCode :: Response -> Int
rsHeaders :: Response -> Headers
rsFlags :: Response -> RsFlags
rsBody :: Response -> ByteString
rsValidator :: Response -> Maybe (Response -> IO Response)
SendFile :: Int -> Headers -> RsFlags -> Maybe (Response -> IO Response) -> FilePath -> Integer -> Integer -> Response
rsCode :: Response -> Int
rsHeaders :: Response -> Headers
rsFlags :: Response -> RsFlags
rsValidator :: Response -> Maybe (Response -> IO Response)

-- | file handle to send from
sfFilePath :: Response -> FilePath

-- | offset to start at
sfOffset :: Response -> Integer

-- | number of bytes to send
sfCount :: Response -> Integer

-- | The body of an HTTP <a>Request</a>
newtype RqBody
Body :: ByteString -> RqBody
unBody :: RqBody -> ByteString

-- | a value extract from the <tt>QUERY_STRING</tt> or <a>Request</a> body
--   
--   If the input value was a file, then it will be saved to a temporary
--   file on disk and <a>inputValue</a> will contain <tt>Left
--   pathToTempFile</tt>.
data Input
Input :: Either FilePath ByteString -> Maybe FilePath -> ContentType -> Input
inputValue :: Input -> Either FilePath ByteString
inputFilename :: Input -> Maybe FilePath
inputContentType :: Input -> ContentType

-- | an HTTP header
data HeaderPair
HeaderPair :: ByteString -> [ByteString] -> HeaderPair

-- | header name
hName :: HeaderPair -> ByteString

-- | header value (or values if multiple occurances of the header are
--   present)
hValue :: HeaderPair -> [ByteString]

-- | get the request body from the Request and replace it with Nothing
--   
--   IMPORTANT: You can really only call this function once. Subsequent
--   calls will return <a>Nothing</a>.
takeRequestBody :: MonadIO m => Request -> m (Maybe RqBody)

-- | read the request body inputs
--   
--   This will only work if the body inputs have already been decoded.
--   Otherwise it will return Nothing.
readInputsBody :: Request -> IO (Maybe [(String, Input)])

-- | Converts a Request into a String representing the corresponding URL
rqURL :: Request -> String

-- | Takes a list of (key,val) pairs and converts it into Headers. The keys
--   will be converted to lowercase
mkHeaders :: [(String, String)] -> Headers

-- | Lookup header value. Key is case-insensitive.
getHeader :: HasHeaders r => String -> r -> Maybe ByteString

-- | Lookup header value. Key is a case-insensitive bytestring.
getHeaderBS :: HasHeaders r => ByteString -> r -> Maybe ByteString

-- | Lookup header value with a case-sensitive key. The key must be
--   lowercase.
getHeaderUnsafe :: HasHeaders r => ByteString -> r -> Maybe ByteString

-- | Returns True if the associated key is found in the Headers. The lookup
--   is case insensitive.
hasHeader :: HasHeaders r => String -> r -> Bool

-- | Acts as <a>hasHeader</a> with ByteStrings
hasHeaderBS :: HasHeaders r => ByteString -> r -> Bool

-- | Acts as <a>hasHeaderBS</a> but the key is case sensitive. It should be
--   in lowercase.
hasHeaderUnsafe :: HasHeaders r => ByteString -> r -> Bool

-- | Associates the key/value pair in the headers. Forces the key to be
--   lowercase.
setHeader :: HasHeaders r => String -> String -> r -> r

-- | Acts as <a>setHeader</a> but with ByteStrings.
setHeaderBS :: HasHeaders r => ByteString -> ByteString -> r -> r

-- | Sets the key to the HeaderPair. This is the only way to associate a
--   key with multiple values via the setHeader* functions. Does not force
--   the key to be in lowercase or guarantee that the given key and the key
--   in the HeaderPair will match.
setHeaderUnsafe :: HasHeaders r => ByteString -> HeaderPair -> r -> r

-- | Add a key/value pair to the header. If the key already has a value
--   associated with it, then the value will be appended. Forces the key to
--   be lowercase.
addHeader :: HasHeaders r => String -> String -> r -> r

-- | Acts as addHeader except for ByteStrings
addHeaderBS :: HasHeaders r => ByteString -> ByteString -> r -> r

-- | Add a key/value pair to the header using the underlying HeaderPair
--   data type. Does not force the key to be in lowercase or guarantee that
--   the given key and the key in the HeaderPair will match.
addHeaderUnsafe :: HasHeaders r => ByteString -> HeaderPair -> r -> r

-- | Sets the Response status code to the provided Int and lifts the
--   computation into a Monad.
setRsCode :: Monad m => Int -> Response -> m Response

-- | function to log access requests (see also: <a>logMAccess</a>) type
--   LogAccess time = ( String -- ^ host -&gt; String -- ^ user -&gt; time
--   -- ^ time -&gt; String -- ^ requestLine -&gt; Int -- ^ responseCode
--   -&gt; Integer -- ^ size -&gt; String -- ^ referer -&gt; String -- ^
--   userAgent -&gt; IO ())
type LogAccess time = String -> String -> time -> String -> Int -> Integer -> String -> String -> IO ()

-- | log access requests using hslogger and apache-style log formatting
--   
--   see also: <a>Conf</a>
logMAccess :: FormatTime t => LogAccess t

-- | HTTP configuration
data Conf
Conf :: Int -> Maybe (Response -> IO Response) -> (forall t. FormatTime t => Maybe (LogAccess t)) -> Int -> Maybe ThreadGroup -> Conf

-- | Port for the server to listen on.
port :: Conf -> Int

-- | a function to validate the output on-the-fly
validator :: Conf -> Maybe (Response -> IO Response)

-- | function to log access requests (see also: <a>logMAccess</a>)
logAccess :: Conf -> forall t. FormatTime t => Maybe (LogAccess t)

-- | number of seconds to wait before killing an inactive thread
timeout :: Conf -> Int

-- | ThreadGroup for registering spawned threads for handling requests
threadGroup :: Conf -> Maybe ThreadGroup

-- | Default configuration contains no validator and the port is set to
--   8000
nullConf :: Conf

-- | Creates a Response with the given Int as the status code and the
--   provided String as the body of the Response
result :: Int -> String -> Response

-- | Acts as <a>result</a> but works with ByteStrings directly.
--   
--   By default, Transfer-Encoding: chunked will be used
resultBS :: Int -> ByteString -> Response

-- | Sets the Response's status code to the given Int and redirects to the
--   given URI
redirect :: ToSURI s => Int -> s -> Response -> Response

-- | <a>True</a> if <a>Request</a> is HTTP version <tt>1.0</tt>
isHTTP1_0 :: Request -> Bool

-- | <a>True</a> if <a>Request</a> is HTTP version <tt>1.1</tt>
isHTTP1_1 :: Request -> Bool

-- | Result flags
data RsFlags
RsFlags :: Length -> RsFlags
rsfLength :: RsFlags -> Length

-- | Default RsFlags: automatically use <tt>Transfer-Encoding:
--   Chunked</tt>.
nullRsFlags :: RsFlags

-- | Automatically add a Content-Length header. Do not use
--   Transfer-Encoding: Chunked
contentLength :: Response -> Response

-- | Do not automatically add a Content-Length header. Do automatically use
--   Transfer-Encoding: Chunked
chunked :: Response -> Response

-- | Do not automatically add a Content-Length field to the <a>Response</a>
noContentLength :: Response -> Response

-- | HTTP version
data HttpVersion
HttpVersion :: Int -> Int -> HttpVersion

-- | A flag value set in the <a>Response</a> which controls how the
--   <tt>Content-Length</tt> header is set, and whether *chunked* output
--   encoding is used.
--   
--   see also: <a>nullRsFlags</a>, <tt>notContentLength</tt>, and
--   <a>chunked</a>
data Length

-- | automatically add a <tt>Content-Length</tt> header to the
--   <a>Response</a>
ContentLength :: Length

-- | do not add a <tt>Content-Length</tt> header. Do use <tt>chunked</tt>
--   output encoding
TransferEncodingChunked :: Length

-- | do not set <tt>Content-Length</tt> or <tt>chunked</tt> output
--   encoding.
NoContentLength :: Length

-- | HTTP request method
data Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method

-- | a Map of HTTP headers
--   
--   the Map key is the header converted to lowercase
type Headers = Map ByteString HeaderPair

-- | Should the connection be used for further messages after this.
--   isHTTP1_0 &amp;&amp; hasKeepAlive || isHTTP1_1 &amp;&amp;
--   hasNotConnectionClose
--   
--   In addition to this rule All 1xx (informational), 204 (no content),
--   and 304 (not modified) responses MUST NOT include a message-body and
--   therefore are eligible for connection keep-alive.
continueHTTP :: Request -> Response -> Bool

-- | hostname &amp; port
type Host = (String, Int)

-- | A MIME media type value. The <a>Show</a> instance is derived
--   automatically. Use <a>showContentType</a> to obtain the standard
--   string representation. See <a>http://www.ietf.org/rfc/rfc2046.txt</a>
--   for more information about MIME media types.
data ContentType
ContentType :: String -> String -> [(String, String)] -> ContentType

-- | The top-level media type, the general type of the data. Common
--   examples are "text", "image", "audio", "video", "multipart", and
--   "application".
ctType :: ContentType -> String

-- | The media subtype, the specific data format. Examples include "plain",
--   "html", "jpeg", "form-data", etc.
ctSubtype :: ContentType -> String

-- | Media type parameters. On common example is the charset parameter for
--   the "text" top-level type, e.g. <tt>("charset","ISO-8859-1")</tt>.
ctParameters :: ContentType -> [(String, String)]
readDec' :: (Num a, Eq a) => String -> a

-- | convert a 'ReadS a' result to 'Maybe a'
fromReadS :: [(a, String)] -> Maybe a

-- | This class is used by <a>path</a> to parse a path component into a
--   value.
--   
--   The instances for number types (<a>Int</a>, <a>Float</a>, etc) use
--   <a>readM</a> to parse the path component.
--   
--   The instance for <a>String</a>, on the other hand, returns the
--   unmodified path component.
--   
--   See the following section of the Happstack Crash Course for detailed
--   instructions using and extending <a>FromReqURI</a>:
--   
--   
--   <a>http://www.happstack.com/docs/crashcourse/RouteFilters.html#FromReqURI</a>
class FromReqURI a
fromReqURI :: FromReqURI a => String -> Maybe a


-- | This module defines the Monad stack used by Happstack. You mostly
--   don't want to be looking in here. Look in
--   <a>Happstack.Server.Monads</a> instead.
module Happstack.Server.Internal.Monads

-- | An alias for <a>WebT</a> when using <a>IO</a>.
type Web a = WebT IO a

-- | An alias for <tt><a>ServerPartT</a> <a>IO</a></tt>
type ServerPart a = ServerPartT IO a

-- | <a>ServerPartT</a> is a rich, featureful monad for web development.
--   
--   see also: <tt>simpleHTTP</tt>, <a>ServerMonad</a>, <a>FilterMonad</a>,
--   <a>WebMonad</a>, and <tt>HasRqData</tt>
newtype ServerPartT m a
ServerPartT :: ReaderT Request (WebT m) a -> ServerPartT m a
unServerPartT :: ServerPartT m a -> ReaderT Request (WebT m) a

-- | Particularly useful when combined with <tt>runWebT</tt> to produce a
--   <tt>m (<a>Maybe</a> <a>Response</a>)</tt> from a <a>Request</a>.
runServerPartT :: ServerPartT m a -> Request -> WebT m a

-- | function for lifting WebT to ServerPartT
--   
--   NOTE: This is mostly for internal use. If you want to access the
--   <a>Request</a> in user-code see <a>askRq</a> from <a>ServerMonad</a>.
--   
--   <pre>
--   do request &lt;- askRq
--      ...
--   </pre>
withRequest :: (Request -> WebT m a) -> ServerPartT m a

-- | A constructor for a <a>ServerPartT</a> when you don't care about the
--   request.
--   
--   NOTE: This is mostly for internal use. If you think you need to use it
--   in your own code, you might consider asking on the mailing list or IRC
--   to find out if there is an alternative solution.
anyRequest :: Monad m => WebT m a -> ServerPartT m a

-- | Apply a function to transform the inner monad of
--   <tt><a>ServerPartT</a> m</tt>.
--   
--   Often used when transforming a monad with <a>ServerPartT</a>, since
--   <tt>simpleHTTP</tt> requires a <tt><a>ServerPartT</a> <a>IO</a>
--   a</tt>. Refer to <a>UnWebT</a> for an explanation of the structure of
--   the monad.
--   
--   Here is an example. Suppose you want to embed an <a>ErrorT</a> into
--   your <a>ServerPartT</a> to enable <a>throwError</a> and
--   <a>catchError</a> in your <a>Monad</a>.
--   
--   <pre>
--   type MyServerPartT e m a = ServerPartT (ErrorT e m) a
--   </pre>
--   
--   Now suppose you want to pass <tt>MyServerPartT</tt> into a function
--   that demands a <tt><a>ServerPartT</a> <a>IO</a> a</tt> (e.g.
--   <tt>simpleHTTP</tt>). You can provide the function:
--   
--   <pre>
--   unpackErrorT :: (Monad m, Show e) =&gt; UnWebT (ErrorT e m) a -&gt; UnWebT m a
--   unpackErrorT et = do
--      eitherV &lt;- runErrorT et
--      return $ case eitherV of
--          Left err -&gt; Just (Left $ toResponse $
--                                   "Catastrophic failure " ++ show err
--                           , filterFun $ \r -&gt; r{rsCode = 500})
--          Right x -&gt; x
--   </pre>
--   
--   With <tt>unpackErrorT</tt> you can now call <tt>simpleHTTP</tt>. Just
--   wrap your <a>ServerPartT</a> list.
--   
--   <pre>
--   simpleHTTP nullConf $ mapServerPartT unpackErrorT (myPart `catchError` myHandler)
--   </pre>
--   
--   Or alternatively:
--   
--   <pre>
--   simpleHTTP' unpackErrorT nullConf (myPart `catchError` myHandler)
--   </pre>
--   
--   Also see <a>spUnwrapErrorT</a> for a more sophisticated version of
--   this function.
mapServerPartT :: (UnWebT m a -> UnWebT n b) -> (ServerPartT m a -> ServerPartT n b)

-- | A variant of <a>mapServerPartT</a> where the first argument also takes
--   a <a>Request</a>. Useful if you want to <a>runServerPartT</a> on a
--   different <a>ServerPartT</a> inside your monad (see
--   <tt>spUnwrapErrorT</tt>).
mapServerPartT' :: (Request -> UnWebT m a -> UnWebT n b) -> (ServerPartT m a -> ServerPartT n b)

-- | The <a>ServerMonad</a> class provides methods for reading or locally
--   modifying the <a>Request</a>. It is essentially a specialized version
--   of the <a>MonadReader</a> class. Providing the unique names,
--   <a>askRq</a> and <a>localRq</a> makes it easier to use
--   <a>ServerPartT</a> and <a>ReaderT</a> together.
class Monad m => ServerMonad m
askRq :: ServerMonad m => m Request
localRq :: ServerMonad m => (Request -> Request) -> m a -> m a

-- | A monoid operation container. If <tt>a</tt> is a monoid, then
--   <a>SetAppend</a> is a monoid with the following behaviors:
--   
--   <pre>
--   Set    x `mappend` Append y = Set    (x `mappend` y)
--   Append x `mappend` Append y = Append (x `mappend` y)
--   _        `mappend` Set y    = Set y
--   </pre>
--   
--   A simple way of summarizing this is, if the right side is
--   <a>Append</a>, then the right is appended to the left. If the right
--   side is <a>Set</a>, then the left side is ignored.
data SetAppend a
Set :: a -> SetAppend a
Append :: a -> SetAppend a

-- | Extract the value from a <a>SetAppend</a>. Note that a
--   <a>SetAppend</a> is actually a <tt>CoPointed</tt> from:
--   <a>http://hackage.haskell.org/packages/archive/category-extras/latest/doc/html/Control-Functor-Pointed.html</a>
--   But lets not drag in that dependency. yet...
extract :: SetAppend t -> t

-- | <a>FilterFun</a> is a lot more fun to type than <tt><a>SetAppend</a>
--   (<a>Dual</a> (<a>Endo</a> a))</tt>.
type FilterFun a = SetAppend (Dual (Endo a))
unFilterFun :: FilterFun a -> (a -> a)

-- | turn a function into a <a>FilterFun</a>. Primarily used with
--   <a>mapServerPartT</a>
filterFun :: (a -> a) -> FilterFun a
newtype FilterT a m b
FilterT :: WriterT (FilterFun a) m b -> FilterT a m b
unFilterT :: FilterT a m b -> WriterT (FilterFun a) m b

-- | A set of functions for manipulating filters.
--   
--   <a>ServerPartT</a> implements <a>FilterMonad</a> <a>Response</a> so
--   these methods are the fundamental ways of manipulating <a>Response</a>
--   values.
class Monad m => FilterMonad a m | m -> a
setFilter :: FilterMonad a m => (a -> a) -> m ()
composeFilter :: FilterMonad a m => (a -> a) -> m ()
getFilter :: FilterMonad a m => m b -> m (b, a -> a)

-- | Resets all your filters. An alias for <tt><a>setFilter</a>
--   <a>id</a></tt>.
ignoreFilters :: FilterMonad a m => m ()

-- | The basic <a>Response</a> building object.
newtype WebT m a
WebT :: ErrorT Response (FilterT (Response) (MaybeT m)) a -> WebT m a
unWebT :: WebT m a -> ErrorT Response (FilterT (Response) (MaybeT m)) a

-- | <a>UnWebT</a> is almost exclusively used with <a>mapServerPartT</a>.
--   If you are not using <a>mapServerPartT</a> then you do not need to
--   wrap your head around this type. If you are -- the type is not as
--   complex as it first appears.
--   
--   It is worth discussing the unpacked structure of <a>WebT</a> a bit as
--   it's exposed in <a>mapServerPartT</a> and <a>mapWebT</a>.
--   
--   A fully unpacked <a>WebT</a> has a structure that looks like:
--   
--   <pre>
--   ununWebT $ WebT m a :: m (Maybe (Either Response a, FilterFun Response))
--   </pre>
--   
--   So, ignoring <tt>m</tt>, as it is just the containing <a>Monad</a>,
--   the outermost layer is a <a>Maybe</a>. This is <a>Nothing</a> if
--   <a>mzero</a> was called or <tt><a>Just</a> (<a>Either</a>
--   <a>Response</a> a, <a>SetAppend</a> (<a>Endo</a>
--   <a>Response</a>))</tt> if <a>mzero</a> wasn't called. Inside the
--   <a>Maybe</a>, there is a pair. The second element of the pair is our
--   filter function <tt><a>FilterFun</a> <a>Response</a></tt>.
--   <tt><a>FilterFun</a> <a>Response</a></tt> is a type alias for
--   <tt><a>SetAppend</a> (<a>Dual</a> (<a>Endo</a> <a>Response</a>))</tt>.
--   This is just a wrapper for a <tt><a>Response</a> -&gt;
--   <a>Response</a></tt> function with a particular <a>Monoid</a>
--   behavior. The value
--   
--   <pre>
--   Append (Dual (Endo f))
--   </pre>
--   
--   Causes <tt>f</tt> to be composed with the previous filter.
--   
--   <pre>
--   Set (Dual (Endo f))
--   </pre>
--   
--   Causes <tt>f</tt> to not be composed with the previous filter.
--   
--   Finally, the first element of the pair is either <tt><a>Left</a>
--   <a>Response</a></tt> or <tt><a>Right</a> a</tt>.
--   
--   Another way of looking at all these pieces is from the behaviors they
--   control. The <a>Maybe</a> controls the <a>mzero</a> behavior.
--   <tt><a>Set</a> (<a>Endo</a> f)</tt> comes from the <a>setFilter</a>
--   behavior. Likewise, <tt><a>Append</a> (<a>Endo</a> f)</tt> is from
--   <a>composeFilter</a>. <tt><a>Left</a> <a>Response</a></tt> is what you
--   get when you call <a>finishWith</a> and <tt><a>Right</a> a</tt> is the
--   normal exit.
--   
--   An example case statement looks like:
--   
--   <pre>
--   ex1 webt = do
--     val &lt;- ununWebT webt
--     case val of
--         Nothing -&gt; Nothing  -- this is the interior value when mzero was used
--         Just (Left r, f) -&gt; Just (Left r, f) -- r is the value that was passed into "finishWith"
--                                              -- f is our filter function
--         Just (Right a, f) -&gt; Just (Right a, f) -- a is our normal monadic value
--                                                -- f is still our filter function
--   </pre>
type UnWebT m a = m (Maybe (Either Response a, FilterFun Response))

-- | <a>WebMonad</a> provides a means to end the current computation and
--   return a <a>Response</a> immediately. This provides an alternate
--   escape route. In particular it has a monadic value of any type. And
--   unless you call <tt><a>setFilter</a> <a>id</a></tt> first your
--   response filters will be applied normally.
--   
--   Extremely useful when you're deep inside a monad and decide that you
--   want to return a completely different content type, since it doesn't
--   force you to convert all your return types to <a>Response</a> early
--   just to accommodate this.
--   
--   see also: <a>escape</a> and <a>escape'</a>
class Monad m => WebMonad a m | m -> a
finishWith :: WebMonad a m => a -> m b

-- | Used to ignore all your filters and immediately end the computation. A
--   combination of <a>ignoreFilters</a> and <a>finishWith</a>.
escape :: (WebMonad a m, FilterMonad a m) => m a -> m b

-- | An alternate form of <a>escape</a> that can be easily used within a do
--   block.
escape' :: (WebMonad a m, FilterMonad a m) => a -> m b

-- | For when you really need to unpack a <a>WebT</a> entirely (and not
--   just unwrap the first layer with <a>unWebT</a>).
ununWebT :: WebT m a -> UnWebT m a

-- | For wrapping a <a>WebT</a> back up. <tt><a>mkWebT</a> .
--   <a>ununWebT</a> = <a>id</a></tt>
mkWebT :: UnWebT m a -> WebT m a

-- | See <a>mapServerPartT</a> for a discussion of this function.
mapWebT :: (UnWebT m a -> UnWebT n b) -> (WebT m a -> WebT n b)

-- | This is kinda like a very oddly shaped <a>mapServerPartT</a> or
--   <a>mapWebT</a>. You probably want one or the other of those.
localContext :: Monad m => (WebT m a -> WebT m' a) -> ServerPartT m a -> ServerPartT m' a

-- | Deprecated: use <a>msum</a>.

-- | <i>Deprecated: Use msum instead </i>
multi :: Monad m => [ServerPartT m a] -> ServerPartT m a

-- | What is this for, exactly? I don't understand why <tt>Show a</tt> is
--   even in the context Deprecated: This function appears to do nothing at
--   all. If it use it, let us know why.

-- | <i>Deprecated: This function appears to do nothing. </i>
debugFilter :: (MonadIO m, Show a) => ServerPartT m a -> ServerPartT m a
outputTraceMessage :: String -> a -> a
mkFailMessage :: (FilterMonad Response m, WebMonad Response m) => String -> m b
failResponse :: String -> Response
failHtml :: String -> String
escapeString :: String -> String
instance [overlap ok] Eq a => Eq (SetAppend a)
instance [overlap ok] Show a => Show (SetAppend a)
instance [overlap ok] Functor m => Functor (FilterT a m)
instance [overlap ok] Applicative m => Applicative (FilterT a m)
instance [overlap ok] Monad m => Monad (FilterT a m)
instance [overlap ok] MonadTrans (FilterT a)
instance [overlap ok] Functor m => Functor (WebT m)
instance [overlap ok] Monad m => Monad (ServerPartT m)
instance [overlap ok] Monad m => MonadPlus (ServerPartT m)
instance [overlap ok] Functor m => Functor (ServerPartT m)
instance [overlap ok] (Error e, WebMonad a m) => WebMonad a (ErrorT e m)
instance [overlap ok] (Error e, FilterMonad a m) => FilterMonad a (ErrorT e m)
instance [overlap ok] (Error e, ServerMonad m) => ServerMonad (ErrorT e m)
instance [overlap ok] (WebMonad a m, Monoid w) => WebMonad a (RWST r w s m)
instance [overlap ok] (WebMonad a m, Monoid w) => WebMonad a (RWST r w s m)
instance [overlap ok] (FilterMonad res m, Monoid w) => FilterMonad res (RWST r w s m)
instance [overlap ok] (FilterMonad res m, Monoid w) => FilterMonad res (RWST r w s m)
instance [overlap ok] (ServerMonad m, Monoid w) => ServerMonad (RWST r w s m)
instance [overlap ok] (ServerMonad m, Monoid w) => ServerMonad (RWST r w s m)
instance [overlap ok] (WebMonad a m, Monoid w) => WebMonad a (WriterT w m)
instance [overlap ok] (WebMonad a m, Monoid w) => WebMonad a (WriterT w m)
instance [overlap ok] (FilterMonad res m, Monoid w) => FilterMonad res (WriterT w m)
instance [overlap ok] (FilterMonad res m, Monoid w) => FilterMonad res (WriterT w m)
instance [overlap ok] (ServerMonad m, Monoid w) => ServerMonad (WriterT w m)
instance [overlap ok] (ServerMonad m, Monoid w) => ServerMonad (WriterT w m)
instance [overlap ok] WebMonad a m => WebMonad a (StateT s m)
instance [overlap ok] WebMonad a m => WebMonad a (StateT s m)
instance [overlap ok] FilterMonad res m => FilterMonad res (StateT s m)
instance [overlap ok] FilterMonad res m => FilterMonad res (StateT s m)
instance [overlap ok] ServerMonad m => ServerMonad (StateT s m)
instance [overlap ok] ServerMonad m => ServerMonad (StateT s m)
instance [overlap ok] WebMonad a m => WebMonad a (ReaderT r m)
instance [overlap ok] FilterMonad res m => FilterMonad res (ReaderT r m)
instance [overlap ok] ServerMonad m => ServerMonad (ReaderT r m)
instance [overlap ok] MonadWriter w m => MonadWriter w (WebT m)
instance [overlap ok] MonadError e m => MonadError e (WebT m)
instance [overlap ok] MonadState st m => MonadState st (WebT m)
instance [overlap ok] MonadReader r m => MonadReader r (WebT m)
instance [overlap ok] (Functor m, MonadPlus m) => Alternative (WebT m)
instance [overlap ok] (Monad m, Functor m) => Applicative (WebT m)
instance [overlap ok] Monad m => Monoid (WebT m a)
instance [overlap ok] Monad m => FilterMonad Response (WebT m)
instance [overlap ok] Monad m => MonadPlus (WebT m)
instance [overlap ok] MonadTrans WebT
instance [overlap ok] Monad m => WebMonad Response (WebT m)
instance [overlap ok] Monad m => Monad (WebT m)
instance [overlap ok] MonadBaseControl b m => MonadBaseControl b (WebT m)
instance [overlap ok] MonadTransControl WebT
instance [overlap ok] MonadIO m => MonadIO (WebT m)
instance [overlap ok] MonadBase b m => MonadBase b (WebT m)
instance [overlap ok] Monad m => FilterMonad a (FilterT a m)
instance [overlap ok] MonadBaseControl b m => MonadBaseControl b (FilterT a m)
instance [overlap ok] MonadTransControl (FilterT a)
instance [overlap ok] MonadIO m => MonadIO (FilterT a m)
instance [overlap ok] MonadBase b m => MonadBase b (FilterT a m)
instance [overlap ok] Functor SetAppend
instance [overlap ok] Monoid a => Monoid (SetAppend a)
instance [overlap ok] Monad m => ServerMonad (ServerPartT m)
instance [overlap ok] Monad m => WebMonad Response (ServerPartT m)
instance [overlap ok] Monad m => FilterMonad Response (ServerPartT m)
instance [overlap ok] (Monad m, MonadState s m) => MonadState s (ServerPartT m)
instance [overlap ok] (Monad m, MonadReader r m) => MonadReader r (ServerPartT m)
instance [overlap ok] (Monad m, MonadError e m) => MonadError e (ServerPartT m)
instance [overlap ok] (Monad m, MonadWriter w m) => MonadWriter w (ServerPartT m)
instance [overlap ok] (Functor m, MonadPlus m) => Alternative (ServerPartT m)
instance [overlap ok] (Monad m, Functor m) => Applicative (ServerPartT m)
instance [overlap ok] Monad m => Monoid (ServerPartT m a)
instance [overlap ok] MonadTrans ServerPartT
instance [overlap ok] MonadBaseControl b m => MonadBaseControl b (ServerPartT m)
instance [overlap ok] MonadTransControl ServerPartT
instance [overlap ok] MonadIO m => MonadIO (ServerPartT m)
instance [overlap ok] MonadBase b m => MonadBase b (ServerPartT m)

module Happstack.Server.Internal.Handler
request :: TimeoutIO -> Maybe (LogAccess UTCTime) -> Host -> (Request -> IO Response) -> IO ()

-- | Unserializes the bytestring into a response. If there is an error it
--   will return <tt>Left msg</tt>.
parseResponse :: ByteString -> Either String Response

-- | Serializes the request to the given handle
putRequest :: Handle -> Request -> IO ()


-- | a very simple interface for acting as an HTTP client. This is mostly
--   used for things like <a>Happstack.Server.Proxy</a>. You are more
--   likely to want a library like http-enumerator
--   <a>http://hackage.haskell.org/package/http-enumerator</a>.
module Happstack.Server.Client

-- | Sends the serialized request to the host defined in the request and
--   attempts to parse response upon arrival.
getResponse :: Request -> IO (Either String Response)

module Happstack.Server.Internal.Listen

-- | Bind and listen port
listen :: Conf -> (Request -> IO Response) -> IO ()

-- | Use a previously bind port and listen
listen' :: Socket -> Conf -> (Request -> IO Response) -> IO ()
listenOn :: Int -> IO Socket
listenOnIPv4 :: String -> Int -> IO Socket

module Happstack.Server.Internal.LowLevel


-- | Functions for creating, adding, and expiring cookies. To lookup cookie
--   values see <a>Happstack.Server.RqData</a>.
module Happstack.Server.Cookie

-- | a type for HTTP cookies. Usually created using <a>mkCookie</a>.
data Cookie
Cookie :: String -> String -> String -> String -> String -> Bool -> Bool -> Cookie
cookieVersion :: Cookie -> String
cookiePath :: Cookie -> String
cookieDomain :: Cookie -> String
cookieName :: Cookie -> String
cookieValue :: Cookie -> String
secure :: Cookie -> Bool
httpOnly :: Cookie -> Bool

-- | Specify the lifetime of a cookie.
--   
--   Note that we always set the max-age and expires headers because
--   internet explorer does not honor max-age. You can specific
--   <a>MaxAge</a> or <a>Expires</a> and the other will be calculated for
--   you. Choose which ever one makes your life easiest.
data CookieLife

-- | session cookie - expires when browser is closed
Session :: CookieLife

-- | life time of cookie in seconds
MaxAge :: Int -> CookieLife

-- | cookie expiration date
Expires :: UTCTime -> CookieLife

-- | cookie already expired
Expired :: CookieLife

-- | Creates a cookie with a default version of 1, empty domain, a path of
--   <a>/</a>, secure == False and httpOnly == False
--   
--   see also: <tt>addCookie</tt>
mkCookie :: String -> String -> Cookie

-- | Add the <a>Cookie</a> to <a>Response</a>.
--   
--   example
--   
--   <pre>
--   main = simpleHTTP nullConf $
--     do addCookie Session (mkCookie "name" "value")
--        ok $ "You now have a session cookie."
--   </pre>
--   
--   see also: <a>addCookies</a>
addCookie :: (MonadIO m, FilterMonad Response m) => CookieLife -> Cookie -> m ()

-- | Add the list <a>Cookie</a> to the <a>Response</a>.
--   
--   see also: <a>addCookie</a>
addCookies :: (MonadIO m, FilterMonad Response m) => [(CookieLife, Cookie)] -> m ()

-- | Expire the named cookie immediately and set the cookie value to
--   <tt>""</tt>
--   
--   <pre>
--   main = simpleHTTP nullConf $
--     do expireCookie "name"
--        ok $ "The cookie has been expired."
--   </pre>
expireCookie :: (MonadIO m, FilterMonad Response m) => String -> m ()


-- | Functions and classes related to generating a <a>Response</a> and
--   setting the response code. For detailed instruction see the Happstack
--   Crash Course:
--   <a>http://happstack.com/docs/crashcourse/HelloWorld.html#response_code</a>
module Happstack.Server.Response

-- | <a>toResponse</a> will convert a value into a <a>Response</a> body,
--   set the <tt>content-type</tt>, and set the default response code for
--   that type.
--   
--   <tt>happstack-server</tt> Example:
--   
--   <pre>
--   main = simpleHTTP nullConf $ toResponse "hello, world!"
--   </pre>
--   
--   will generate a <a>Response</a> with the content-type
--   <tt>text/plain</tt>, the response code <tt>200 OK</tt>, and the body:
--   <tt>hello, world!</tt>.
--   
--   <tt>simpleHTTP</tt> will call <a>toResponse</a> automatically, so the
--   above can be shortened to:
--   
--   <pre>
--   main = simpleHTTP nullConf $ "hello, world!"
--   </pre>
--   
--   <tt>happstack-lite</tt> Example:
--   
--   <pre>
--   main = serve Nothing $ toResponse "hello, world!"
--   </pre>
--   
--   Minimal definition: <a>toMessage</a> (and usually
--   <a>toContentType</a>).
class ToMessage a where toContentType _ = pack "text/plain" toMessage = error "Happstack.Server.SimpleHTTP.ToMessage.toMessage: Not defined" toResponse val = let bs = toMessage val res = Response 200 empty nullRsFlags bs Nothing in setHeaderBS (pack "Content-Type") (toContentType val) res
toContentType :: ToMessage a => a -> ByteString
toMessage :: ToMessage a => a -> ByteString
toResponse :: ToMessage a => a -> Response

-- | alias for: <tt>fmap toResponse</tt>
--   
--   turns <tt>m a</tt> into <tt>m <a>Response</a></tt> using
--   <a>toResponse</a>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ flatten $ do return "flatten me."
--   </pre>
flatten :: (ToMessage a, Functor f) => f a -> f Response

-- | A low-level function to build a <a>Response</a> from a content-type
--   and a <tt>ByteString</tt>.
--   
--   Creates a <a>Response</a> in a manner similar to the <a>ToMessage</a>
--   class, but without requiring an instance declaration.
--   
--   example:
--   
--   <pre>
--   import Data.ByteString.Char8 as C
--   import Data.ByteString.Lazy.Char8 as L
--   import Happstack.Server
--   
--   main = simpleHTTP nullConf $ ok $ toResponseBS (C.pack "text/plain") (L.pack "hello, world")
--   </pre>
--   
--   (note: <a>pack</a> and <a>pack</a> only work for ascii. For unicode
--   strings you would need to use <tt>utf8-string</tt>, <tt>text</tt>, or
--   something similar to create a valid <tt>ByteString</tt>).
toResponseBS :: ByteString -> ByteString -> Response

-- | Respond with <tt>200 OK</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ ok "Everything is OK"
--   </pre>
ok :: FilterMonad Response m => a -> m a

-- | Respond with <tt>204 No Content</tt>
--   
--   A <tt>204 No Content</tt> response may not contain a message-body. If
--   you try to supply one, it will be dutifully ignored.
--   
--   <pre>
--   main = simpleHTTP nullConf $ noContent "This will be ignored."
--   </pre>
noContent :: FilterMonad Response m => a -> m a

-- | Respond with <tt>500 Internal Server Error</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ internalServerError "Sorry, there was an internal server error."
--   </pre>
internalServerError :: FilterMonad Response m => a -> m a

-- | Responds with <tt>502 Bad Gateway</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ badGateway "Bad Gateway."
--   </pre>
badGateway :: FilterMonad Response m => a -> m a

-- | Respond with <tt>400 Bad Request</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ badRequest "Bad Request."
--   </pre>
badRequest :: FilterMonad Response m => a -> m a

-- | Respond with <tt>401 Unauthorized</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ unauthorized "You are not authorized."
--   </pre>
unauthorized :: FilterMonad Response m => a -> m a

-- | Respond with <tt>403 Forbidden</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ forbidden "Sorry, it is forbidden."
--   </pre>
forbidden :: FilterMonad Response m => a -> m a

-- | Respond with <tt>404 Not Found</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ notFound "What you are looking for has not been found."
--   </pre>
notFound :: FilterMonad Response m => a -> m a

-- | A nicely formatted rendering of a <a>Response</a>
prettyResponse :: Response -> String

-- | Respond with <tt>413 Request Entity Too Large</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ requestEntityTooLarge "That's too big for me to handle."
--   </pre>
requestEntityTooLarge :: FilterMonad Response m => a -> m a

-- | Respond with <tt>303 See Other</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ seeOther "http://example.org/" "What you are looking for is now at http://example.org/"
--   </pre>
--   
--   NOTE: The second argument of <a>seeOther</a> is the message body which
--   will sent to the browser. According to the HTTP 1.1 spec,
--   
--   <pre>
--   the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).
--   </pre>
--   
--   This is because pre-HTTP/1.1 user agents do not support 303. However,
--   in practice you can probably just use <tt>""</tt> as the second
--   argument.
seeOther :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res

-- | Respond with <tt>302 Found</tt>.
--   
--   You probably want <a>seeOther</a>. This method is not in popular use
--   anymore, and is generally treated like 303 by most user-agents anyway.
found :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res

-- | Respond with <tt>301 Moved Permanently</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ movedPermanently "http://example.org/" "What you are looking for is now at http://example.org/"
--   </pre>
movedPermanently :: (FilterMonad Response m, ToSURI a) => a -> res -> m res

-- | Respond with <tt>307 Temporary Redirect</tt>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ tempRedirect "http://example.org/" "What you are looking for is temporarily at http://example.org/"
--   </pre>
tempRedirect :: (FilterMonad Response m, ToSURI a) => a -> res -> m res

-- | Set an arbitrary return code in your response.
--   
--   A filter for setting the response code. Generally you will use a
--   helper function like <a>ok</a> or <a>seeOther</a>.
--   
--   <pre>
--   main = simpleHTTP nullConf $ do setResponseCode 200
--                                   return "Everything is OK"
--   </pre>
--   
--   see also: <a>resp</a>
setResponseCode :: FilterMonad Response m => Int -> m ()

-- | Same as <tt><a>setResponseCode</a> status &gt;&gt; return val</tt>.
--   
--   Use this if you want to set a response code that does not already have
--   a helper function.
--   
--   <pre>
--   main = simpleHTTP nullConf $ resp 200 "Everything is OK"
--   </pre>
resp :: FilterMonad Response m => Int -> b -> m b

-- | Honor an <tt>if-modified-since</tt> header in a <a>Request</a>. If the
--   <a>Request</a> includes the <tt>if-modified-since</tt> header and the
--   <a>Response</a> has not been modified, then return 304 (Not Modified),
--   otherwise return the <a>Response</a>.
ifModifiedSince :: UTCTime -> Request -> Response -> Response
instance [overlap ok] ToMessage ByteString
instance [overlap ok] ToMessage ByteString
instance [overlap ok] ToMessage Response
instance [overlap ok] ToMessage Html
instance [overlap ok] ToMessage Html
instance [overlap ok] ToMessage Html
instance [overlap ok] ToMessage a => ToMessage (Maybe a)
instance [overlap ok] ToMessage Integer
instance [overlap ok] ToMessage Text
instance [overlap ok] ToMessage Text
instance [overlap ok] ToMessage String
instance [overlap ok] ToMessage ()


-- | Functions for extracting values from the query string, form data,
--   cookies, etc.
--   
--   For in-depth documentation see the following section of the Happstack
--   Crash Course:
--   
--   <a>http://happstack.com/docs/crashcourse/RqData.html</a>
module Happstack.Server.RqData

-- | Gets the first matching named input parameter as a <a>String</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--        do foo &lt;- look "foo"
--           ok $ toResponse $ "foo = " ++ foo
--   </pre>
--   
--   see also: <a>looks</a>, <a>lookBS</a>, and <a>lookBSs</a>
look :: (Functor m, Monad m, HasRqData m) => String -> m String

-- | Gets all matches for the named input parameter as <a>String</a>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>look</a> and <a>lookBSs</a>
looks :: (Functor m, Monad m, HasRqData m) => String -> m [String]

-- | Gets the first matching named input parameter as a lazy <a>Text</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookTexts</a>, <a>look</a>, <a>looks</a>, <a>lookBS</a>,
--   and <a>lookBSs</a>
lookText :: (Functor m, Monad m, HasRqData m) => String -> m Text

-- | Gets the first matching named input parameter as a strict <a>Text</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookTexts</a>, <a>look</a>, <a>looks</a>, <a>lookBS</a>,
--   and <a>lookBSs</a>
lookText' :: (Functor m, Monad m, HasRqData m) => String -> m Text

-- | Gets all matches for the named input parameter as lazy <a>Text</a>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookText</a>, <a>looks</a> and <a>lookBSs</a>
lookTexts :: (Functor m, Monad m, HasRqData m) => String -> m [Text]

-- | Gets all matches for the named input parameter as strict <a>Text</a>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookText'</a>, <a>looks</a> and <a>lookBSs</a>
lookTexts' :: (Functor m, Monad m, HasRqData m) => String -> m [Text]

-- | Gets the first matching named input parameter as a lazy
--   <tt>ByteString</tt>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookBSs</a>
lookBS :: (Functor m, Monad m, HasRqData m) => String -> m ByteString

-- | Gets all matches for the named input parameter as lazy
--   <tt>ByteString</tt>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookBS</a>
lookBSs :: (Functor m, Monad m, HasRqData m) => String -> m [ByteString]

-- | Gets the first matching named input parameter and decodes it using
--   <a>Read</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookReads</a>
lookRead :: (Functor m, Monad m, HasRqData m, FromReqURI a) => String -> m a

-- | Gets all matches for the named input parameter and decodes them using
--   <a>Read</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookReads</a>
lookReads :: (Functor m, Monad m, HasRqData m, FromReqURI a) => String -> m [a]

-- | Gets the first matching named file
--   
--   Files can only appear in the request body. Additionally, the form must
--   set enctype="multipart/form-data".
--   
--   This function returns a tuple consisting of:
--   
--   <ol>
--   <li>The temporary location of the uploaded file</li>
--   <li>The local filename supplied by the browser</li>
--   <li>The content-type supplied by the browser</li>
--   </ol>
--   
--   If the user does not supply a file in the html form input field, the
--   behaviour will depend upon the browser. Most browsers will send a
--   0-length file with an empty file name, so checking that (2) is not
--   empty is usually sufficient to ensure the field has been filled.
--   
--   NOTE: You must move the file from the temporary location before the
--   <a>Response</a> is sent. The temporary files are automatically removed
--   after the <a>Response</a> is sent.
lookFile :: (Monad m, HasRqData m) => String -> m (FilePath, FilePath, ContentType)

-- | gets all the input parameters, and converts them to a <a>String</a>
--   
--   The results will contain the QUERY_STRING followed by the Request
--   body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookPairsBS</a>
lookPairs :: (Monad m, HasRqData m) => m [(String, Either FilePath String)]

-- | gets all the input parameters
--   
--   The results will contain the QUERY_STRING followed by the Request
--   body.
--   
--   see also: <a>lookPairs</a>
lookPairsBS :: (Monad m, HasRqData m) => m [(String, Either FilePath ByteString)]

-- | Gets the named cookie the cookie name is case insensitive
lookCookie :: (Monad m, HasRqData m) => String -> m Cookie

-- | gets the named cookie as a string
lookCookieValue :: (Functor m, Monad m, HasRqData m) => String -> m String

-- | gets the named cookie as the requested Read type
readCookieValue :: (Functor m, Monad m, HasRqData m, FromReqURI a) => String -> m a

-- | Gets the first matching named input parameter
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookInputs</a>
lookInput :: (Monad m, HasRqData m) => String -> m Input

-- | Gets all matches for the named input parameter
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookInput</a>
lookInputs :: (Monad m, HasRqData m) => String -> m [Input]

-- | limit the scope to the Request body
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do foo &lt;- body $ look "foo"
--          ok $ toResponse $ "foo = " ++ foo
--   </pre>
body :: HasRqData m => m a -> m a

-- | limit the scope to the QUERY_STRING
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do foo &lt;- queryString $ look "foo"
--          ok $ toResponse $ "foo = " ++ foo
--   </pre>
queryString :: HasRqData m => m a -> m a

-- | limit the scope to <a>Input</a>s which produce a <tt>ByteString</tt>
--   (aka, not a file)
bytestring :: HasRqData m => m a -> m a

-- | convert or validate a value
--   
--   This is similar to <a>fmap</a> except that the function can fail by
--   returning Left and an error message. The error will be propagated by
--   calling <a>rqDataError</a>.
--   
--   This function is useful for a number of things including:
--   
--   <ol>
--   <li>Parsing a <a>String</a> into another type</li>
--   <li>Checking that a value meets some requirements (for example, that
--   is an Int between 1 and 10).</li>
--   </ol>
--   
--   Example usage at:
--   
--   <a>http://happstack.com/docs/crashcourse/RqData.html#rqdatacheckrq</a>
checkRq :: (Monad m, HasRqData m) => m a -> (a -> Either String b) -> m b

-- | like <a>checkRq</a> but the check function can be monadic
checkRqM :: (Monad m, HasRqData m) => m a -> (a -> m (Either String b)) -> m b

-- | use <a>fromReqURI</a> to convert a <a>String</a> to a value of type
--   <tt>a</tt>
--   
--   <pre>
--   look "key" `checkRq` (readRq "key")
--   </pre>
--   
--   use with <a>checkRq</a>
readRq :: FromReqURI a => String -> String -> Either String a

-- | use <a>read</a> to convert a <a>String</a> to a value of type
--   <tt>a</tt>
--   
--   <pre>
--   look "key" `checkRq` (unsafeReadRq "key")
--   </pre>
--   
--   use with <a>checkRq</a>
--   
--   NOTE: This function is marked unsafe because some Read instances are
--   vulnerable to attacks that attempt to create an out of memory
--   condition. For example:
--   
--   <pre>
--   read "1e10000000000000" :: Integer
--   </pre>
--   
--   see also: <a>readRq</a>
unsafeReadRq :: Read a => String -> String -> Either String a

-- | The POST/PUT body of a Request is not received or decoded unless this
--   function is invoked.
--   
--   It is an error to try to use the look functions for a POST/PUT request
--   with out first calling this function.
--   
--   It is ok to call <a>decodeBody</a> at the beginning of every request:
--   
--   <pre>
--   main = simpleHTTP nullConf $
--             do decodeBody (defaultBodyPolicy "/tmp/" 4096 4096 4096)
--                handlers
--   </pre>
--   
--   You can achieve finer granularity quotas by calling <a>decodeBody</a>
--   with different values in different handlers.
--   
--   Only the first call to <a>decodeBody</a> will have any effect. Calling
--   it a second time, even with different quota values, will do nothing.
decodeBody :: (ServerMonad m, MonadPlus m, MonadIO m, FilterMonad Response m, WebMonad Response m) => BodyPolicy -> m ()

-- | see <a>defaultBodyPolicy</a>
data BodyPolicy
BodyPolicy :: (Int64 -> Int64 -> Int64 -> InputWorker) -> Int64 -> Int64 -> Int64 -> BodyPolicy
inputWorker :: BodyPolicy -> Int64 -> Int64 -> Int64 -> InputWorker

-- | maximum bytes for files uploaded in this <a>Request</a>
maxDisk :: BodyPolicy -> Int64

-- | maximum bytes for all non-file values in the <a>Request</a> body
maxRAM :: BodyPolicy -> Int64

-- | maximum bytes of overhead for headers in <tt>multipart/form-data</tt>
maxHeader :: BodyPolicy -> Int64

-- | create a <a>BodyPolicy</a> for use with decodeBody
defaultBodyPolicy :: FilePath -> Int64 -> Int64 -> Int64 -> BodyPolicy

-- | An applicative functor and monad for looking up key/value pairs in the
--   QUERY_STRING, Request body, and cookies.
data RqData a

-- | transform the result of 'RqData a'.
--   
--   This is similar to <a>fmap</a> except it also allows you to modify the
--   <a>Errors</a> not just <tt>a</tt>.
mapRqData :: (Either (Errors String) a -> Either (Errors String) b) -> RqData a -> RqData b

-- | a list of errors
newtype Errors a
Errors :: [a] -> Errors a
unErrors :: Errors a -> [a]

-- | run <a>RqData</a> in a <a>ServerMonad</a>.
--   
--   Example: a simple <tt>GET</tt> or <tt>POST</tt> variable based
--   authentication guard. It handles the request with
--   <tt>errorHandler</tt> if authentication fails.
--   
--   <pre>
--   data AuthCredentials = AuthCredentials { username :: String,  password :: String }
--   
--   isValid :: AuthCredentials -&gt; Bool
--   isValid = const True
--   
--   myRqData :: RqData AuthCredentials
--   myRqData = do
--      username &lt;- look "username"
--      password &lt;- look "password"
--      return (AuthCredentials username password)
--   
--   checkAuth :: (String -&gt; ServerPart Response) -&gt; ServerPart Response
--   checkAuth errorHandler = do
--      d &lt;- getDataFn myRqData
--      case d of
--          (Left e) -&gt; errorHandler (unlines e)
--          (Right a) | isValid a -&gt; mzero
--          (Right a) | otherwise -&gt; errorHandler "invalid"
--   </pre>
--   
--   NOTE: you must call <a>decodeBody</a> prior to calling this function
--   if the request method is POST or PUT.
getDataFn :: (HasRqData m, ServerMonad m) => RqData a -> m (Either [String] a)

-- | similar to <a>getDataFn</a>, except it calls a sub-handler on success
--   or <a>mzero</a> on failure.
--   
--   NOTE: you must call <a>decodeBody</a> prior to calling this function
--   if the request method is POST or PUT.
withDataFn :: (HasRqData m, MonadPlus m, ServerMonad m) => RqData a -> (a -> m r) -> m r

-- | Used by <a>withData</a> and <a>getData</a>. Make your preferred data
--   type an instance of <a>FromData</a> to use those functions.
class FromData a
fromData :: FromData a => RqData a

-- | A variant of <a>getDataFn</a> that uses <a>FromData</a> to chose your
--   <a>RqData</a> for you. The example from <a>getData</a> becomes:
--   
--   <pre>
--   data AuthCredentials = AuthCredentials { username :: String,  password :: String }
--   
--   isValid :: AuthCredentials -&gt; Bool
--   isValid = const True
--   
--   myRqData :: RqData AuthCredentials
--   myRqData = do
--      username &lt;- look "username"
--      password &lt;- look "password"
--      return (AuthCredentials username password)
--   
--   instance FromData AuthCredentials where
--      fromData = myRqData
--   
--   checkAuth :: (String -&gt; ServerPart Response) -&gt; ServerPart Response
--   checkAuth errorHandler = do
--      d &lt;- getData
--      case d of
--          (Left e) -&gt; errorHandler (unlines e)
--          (Right a) | isValid a -&gt; mzero
--          (Right a) | otherwise -&gt; errorHandler "invalid"
--   </pre>
--   
--   NOTE: you must call <a>decodeBody</a> prior to calling this function
--   if the request method is POST or PUT.
getData :: (HasRqData m, ServerMonad m, FromData a) => m (Either [String] a)

-- | similar to <a>getData</a> except it calls a subhandler on success or
--   <a>mzero</a> on failure.
--   
--   NOTE: you must call <a>decodeBody</a> prior to calling this function
--   if the request method is POST or PUT.
withData :: (HasRqData m, FromData a, MonadPlus m, ServerMonad m) => (a -> m r) -> m r

-- | the environment used to lookup query parameters. It consists of the
--   triple: (query string inputs, body inputs, cookie inputs)
type RqEnv = ([(String, Input)], Maybe [(String, Input)], [(String, Cookie)])

-- | A class for monads which contain a <a>RqEnv</a>
class HasRqData m
askRqEnv :: HasRqData m => m RqEnv
localRqEnv :: HasRqData m => (RqEnv -> RqEnv) -> m a -> m a
rqDataError :: HasRqData m => Errors String -> m a
instance [overlap ok] Typeable1 Errors
instance [overlap ok] Functor (ReaderError r e)
instance [overlap ok] Monad (ReaderError r e)
instance [overlap ok] Error e => MonadPlus (ReaderError r e)
instance [overlap ok] Eq a => Eq (Errors a)
instance [overlap ok] Ord a => Ord (Errors a)
instance [overlap ok] Show a => Show (Errors a)
instance [overlap ok] Read a => Read (Errors a)
instance [overlap ok] Data a => Data (Errors a)
instance [overlap ok] Functor RqData
instance [overlap ok] Monad RqData
instance [overlap ok] MonadPlus RqData
instance [overlap ok] Applicative RqData
instance [overlap ok] Alternative RqData
instance [overlap ok] MonadReader RqEnv RqData
instance [overlap ok] FromData a => FromData (Maybe a)
instance [overlap ok] (FromData a, FromData b, FromData c, FromData d) => FromData (a, b, c, d)
instance [overlap ok] (FromData a, FromData b, FromData c) => FromData (a, b, c)
instance [overlap ok] (FromData a, FromData b) => FromData (a, b)
instance [overlap ok] (Monad m, Error e, HasRqData m) => HasRqData (ErrorT e m)
instance [overlap ok] (Monad m, HasRqData m, Monoid w) => HasRqData (RWST r w s m)
instance [overlap ok] (Monad m, HasRqData m, Monoid w) => HasRqData (RWST r w s m)
instance [overlap ok] (Monad m, HasRqData m, Monoid w) => HasRqData (WriterT w m)
instance [overlap ok] (Monad m, HasRqData m, Monoid w) => HasRqData (WriterT w m)
instance [overlap ok] (Monad m, HasRqData m) => HasRqData (StateT s m)
instance [overlap ok] (Monad m, HasRqData m) => HasRqData (StateT s m)
instance [overlap ok] (Monad m, HasRqData m) => HasRqData (ReaderT s m)
instance [overlap ok] MonadIO m => HasRqData (ServerPartT m)
instance [overlap ok] HasRqData RqData
instance [overlap ok] Error (Errors String)
instance [overlap ok] Monoid (Errors a)
instance [overlap ok] (Monoid e, Error e) => Alternative (ReaderError r e)
instance [overlap ok] (Monoid e, Error e) => Applicative (ReaderError r e)
instance [overlap ok] Error e => MonadReader r (ReaderError r e)


-- | This module provides four classes and some related functions which
--   provide <a>ServerPartT</a> with much of its web-centric behavior.
--   
--   <ol>
--   <li><a>ServerMonad</a> provides access to the HTTP
--   <tt>Request</tt></li>
--   <li><a>FilterMonad</a> provides the ability to apply filters and
--   transformations to a <a>Response</a></li>
--   <li><a>WebMonad</a> provides a way to escape a computation early and
--   return a <a>Response</a></li>
--   <li><a>HasRqData</a> which provides access to the decoded QUERY_STRING
--   and request body/form data</li>
--   </ol>
module Happstack.Server.Monads

-- | <a>ServerPartT</a> is a rich, featureful monad for web development.
--   
--   see also: <tt>simpleHTTP</tt>, <a>ServerMonad</a>, <a>FilterMonad</a>,
--   <a>WebMonad</a>, and <tt>HasRqData</tt>
data ServerPartT m a

-- | An alias for <tt><a>ServerPartT</a> <a>IO</a></tt>
type ServerPart a = ServerPartT IO a

-- | A class alias for all the classes a standard server monad (such as
--   <a>ServerPartT</a>) is expected to have instances for. This allows you
--   to keep your type signatures shorter and easier to understand.
class (ServerMonad m, WebMonad Response m, FilterMonad Response m, MonadIO m, MonadPlus m, HasRqData m, Monad m, Functor m, Applicative m, Alternative m) => Happstack m

-- | The <a>ServerMonad</a> class provides methods for reading or locally
--   modifying the <a>Request</a>. It is essentially a specialized version
--   of the <a>MonadReader</a> class. Providing the unique names,
--   <a>askRq</a> and <a>localRq</a> makes it easier to use
--   <a>ServerPartT</a> and <a>ReaderT</a> together.
class Monad m => ServerMonad m
askRq :: ServerMonad m => m Request
localRq :: ServerMonad m => (Request -> Request) -> m a -> m a

-- | Apply a function to transform the inner monad of
--   <tt><a>ServerPartT</a> m</tt>.
--   
--   Often used when transforming a monad with <a>ServerPartT</a>, since
--   <tt>simpleHTTP</tt> requires a <tt><a>ServerPartT</a> <a>IO</a>
--   a</tt>. Refer to <a>UnWebT</a> for an explanation of the structure of
--   the monad.
--   
--   Here is an example. Suppose you want to embed an <a>ErrorT</a> into
--   your <a>ServerPartT</a> to enable <a>throwError</a> and
--   <a>catchError</a> in your <a>Monad</a>.
--   
--   <pre>
--   type MyServerPartT e m a = ServerPartT (ErrorT e m) a
--   </pre>
--   
--   Now suppose you want to pass <tt>MyServerPartT</tt> into a function
--   that demands a <tt><a>ServerPartT</a> <a>IO</a> a</tt> (e.g.
--   <tt>simpleHTTP</tt>). You can provide the function:
--   
--   <pre>
--   unpackErrorT :: (Monad m, Show e) =&gt; UnWebT (ErrorT e m) a -&gt; UnWebT m a
--   unpackErrorT et = do
--      eitherV &lt;- runErrorT et
--      return $ case eitherV of
--          Left err -&gt; Just (Left $ toResponse $
--                                   "Catastrophic failure " ++ show err
--                           , filterFun $ \r -&gt; r{rsCode = 500})
--          Right x -&gt; x
--   </pre>
--   
--   With <tt>unpackErrorT</tt> you can now call <tt>simpleHTTP</tt>. Just
--   wrap your <a>ServerPartT</a> list.
--   
--   <pre>
--   simpleHTTP nullConf $ mapServerPartT unpackErrorT (myPart `catchError` myHandler)
--   </pre>
--   
--   Or alternatively:
--   
--   <pre>
--   simpleHTTP' unpackErrorT nullConf (myPart `catchError` myHandler)
--   </pre>
--   
--   Also see <a>spUnwrapErrorT</a> for a more sophisticated version of
--   this function.
mapServerPartT :: (UnWebT m a -> UnWebT n b) -> (ServerPartT m a -> ServerPartT n b)

-- | A variant of <a>mapServerPartT</a> where the first argument also takes
--   a <a>Request</a>. Useful if you want to <a>runServerPartT</a> on a
--   different <a>ServerPartT</a> inside your monad (see
--   <tt>spUnwrapErrorT</tt>).
mapServerPartT' :: (Request -> UnWebT m a -> UnWebT n b) -> (ServerPartT m a -> ServerPartT n b)

-- | <a>UnWebT</a> is almost exclusively used with <a>mapServerPartT</a>.
--   If you are not using <a>mapServerPartT</a> then you do not need to
--   wrap your head around this type. If you are -- the type is not as
--   complex as it first appears.
--   
--   It is worth discussing the unpacked structure of <a>WebT</a> a bit as
--   it's exposed in <a>mapServerPartT</a> and <a>mapWebT</a>.
--   
--   A fully unpacked <a>WebT</a> has a structure that looks like:
--   
--   <pre>
--   ununWebT $ WebT m a :: m (Maybe (Either Response a, FilterFun Response))
--   </pre>
--   
--   So, ignoring <tt>m</tt>, as it is just the containing <a>Monad</a>,
--   the outermost layer is a <a>Maybe</a>. This is <a>Nothing</a> if
--   <a>mzero</a> was called or <tt><a>Just</a> (<a>Either</a>
--   <a>Response</a> a, <a>SetAppend</a> (<a>Endo</a>
--   <a>Response</a>))</tt> if <a>mzero</a> wasn't called. Inside the
--   <a>Maybe</a>, there is a pair. The second element of the pair is our
--   filter function <tt><a>FilterFun</a> <a>Response</a></tt>.
--   <tt><a>FilterFun</a> <a>Response</a></tt> is a type alias for
--   <tt><a>SetAppend</a> (<a>Dual</a> (<a>Endo</a> <a>Response</a>))</tt>.
--   This is just a wrapper for a <tt><a>Response</a> -&gt;
--   <a>Response</a></tt> function with a particular <a>Monoid</a>
--   behavior. The value
--   
--   <pre>
--   Append (Dual (Endo f))
--   </pre>
--   
--   Causes <tt>f</tt> to be composed with the previous filter.
--   
--   <pre>
--   Set (Dual (Endo f))
--   </pre>
--   
--   Causes <tt>f</tt> to not be composed with the previous filter.
--   
--   Finally, the first element of the pair is either <tt><a>Left</a>
--   <a>Response</a></tt> or <tt><a>Right</a> a</tt>.
--   
--   Another way of looking at all these pieces is from the behaviors they
--   control. The <a>Maybe</a> controls the <a>mzero</a> behavior.
--   <tt><a>Set</a> (<a>Endo</a> f)</tt> comes from the <a>setFilter</a>
--   behavior. Likewise, <tt><a>Append</a> (<a>Endo</a> f)</tt> is from
--   <a>composeFilter</a>. <tt><a>Left</a> <a>Response</a></tt> is what you
--   get when you call <a>finishWith</a> and <tt><a>Right</a> a</tt> is the
--   normal exit.
--   
--   An example case statement looks like:
--   
--   <pre>
--   ex1 webt = do
--     val &lt;- ununWebT webt
--     case val of
--         Nothing -&gt; Nothing  -- this is the interior value when mzero was used
--         Just (Left r, f) -&gt; Just (Left r, f) -- r is the value that was passed into "finishWith"
--                                              -- f is our filter function
--         Just (Right a, f) -&gt; Just (Right a, f) -- a is our normal monadic value
--                                                -- f is still our filter function
--   </pre>
type UnWebT m a = m (Maybe (Either Response a, FilterFun Response))

-- | turn a function into a <a>FilterFun</a>. Primarily used with
--   <a>mapServerPartT</a>
filterFun :: (a -> a) -> FilterFun a

-- | A set of functions for manipulating filters.
--   
--   <a>ServerPartT</a> implements <a>FilterMonad</a> <a>Response</a> so
--   these methods are the fundamental ways of manipulating <a>Response</a>
--   values.
class Monad m => FilterMonad a m | m -> a
setFilter :: FilterMonad a m => (a -> a) -> m ()
composeFilter :: FilterMonad a m => (a -> a) -> m ()
getFilter :: FilterMonad a m => m b -> m (b, a -> a)

-- | Resets all your filters. An alias for <tt><a>setFilter</a>
--   <a>id</a></tt>.
ignoreFilters :: FilterMonad a m => m ()

-- | Add headers into the response. This method does not overwrite any
--   existing header of the same name, hence the name <a>addHeaderM</a>. If
--   you want to replace a header use <a>setHeaderM</a>.
addHeaderM :: FilterMonad Response m => String -> String -> m ()

-- | Get a header out of the request.
getHeaderM :: ServerMonad m => String -> m (Maybe ByteString)

-- | Set a header into the response. This will replace an existing header
--   of the same name. Use <a>addHeaderM</a> if you want to add more than
--   one header of the same name.
setHeaderM :: FilterMonad Response m => String -> String -> m ()

-- | Set a far-future Expires header. Useful for static resources. If the
--   browser has the resource cached, no extra request is spent.
neverExpires :: FilterMonad Response m => m ()

-- | <a>WebMonad</a> provides a means to end the current computation and
--   return a <a>Response</a> immediately. This provides an alternate
--   escape route. In particular it has a monadic value of any type. And
--   unless you call <tt><a>setFilter</a> <a>id</a></tt> first your
--   response filters will be applied normally.
--   
--   Extremely useful when you're deep inside a monad and decide that you
--   want to return a completely different content type, since it doesn't
--   force you to convert all your return types to <a>Response</a> early
--   just to accommodate this.
--   
--   see also: <a>escape</a> and <a>escape'</a>
class Monad m => WebMonad a m | m -> a
finishWith :: WebMonad a m => a -> m b

-- | Used to ignore all your filters and immediately end the computation. A
--   combination of <a>ignoreFilters</a> and <a>finishWith</a>.
escape :: (WebMonad a m, FilterMonad a m) => m a -> m b

-- | An alternate form of <a>escape</a> that can be easily used within a do
--   block.
escape' :: (WebMonad a m, FilterMonad a m) => a -> m b

-- | Run an <a>IO</a> action and, if it returns <a>Just</a>, pass it to the
--   second argument.
require :: (MonadIO m, MonadPlus m) => IO (Maybe a) -> (a -> m r) -> m r

-- | A variant of require that can run in any monad, not just <a>IO</a>.
requireM :: (MonadTrans t, Monad m, MonadPlus (t m)) => m (Maybe a) -> (a -> t m r) -> t m r
instance [overlap ok] (Happstack m, Error e) => Happstack (ErrorT e m)
instance [overlap ok] (Happstack m, Monoid w) => Happstack (RWST r w s m)
instance [overlap ok] (Happstack m, Monoid w) => Happstack (RWST r w s m)
instance [overlap ok] (Happstack m, Monoid w) => Happstack (WriterT w m)
instance [overlap ok] (Happstack m, Monoid w) => Happstack (WriterT w m)
instance [overlap ok] Happstack m => Happstack (ReaderT r m)
instance [overlap ok] Happstack m => Happstack (StateT s m)
instance [overlap ok] Happstack m => Happstack (StateT s m)
instance [overlap ok] (Functor m, Monad m, MonadPlus m, MonadIO m) => Happstack (ServerPartT m)


-- | Support for basic access authentication
--   <a>http://en.wikipedia.org/wiki/Basic_access_authentication</a>
module Happstack.Server.Auth

-- | A simple HTTP basic authentication guard.
--   
--   If authentication fails, this part will call <a>mzero</a>.
--   
--   example:
--   
--   <pre>
--   main = simpleHTTP nullConf $ 
--    msum [ basicAuth "127.0.0.1" (fromList [("happstack","rocks")]) $ ok "You are in the secret club"
--         , ok "You are not in the secret club." 
--         ]
--   </pre>
basicAuth :: Happstack m => String -> Map String String -> m a -> m a


-- | Some useful functions if you want to wrap the <a>ServerPartT</a> monad
--   transformer around the <a>ErrorT</a> monad transformer. e.g.,
--   <tt><a>ServerPartT</a> (<a>ErrorT</a> e m) a</tt>. This allows you to
--   use <tt>throwError</tt> and <tt>catchError</tt> inside your monad.
module Happstack.Server.Error

-- | Flatten <tt><a>ServerPartT</a> (<a>ErrorT</a> e m) a</tt> into a
--   <tt><a>ServerPartT</a> m a</tt> so that it can be use with
--   <tt>simpleHTTP</tt>. Used with <tt>mapServerPartT'</tt>, e.g.,
--   
--   <pre>
--   simpleHTTP conf $ mapServerPartT' (spUnWrapErrorT simpleErrorHandler)  $ myPart `catchError` errorPart
--   </pre>
--   
--   Note that in this example, <tt>simpleErrorHandler</tt> will only be
--   run if <tt>errorPart</tt> throws an error. You can replace
--   <tt>simpleErrorHandler</tt> with your own custom error handler.
--   
--   see also: <a>simpleErrorHandler</a>
spUnwrapErrorT :: Monad m => (e -> ServerPartT m a) -> Request -> UnWebT (ErrorT e m) a -> UnWebT m a

-- | A simple error handler which can be used with <a>spUnwrapErrorT</a>.
--   
--   It returns the error message as a plain text message to the browser.
--   More sophisticated behaviour can be achieved by calling your own
--   custom error handler instead.
--   
--   see also: <a>spUnwrapErrorT</a>
simpleErrorHandler :: Monad m => String -> ServerPartT m Response

-- | This <tt>ServerPart</tt> modifier enables the use of
--   <tt>throwError</tt> and <tt>catchError</tt> inside the <a>WebT</a>
--   actions, by adding the <a>ErrorT</a> monad transformer to the stack.
--   
--   You can wrap the complete second argument to <tt>simpleHTTP</tt> in
--   this function.
--   
--   DEPRECATED: use <a>spUnwrapErrorT</a> instead.

-- | <i>Deprecated: Use spUnwrapErrorT </i>
errorHandlerSP :: (Monad m, Error e) => (Request -> e -> WebT m a) -> ServerPartT (ErrorT e m) a -> ServerPartT m a


-- | Support for creating a proxy or reverse-proxy server
module Happstack.Server.Proxy

-- | <a>proxyServe</a> is for creating a part that acts as a proxy. The
--   sole argument <tt>[<a>String</a>]</tt> is a list of allowed domains
--   for proxying. This matches the domain part of the request and the
--   wildcard * can be used. E.g.
--   
--   <ul>
--   <li>"*" to match anything.</li>
--   <li>"*.example.com" to match anything under example.com</li>
--   <li>"example.com" to match just example.com</li>
--   </ul>
--   
--   TODO: annoyingly enough, this method eventually calls <tt>escape</tt>,
--   so any headers you set won't be used, and the computation immediately
--   ends.
proxyServe :: (MonadIO m, WebMonad Response m, ServerMonad m, MonadPlus m, FilterMonad Response m) => [String] -> m Response

-- | Take a proxy <a>Request</a> and create a <a>Response</a>. Your basic
--   proxy building block. See <a>unproxify</a>.
--   
--   TODO: this would be more useful if it didn't call <tt>escape</tt>
--   (e.g. it let you modify the response afterwards, or set additional
--   headers)
proxyServe' :: (MonadIO m, FilterMonad Response m, WebMonad Response m) => Request -> m Response

-- | This is a reverse proxy implementation. See <a>unrproxify</a>.
--   
--   TODO: this would be more useful if it didn't call <tt>escape</tt>,
--   just like <a>proxyServe'</a>.
rproxyServe :: (ServerMonad m, WebMonad Response m, FilterMonad Response m, MonadIO m) => String -> [(String, String)] -> m Response
unproxify :: Request -> Request
unrproxify :: String -> [(String, String)] -> Request -> Request


-- | Support for validating server output on-the-fly. Validators can be
--   configured on a per content-type basis.
module Happstack.Server.Validation

-- | Set the validator which should be used for this particular
--   <a>Response</a> when validation is enabled.
--   
--   Calling this function does not enable validation. That can only be
--   done by enabling the validation in the <a>Conf</a> that is passed to
--   <tt>simpleHTTP</tt>.
--   
--   You do not need to call this function if the validator set in
--   <a>Conf</a> does what you want already.
--   
--   Example: (use <a>noopValidator</a> instead of the default supplied by
--   <a>validateConf</a>)
--   
--   <pre>
--   simpleHTTP validateConf $ ok . setValidator noopValidator =&lt;&lt; htmlPage
--   </pre>
--   
--   See also: <a>validateConf</a>, <a>wdgHTMLValidator</a>,
--   <a>noopValidator</a>, <a>lazyProcValidator</a>.
setValidator :: (Response -> IO Response) -> Response -> Response

-- | <tt>ServerPart</tt> version of <a>setValidator</a>.
--   
--   Example: (Set validator to <a>noopValidator</a>)
--   
--   <pre>
--   simpleHTTP validateConf $ setValidatorSP noopValidator (dir "ajax" ... )
--   </pre>
setValidatorSP :: (Monad m, ToMessage r) => (Response -> IO Response) -> m r -> m Response

-- | Extend <a>nullConf</a> by enabling validation and setting
--   <a>wdgHTMLValidator</a> as the default validator for
--   <tt>text/html</tt>.
--   
--   Example:
--   
--   <pre>
--   simpleHTTP validateConf . anyRequest $ ok htmlPage
--   </pre>
validateConf :: Conf

-- | Actually perform the validation on a <a>Response</a>.
--   
--   Run the validator specified in the <a>Response</a>. If none is provide
--   use the supplied default instead.
--   
--   Note: This function will run validation unconditionally. You probably
--   want <a>setValidator</a> or <a>validateConf</a>.
runValidator :: (Response -> IO Response) -> Response -> IO Response

-- | Validate <tt>text/html</tt> content with <tt>WDG HTML Validator</tt>.
--   
--   This function expects the executable to be named <tt>validate</tt> and
--   it must be in the default <tt>PATH</tt>.
--   
--   See also: <a>setValidator</a>, <a>validateConf</a>,
--   <a>lazyProcValidator</a>.
wdgHTMLValidator :: (MonadIO m, ToMessage r) => r -> m Response

-- | A validator which always succeeds.
--   
--   Useful for selectively disabling validation. For example, if you are
--   sending down HTML fragments to an AJAX application and the default
--   validator only understands complete documents.
noopValidator :: Response -> IO Response

-- | Validate the <a>Response</a> using an external application.
--   
--   If the external application returns 0, the original response is
--   returned unmodified. If the external application returns non-zero, a
--   <a>Response</a> containing the error messages and original response
--   body is returned instead.
--   
--   This function also takes a predicate filter which is applied to the
--   content-type of the response. The filter will only be applied if the
--   predicate returns true.
--   
--   NOTE: This function requires the use of -threaded to avoid blocking.
--   However, you probably need that for Happstack anyway.
--   
--   See also: <a>wdgHTMLValidator</a>.
lazyProcValidator :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> (Maybe ByteString -> Bool) -> Response -> IO Response


-- | Build your own file serving functions
--   
--   If the functions in <a>Happstack.Server.FileServe</a> do not quite do
--   you want you can roll your own by reusing pieces from this module.
--   
--   You will likely want to start by copying the source for a function
--   like, <a>serveDirectory</a> and then modifying it to suit your needs.
module Happstack.Server.FileServe.BuildingBlocks

-- | Serve files from a directory and its subdirectories using
--   <tt>sendFile</tt>.
--   
--   Usage:
--   
--   <pre>
--   fileServe ["index.html"] "path/to/files/on/disk"
--   </pre>
--   
--   <a>fileServe</a> does not support directory browsing. See
--   <a>serveDirectory</a>
--   
--   DEPRECATED: use <a>serveDirectory</a> instead.
--   
--   Note:
--   
--   The list of index files <tt>["index.html"]</tt> is only used to
--   determine what file to show if the user requests a directory. You *do
--   not* need to explicitly list all the files you want to serve.

-- | <i>Deprecated: use serveDirectory instead. </i>
fileServe :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [FilePath] -> FilePath -> m Response

-- | Serve files from a directory and its subdirectories (parameterizable
--   version)
--   
--   Parameterize this function to create functions like, <a>fileServe</a>,
--   <a>fileServeLazy</a>, and <a>fileServeStrict</a>
--   
--   You supply:
--   
--   <ol>
--   <li>a low-level function which takes a content-type and
--   <a>FilePath</a> and generates a Response</li>
--   <li>a function which determines the content-type from the
--   <a>FilePath</a></li>
--   <li>a list of all the default index files</li>
--   </ol>
--   
--   NOTE: unlike fileServe, there are no index files by default. See
--   <a>defaultIxFiles</a>.
fileServe' :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (String -> FilePath -> m Response) -> (FilePath -> m String) -> (FilePath -> m Response) -> FilePath -> m Response

-- | Serve files from a directory and its subdirectories (lazy ByteString
--   version).
--   
--   WARNING: May leak file handles. You should probably use
--   <a>fileServe</a> instead.
fileServeLazy :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [FilePath] -> FilePath -> m Response

-- | Serve files from a directory and its subdirectories (strict ByteString
--   version).
--   
--   WARNING: the entire file will be read into RAM before being served.
--   You should probably use <a>fileServe</a> instead.
fileServeStrict :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [FilePath] -> FilePath -> m Response

-- | see <a>serveDirectory</a>
data Browsing
EnableBrowsing :: Browsing
DisableBrowsing :: Browsing

-- | Serve files and directories from a directory and its subdirectories
--   using <tt>sendFile</tt>.
--   
--   Usage:
--   
--   <pre>
--   serveDirectory EnableBrowsing ["index.html"] "path/to/files/on/disk"
--   </pre>
--   
--   If the requested path does not match a file or directory on the disk,
--   then <a>serveDirectory</a> calls <a>mzero</a>.
--   
--   If the requested path is a file then the file is served normally.
--   
--   If the requested path is a directory, then the result depends on what
--   the first two arguments to the function are.
--   
--   The first argument controls whether directory browsing is enabled.
--   
--   The second argument is a list of index files (such as index.html).
--   
--   When a directory is requested, <a>serveDirectory</a> will first try to
--   find one of the index files (in the order they are listed). If that
--   fails, it will show a directory listing if <a>EnableBrowsing</a> is
--   set, otherwise it will return <tt>forbidden "Directory index
--   forbidden"</tt>.
--   
--   Here is an explicit list of all the possible outcomes when the
--   argument is a (valid) directory:
--   
--   <ul>
--   <li><i><tt><a>DisableBrowsing</a>, empty index file list</tt></i></li>
--   </ul>
--   
--   This will always return, forbidden "Directory index forbidden"
--   
--   <ul>
--   <li><i><tt><a>DisableBrowsing</a>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown.</li>
--   <li>Otherwise returns, forbidden "Directory index forbidden"</li>
--   </ol>
--   
--   <ul>
--   <li><i><tt><a>EnableBrowsing</a>, empty index file list</tt></i></li>
--   </ul>
--   
--   Always shows a directory index.
--   
--   <ul>
--   <li><i><tt><a>EnableBrowsing</a>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown</li>
--   <li>Otherwise shows a directory index</li>
--   </ol>
--   
--   see also: <a>defaultIxFiles</a>, <a>serveFile</a>
serveDirectory :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => Browsing -> [FilePath] -> FilePath -> m Response

-- | like <a>serveDirectory</a> but with custom mimeTypes
serveDirectory' :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => Browsing -> [FilePath] -> (FilePath -> m String) -> FilePath -> m Response

-- | Serve a single, specified file. The name of the file being served is
--   specified explicity. It is not derived automatically from the
--   <a>Request</a> url.
--   
--   example 1:
--   
--   Serve as a specific content-type:
--   
--   <pre>
--   serveFile (asContentType "image/jpeg") "/srv/data/image.jpg"
--   </pre>
--   
--   example 2:
--   
--   Serve guessing the content-type from the extension:
--   
--   <pre>
--   serveFile (guessContentTypeM mimeTypes) "/srv/data/image.jpg"
--   </pre>
--   
--   If the specified path does not exist or is not a file, this function
--   will return <a>mzero</a>.
--   
--   WARNING: No security checks are performed.
--   
--   NOTE: alias for <a>serveFileUsing</a> <a>filePathSendFile</a>
serveFile :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (FilePath -> m String) -> FilePath -> m Response

-- | Like <a>serveFile</a>, but uses <a>combineSafe</a> to prevent
--   directory traversal attacks when the path to the file is supplied by
--   the user.
serveFileFrom :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => FilePath -> (FilePath -> m String) -> FilePath -> m Response

-- | Serve a single, specified file. The name of the file being served is
--   specified explicity. It is not derived automatically from the
--   <a>Request</a> url.
--   
--   example 1:
--   
--   Serve using sendfile() and the specified content-type
--   
--   <pre>
--   serveFileUsing filePathSendFile (asContentType "image/jpeg") "/srv/data/image.jpg"
--   </pre>
--   
--   example 2:
--   
--   Serve using a lazy ByteString and the guess the content-type from the
--   extension
--   
--   <pre>
--   serveFileUsing filePathLazy (guessContentTypeM mimeTypes) "/srv/data/image.jpg"
--   </pre>
--   
--   WARNING: No security checks are performed.
serveFileUsing :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (String -> FilePath -> m Response) -> (FilePath -> m String) -> FilePath -> m Response

-- | Use sendFile to send the contents of a Handle
sendFileResponse :: String -> FilePath -> Maybe (UTCTime, Request) -> Integer -> Integer -> Response

-- | Send the contents of a Lazy ByteString
lazyByteStringResponse :: String -> ByteString -> Maybe (UTCTime, Request) -> Integer -> Integer -> Response

-- | Send the contents of a Lazy ByteString
strictByteStringResponse :: String -> ByteString -> Maybe (UTCTime, Request) -> Integer -> Integer -> Response

-- | Send the specified file with the specified mime-type using sendFile()
--   
--   NOTE: assumes file exists and is readable by the server. See
--   <a>serveFileUsing</a>.
--   
--   WARNING: No security checks are performed.
filePathSendFile :: (ServerMonad m, MonadIO m) => String -> FilePath -> m Response

-- | Send the specified file with the specified mime-type using lazy
--   ByteStrings
--   
--   NOTE: assumes file exists and is readable by the server. See
--   <a>serveFileUsing</a>.
--   
--   WARNING: No security checks are performed.
filePathLazy :: (ServerMonad m, MonadIO m) => String -> FilePath -> m Response

-- | Send the specified file with the specified mime-type using strict
--   ByteStrings
--   
--   NOTE: assumes file exists and is readable by the server. See
--   <a>serveFileUsing</a>.
--   
--   WARNING: No security checks are performed.
filePathStrict :: (ServerMonad m, MonadIO m) => String -> FilePath -> m Response

-- | a <a>Map</a> from file extensions to content-types
--   
--   example:
--   
--   <pre>
--   myMimeMap :: MimeMap
--   myMimeMap = Map.fromList [("gz","application/x-gzip"), ... ]
--   </pre>
--   
--   see also: <a>mimeTypes</a>
type MimeMap = Map String String

-- | Ready collection of common mime types. Except for the first two
--   entries, the mappings come from an Ubuntu 8.04 /etc/mime.types file.
mimeTypes :: MimeMap

-- | returns a specific content type, completely ignoring the
--   <a>FilePath</a> argument.
--   
--   Use this with <a>serveFile</a> if you want to explicitly specify the
--   content-type.
--   
--   see also: <a>guessContentTypeM</a>, <a>serveFile</a>
asContentType :: Monad m => String -> (FilePath -> m String)

-- | try to guess the content-type of a file based on its extension
--   
--   see also: <a>guessContentTypeM</a>
guessContentType :: MimeMap -> FilePath -> Maybe String

-- | try to guess the content-type of a file based on its extension
--   
--   defaults to <a>application/octet-stream</a> if no match was found.
--   
--   Useful as an argument to <a>serveFile</a>
--   
--   see also: <a>guessContentType</a>, <a>serveFile</a>
guessContentTypeM :: Monad m => MimeMap -> (FilePath -> m String)
data EntryKind
File :: EntryKind
Directory :: EntryKind
UnknownKind :: EntryKind
browseIndex :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m, ToMessage b) => (FilePath -> [FilePath] -> m b) -> (String -> FilePath -> m Response) -> (FilePath -> m String) -> [String] -> FilePath -> m Response

-- | a function to generate an HTML page showing the contents of a
--   directory on the disk
--   
--   see also: <a>browseIndex</a>, <a>renderDirectoryContentsTable</a>
renderDirectoryContents :: MonadIO m => FilePath -> [FilePath] -> m Html

-- | a function to generate an HTML table showing the contents of a
--   directory on the disk
--   
--   This function generates most of the content of the
--   <a>renderDirectoryContents</a> page. If you want to style the page
--   differently, or add google analytics code, etc, you can just create a
--   new page template to wrap around this HTML.
--   
--   see also: <a>getMetaData</a>, <a>renderDirectoryContents</a>
renderDirectoryContentsTable :: [(FilePath, Maybe UTCTime, Maybe Integer, EntryKind)] -> Html

-- | Prevents files of the form '.foo' or 'bar/.foo' from being served
blockDotFiles :: (Request -> IO Response) -> Request -> IO Response

-- | a list of common index files. Specifically: <tt>index.html</tt>,
--   <tt>index.xml</tt>, <tt>index.gif</tt>
--   
--   Typically used as an argument to <tt>serveDiretory</tt>.
defaultIxFiles :: [FilePath]

-- | Combine two <a>FilePath</a>s, ensuring that the resulting path leads
--   to a file within the first <a>FilePath</a>.
--   
--   <pre>
--   &gt;&gt;&gt; combineSafe "/var/uploads/" "etc/passwd"
--   Just "/var/uploads/etc/passwd"
--   
--   &gt;&gt;&gt; combineSafe "/var/uploads/" "/etc/passwd"
--   Nothing
--   
--   &gt;&gt;&gt; combineSafe "/var/uploads/" "../../etc/passwd"
--   Nothing
--   
--   &gt;&gt;&gt; combineSafe "/var/uploads/" "../uploads/home/../etc/passwd"
--   Just "/var/uploads/etc/passwd"
--   </pre>
combineSafe :: FilePath -> FilePath -> Maybe FilePath
isSafePath :: [FilePath] -> Bool

-- | try to find an index file, calls mzero on failure
tryIndex :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (String -> FilePath -> m Response) -> (FilePath -> m String) -> [String] -> FilePath -> m Response

-- | attempt to serve index files
doIndex :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [FilePath] -> MimeMap -> FilePath -> m Response
doIndex' :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (String -> FilePath -> m Response) -> (FilePath -> m String) -> [String] -> FilePath -> m Response
doIndexLazy :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [String] -> MimeMap -> FilePath -> m Response
doIndexStrict :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [String] -> MimeMap -> FilePath -> m Response

-- | return a simple <a>File not found 404 page.</a>
fileNotFound :: (Monad m, FilterMonad Response m) => FilePath -> m Response

-- | Returns True if the given String either starts with a . or is of the
--   form <a>foo/.bar</a>, e.g. the typical *nix convention for hidden
--   files.
isDot :: String -> Bool
instance [overlap ok] Typeable EntryKind
instance [overlap ok] Typeable Browsing
instance [overlap ok] Eq EntryKind
instance [overlap ok] Ord EntryKind
instance [overlap ok] Read EntryKind
instance [overlap ok] Show EntryKind
instance [overlap ok] Data EntryKind
instance [overlap ok] Enum EntryKind
instance [overlap ok] Eq Browsing
instance [overlap ok] Enum Browsing
instance [overlap ok] Ord Browsing
instance [overlap ok] Read Browsing
instance [overlap ok] Show Browsing
instance [overlap ok] Data Browsing


-- | functions for serving static files from the disk
module Happstack.Server.FileServe

-- | see <a>serveDirectory</a>
data Browsing
EnableBrowsing :: Browsing
DisableBrowsing :: Browsing

-- | Serve files and directories from a directory and its subdirectories
--   using <tt>sendFile</tt>.
--   
--   Usage:
--   
--   <pre>
--   serveDirectory EnableBrowsing ["index.html"] "path/to/files/on/disk"
--   </pre>
--   
--   If the requested path does not match a file or directory on the disk,
--   then <a>serveDirectory</a> calls <a>mzero</a>.
--   
--   If the requested path is a file then the file is served normally.
--   
--   If the requested path is a directory, then the result depends on what
--   the first two arguments to the function are.
--   
--   The first argument controls whether directory browsing is enabled.
--   
--   The second argument is a list of index files (such as index.html).
--   
--   When a directory is requested, <a>serveDirectory</a> will first try to
--   find one of the index files (in the order they are listed). If that
--   fails, it will show a directory listing if <a>EnableBrowsing</a> is
--   set, otherwise it will return <tt>forbidden "Directory index
--   forbidden"</tt>.
--   
--   Here is an explicit list of all the possible outcomes when the
--   argument is a (valid) directory:
--   
--   <ul>
--   <li><i><tt><a>DisableBrowsing</a>, empty index file list</tt></i></li>
--   </ul>
--   
--   This will always return, forbidden "Directory index forbidden"
--   
--   <ul>
--   <li><i><tt><a>DisableBrowsing</a>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown.</li>
--   <li>Otherwise returns, forbidden "Directory index forbidden"</li>
--   </ol>
--   
--   <ul>
--   <li><i><tt><a>EnableBrowsing</a>, empty index file list</tt></i></li>
--   </ul>
--   
--   Always shows a directory index.
--   
--   <ul>
--   <li><i><tt><a>EnableBrowsing</a>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown</li>
--   <li>Otherwise shows a directory index</li>
--   </ol>
--   
--   see also: <a>defaultIxFiles</a>, <a>serveFile</a>
serveDirectory :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => Browsing -> [FilePath] -> FilePath -> m Response

-- | Serve a single, specified file. The name of the file being served is
--   specified explicity. It is not derived automatically from the
--   <a>Request</a> url.
--   
--   example 1:
--   
--   Serve as a specific content-type:
--   
--   <pre>
--   serveFile (asContentType "image/jpeg") "/srv/data/image.jpg"
--   </pre>
--   
--   example 2:
--   
--   Serve guessing the content-type from the extension:
--   
--   <pre>
--   serveFile (guessContentTypeM mimeTypes) "/srv/data/image.jpg"
--   </pre>
--   
--   If the specified path does not exist or is not a file, this function
--   will return <a>mzero</a>.
--   
--   WARNING: No security checks are performed.
--   
--   NOTE: alias for <a>serveFileUsing</a> <a>filePathSendFile</a>
serveFile :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => (FilePath -> m String) -> FilePath -> m Response

-- | Like <a>serveFile</a>, but uses <a>combineSafe</a> to prevent
--   directory traversal attacks when the path to the file is supplied by
--   the user.
serveFileFrom :: (ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => FilePath -> (FilePath -> m String) -> FilePath -> m Response

-- | a <a>Map</a> from file extensions to content-types
--   
--   example:
--   
--   <pre>
--   myMimeMap :: MimeMap
--   myMimeMap = Map.fromList [("gz","application/x-gzip"), ... ]
--   </pre>
--   
--   see also: <a>mimeTypes</a>
type MimeMap = Map String String

-- | Ready collection of common mime types. Except for the first two
--   entries, the mappings come from an Ubuntu 8.04 /etc/mime.types file.
mimeTypes :: MimeMap

-- | returns a specific content type, completely ignoring the
--   <a>FilePath</a> argument.
--   
--   Use this with <a>serveFile</a> if you want to explicitly specify the
--   content-type.
--   
--   see also: <a>guessContentTypeM</a>, <a>serveFile</a>
asContentType :: Monad m => String -> (FilePath -> m String)

-- | try to guess the content-type of a file based on its extension
--   
--   defaults to <a>application/octet-stream</a> if no match was found.
--   
--   Useful as an argument to <a>serveFile</a>
--   
--   see also: <a>guessContentType</a>, <a>serveFile</a>
guessContentTypeM :: Monad m => MimeMap -> (FilePath -> m String)

-- | a list of common index files. Specifically: <tt>index.html</tt>,
--   <tt>index.xml</tt>, <tt>index.gif</tt>
--   
--   Typically used as an argument to <tt>serveDiretory</tt>.
defaultIxFiles :: [FilePath]

-- | Serve files from a directory and its subdirectories using
--   <tt>sendFile</tt>.
--   
--   Usage:
--   
--   <pre>
--   fileServe ["index.html"] "path/to/files/on/disk"
--   </pre>
--   
--   <a>fileServe</a> does not support directory browsing. See
--   <a>serveDirectory</a>
--   
--   DEPRECATED: use <a>serveDirectory</a> instead.
--   
--   Note:
--   
--   The list of index files <tt>["index.html"]</tt> is only used to
--   determine what file to show if the user requests a directory. You *do
--   not* need to explicitly list all the files you want to serve.

-- | <i>Deprecated: use serveDirectory instead. </i>
fileServe :: (WebMonad Response m, ServerMonad m, FilterMonad Response m, MonadIO m, MonadPlus m) => [FilePath] -> FilePath -> m Response


-- | Route an incoming <a>Request</a> to a handler. For more in-depth
--   documentation see this section of the Happstack Crash Course:
--   <a>http://happstack.com/docs/crashcourse/RouteFilters.html</a>
module Happstack.Server.Routing

-- | guard which checks that an insecure connection was made via http://
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do https
--          ...
--   </pre>
http :: (ServerMonad m, MonadPlus m) => m ()

-- | guard which checks that a secure connection was made via https://
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do https
--          ...
--   </pre>
https :: (ServerMonad m, MonadPlus m) => m ()

-- | Guard against the method. This function also guards against *any
--   remaining path segments*. See <a>method</a> for the version that
--   guards only by method.
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do methodM [GET, HEAD]
--          ...
--   </pre>
--   
--   NOTE: This function is largely retained for backwards compatibility.
--   The fact that implicitly calls <a>nullDir</a> is often forgotten and
--   leads to confusion. It is probably better to just use <a>method</a>
--   and call <a>nullDir</a> explicitly.
--   
--   This function will likely be deprecated in the future.
methodM :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

-- | Guard against the method only (as opposed to <a>methodM</a>).
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do methodOnly [GET, HEAD]
--          ...
--   </pre>

-- | <i>Deprecated: this function is just an alias for method now </i>
methodOnly :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

-- | Guard against the method. Note, this function also guards against any
--   remaining path segments. Similar to <a>methodM</a> but with a
--   different type signature.
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler = methodSP [GET, HEAD] $ subHandler
--   </pre>
--   
--   NOTE: This style of combinator is going to be deprecated in the
--   future. It is better to just use <a>method</a>.
--   
--   <pre>
--   handler :: ServerPart Response
--   handler = method [GET, HEAD] &gt;&gt; nullDir &gt;&gt; subHandler
--   </pre>

-- | <i>Deprecated: use method instead. </i>
methodSP :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m b -> m b

-- | Guard against the method only (as opposed to <a>methodM</a>).
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do methodOnly [GET, HEAD]
--          ...
--   </pre>
method :: (ServerMonad m, MonadPlus m, MatchMethod method) => method -> m ()

-- | instances of this class provide a variety of ways to match on the
--   <a>Request</a> method.
--   
--   Examples:
--   
--   <pre>
--   method GET                  -- match GET or HEAD
--   method [GET, POST]          -- match GET, HEAD or POST
--   method HEAD                 -- match HEAD /but not/ GET
--   method (== GET)             -- match GET or HEAD
--   method (not . (==) DELETE)  -- match any method except DELETE
--   method ()                   -- match any method
--   </pre>
--   
--   As you can see, GET implies that HEAD should match as well. This is to
--   make it harder to write an application that uses HTTP incorrectly.
--   Happstack handles HEAD requests automatically, but we still need to
--   make sure our handlers don't mismatch or a HEAD will result in a 404.
--   
--   If you must, you can still do something like this to match GET without
--   HEAD:
--   
--   <pre>
--   guardRq ((== GET) . rqMethod)
--   </pre>
class MatchMethod m
matchMethod :: MatchMethod m => m -> Method -> Bool

-- | Pop a path element and run the supplied handler if it matches the
--   given string.
--   
--   <pre>
--   handler :: ServerPart Response
--   handler = dir "foo" $ dir "bar" $ subHandler
--   </pre>
--   
--   The path element can not contain '/'. See also <a>dirs</a>.
dir :: (ServerMonad m, MonadPlus m) => String -> m a -> m a

-- | Guard against a <a>FilePath</a>. Unlike <a>dir</a> the <a>FilePath</a>
--   may contain '/'. If the guard succeeds, the matched elements will be
--   popped from the directory stack.
--   
--   <pre>
--   dirs "foo/bar" $ ...
--   </pre>
--   
--   See also: <a>dir</a>.
dirs :: (ServerMonad m, MonadPlus m) => FilePath -> m a -> m a

-- | guard which only succeeds if there are no remaining path segments
--   
--   Often used if you want to explicitly assign a route for <a>/</a>
nullDir :: (ServerMonad m, MonadPlus m) => m ()

-- | Guard which checks that the Request URI ends in <tt>'/'</tt>. Useful
--   for distinguishing between <tt>foo</tt> and <tt>foo/</tt>
trailingSlash :: (ServerMonad m, MonadPlus m) => m ()

-- | The opposite of <a>trailingSlash</a>.
noTrailingSlash :: (ServerMonad m, MonadPlus m) => m ()

-- | Pop any path element and run the handler.
--   
--   Succeeds if a path component was popped. Fails is the remaining path
--   was empty.
anyPath :: (ServerMonad m, MonadPlus m) => m r -> m r

-- | Pop a path element and parse it using the <a>fromReqURI</a> in the
--   <a>FromReqURI</a> class.
path :: (FromReqURI a, MonadPlus m, ServerMonad m) => (a -> m b) -> m b

-- | Grab the rest of the URL (dirs + query) and passes it to your handler.
uriRest :: ServerMonad m => (String -> m a) -> m a

-- | Guard against the host.
--   
--   This matches against the <tt>host</tt> header specified in the
--   incoming <a>Request</a>.
--   
--   Can be used to support virtual hosting,
--   <a>http://en.wikipedia.org/wiki/Virtual_hosting</a>
--   
--   Note that this matches against the value of the <tt>Host</tt> header
--   which may include the port number.
--   
--   <a>http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.23</a>
--   
--   see also: <a>withHost</a>
host :: (ServerMonad m, MonadPlus m) => String -> m a -> m a

-- | Lookup the <tt>host</tt> header in the incoming request and pass it to
--   the handler.
--   
--   see also: <a>host</a>
withHost :: (ServerMonad m, MonadPlus m) => (String -> m a) -> m a

-- | Guard using an arbitrary function on the <a>Request</a>.
guardRq :: (ServerMonad m, MonadPlus m) => (Request -> Bool) -> m ()
instance [overlap ok] MatchMethod ()
instance [overlap ok] MatchMethod (Method -> Bool)
instance [overlap ok] MatchMethod [Method]
instance [overlap ok] MatchMethod Method


-- | <a>simpleHTTP</a> is a self-contained HTTP server which can be used to
--   run a <a>ServerPart</a>.
--   
--   A very simple, "Hello World!" web app looks like:
--   
--   <pre>
--   import Happstack.Server
--   main = simpleHTTP nullConf $ ok "Hello World!"
--   </pre>
--   
--   By default the server will listen on port 8000. Run the app and point
--   your browser at: <a>http://localhost:8000/</a>
--   
--   For FastCGI support see:
--   <a>http://hackage.haskell.org/package/happstack-fastcgi</a>
module Happstack.Server.SimpleHTTP

-- | start the server, and handle requests using the supplied
--   <a>ServerPart</a>.
--   
--   This function will not return, though it may throw an exception.
--   
--   NOTE: The server will only listen on IPv4 due to portability issues in
--   the <a>Network</a> module. For IPv6 support, use
--   <a>simpleHTTPWithSocket</a> with custom socket.
simpleHTTP :: ToMessage a => Conf -> ServerPartT IO a -> IO ()

-- | A combination of <a>simpleHTTP''</a> and <a>mapServerPartT</a>. See
--   <a>mapServerPartT</a> for a discussion of the first argument of this
--   function.
--   
--   NOTE: This function always binds to IPv4 ports until Network module is
--   fixed to support IPv6 in a portable way. Use
--   <a>simpleHTTPWithSocket</a> with custom socket if you want different
--   behaviour.
simpleHTTP' :: (ToMessage b, Monad m, Functor m) => (UnWebT m a -> UnWebT IO b) -> Conf -> ServerPartT m a -> IO ()

-- | Generate a result from a <a>ServerPartT</a> and a <a>Request</a>. This
--   is mainly used by CGI (and fast-cgi) wrappers.
simpleHTTP'' :: (ToMessage b, Monad m, Functor m) => ServerPartT m b -> Request -> m Response

-- | Run <a>simpleHTTP</a> with a previously bound socket. Useful if you
--   want to run happstack as user on port 80. Use something like this:
--   
--   <pre>
--   import System.Posix.User (setUserID, UserEntry(..), getUserEntryForName)
--   
--   main = do
--       let conf = nullConf { port = 80 }
--       socket &lt;- bindPort conf
--       -- do other stuff as root here
--       getUserEntryForName "www" &gt;&gt;= setUserID . userID
--       -- finally start handling incoming requests
--       tid &lt;- forkIO $ simpleHTTPWithSocket socket Nothing conf impl
--   </pre>
--   
--   Note: It's important to use the same conf (or at least the same port)
--   for <a>bindPort</a> and <a>simpleHTTPWithSocket</a>.
--   
--   see also: <a>bindPort</a>, <a>bindIPv4</a>
simpleHTTPWithSocket :: ToMessage a => Socket -> Conf -> ServerPartT IO a -> IO ()

-- | Like <a>simpleHTTP'</a> with a socket.
simpleHTTPWithSocket' :: (ToMessage b, Monad m, Functor m) => (UnWebT m a -> UnWebT IO b) -> Socket -> Conf -> ServerPartT m a -> IO ()

-- | Bind port and return the socket for use with
--   <a>simpleHTTPWithSocket</a>. This function always binds to IPv4 ports
--   until Network module is fixed to support IPv6 in a portable way.
bindPort :: Conf -> IO Socket

-- | Bind to ip and port and return the socket for use with
--   <a>simpleHTTPWithSocket</a>.
--   
--   <pre>
--   import Happstack.Server
--   
--   main = do let conf = nullConf
--                 addr = "127.0.0.1"
--             s &lt;- bindIPv4 addr (port conf)
--             simpleHTTPWithSocket s conf $ ok $ toResponse $
--               "now listening on ip addr " ++ addr ++
--               " and port " ++ show (port conf)
--   </pre>
bindIPv4 :: String -> Int -> IO Socket

-- | Parse command line options into a <a>Conf</a>.
parseConfig :: [String] -> Either [String] Conf

-- | Wait for a signal. On unix, a signal is sigINT or sigTERM (aka
--   Control-C).
--   
--   On windows, the signal is entering: e <a>return</a>
waitForTermination :: IO ()


-- | Filter for compressing the <a>Response</a> body.
module Happstack.Server.Internal.Compression

-- | reads the <tt>Accept-Encoding</tt> header. Then, if possible will
--   compress the response body with methods <tt>gzip</tt> or
--   <tt>deflate</tt>.
--   
--   <pre>
--   main =
--     simpleHTTP nullConf $
--        do str &lt;- compressedResponseFilter
--           return $ toResponse ("This response compressed using: " ++ str)
--   </pre>
compressedResponseFilter :: (FilterMonad Response m, MonadPlus m, WebMonad Response m, ServerMonad m) => m String

-- | Ignore the <tt>Accept-Encoding</tt> header in the <a>Request</a> and
--   attempt to compress the body of the response using the supplied
--   compressor.
--   
--   We can not compress files being transfered using <a>SendFile</a>. If
--   <tt>identity</tt> is an allowed encoding, then just return the
--   <a>Response</a> unmodified. Otherwise we return <a>406 Not
--   Acceptable</a>.
--   
--   see also: <a>gzipFilter</a> and <tt>defaultFilter</tt>
compressWithFilter :: FilterMonad Response m => (ByteString -> ByteString) -> String -> Bool -> m ()

-- | Ignore the <tt>Accept-Encoding</tt> header in the <a>Request</a> and
--   attempt to compress the body of the response with <tt>gzip</tt>.
--   
--   calls <a>compressWithFilter</a> using <a>compress</a>.
--   
--   see also: <a>compressedResponseFilter</a>
gzipFilter :: FilterMonad Response m => String -> Bool -> m ()

-- | Ignore the <tt>Accept-Encoding</tt> header in the <a>Request</a> and
--   attempt compress the body of the response with zlib's <tt>deflate</tt>
--   method
--   
--   calls <a>compressWithFilter</a> using <a>compress</a>.
--   
--   see also: <a>compressedResponseFilter</a>
deflateFilter :: FilterMonad Response m => String -> Bool -> m ()

-- | a parser for the Accept-Encoding header
encodings :: GenParser Char st [(String, Maybe Double)]

module Happstack.Server.I18N

-- | parse the 'Accept-Language' header, or [] if not found.
acceptLanguage :: Happstack m => m [(Text, Maybe Double)]

-- | deconstruct the <a>acceptLanguage</a> results a return a list of
--   languages sorted by preference in descending order.
--   
--   Note: this implementation does not conform to RFC4647
--   
--   Among other things, it does not handle wildcards. A proper
--   implementation needs to take a list of available languages.
bestLanguage :: [(Text, Maybe Double)] -> [Text]


-- | Filter for compressing the <tt>Response</tt> body.
module Happstack.Server.Compression

-- | reads the <tt>Accept-Encoding</tt> header. Then, if possible will
--   compress the response body with methods <tt>gzip</tt> or
--   <tt>deflate</tt>.
--   
--   <pre>
--   main =
--     simpleHTTP nullConf $
--        do str &lt;- compressedResponseFilter
--           return $ toResponse ("This response compressed using: " ++ str)
--   </pre>
compressedResponseFilter :: (FilterMonad Response m, MonadPlus m, WebMonad Response m, ServerMonad m) => m String


-- | Happstack.Server provides a self-contained HTTP server and a rich
--   collection of types and functions for routing Requests, generating
--   Responses, working with query parameters, form data, and cookies,
--   serving files and more.
--   
--   A very simple, "Hello World!" web app looks like:
--   
--   <pre>
--   import Happstack.Server
--   main = simpleHTTP nullConf $ ok "Hello World!"
--   </pre>
--   
--   By default the server will listen on port 8000. Run the app and point
--   your browser at: <a>http://localhost:8000/</a>
--   
--   At the core of the Happstack server we have the <a>simpleHTTP</a>
--   function which starts the HTTP server:
--   
--   <pre>
--   simpleHTTP :: ToMessage a =&gt; Conf -&gt; ServerPart a -&gt; IO ()
--   </pre>
--   
--   and we have the user supplied <a>ServerPart</a> (also known as,
--   <a>ServerPartT</a> <a>IO</a>), which generates a <a>Response</a> for
--   each incoming <a>Request</a>.
--   
--   A trivial HTTP app server might just take a user supplied function
--   like:
--   
--   <pre>
--   myApp :: Request -&gt; IO Response
--   </pre>
--   
--   For each incoming <a>Request</a> the server would fork a new thread,
--   run <tt>myApp</tt> to generate a <a>Response</a>, and then send the
--   <a>Response</a> back to the client. But, that would be a pretty barren
--   wasteland to work in.
--   
--   The model for <a>ServerPart</a> is essential the same, except we use
--   the much richer <a>ServerPart</a> monad instead of the <a>IO</a>
--   monad.
--   
--   For in-depth documentation and runnable examples I highly recommend
--   The Happstack Crash Course
--   <a>http://happstack.com/docs/crashcourse/index.html</a>.
module Happstack.Server