-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Snap: A Haskell Web Framework (Core)
--
-- This is the first developer prerelease of the Snap framework. 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.2.14
-- | 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 ()
debugSeq :: (MonadIO m) => String -> m ()
debugErrnoSeq :: (MonadIO m) => String -> m ()
_debugMVar :: MVar ()
debugOn :: (MonadIO m) => String -> m ()
debugErrnoOn :: (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.Iteratee in the iteratee library.
--
-- WARNING: Note that all of these types are scheduled to change
-- in the darcs head version of the iteratee library;
-- John Lato et al. are working on a much improved iteratee formulation.
module Snap.Iteratee
type Stream = StreamG WrappedByteString Word8
type IterV m = IterGV WrappedByteString Word8 m
type Iteratee m = IterateeG WrappedByteString Word8 m
type Enumerator m a = Iteratee m a -> m (Iteratee m a)
-- | Enumerates a strict bytestring.
enumBS :: (Monad m) => ByteString -> Enumerator m a
-- | Enumerates a lazy bytestring.
enumLBS :: (Monad m) => ByteString -> Enumerator m a
enumFile :: FilePath -> Iteratee IO a -> IO (Iteratee IO a)
enumFilePartial :: FilePath -> (Int64, Int64) -> Iteratee IO a -> IO (Iteratee IO a)
data InvalidRangeException
-- | Converts a wrapped bytestring to a lazy bytestring.
fromWrap :: WrappedByteString Word8 -> ByteString
-- | Converts a lazy bytestring to a wrapped bytestring.
toWrap :: ByteString -> WrappedByteString Word8
-- | Skip n elements of the stream, if there are that many This is the
-- Int64 version of the drop function in the iteratee library
drop' :: (StreamChunk s el, Monad m) => Int64 -> IterateeG s el m ()
-- | Reads n elements from a stream and applies the given iteratee to the
-- stream of the read elements. Reads exactly n elements, and if the
-- stream is short propagates an error.
takeExactly :: (StreamChunk s el, Monad m) => Int64 -> EnumeratorN s el s el m a
-- | Reads up to n elements from a stream and applies the given iteratee to
-- the stream of the read elements. If more than n elements are read,
-- propagates an error.
takeNoMoreThan :: (StreamChunk s el, Monad m) => Int64 -> EnumeratorN s el s el m a
-- | Wraps an Iteratee, counting the number of bytes consumed by it.
countBytes :: (Monad m) => Iteratee m a -> Iteratee m (a, Int64)
-- | Buffers an iteratee.
--
-- Our enumerators produce a lot of little strings; rather than spending
-- all our time doing kernel context switches for 4-byte write() calls,
-- we buffer the iteratee to send 8KB at a time.
--
-- The IORef returned can be set to True to cancel buffering. We
-- added this so that transfer-encoding: chunked (which needs its own
-- buffer and therefore doesn't need its output buffered) can
-- switch the outer buffer off.
bufferIteratee :: Iteratee IO a -> IO (Iteratee IO a, IORef Bool)
-- | 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 IO a -> IO (Iteratee 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 IO a -> IO (Iteratee IO a)
instance Typeable InvalidRangeException
instance Exception InvalidRangeException
instance Show InvalidRangeException
instance (Functor m, MonadCatchIO m) => MonadCatchIO (IterateeG s el 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 IO ()
iterateeDebugWrapper :: String -> Iteratee IO a -> Iteratee IO a
instance Show (WrappedByteString Word8)
-- | 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 ()
type Enumerator a = Enumerator IO a
-- | 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 type
data SomeEnumerator
SomeEnumerator :: (forall a. Enumerator 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 (currently
-- always False).
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 enumerator
Enum :: (forall a. Enumerator 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 a -> Enumerator a) -> ResponseBody -> ResponseBody
rspBodyToEnum :: ResponseBody -> Enumerator a
-- | Represents an HTTP response.
data Response
Response :: Headers -> !HttpVersion -> !Maybe Int64 -> ResponseBody -> !Int -> !ByteString -> !Bool -> Response
rspHeaders :: Response -> Headers
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 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 a -> Enumerator a) -> Response -> Response
-- | Sets the Content-Type in the Response headers.
setContentType :: ByteString -> Response -> Response
-- | Adds an HTTP Cookie to the Response headers.
addCookie :: 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 Eq Cookie
instance Show Cookie
instance Show Method
instance Read Method
instance Ord Method
instance Eq Method
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
-- | 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
--
data Snap a
-- | Runs a Snap monad action in the 'Iteratee IO' monad.
runSnap :: Snap a -> (ByteString -> IO ()) -> Request -> Iteratee IO (Request, Response)
-- | This exception is thrown if the handler you supply to runSnap
-- fails.
data NoHandlerException
NoHandlerException :: NoHandlerException
-- | Short-circuits a Snap monad action early, storing the given
-- Response value in its state.
finishWith :: Response -> Snap 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 :: Snap a
-- | Runs a Snap monad action only if the request's HTTP method
-- matches the given method.
method :: Method -> Snap a -> Snap 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 :: ByteString -> Snap a -> Snap 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 :: ByteString -> Snap a -> Snap a
-- | Runs a Snap monad action only when rqPathInfo is empty.
ifTop :: Snap a -> Snap 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 :: [(ByteString, Snap a)] -> Snap 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 :: [(ByteString, Snap a)] -> Snap a
-- | Grabs the Request object out of the Snap monad.
getRequest :: Snap Request
-- | Grabs the Response object out of the Snap monad.
getResponse :: Snap Response
-- | Puts a new Request object into the Snap monad.
putRequest :: Request -> Snap ()
-- | Puts a new Response object into the Snap monad.
putResponse :: Response -> Snap ()
-- | Modifies the Request object stored in a Snap monad.
modifyRequest :: (Request -> Request) -> Snap ()
-- | Modifes the Response object stored in a Snap monad.
modifyResponse :: (Response -> Response) -> Snap ()
-- | 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 :: (Request -> Request) -> Snap a -> Snap a
-- | Fetches the Request from state and hands it to the given
-- action.
withRequest :: (Request -> Snap a) -> Snap a
-- | Fetches the Response from state and hands it to the given
-- action.
withResponse :: (Response -> Snap a) -> Snap a
-- | Log an error message in the Snap monad
logError :: ByteString -> Snap ()
-- | Sends the request body through an iteratee (data consumer) and returns
-- the result.
runRequestBody :: Iteratee IO a -> Snap a
-- | Returns the request body as a bytestring.
getRequestBody :: Snap 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 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 :: Snap ()
-- | 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' :: CIByteString -> Snap ()
-- | 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 (currently
-- always False).
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 :: ByteString -> Snap (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 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
-- | Adds an HTTP Cookie to the Response headers.
addCookie :: 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
-- | 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 :: ByteString -> Snap ()
-- | 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' :: ByteString -> Int -> Snap ()
-- | Sets an HTTP response body to the given Enumerator value.
setResponseBody :: (forall a. Enumerator a) -> Response -> Response
-- | Modifies a response body.
modifyResponseBody :: (forall a. Enumerator a -> Enumerator a) -> Response -> Response
-- | Adds the output from the given enumerator to the Response
-- stored in the Snap monad state.
addToOutput :: (forall a. Enumerator a) -> Snap ()
-- | 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 :: ByteString -> Snap ()
-- | 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 :: Text -> Snap ()
-- | 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 :: Text -> Snap ()
-- | 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 :: ByteString -> Snap ()
-- | 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 :: FilePath -> Snap ()
-- | 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 :: FilePath -> (Int64, Int64) -> Snap ()
type Enumerator a = Enumerator IO a
-- | An existential wrapper for the Enumerator type
data SomeEnumerator
SomeEnumerator :: (forall a. Enumerator 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
-- | 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 :: Snap FilePath
-- | Serves files out of the given directory. The relative path given in
-- rqPathInfo is searched for the given 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.
--
-- Uses defaultMimeTypes to determine the Content-Type
-- based on the file's extension.
fileServe :: FilePath -> Snap ()
-- | Same as fileServe, with control over the MIME mapping used.
fileServe' :: MimeMap -> FilePath -> Snap ()
-- | 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.
fileServeSingle :: FilePath -> Snap ()
-- | Same as fileServeSingle, with control over the MIME mapping
-- used.
fileServeSingle' :: ByteString -> FilePath -> Snap ()
-- | 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
-- | A type alias for MIME type
type MimeMap = Map FilePath ByteString
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 :: Snap a -> Snap ()
-- | The same as withCompression, with control over which MIME types
-- to compress.
withCompression' :: Set ByteString -> Snap a -> Snap ()
instance Typeable BadAcceptEncodingException
instance Exception BadAcceptEncodingException
instance Show BadAcceptEncodingException