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.

Functions for control flow and early termination

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.

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.

A short note about URL decoding: path matching and variable capture are done
on decoded URLs, but the contents of rqContextPath and rqPathInfo will
contain the original encoded URL, i.e. what the user entered. For example,
in the following scenario:

route [ ("a b c d/", foo ) ]

A request for "/a+b+c+d" will be sent to foo with rqContextPath set
to "a+b+c+d".

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.

Logging

Grabbing/transforming request bodies

Sends the request body through an iteratee (data consumer) and
returns the result.

If the iteratee you pass in here throws an exception, Snap will attempt to
clear the rest of the unread request body before rethrowing the exception.
If your iteratee used terminateConnection, however, Snap will give up and
immediately close the socket.

This function is deprecated as of 0.6; it places no limits on the size of
the request being read, and as such, if used, can result in a
denial-of-service attack on your server. Please use readRequestBody
instead.

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.

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&param=bar2"), looking up
"param" in the mapping will give you ["bar1", "bar2"].

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.

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.

The "context path" of the request; catenating rqContextPath,
and rqPathInfo should get you back to the original rqURI
(ignoring query strings). 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.

Returns the parameters mapping for this Request. "Parameters"
are automatically decoded from the URI's query string and POST body
and entered into this mapping. The rqParams value is thus a union of
rqQueryParams and rqPostParams.

The parameter mapping decoded from the POST body. Note that Snap
only auto-decodes POST request bodies when the request's
Content-Type is application/x-www-form-urlencoded.
For multipart/form-data use handleFileUploads
to decode the POST request and fill this mapping.

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.

See rqPostParam. Looks up a value for the given named parameter in the
POST form parameters mapping in Request. If more than one value was
entered for the given parameter name, getPostParam gloms the values
together with:

See rqQueryParam. Looks up a value for the given named parameter in the
query string parameters mapping in Request. If more than one value was
entered for the given parameter name, getQueryParam gloms the values
together with:

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.

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.

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.

The buffering mode controls whether Snap will buffer the output or not.
You may wish to disable buffering when using Comet-like techniques which
rely on the immediate sending of output data in order to maintain
interactive semantics.

The buffering mode controls whether Snap will buffer the output or not.
You may wish to disable buffering when using Comet-like techniques which
rely on the immediate sending of output data in order to maintain
interactive semantics.

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().

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().