-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Snap: A Haskell Web Framework (Core)
--
-- Snap is a simple and fast web development framework and server written
-- in Haskell. For more information or to download the latest version,
-- you can visit the Snap project website at
-- http://snapframework.com/.
--
-- This library contains the core definitions and types for the Snap
-- framework, including:
--
--
-- - Primitive types and functions for HTTP (requests, responses,
-- cookies, post/query parameters, etc)
-- - Type aliases and helper functions for Iteratee I/O
-- - A monad for programming web handlers called "Snap", inspired by
-- happstack's (http://happstack.com/index.html), which
-- allows:
--
--
--
-- - Stateful access to the HTTP request and response objects
-- - Monadic failure (i.e. MonadPlus/Alternative instances) for
-- declining to handle requests and chaining handlers together
-- - Early termination of the computation if you know early what you
-- want to return and want to prevent further monadic processing
--
--
-- Quick start: The Snap monad and HTTP definitions are in
-- Snap.Types, some iteratee utilities are in
-- Snap.Iteratee.
--
-- Higher-level facilities for building web applications (like
-- user/session management, component interfaces, data modeling, etc.)
-- are planned but not yet implemented, so this release will mostly be of
-- interest for those who:
--
--
-- - need a fast and minimal HTTP API at roughly the same level of
-- abstraction as Java servlets, or
-- - are interested in contributing to the Snap Framework project.
--
@package snap-core
@version 0.4.3
-- | An internal Snap module for (optionally) printing debugging messages.
-- Normally debug does nothing, but if you set DEBUG=1 in
-- the environment you'll get debugging messages. We use
-- unsafePerformIO to make sure that the call to getEnv
-- is only made once.
--
-- N.B. this is an internal interface, please don't write external
-- code that depends on it.
module Snap.Internal.Debug
debugErrno :: MonadIO m => String -> m ()
debug :: MonadIO m => String -> m ()
debugIgnore :: MonadIO m => String -> m ()
debugErrnoIgnore :: MonadIO m => String -> m ()
-- | Snap Framework type aliases and utilities for iteratees. Note that as
-- a convenience, this module also exports everything from
-- Data.Enumerator in the enumerator library.
module Snap.Iteratee
-- | Enumerates a strict bytestring.
enumBS :: Monad m => ByteString -> Enumerator ByteString m a
-- | Enumerates a lazy bytestring.
enumLBS :: Monad m => ByteString -> Enumerator ByteString m a
-- | Enumerates a Builder.
enumBuilder :: Monad m => Builder -> Enumerator Builder m a
enumFile :: FilePath -> Enumerator ByteString IO a
enumFilePartial :: FilePath -> (Int64, Int64) -> Enumerator ByteString IO a
data InvalidRangeException
joinI' :: Monad m => Iteratee a m (Step a m b) -> Iteratee a m b
-- | Wraps an Iteratee, counting the number of bytes consumed by it.
countBytes :: Monad m => forall a. Iteratee ByteString m a -> Iteratee ByteString m (a, Int64)
-- | Skip n elements of the stream, if there are that many
drop' :: Monad m => Int64 -> Iteratee ByteString m ()
-- | Creates a buffer to be passed into
-- unsafeBufferIterateeWithBuffer.
mkIterateeBuffer :: IO (ForeignPtr CChar)
-- | Buffers an iteratee, "unsafely". Here we use a fixed binary buffer
-- which we'll re-use, meaning that if you hold on to any of the
-- bytestring data passed into your iteratee (instead of, let's say,
-- shoving it right out a socket) it'll get changed out from underneath
-- you, breaking referential transparency. Use with caution!
--
-- This version accepts a buffer created by mkIterateeBuffer.
unsafeBufferIterateeWithBuffer :: ForeignPtr CChar -> Iteratee ByteString IO a -> Iteratee ByteString IO a
-- | Buffers an iteratee, "unsafely". Here we use a fixed binary buffer
-- which we'll re-use, meaning that if you hold on to any of the
-- bytestring data passed into your iteratee (instead of, let's say,
-- shoving it right out a socket) it'll get changed out from underneath
-- you, breaking referential transparency. Use with caution!
unsafeBufferIteratee :: Iteratee ByteString IO a -> IO (Iteratee ByteString IO a)
take :: Monad m => Int -> Enumeratee ByteString ByteString m a
-- | Skip n elements of the stream, if there are that many
drop :: Monad m => Int -> Iteratee ByteString m ()
-- | Reads n bytes from a stream and applies the given iteratee to the
-- stream of the read elements. Reads exactly n bytes, and if the stream
-- is short propagates an error.
takeExactly :: Monad m => Int64 -> Enumeratee ByteString ByteString m a
takeNoMoreThan :: Monad m => Int64 -> Enumeratee ByteString ByteString m a
skipToEof :: Monad m => Iteratee a m ()
mapEnum :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Enumerator aIn m a -> Enumerator aOut m a
mapIter :: Monad m => (aOut -> aIn) -> (aIn -> aOut) -> Iteratee aIn m a -> Iteratee aOut m a
killIfTooSlow :: MonadIO m => m () -> Double -> Int -> Iteratee ByteString m a -> Iteratee ByteString m a
data TooManyBytesReadException
data ShortWriteException
data RateTooSlowException
-- | A Stream is a sequence of chunks generated by an
-- Enumerator.
--
-- (Chunks []) is used to indicate that a stream is still
-- active, but currently has no available data. Iteratees should ignore
-- empty chunks.
data Stream a :: * -> *
Chunks :: [a] -> Stream a
EOF :: Stream a
data Step a m :: (* -> *) b :: * -> (* -> *) -> * -> *
-- | The Iteratee is capable of accepting more input. Note that more
-- input is not necessarily required; the Iteratee might be able
-- to generate a value immediately if it receives EOF.
Continue :: (Stream a -> Iteratee a m b) -> Step a b
-- | The Iteratee cannot receive any more input, and has generated a
-- result. Included in this value is left-over input, which can be passed
-- to composed Iteratees.
Yield :: b -> Stream a -> Step a b
-- | The Iteratee encountered an error which prevents it from
-- proceeding further.
Error :: SomeException -> Step a b
-- | The primary data type for this library, which consumes input from a
-- Stream until it either generates a value or encounters an
-- error. Rather than requiring all input at once, an iteratee will
-- return Continue when it is capable of processing more data.
--
-- In general, iteratees begin in the Continue state. As each
-- chunk is passed to the continuation, the iteratee returns the next
-- step: Continue for more data, Yield when it's finished,
-- or Error to abort processing.
newtype Iteratee a m :: (* -> *) b :: * -> (* -> *) -> * -> *
Iteratee :: m (Step a m b) -> Iteratee a b
runIteratee :: Iteratee a b -> m (Step a m b)
-- | While Iteratees consume data, enumerators generate it. Since
-- Iteratee is an alias for m (Step a m
-- b), Enumerators can be considered step transformers of
-- type Step a m b -> m (Step a m b).
--
-- Enumerators typically read from an external source (parser,
-- handle, random generator, etc). They feed chunks into an
-- Iteratee until the source runs out of data (triggering
-- EOF) or the iteratee finishes processing (Yields a
-- value).
type Enumerator a m :: (* -> *) b = Step a m b -> Iteratee a m b
-- | In cases where an enumerator acts as both a source and sink, the
-- resulting type is named an Enumeratee. Enumeratees have two
-- input types, “outer a” (aOut) and “inner a” (aIn).
type Enumeratee ao ai m :: (* -> *) b = Step ai m b -> Iteratee ao m (Step ai m b)
-- |
-- returnI step = Iteratee (return step)
--
returnI :: Monad m => Step a m b -> Iteratee a m b
-- |
-- yield x extra = returnI (Yield x extra)
--
--
-- WARNING: due to the current encoding of iteratees in this library,
-- careless use of the yield primitive may violate the monad laws.
-- To prevent this, always make sure that an iteratee never yields extra
-- data unless it has received at least one input element.
--
-- More strictly, iteratees may not yield data that they did not receive
-- as input. Don't use yield to “inject” elements into the stream.
yield :: Monad m => b -> Stream a -> Iteratee a m b
-- |
-- continue k = returnI (Continue k)
--
continue :: Monad m => (Stream a -> Iteratee a m b) -> Iteratee a m b
-- |
-- throwError exc = returnI (Error (toException exc))
--
throwError :: (Monad m, Exception e) => e -> Iteratee a m b
-- | Runs the iteratee, and calls an exception handler if an Error
-- is returned. By handling errors within the enumerator library, and
-- requiring all errors to be represented by SomeException,
-- libraries with varying error types can be easily composed.
--
-- Since: 0.1.1
catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m b
-- | Deprecated in 0.4.5: use continue instead
liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b
-- | Equivalent to '(>>=)' for m (Step a m b); allows
-- Iteratees with different input types to be composed.
(>>==) :: Monad m => Iteratee a m b -> (Step a m b -> Iteratee a' m b') -> Iteratee a' m b'
-- |
-- '(==<<)' = flip '(>>==)'
--
(==<<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'
-- |
-- '($$)' = '(==<<)'
--
--
-- This might be easier to read when passing a chain of iteratees to an
-- enumerator.
--
-- Since: 0.1.1
($$) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'
-- |
-- '(>==>)' e1 e2 s = e1 s >>== e2
--
--
-- Since: 0.1.1
(>==>) :: Monad m => Enumerator a m b -> (Step a m b -> Iteratee a' m b') -> Step a m b -> Iteratee a' m b'
-- |
-- '(<==<)' = flip '(>==>)'
--
--
-- Since: 0.1.1
(<==<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Enumerator a m b -> Step a m b -> Iteratee a' m b'
-- | Run an iteratee until it finishes, and return either the final value
-- (if it succeeded) or the error (if it failed).
run :: Monad m => Iteratee a m b -> m (Either SomeException b)
-- | Like run, except errors are converted to exceptions and thrown.
-- Primarily useful for small scripts or other simple cases.
--
-- Since: 0.4.1
run_ :: Monad m => Iteratee a m b -> m b
-- |
-- consume = takeWhile (const True)
--
--
-- Since: 0.4.5
consume :: Monad m => Iteratee a m [a]
-- | Check whether a stream has reached EOF. Most clients should use
-- Data.Enumerator.List.head instead.
isEOF :: Monad m => Iteratee a m Bool
-- | Lift an Iteratee onto a monad transformer, re-wrapping the
-- Iteratee’s inner monadic values.
--
-- Since: 0.1.1
liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b
-- | Deprecated in 0.4.5: use Data.Enumerator.List.fold instead
--
-- Since: 0.1.1
liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
-- | Deprecated in 0.4.5: use Data.Enumerator.List.fold instead
--
-- Since: 0.1.1
liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
-- | Deprecated in 0.4.5: use Data.Enumerator.List.foldM instead
--
-- Since: 0.1.1
liftFoldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
-- | Print chunks as they're received from the enumerator, optionally
-- printing empty chunks.
printChunks :: (MonadIO m, Show a) => Bool -> Iteratee a m ()
-- | Get the next element from the stream, or Nothing if the stream
-- has ended.
--
-- Since: 0.4.5
head :: Monad m => Iteratee a m (Maybe a)
-- | Peek at the next element in the stream, or Nothing if the
-- stream has ended.
peek :: Monad m => Iteratee a m (Maybe a)
-- | Sends EOF to its iteratee. Most clients should use run
-- or run_ instead.
enumEOF :: Monad m => Enumerator a m b
-- | enumList n xs enumerates xs as a stream,
-- passing n inputs per chunk.
--
-- Primarily useful for testing and debugging.
enumList :: Monad m => Integer -> [a] -> Enumerator a m b
-- | Compose a list of Enumerators using '(>>==)'
concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b
-- |
-- checkDone = checkDoneEx (Chunks [])
--
--
-- Use this for enumeratees which do not have an input buffer.
checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b
-- | map f applies f to each input element and feeds
-- the resulting outputs to the inner iteratee.
--
-- Since: 0.4.8
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
-- | Feeds outer input elements into the provided iteratee until it yields
-- an inner input, passes that to the inner iteratee, and then loops.
sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b
-- | joinI is used to “flatten” Enumeratees into an
-- Iteratee.
joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b
instance Typeable ShortWriteException
instance Typeable RateTooSlowException
instance Typeable TooManyBytesReadException
instance Typeable InvalidRangeException
instance Exception InvalidRangeException
instance Show InvalidRangeException
instance Exception TooManyBytesReadException
instance Exception RateTooSlowException
instance Exception ShortWriteException
instance Show TooManyBytesReadException
instance Show RateTooSlowException
instance Show ShortWriteException
instance (Functor m, MonadCatchIO m) => MonadCatchIO (Iteratee s m)
-- | An internal Snap module for debugging iteratees.
--
-- N.B. this is an internal interface, please don't write user
-- code that depends on it.
module Snap.Internal.Iteratee.Debug
debugIteratee :: Iteratee ByteString IO ()
iterateeDebugWrapper :: (Show a, MonadIO m) => String -> Iteratee a m b -> Iteratee a m b
iterateeDebugWrapperWith :: MonadIO m => (s -> String) -> String -> Iteratee s m a -> Iteratee s m a
showBuilder :: Builder -> String
-- | Data.CIByteString is a module containing CIByteString, a
-- wrapper for ByteString which provides case-insensitive
-- (ASCII-wise) Ord and Eq instances.
--
-- CIByteString also has an IsString instance, so if you
-- use the "OverloadedStrings" LANGUAGE pragma you can write
-- case-insensitive string literals, e.g.:
--
--
-- > let a = "Foo" in
-- putStrLn $ (show $ unCI a) ++ "==\"FoO\" is " ++
-- show (a == "FoO")
-- "Foo"=="FoO" is True
--
module Data.CIByteString
-- | A case-insensitive newtype wrapper for ByteString
data CIByteString
toCI :: ByteString -> CIByteString
unCI :: CIByteString -> ByteString
ciToLower :: CIByteString -> ByteString
instance IsString CIByteString
instance Ord CIByteString
instance Eq CIByteString
instance Show CIByteString
-- | An internal Snap module containing HTTP types.
--
-- N.B. this is an internal interface, please don't write user
-- code that depends on it. Most of these declarations (except for the
-- unsafe/encapsulation-breaking ones) are re-exported from
-- Snap.Types.
module Snap.Internal.Http.Types
set_c_locale :: IO ()
c_parse_http_time :: CString -> IO CTime
c_format_http_time :: CTime -> CString -> IO ()
c_format_log_time :: CTime -> CString -> IO ()
-- | A type alias for a case-insensitive key-value mapping.
type Headers = Map CIByteString [ByteString]
-- | A typeclass for datatypes which contain HTTP headers.
class HasHeaders a
updateHeaders :: HasHeaders a => (Headers -> Headers) -> a -> a
headers :: HasHeaders a => a -> Headers
-- | Adds a header key-value-pair to the HasHeaders datatype. If a
-- header with the same name already exists, the new value is appended to
-- the headers list.
addHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
-- | Sets a header key-value-pair in a HasHeaders datatype. If a
-- header with the same name already exists, it is overwritten with the
-- new value.
setHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
-- | Gets all of the values for a given header.
getHeaders :: HasHeaders a => CIByteString -> a -> Maybe [ByteString]
-- | Gets a header value out of a HasHeaders datatype. If many
-- headers came in with the same name, they will be catenated together.
getHeader :: HasHeaders a => CIByteString -> a -> Maybe ByteString
-- | Clears a header value from a HasHeaders datatype.
deleteHeader :: HasHeaders a => CIByteString -> a -> a
-- | Enumerates the HTTP method values (see
-- http://tools.ietf.org/html/rfc2068.html#section-5.1.1).
data Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method
type HttpVersion = (Int, Int)
-- | A datatype representing an HTTP cookie.
data Cookie
Cookie :: !ByteString -> !ByteString -> !Maybe UTCTime -> !Maybe ByteString -> !Maybe ByteString -> Cookie
-- | The name of the cookie.
cookieName :: Cookie -> !ByteString
-- | The cookie's string value.
cookieValue :: Cookie -> !ByteString
-- | The cookie's expiration value, if it has one.
cookieExpires :: Cookie -> !Maybe UTCTime
-- | The cookie's "domain" value, if it has one.
cookieDomain :: Cookie -> !Maybe ByteString
-- | The cookie path.
cookiePath :: Cookie -> !Maybe ByteString
-- | A type alias for the HTTP parameters mapping. Each parameter key maps
-- to a list of ByteString values; if a parameter is specified multiple
-- times (e.g.: "GET /foo?param=bar1¶m=bar2"), looking
-- up "param" in the mapping will give you ["bar1",
-- "bar2"].
type Params = Map ByteString [ByteString]
-- | An existential wrapper for the 'Enumerator ByteString IO a' type
data SomeEnumerator
SomeEnumerator :: (forall a. Enumerator ByteString IO a) -> SomeEnumerator
-- | Contains all of the information about an incoming HTTP request.
data Request
Request :: !ByteString -> !Int -> !ByteString -> !Int -> !ByteString -> !Int -> !ByteString -> !Bool -> Headers -> IORef SomeEnumerator -> !Maybe Int -> !Method -> !HttpVersion -> [Cookie] -> !ByteString -> !ByteString -> !ByteString -> !ByteString -> !ByteString -> Params -> Request
-- | The server name of the request, as it came in from the request's
-- Host: header.
rqServerName :: Request -> !ByteString
-- | Returns the port number the HTTP server is listening on.
rqServerPort :: Request -> !Int
-- | The remote IP address.
rqRemoteAddr :: Request -> !ByteString
-- | The remote TCP port number.
rqRemotePort :: Request -> !Int
-- | The local IP address for this request.
rqLocalAddr :: Request -> !ByteString
-- | Returns the port number the HTTP server is listening on.
rqLocalPort :: Request -> !Int
-- | Returns the HTTP server's idea of its local hostname.
rqLocalHostname :: Request -> !ByteString
-- | Returns True if this is an HTTPS session.
rqIsSecure :: Request -> !Bool
rqHeaders :: Request -> Headers
rqBody :: Request -> IORef SomeEnumerator
-- | Returns the Content-Length of the HTTP request body.
rqContentLength :: Request -> !Maybe Int
-- | Returns the HTTP request method.
rqMethod :: Request -> !Method
-- | Returns the HTTP version used by the client.
rqVersion :: Request -> !HttpVersion
-- | Returns a list of the cookies that came in from the HTTP request
-- headers.
rqCookies :: Request -> [Cookie]
-- | We'll be doing web components (or "snaplets") for version 0.2. The
-- "snaplet path" refers to the place on the URL where your containing
-- snaplet is hung. The value of rqSnapletPath is either
-- "" (at the top-level context) or is a path beginning with a
-- slash, but not ending with one.
--
-- An identity is that:
--
--
-- rqURI r == 'S.concat' [ rqSnapletPath r
-- , rqContextPath r
-- , rqPathInfo r ]
--
--
-- note that until we introduce snaplets in v0.2, rqSnapletPath
-- will be ""
rqSnapletPath :: Request -> !ByteString
-- | Handlers can (will be; --ed) be hung on a URI "entry
-- point"; this is called the "context path". If a handler is hung on the
-- context path "/foo/", and you request "/foo/bar",
-- the value of rqPathInfo will be "bar".
rqPathInfo :: Request -> !ByteString
-- | The "context path" of the request; catenating rqContextPath,
-- and rqPathInfo should get you back to the original
-- rqURI. The rqContextPath always begins and ends with a
-- slash ("/") character, and represents the path (relative to
-- your component/snaplet) you took to get to your handler.
rqContextPath :: Request -> !ByteString
-- | Returns the URI requested by the client.
rqURI :: Request -> !ByteString
-- | Returns the HTTP query string for this Request.
rqQueryString :: Request -> !ByteString
-- | Returns the Params mapping for this Request.
-- "Parameters" are automatically decoded from the query string and
-- POST body and entered into this mapping.
rqParams :: Request -> Params
data ResponseBody
-- | output body is a Builder enumerator
Enum :: (forall a. Enumerator Builder IO a) -> ResponseBody
-- | output body is sendfile(), optional second argument is a byte range to
-- send
SendFile :: FilePath -> (Maybe (Int64, Int64)) -> ResponseBody
rspBodyMap :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> ResponseBody -> ResponseBody
rspBodyToEnum :: ResponseBody -> Enumerator Builder IO a
-- | Represents an HTTP response.
data Response
Response :: Headers -> Map ByteString Cookie -> !HttpVersion -> !Maybe Int64 -> ResponseBody -> !Int -> !ByteString -> !Bool -> Response
rspHeaders :: Response -> Headers
rspCookies :: Response -> Map ByteString Cookie
rspHttpVersion :: Response -> !HttpVersion
-- | We will need to inspect the content length no matter what, and looking
-- up "content-length" in the headers and parsing the number out of the
-- text will be too expensive.
rspContentLength :: Response -> !Maybe Int64
rspBody :: Response -> ResponseBody
-- | Returns the HTTP status code.
rspStatus :: Response -> !Int
-- | Returns the HTTP status explanation string.
rspStatusReason :: Response -> !ByteString
-- | If true, we are transforming the request body with
-- transformRequestBody
rspTransformingRqBody :: Response -> !Bool
-- | Looks up the value(s) for the given named parameter. Parameters
-- initially come from the request's query string and any decoded POST
-- body (if the request's Content-Type is
-- application/x-www-form-urlencoded). Parameter values can be
-- modified within handlers using rqModifyParams.
rqParam :: ByteString -> Request -> Maybe [ByteString]
-- | Modifies the parameters mapping (which is a Map ByteString
-- ByteString) in a Request using the given function.
rqModifyParams :: (Params -> Params) -> Request -> Request
-- | Writes a key-value pair to the parameters mapping within the given
-- request.
rqSetParam :: ByteString -> [ByteString] -> Request -> Request
-- | An empty Response.
emptyResponse :: Response
-- | Sets an HTTP response body to the given Enumerator value.
setResponseBody :: (forall a. Enumerator Builder IO a) -> Response -> Response
-- | Sets the HTTP response status. Note: normally you would use
-- setResponseCode unless you needed a custom response
-- explanation.
setResponseStatus :: Int -> ByteString -> Response -> Response
-- | Sets the HTTP response code.
setResponseCode :: Int -> Response -> Response
-- | Modifies a response body.
modifyResponseBody :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> Response -> Response
-- | Sets the Content-Type in the Response headers.
setContentType :: ByteString -> Response -> Response
-- | addCookie has been deprecated and will be removed in 0.5. Please use
-- addResponseCookie instead.
addCookie :: Cookie -> Response -> Response
-- | Adds an HTTP Cookie to Response headers.
addResponseCookie :: Cookie -> Response -> Response
-- | Gets an HTTP Cookie with the given name from Response
-- headers.
getResponseCookie :: ByteString -> Response -> Maybe Cookie
-- | Returns a list of Cookies present in Response
getResponseCookies :: Response -> [Cookie]
-- | Deletes an HTTP Cookie from the Response headers.
deleteResponseCookie :: ByteString -> Response -> Response
-- | Modifies an HTTP Cookie with given name in Response
-- headers. Nothing will happen if a matching Cookie can not be
-- found in Response.
modifyResponseCookie :: ByteString -> (Cookie -> Cookie) -> Response -> Response
-- | A note here: if you want to set the Content-Length for the
-- response, Snap forces you to do it with this function rather than by
-- setting it in the headers; the Content-Length in the headers
-- will be ignored.
--
-- The reason for this is that Snap needs to look up the value of
-- Content-Length for each request, and looking the string value
-- up in the headers and parsing the number out of the text will be too
-- expensive.
--
-- If you don't set a content length in your response, HTTP keep-alive
-- will be disabled for HTTP/1.0 clients, forcing a Connection:
-- close. For HTTP/1.1 clients, Snap will switch to the chunked
-- transfer encoding if Content-Length is not specified.
setContentLength :: Int64 -> Response -> Response
-- | Removes any Content-Length set in the Response.
clearContentLength :: Response -> Response
-- | Converts a CTime into an HTTP timestamp.
formatHttpTime :: CTime -> IO ByteString
-- | Converts a CTime into common log entry format.
formatLogTime :: CTime -> IO ByteString
-- | Converts an HTTP timestamp into a CTime.
parseHttpTime :: ByteString -> IO CTime
parseToCompletion :: Parser a -> ByteString -> Maybe a
pUrlEscaped :: Parser ByteString
-- | Decodes an URL-escaped string (see
-- http://tools.ietf.org/html/rfc2396.html#section-2.4)
urlDecode :: ByteString -> Maybe ByteString
-- | URL-escapes a string (see
-- http://tools.ietf.org/html/rfc2396.html#section-2.4)
urlEncode :: ByteString -> ByteString
hexd :: Word8 -> Builder
finish :: Result a -> Result a
fromStr :: String -> ByteString
toStr :: ByteString -> String
statusReasonMap :: IntMap ByteString
instance Show Method
instance Read Method
instance Ord Method
instance Eq Method
instance Eq Cookie
instance Show Cookie
instance HasHeaders Response
instance Show Response
instance HasHeaders Headers
instance HasHeaders Request
instance Show Request
-- | This module contains the core type definitions, class instances, and
-- functions for HTTP as well as the Snap monad, which is used for
-- web handlers.
module Snap.Types
data Snap a
-- | Runs a Snap monad action in the 'Iteratee IO' monad.
runSnap :: Snap a -> (ByteString -> IO ()) -> (Int -> IO ()) -> Request -> Iteratee ByteString IO (Request, Response)
-- | Snap is the Monad that user web handlers run in.
-- Snap gives you:
--
--
-- - stateful access to fetch or modify an HTTP Request
-- - stateful access to fetch or modify an HTTP Response
-- - failure / Alternative / MonadPlus semantics: a
-- Snap handler can choose not to handle a given request, using
-- empty or its synonym pass, and you can try alternative
-- handlers with the <|> operator:
--
--
--
-- a :: Snap String
-- a = pass
--
-- b :: Snap String
-- b = return "foo"
--
-- c :: Snap String
-- c = a <|> b -- try running a, if it fails then try b
--
--
--
-- - convenience functions (writeBS, writeLBS,
-- writeText, writeLazyText, addToOutput) for
-- writing output to the Response:
--
--
--
-- a :: (forall a . Enumerator a) -> Snap ()
-- a someEnumerator = do
-- writeBS "I'm a strict bytestring"
-- writeLBS "I'm a lazy bytestring"
-- addToOutput someEnumerator
--
--
--
-- - early termination: if you call finishWith:
--
--
--
-- a :: Snap ()
-- a = do
-- modifyResponse $ setResponseStatus 500 "Internal Server Error"
-- writeBS "500 error"
-- r <- getResponse
-- finishWith r
--
--
-- then any subsequent processing will be skipped and supplied
-- Response value will be returned from runSnap as-is.
--
--
-- - access to the IO monad through a MonadIO
-- instance:
--
--
--
-- a :: Snap ()
-- a = liftIO fireTheMissiles
--
--
--
-- - the ability to set a timeout which will kill the handler thread
-- after N seconds of inactivity:
--
--
--
-- a :: Snap ()
-- a = setTimeout 30
--
--
-- You may notice that most of the type signatures in this module contain
-- a (MonadSnap m) => ... typeclass constraint.
-- MonadSnap is a typeclass which, in essence, says "you can get
-- back to the Snap monad from here". Using MonadSnap you
-- can extend the Snap monad with additional functionality and
-- still have access to most of the Snap functions without writing
-- lift everywhere. Instances are already provided for most of the
-- common monad transformers (ReaderT, WriterT,
-- StateT, etc.).
--
-- MonadSnap is a type class, analogous to MonadIO for
-- IO, that makes it easy to wrap Snap inside monad
-- transformers.
class (Monad m, MonadIO m, MonadCatchIO m, MonadPlus m, Functor m, Applicative m, Alternative m) => MonadSnap m
liftSnap :: MonadSnap m => Snap a -> m a
-- | This exception is thrown if the handler you supply to runSnap
-- fails.
data NoHandlerException
NoHandlerException :: NoHandlerException
-- | This function brackets a Snap action in resource acquisition and
-- release. This is provided because MonadCatchIO's bracket
-- function doesn't work properly in the case of a short-circuit return
-- from the action being bracketed.
--
-- In order to prevent confusion regarding the effects of the aquisition
-- and release actions on the Snap state, this function doesn't accept
-- Snap actions for the acquire or release actions.
--
-- This function will run the release action in all cases where the
-- acquire action succeeded. This includes the following behaviors from
-- the bracketed Snap action.
--
--
-- - Normal completion
-- - Short-circuit completion, either from calling fail or
-- finishWith
-- - An exception being thrown.
--
bracketSnap :: IO a -> (a -> IO b) -> (a -> Snap c) -> Snap c
-- | Short-circuits a Snap monad action early, storing the given
-- Response value in its state.
finishWith :: MonadSnap m => Response -> m a
-- | Capture the flow of control in case a handler calls finishWith.
--
-- WARNING: in the event of a call to transformRequestBody
-- it is possible to violate HTTP protocol safety when using this
-- function. If you call catchFinishWith it is suggested that you
-- do not modify the body of the Response which was passed to the
-- finishWith call.
catchFinishWith :: Snap a -> Snap (Either Response a)
-- | Fails out of a Snap monad action. This is used to indicate that
-- you choose not to handle the given request within the given handler.
pass :: MonadSnap m => m a
-- | Runs a Snap monad action only if the request's HTTP method
-- matches the given method.
method :: MonadSnap m => Method -> m a -> m a
-- | Runs a Snap monad action only if the request's HTTP method
-- matches one of the given methods.
methods :: MonadSnap m => [Method] -> m a -> m a
-- | Runs a Snap monad action only for requests where
-- rqPathInfo is exactly equal to the given string. If the path
-- matches, locally sets rqContextPath to the old value of
-- rqPathInfo, sets rqPathInfo="", and runs the given
-- handler.
path :: MonadSnap m => ByteString -> m a -> m a
-- | Runs a Snap monad action only when the rqPathInfo of the
-- request starts with the given path. For example,
--
--
-- dir "foo" handler
--
--
-- Will fail if rqPathInfo is not "/foo" or
-- "/foo/...", and will add "foo/" to the handler's
-- local rqContextPath.
dir :: MonadSnap m => ByteString -> m a -> m a
-- | Runs a Snap monad action only when rqPathInfo is empty.
ifTop :: MonadSnap m => m a -> m a
-- | A web handler which, given a mapping from URL entry points to web
-- handlers, efficiently routes requests to the correct handler.
--
-- The URL entry points are given as relative paths, for example:
--
--
-- route [ ("foo/bar/quux", fooBarQuux) ]
--
--
-- If the URI of the incoming request is
--
--
-- /foo/bar/quux
--
--
-- or
--
--
-- /foo/bar/quux/...anything...
--
--
-- then the request will be routed to "fooBarQuux", with
-- rqContextPath set to "/foo/bar/quux/" and
-- rqPathInfo set to "...anything...".
--
-- A path component within an URL entry point beginning with a colon
-- (":") is treated as a variable capture; the
-- corresponding path component within the request URI will be entered
-- into the rqParams parameters mapping with the given name. For
-- instance, if the routes were:
--
--
-- route [ ("foo/:bar/baz", fooBazHandler) ]
--
--
-- Then a request for "/foo/saskatchewan/baz" would be routed to
-- fooBazHandler with a mapping for:
--
--
-- "bar" => "saskatchewan"
--
--
-- in its parameters table.
--
-- Longer paths are matched first, and specific routes are matched before
-- captures. That is, if given routes:
--
--
-- [ ("a", h1), ("a/b", h2), ("a/:x", h3) ]
--
--
-- a request for "/a/b" will go to h2, "/a/s"
-- for any s will go to h3, and "/a" will go to
-- h1.
--
-- The following example matches "/article" to an article index,
-- "/login" to a login, and "/article/..." to an
-- article renderer.
--
--
-- route [ ("article", renderIndex)
-- , ("article/:id", renderArticle)
-- , ("login", method POST doLogin) ]
--
route :: MonadSnap m => [(ByteString, m a)] -> m a
-- | The routeLocal function is the same as route', except it
-- doesn't change the request's context path. This is useful if you want
-- to route to a particular handler but you want that handler to receive
-- the rqPathInfo as it is.
routeLocal :: MonadSnap m => [(ByteString, m a)] -> m a
-- | Grabs the Request object out of the Snap monad.
getRequest :: MonadSnap m => m Request
-- | Grabs the Response object out of the Snap monad.
getResponse :: MonadSnap m => m Response
-- | Puts a new Request object into the Snap monad.
putRequest :: MonadSnap m => Request -> m ()
-- | Puts a new Response object into the Snap monad.
putResponse :: MonadSnap m => Response -> m ()
-- | Modifies the Request object stored in a Snap monad.
modifyRequest :: MonadSnap m => (Request -> Request) -> m ()
-- | Modifes the Response object stored in a Snap monad.
modifyResponse :: MonadSnap m => (Response -> Response) -> m ()
-- | Runs a Snap action with a locally-modified Request state
-- object. The Request object in the Snap monad state after the
-- call to localRequest will be unchanged.
localRequest :: MonadSnap m => (Request -> Request) -> m a -> m a
-- | Fetches the Request from state and hands it to the given
-- action.
withRequest :: MonadSnap m => (Request -> m a) -> m a
-- | Fetches the Response from state and hands it to the given
-- action.
withResponse :: MonadSnap m => (Response -> m a) -> m a
-- | Log an error message in the Snap monad
logError :: MonadSnap m => ByteString -> m ()
-- | Sends the request body through an iteratee (data consumer) and returns
-- the result.
runRequestBody :: MonadSnap m => Iteratee ByteString IO a -> m a
-- | Returns the request body as a bytestring.
getRequestBody :: MonadSnap m => m ByteString
-- | Normally Snap is careful to ensure that the request body is fully
-- consumed after your web handler runs, but before the Response
-- enumerator is streamed out the socket. If you want to transform the
-- request body into some output in O(1) space, you should use this
-- function.
--
-- Note that upon calling this function, response processing finishes
-- early as if you called finishWith. Make sure you set any
-- content types, headers, cookies, etc. before you call this function.
transformRequestBody :: (forall a. Enumerator Builder IO a) -> Snap ()
-- | Contains all of the information about an incoming HTTP request.
data Request
-- | Represents an HTTP response.
data Response
-- | A type alias for a case-insensitive key-value mapping.
type Headers = Map CIByteString [ByteString]
-- | A typeclass for datatypes which contain HTTP headers.
class HasHeaders a
updateHeaders :: HasHeaders a => (Headers -> Headers) -> a -> a
headers :: HasHeaders a => a -> Headers
-- | A type alias for the HTTP parameters mapping. Each parameter key maps
-- to a list of ByteString values; if a parameter is specified multiple
-- times (e.g.: "GET /foo?param=bar1¶m=bar2"), looking
-- up "param" in the mapping will give you ["bar1",
-- "bar2"].
type Params = Map ByteString [ByteString]
-- | Enumerates the HTTP method values (see
-- http://tools.ietf.org/html/rfc2068.html#section-5.1.1).
data Method
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method
-- | A datatype representing an HTTP cookie.
data Cookie
Cookie :: !ByteString -> !ByteString -> !Maybe UTCTime -> !Maybe ByteString -> !Maybe ByteString -> Cookie
-- | The name of the cookie.
cookieName :: Cookie -> !ByteString
-- | The cookie's string value.
cookieValue :: Cookie -> !ByteString
-- | The cookie's expiration value, if it has one.
cookieExpires :: Cookie -> !Maybe UTCTime
-- | The cookie's "domain" value, if it has one.
cookieDomain :: Cookie -> !Maybe ByteString
-- | The cookie path.
cookiePath :: Cookie -> !Maybe ByteString
type HttpVersion = (Int, Int)
-- | Adds a header key-value-pair to the HasHeaders datatype. If a
-- header with the same name already exists, the new value is appended to
-- the headers list.
addHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
-- | Sets a header key-value-pair in a HasHeaders datatype. If a
-- header with the same name already exists, it is overwritten with the
-- new value.
setHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
-- | Gets a header value out of a HasHeaders datatype. If many
-- headers came in with the same name, they will be catenated together.
getHeader :: HasHeaders a => CIByteString -> a -> Maybe ByteString
-- | Clears a header value from a HasHeaders datatype.
deleteHeader :: HasHeaders a => CIByteString -> a -> a
-- | Modifies the Request in the state to set the
-- rqRemoteAddr field to the value in the X-Forwarded-For header.
-- If the header is not present, this action has no effect.
--
-- This action should be used only when working behind a reverse http
-- proxy that sets the X-Forwarded-For header. This is the only way to
-- ensure the value in the X-Forwarded-For header can be trusted.
--
-- This is provided as a filter so actions that require the remote
-- address can get it in a uniform manner. It has specifically limited
-- functionality to ensure that its transformation can be trusted, when
-- used correctly.
ipHeaderFilter :: MonadSnap m => m ()
-- | Modifies the Request in the state to set the
-- rqRemoteAddr field to the value from the header specified. If
-- the header specified is not present, this action has no effect.
--
-- This action should be used only when working behind a reverse http
-- proxy that sets the header being looked at. This is the only way to
-- ensure the value in the header can be trusted.
--
-- This is provided as a filter so actions that require the remote
-- address can get it in a uniform manner. It has specifically limited
-- functionality to ensure that its transformation can be trusted, when
-- used correctly.
ipHeaderFilter' :: MonadSnap m => CIByteString -> m ()
-- | The server name of the request, as it came in from the request's
-- Host: header.
rqServerName :: Request -> ByteString
-- | Returns the port number the HTTP server is listening on.
rqServerPort :: Request -> Int
-- | The remote IP address.
rqRemoteAddr :: Request -> ByteString
-- | The remote TCP port number.
rqRemotePort :: Request -> Int
-- | The local IP address for this request.
rqLocalAddr :: Request -> ByteString
-- | Returns the HTTP server's idea of its local hostname.
rqLocalHostname :: Request -> ByteString
-- | Returns True if this is an HTTPS session.
rqIsSecure :: Request -> Bool
-- | Returns the Content-Length of the HTTP request body.
rqContentLength :: Request -> (Maybe Int)
-- | Returns the HTTP request method.
rqMethod :: Request -> Method
-- | Returns the HTTP version used by the client.
rqVersion :: Request -> HttpVersion
-- | Returns a list of the cookies that came in from the HTTP request
-- headers.
rqCookies :: Request -> [Cookie]
-- | Handlers can (will be; --ed) be hung on a URI "entry
-- point"; this is called the "context path". If a handler is hung on the
-- context path "/foo/", and you request "/foo/bar",
-- the value of rqPathInfo will be "bar".
rqPathInfo :: Request -> ByteString
-- | The "context path" of the request; catenating rqContextPath,
-- and rqPathInfo should get you back to the original
-- rqURI. The rqContextPath always begins and ends with a
-- slash ("/") character, and represents the path (relative to
-- your component/snaplet) you took to get to your handler.
rqContextPath :: Request -> ByteString
-- | Returns the URI requested by the client.
rqURI :: Request -> ByteString
-- | Returns the HTTP query string for this Request.
rqQueryString :: Request -> ByteString
-- | Returns the Params mapping for this Request.
-- "Parameters" are automatically decoded from the query string and
-- POST body and entered into this mapping.
rqParams :: Request -> Params
-- | Looks up the value(s) for the given named parameter. Parameters
-- initially come from the request's query string and any decoded POST
-- body (if the request's Content-Type is
-- application/x-www-form-urlencoded). Parameter values can be
-- modified within handlers using rqModifyParams.
rqParam :: ByteString -> Request -> Maybe [ByteString]
-- | See rqParam. Looks up a value for the given named parameter in
-- the Request. If more than one value was entered for the given
-- parameter name, getParam gloms the values together with:
--
--
-- intercalate " "
--
getParam :: MonadSnap m => ByteString -> m (Maybe ByteString)
-- | See rqParams. Convenience function to return Params from
-- the Request inside of a MonadSnap instance.
getParams :: MonadSnap m => m Params
-- | Modifies the parameters mapping (which is a Map ByteString
-- ByteString) in a Request using the given function.
rqModifyParams :: (Params -> Params) -> Request -> Request
-- | Writes a key-value pair to the parameters mapping within the given
-- request.
rqSetParam :: ByteString -> [ByteString] -> Request -> Request
-- | An empty Response.
emptyResponse :: Response
-- | Sets the HTTP response code.
setResponseCode :: Int -> Response -> Response
-- | Sets the HTTP response status. Note: normally you would use
-- setResponseCode unless you needed a custom response
-- explanation.
setResponseStatus :: Int -> ByteString -> Response -> Response
-- | Returns the HTTP status code.
rspStatus :: Response -> Int
-- | Returns the HTTP status explanation string.
rspStatusReason :: Response -> ByteString
-- | Sets the Content-Type in the Response headers.
setContentType :: ByteString -> Response -> Response
-- | addCookie has been deprecated and will be removed in 0.5. Please use
-- addResponseCookie instead.
addCookie :: Cookie -> Response -> Response
-- | Adds an HTTP Cookie to Response headers.
addResponseCookie :: Cookie -> Response -> Response
-- | Gets an HTTP Cookie with the given name from Response
-- headers.
getResponseCookie :: ByteString -> Response -> Maybe Cookie
-- | Returns a list of Cookies present in Response
getResponseCookies :: Response -> [Cookie]
-- | Deletes an HTTP Cookie from the Response headers.
deleteResponseCookie :: ByteString -> Response -> Response
-- | Modifies an HTTP Cookie with given name in Response
-- headers. Nothing will happen if a matching Cookie can not be
-- found in Response.
modifyResponseCookie :: ByteString -> (Cookie -> Cookie) -> Response -> Response
-- | Gets the HTTP Cookie with the specified name.
getCookie :: MonadSnap m => ByteString -> m (Maybe Cookie)
-- | A note here: if you want to set the Content-Length for the
-- response, Snap forces you to do it with this function rather than by
-- setting it in the headers; the Content-Length in the headers
-- will be ignored.
--
-- The reason for this is that Snap needs to look up the value of
-- Content-Length for each request, and looking the string value
-- up in the headers and parsing the number out of the text will be too
-- expensive.
--
-- If you don't set a content length in your response, HTTP keep-alive
-- will be disabled for HTTP/1.0 clients, forcing a Connection:
-- close. For HTTP/1.1 clients, Snap will switch to the chunked
-- transfer encoding if Content-Length is not specified.
setContentLength :: Int64 -> Response -> Response
-- | Removes any Content-Length set in the Response.
clearContentLength :: Response -> Response
-- | Performs a redirect by setting the Location header to the
-- given target URL/path and the status code to 302 in the
-- Response object stored in a Snap monad. Note that the
-- target URL is not validated in any way. Consider using 'redirect\''
-- instead, which allows you to choose the correct status code.
redirect :: MonadSnap m => ByteString -> m a
-- | Performs a redirect by setting the Location header to the
-- given target URL/path and the status code (should be one of 301, 302,
-- 303 or 307) in the Response object stored in a Snap
-- monad. Note that the target URL is not validated in any way.
redirect' :: MonadSnap m => ByteString -> Int -> m a
-- | Sets an HTTP response body to the given Enumerator value.
setResponseBody :: (forall a. Enumerator Builder IO a) -> Response -> Response
-- | Modifies a response body.
modifyResponseBody :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> Response -> Response
-- | Adds the output from the given enumerator to the Response
-- stored in the Snap monad state.
addToOutput :: MonadSnap m => (forall a. Enumerator Builder IO a) -> m ()
-- | Adds the given Builder to the body of the Response
-- stored in the | Snap monad state.
writeBuilder :: MonadSnap m => Builder -> m ()
-- | Adds the given strict ByteString to the body of the
-- Response stored in the Snap monad state.
--
-- Warning: This function is intentionally non-strict. If any pure
-- exceptions are raised by the expression creating the
-- ByteString, the exception won't actually be raised within the
-- Snap handler.
writeBS :: MonadSnap m => ByteString -> m ()
-- | Adds the given lazy Text to the body of the Response
-- stored in the Snap monad state.
--
-- Warning: This function is intentionally non-strict. If any pure
-- exceptions are raised by the expression creating the
-- ByteString, the exception won't actually be raised within the
-- Snap handler.
writeLazyText :: MonadSnap m => Text -> m ()
-- | Adds the given strict Text to the body of the Response
-- stored in the Snap monad state.
--
-- Warning: This function is intentionally non-strict. If any pure
-- exceptions are raised by the expression creating the
-- ByteString, the exception won't actually be raised within the
-- Snap handler.
writeText :: MonadSnap m => Text -> m ()
-- | Adds the given lazy ByteString to the body of the
-- Response stored in the Snap monad state.
--
-- Warning: This function is intentionally non-strict. If any pure
-- exceptions are raised by the expression creating the
-- ByteString, the exception won't actually be raised within the
-- Snap handler.
writeLBS :: MonadSnap m => ByteString -> m ()
-- | Sets the output to be the contents of the specified file.
--
-- Calling sendFile will overwrite any output queued to be sent in
-- the Response. If the response body is not modified after the
-- call to sendFile, Snap will use the efficient
-- sendfile() system call on platforms that support it.
--
-- If the response body is modified (using modifyResponseBody),
-- the file will be read using mmap().
sendFile :: MonadSnap m => FilePath -> m ()
-- | Sets the output to be the contents of the specified file, within the
-- given (start,end) range.
--
-- Calling sendFilePartial will overwrite any output queued to be
-- sent in the Response. If the response body is not modified
-- after the call to sendFilePartial, Snap will use the efficient
-- sendfile() system call on platforms that support it.
--
-- If the response body is modified (using modifyResponseBody),
-- the file will be read using mmap().
sendFilePartial :: MonadSnap m => FilePath -> (Int64, Int64) -> m ()
-- | Causes the handler thread to be killed n seconds from now.
setTimeout :: MonadSnap m => Int -> m ()
-- | Returns an IO action which you can use to reset the handling
-- thread's timeout value.
getTimeoutAction :: MonadSnap m => m (Int -> IO ())
-- | While Iteratees consume data, enumerators generate it. Since
-- Iteratee is an alias for m (Step a m
-- b), Enumerators can be considered step transformers of
-- type Step a m b -> m (Step a m b).
--
-- Enumerators typically read from an external source (parser,
-- handle, random generator, etc). They feed chunks into an
-- Iteratee until the source runs out of data (triggering
-- EOF) or the iteratee finishes processing (Yields a
-- value).
type Enumerator a m :: (* -> *) b = Step a m b -> Iteratee a m b
-- | An existential wrapper for the 'Enumerator ByteString IO a' type
data SomeEnumerator
SomeEnumerator :: (forall a. Enumerator ByteString IO a) -> SomeEnumerator
-- | Converts a CTime into an HTTP timestamp.
formatHttpTime :: CTime -> IO ByteString
-- | Converts an HTTP timestamp into a CTime.
parseHttpTime :: ByteString -> IO CTime
-- | URL-escapes a string (see
-- http://tools.ietf.org/html/rfc2396.html#section-2.4)
urlEncode :: ByteString -> ByteString
-- | Decodes an URL-escaped string (see
-- http://tools.ietf.org/html/rfc2396.html#section-2.4)
urlDecode :: ByteString -> Maybe ByteString
module Snap.Internal.Parsing
fullyParse :: ByteString -> Parser a -> Either String a
parseNum :: Parser Int64
-- | Parsers for different tokens in an HTTP request.
digit :: Parser Char
letter :: Parser Char
sp :: Parser Char
untilEOL :: Parser ByteString
crlf :: Parser ByteString
-- | Parser for zero or more spaces.
spaces :: Parser [Char]
pSpaces :: Parser ByteString
fieldChars :: Parser ByteString
fieldCharTable :: Vector Bool
-- | Parser for request headers.
pHeaders :: Parser [(ByteString, ByteString)]
pWord :: Parser ByteString
pQuotedString :: Parser ByteString
isRFCText :: Char -> Bool
matchAll :: [Char -> Bool] -> Char -> Bool
pAvPairs :: Parser [(ByteString, ByteString)]
pAvPair :: Parser (ByteString, ByteString)
pParameter :: Parser (ByteString, ByteString)
trim :: ByteString -> ByteString
pValueWithParameters :: Parser (ByteString, [(CIByteString, ByteString)])
pContentTypeWithParameters :: Parser (ByteString, [(CIByteString, ByteString)])
pToken :: Parser ByteString
isToken :: Char -> Bool
strictize :: ByteString -> ByteString
-- | Contains web handlers to serve files from a directory.
module Snap.Util.FileServe
-- | Gets a path from the Request using rqPathInfo and makes
-- sure it is safe to use for opening files. A path is safe if it is a
-- relative path and has no .. elements to escape the intended
-- directory structure.
getSafePath :: MonadSnap m => m FilePath
-- | A type alias for MIME type
type MimeMap = Map FilePath ByteString
-- | A type alias for dynamic handlers
type HandlerMap m = Map FilePath (FilePath -> m ())
-- | A collection of options for serving static files out of a directory.
data DirectoryConfig m
DirectoryConfig :: [FilePath] -> (FilePath -> m ()) -> HandlerMap m -> MimeMap -> (FilePath -> m ()) -> DirectoryConfig m
-- | Files to look for when a directory is requested (e.g., index.html)
indexFiles :: DirectoryConfig m -> [FilePath]
-- | Handler to generate a directory listing if there is no index.
indexGenerator :: DirectoryConfig m -> FilePath -> m ()
-- | Map of extensions to pass to dynamic file handlers. This could be
-- used, for example, to implement CGI dispatch, pretty printing of
-- source code, etc.
dynamicHandlers :: DirectoryConfig m -> HandlerMap m
-- | MIME type map to look up content types.
mimeTypes :: DirectoryConfig m -> MimeMap
-- | Handler that is called before a file is served. It will only be called
-- when a file is actually found, not for generated index pages.
preServeHook :: DirectoryConfig m -> FilePath -> m ()
-- | A very simple configuration for directory serving. This configuration
-- uses built-in MIME types from defaultMimeTypes, and has no
-- index files, index generator, dynamic file handlers, or
-- preServeHook.
simpleDirectoryConfig :: MonadSnap m => DirectoryConfig m
-- | A reasonable default configuration for directory serving. This
-- configuration uses built-in MIME types from defaultMimeTypes,
-- serves common index files index.html and index.htm,
-- but does not autogenerate directory indexes, nor have any dynamic file
-- handlers. The preServeHook will not do anything.
defaultDirectoryConfig :: MonadSnap m => DirectoryConfig m
-- | A more elaborate configuration for file serving. This configuration
-- uses built-in MIME types from defaultMimeTypes, serves common
-- index files index.html and index.htm, and
-- autogenerates directory indexes with a Snap-like feel. It still has no
-- dynamic file handlers, nor preServeHook, which should be added
-- as needed.
--
-- Files recognized as indexes include index.html,
-- index.htm, default.html, default.htm,
-- home.html
fancyDirectoryConfig :: MonadSnap m => DirectoryConfig m
-- | An automatic index generator, which is fairly small and does not rely
-- on any external files (which may not be there depending on external
-- request routing).
--
-- A MimeMap is passed in to display the types of files in the
-- directory listing based on their extension. Preferably, this is the
-- same as the map in the DirectoryConfig
--
-- The styles parameter allows you to apply styles to the directory
-- listing. The listing itself consists of a table, containing a header
-- row using th elements, and one row per file using td elements, so
-- styles for those pieces may be attached to the appropriate tags.
defaultIndexGenerator :: MonadSnap m => MimeMap -> ByteString -> FilePath -> m ()
-- | The default set of mime type mappings we use when serving files. Its
-- value:
--
--
-- Map.fromList [
-- ( ".asc" , "text/plain" ),
-- ( ".asf" , "video/x-ms-asf" ),
-- ( ".asx" , "video/x-ms-asf" ),
-- ( ".avi" , "video/x-msvideo" ),
-- ( ".bz2" , "application/x-bzip" ),
-- ( ".c" , "text/plain" ),
-- ( ".class" , "application/octet-stream" ),
-- ( ".conf" , "text/plain" ),
-- ( ".cpp" , "text/plain" ),
-- ( ".css" , "text/css" ),
-- ( ".cxx" , "text/plain" ),
-- ( ".dtd" , "text/xml" ),
-- ( ".dvi" , "application/x-dvi" ),
-- ( ".gif" , "image/gif" ),
-- ( ".gz" , "application/x-gzip" ),
-- ( ".hs" , "text/plain" ),
-- ( ".htm" , "text/html" ),
-- ( ".html" , "text/html" ),
-- ( ".jar" , "application/x-java-archive" ),
-- ( ".jpeg" , "image/jpeg" ),
-- ( ".jpg" , "image/jpeg" ),
-- ( ".js" , "text/javascript" ),
-- ( ".log" , "text/plain" ),
-- ( ".m3u" , "audio/x-mpegurl" ),
-- ( ".mov" , "video/quicktime" ),
-- ( ".mp3" , "audio/mpeg" ),
-- ( ".mpeg" , "video/mpeg" ),
-- ( ".mpg" , "video/mpeg" ),
-- ( ".ogg" , "application/ogg" ),
-- ( ".pac" , "application/x-ns-proxy-autoconfig" ),
-- ( ".pdf" , "application/pdf" ),
-- ( ".png" , "image/png" ),
-- ( ".ps" , "application/postscript" ),
-- ( ".qt" , "video/quicktime" ),
-- ( ".sig" , "application/pgp-signature" ),
-- ( ".spl" , "application/futuresplash" ),
-- ( ".swf" , "application/x-shockwave-flash" ),
-- ( ".tar" , "application/x-tar" ),
-- ( ".tar.bz2" , "application/x-bzip-compressed-tar" ),
-- ( ".tar.gz" , "application/x-tgz" ),
-- ( ".tbz" , "application/x-bzip-compressed-tar" ),
-- ( ".text" , "text/plain" ),
-- ( ".tgz" , "application/x-tgz" ),
-- ( ".torrent" , "application/x-bittorrent" ),
-- ( ".txt" , "text/plain" ),
-- ( ".wav" , "audio/x-wav" ),
-- ( ".wax" , "audio/x-ms-wax" ),
-- ( ".wma" , "audio/x-ms-wma" ),
-- ( ".wmv" , "video/x-ms-wmv" ),
-- ( ".xbm" , "image/x-xbitmap" ),
-- ( ".xml" , "text/xml" ),
-- ( ".xpm" , "image/x-xpixmap" ),
-- ( ".xwd" , "image/x-xwindowdump" ),
-- ( ".zip" , "application/zip" ) ]
--
defaultMimeTypes :: MimeMap
-- | Serves static files from a directory using the default configuration
-- as given in defaultDirectoryConfig.
serveDirectory :: MonadSnap m => FilePath -> m ()
-- | Serves static files from a directory. Configuration options are passed
-- in a DirectoryConfig that captures various choices about
-- desired behavior. The relative path given in rqPathInfo is
-- searched for a requested file, and the file is served with the
-- appropriate mime type if it is found. Absolute paths and ".."
-- are prohibited to prevent files from being served from outside the
-- sandbox.
serveDirectoryWith :: MonadSnap m => DirectoryConfig m -> FilePath -> m ()
-- | Serves a single file specified by a full or relative path. If the file
-- does not exist, throws an exception (not that it does not pass
-- to the next handler). The path restrictions on serveDirectory
-- don't apply to this function since the path is not being supplied by
-- the user.
serveFile :: MonadSnap m => FilePath -> m ()
-- | Same as serveFile, with control over the MIME mapping used.
serveFileAs :: MonadSnap m => ByteString -> FilePath -> m ()
-- | Serves files out of the given directory, using no index files and
-- default MIME types.
--
-- The function name is obsolete. You should use serveDirectory or
-- serveDirectoryWith instead, which do similar things but with
-- more options and clearer, more consistent names.
fileServe :: MonadSnap m => FilePath -> m ()
-- | Serves files out of the given directory, with a given MIME type
-- mapping.
--
-- The function name is obsolete. You should use
-- serveDirectoryWith instead, which offers more options and a
-- clearer, more consistent name.
fileServe' :: MonadSnap m => MimeMap -> FilePath -> m ()
-- | Serves a single file specified by a full or relative path. The path
-- restrictions on fileServe don't apply to this function since the path
-- is not being supplied by the user.
--
-- The function name is obsolete. You should use serveFile
-- instead, which does the same thing but with a clearer, more consistent
-- name.
fileServeSingle :: MonadSnap m => FilePath -> m ()
-- | Same as fileServeSingle, with control over the MIME mapping
-- used.
--
-- The function name is obsolete. You should use serveFileAs
-- instead, which does the same thing but with a clearer, more consistent
-- name.
fileServeSingle' :: MonadSnap m => ByteString -> FilePath -> m ()
instance Eq RangeReq
instance Show RangeReq
module Snap.Util.GZip
-- | Runs a Snap web handler with compression if available.
--
-- If the client has indicated support for gzip or
-- compress in its Accept-Encoding header, and the
-- Content-Type in the response is one of the following types:
--
--
--
-- Then the given handler's output stream will be compressed,
-- Content-Encoding will be set in the output headers, and the
-- Content-Length will be cleared if it was set. (We can't
-- process the stream in O(1) space if the length is known beforehand.)
--
-- The wrapped handler will be run to completion, and then the
-- Response that's contained within the Snap monad state
-- will be passed to finishWith to prevent further processing.
withCompression :: MonadSnap m => m a -> m ()
-- | The same as withCompression, with control over which MIME types
-- to compress.
withCompression' :: MonadSnap m => Set ByteString -> m a -> m ()
instance Typeable BadAcceptEncodingException
instance Exception BadAcceptEncodingException
instance Show BadAcceptEncodingException
-- | This module contains primitives and helper functions for handling
-- requests with Content-type: multipart/form-data, i.e. HTML
-- forms and file uploads.
--
-- Typically most users will want to use handleFileUploads, which
-- writes uploaded files to a temporary directory before sending them on
-- to a handler specified by the user.
--
-- Users who wish to handle their file uploads differently can use the
-- lower-level streaming Iteratee interface called
-- handleMultipart. That function takes uploaded files and streams
-- them to an Iteratee consumer of the user's choosing.
--
-- Using these functions requires making "policy" decisions which Snap
-- can't really make for users, such as "what's the largest PDF file a
-- user is allowed to upload?" and "should we read form inputs into the
-- parameters mapping?". Policy is specified on a "global" basis (using
-- UploadPolicy), and on a per-file basis (using
-- PartUploadPolicy, which allows you to reject or limit the size
-- of certain uploaded Content-types).
module Snap.Util.FileUploads
-- | Reads uploaded files into a temporary directory and calls a user
-- handler to process them.
--
-- Given a temporary directory, global and file-specific upload policies,
-- and a user handler, this function consumes a request body uploaded
-- with Content-type: multipart/form-data. Each file is read
-- into the temporary directory, and then a list of the uploaded files is
-- passed to the user handler. After the user handler runs (but before
-- the Response body Enumerator is streamed to the client),
-- the files are deleted from disk; so if you want to retain or use the
-- uploaded files in the generated response, you would need to move or
-- otherwise process them.
--
-- The argument passed to the user handler is a list of:
--
--
-- (PartInfo, Either PolicyViolationException FilePath)
--
--
-- The first half of this tuple is a PartInfo, which contains the
-- information the client browser sent about the given upload part (like
-- filename, content-type, etc). The second half of this tuple is an
-- Either stipulating that either:
--
--
-- - the file was rejected on a policy basis because of the provided
-- PartUploadPolicy handler
-- - the file was accepted and exists at the given path.
--
--
-- If the request's Content-type was not
-- "multipart/formdata", this function skips processing using
-- pass.
--
-- If the client's upload rate passes below the configured minimum (see
-- setMinimumUploadRate and setMinimumUploadSeconds), this
-- function throws a RateTooSlowException. This setting is there
-- to protect the server against slowloris-style denial of service
-- attacks.
--
-- If the given UploadPolicy stipulates that you wish form inputs
-- to be placed in the rqParams parameter map (using
-- setProcessFormInputs), and a form input exceeds the maximum
-- allowable size, this function will throw a
-- PolicyViolationException.
--
-- If an uploaded part contains MIME headers longer than a fixed internal
-- threshold (currently 32KB), this function will throw a
-- BadPartException.
handleFileUploads :: MonadSnap m => FilePath -> UploadPolicy -> (PartInfo -> PartUploadPolicy) -> ([(PartInfo, Either PolicyViolationException FilePath)] -> m a) -> m a
-- | Given an upload policy and a function to consume uploaded "parts",
-- consume a request body uploaded with Content-type:
-- multipart/form-data. Normally most users will want to use
-- handleFileUploads (which writes uploaded files to a temporary
-- directory and passes their names to a given handler) rather than this
-- function; the lower-level handleMultipart function should be
-- used if you want to stream uploaded files to your own iteratee
-- function.
--
-- If the request's Content-type was not
-- "multipart/formdata", this function skips processing using
-- pass.
--
-- If the client's upload rate passes below the configured minimum (see
-- setMinimumUploadRate and setMinimumUploadSeconds), this
-- function throws a RateTooSlowException. This setting is there
-- to protect the server against slowloris-style denial of service
-- attacks.
--
-- If the given UploadPolicy stipulates that you wish form inputs
-- to be placed in the rqParams parameter map (using
-- setProcessFormInputs), and a form input exceeds the maximum
-- allowable size, this function will throw a
-- PolicyViolationException.
--
-- If an uploaded part contains MIME headers longer than a fixed internal
-- threshold (currently 32KB), this function will throw a
-- BadPartException.
handleMultipart :: MonadSnap m => UploadPolicy -> (PartInfo -> Iteratee ByteString IO a) -> m [a]
-- | PartInfo contains information about a "part" in a request
-- uploaded with Content-type: multipart/form-data.
data PartInfo
PartInfo :: !ByteString -> !Maybe ByteString -> !ByteString -> PartInfo
partFieldName :: PartInfo -> !ByteString
partFileName :: PartInfo -> !Maybe ByteString
partContentType :: PartInfo -> !ByteString
-- | UploadPolicy controls overall policy decisions relating to
-- multipart/form-data uploads, specifically:
--
--
-- - whether to treat parts without filenames as form input (reading
-- them into the rqParams map)
-- - because form input is read into memory, the maximum size of a form
-- input read in this manner, and the maximum number of form inputs
-- - the minimum upload rate a client must maintain before we kill the
-- connection; if very low-bitrate uploads were allowed then a Snap
-- server would be vulnerable to a trivial denial-of-service using a
-- "slowloris"-type attack
-- - the minimum number of seconds which must elapse before we start
-- killing uploads for having too low an upload rate.
-- - the amount of time we should wait before timing out the connection
-- whenever we receive input from the client.
--
data UploadPolicy
-- | A reasonable set of defaults for upload policy. The default policy is:
--
--
-- - maximum form input size 128kB
-- - maximum number of form inputs 10
-- - minimum upload rate 1kB/s
-- - seconds before rate limiting kicks in 10
-- - inactivity timeout 20 seconds
--
defaultUploadPolicy :: UploadPolicy
-- | Does this upload policy stipulate that we want to treat parts without
-- filenames as form input?
doProcessFormInputs :: UploadPolicy -> Bool
-- | Set the upload policy for treating parts without filenames as form
-- input.
setProcessFormInputs :: Bool -> UploadPolicy -> UploadPolicy
-- | Get the maximum size of a form input which will be read into our
-- rqParams map.
getMaximumFormInputSize :: UploadPolicy -> Int
-- | Set the maximum size of a form input which will be read into our
-- rqParams map.
setMaximumFormInputSize :: Int -> UploadPolicy -> UploadPolicy
-- | Get the minimum rate (in bytes\second/) a client must maintain
-- before we kill the connection.
getMinimumUploadRate :: UploadPolicy -> Double
-- | Set the minimum rate (in bytes\second/) a client must maintain
-- before we kill the connection.
setMinimumUploadRate :: Double -> UploadPolicy -> UploadPolicy
-- | Get the amount of time which must elapse before we begin enforcing the
-- upload rate minimum
getMinimumUploadSeconds :: UploadPolicy -> Int
-- | Set the amount of time which must elapse before we begin enforcing the
-- upload rate minimum
setMinimumUploadSeconds :: Int -> UploadPolicy -> UploadPolicy
-- | Get the "upload timeout". Whenever input is received from the client,
-- the connection timeout is set this many seconds in the future.
getUploadTimeout :: UploadPolicy -> Int
-- | Set the upload timeout.
setUploadTimeout :: Int -> UploadPolicy -> UploadPolicy
-- | Upload policy can be set on an "general" basis (using
-- UploadPolicy), but handlers can also make policy decisions on
-- individual files/parts uploaded. For each part uploaded, handlers can
-- decide:
--
--
-- - whether to allow the file upload at all
-- - the maximum size of uploaded files, if allowed
--
data PartUploadPolicy
-- | Disallows the file to be uploaded.
disallow :: PartUploadPolicy
-- | Allows the file to be uploaded, with maximum size n.
allowWithMaximumSize :: Int64 -> PartUploadPolicy
-- | All of the exceptions defined in this package inherit from
-- FileUploadException, so if you write
--
--
-- foo `catch` \(e :: FileUploadException) -> ...
--
--
-- you can catch a BadPartException, a
-- PolicyViolationException, etc.
data FileUploadException
fileUploadExceptionReason :: FileUploadException -> Text
data BadPartException
badPartExceptionReason :: BadPartException -> Text
data PolicyViolationException
policyViolationExceptionReason :: PolicyViolationException -> Text
instance Typeable FileUploadException
instance Typeable BadPartException
instance Typeable PolicyViolationException
instance Show PartInfo
instance Show UploadPolicy
instance Eq UploadPolicy
instance Show PartUploadPolicy
instance Eq PartUploadPolicy
instance Show a => Show (Capture a)
instance Show PolicyViolationException
instance Exception PolicyViolationException
instance Show BadPartException
instance Exception BadPartException
instance Exception FileUploadException
instance Show FileUploadException