snap-core-0.2.8: Snap: A Haskell Web Framework (Core)



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.



type Headers = Map CIByteString [ByteString]Source

A type alias for a case-insensitive key-value mapping.

class HasHeaders a whereSource

A typeclass for datatypes which contain HTTP headers.


updateHeaders :: (Headers -> Headers) -> a -> aSource

Modify the datatype's headers.

headers :: a -> HeadersSource

Retrieve the headers from a datatype that has headers.

addHeader :: HasHeaders a => CIByteString -> ByteString -> a -> aSource

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.

setHeader :: HasHeaders a => CIByteString -> ByteString -> a -> aSource

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.

getHeaders :: HasHeaders a => CIByteString -> a -> Maybe [ByteString]Source

Gets all of the values for a given header.

getHeader :: HasHeaders a => CIByteString -> a -> Maybe ByteStringSource

Gets a header value out of a HasHeaders datatype. If many headers came in with the same name, they will be catenated together.

data Method Source

Enumerates the HTTP method values (see



data Cookie Source

A datatype representing an HTTP cookie.




cookieName :: !ByteString

The name of the cookie.

cookieValue :: !ByteString

The cookie's string value.

cookieExpires :: !(Maybe UTCTime)

The cookie's expiration value, if it has one.

cookieDomain :: !(Maybe ByteString)

The cookie's "domain" value, if it has one.

cookiePath :: !(Maybe ByteString)

The cookie path.


type Params = Map ByteString [ByteString]Source

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"].

data SomeEnumerator Source


SomeEnumerator (forall a. Enumerator a) 

data Request Source

Contains all of the information about an incoming HTTP request.




rqServerName :: !ByteString

The server name of the request, as it came in from the request's Host: header.

rqServerPort :: !Int

Returns the port number the HTTP server is listening on.

rqRemoteAddr :: !ByteString

The remote IP address.

rqRemotePort :: !Int

The remote TCP port number.

rqLocalAddr :: !ByteString

The local IP address for this request.

rqLocalPort :: !Int

Returns the port number the HTTP server is listening on.

rqLocalHostname :: !ByteString

Returns the HTTP server's idea of its local hostname.

rqIsSecure :: !Bool

Returns True if this is an HTTPS session (currently always False).

rqHeaders :: Headers
rqBody :: IORef SomeEnumerator
rqContentLength :: !(Maybe Int)

Returns the Content-Length of the HTTP request body.

rqMethod :: !Method

Returns the HTTP request method.

rqVersion :: !HttpVersion

Returns the HTTP version used by the client.

rqCookies :: [Cookie]

Returns a list of the cookies that came in from the HTTP request headers.

rqSnapletPath :: !ByteString

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 ""

rqPathInfo :: !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".

rqContextPath :: !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.

rqURI :: !ByteString

Returns the URI requested by the client.

rqQueryString :: !ByteString

Returns the HTTP query string for this Request.

rqParams :: Params

Returns the Params mapping for this Request. "Parameters" are automatically decoded from the query string and POST body and entered into this mapping.

data ResponseBody Source


Enum (forall a. Enumerator a)

output body is enumerator

SendFile FilePath

output body is sendfile()

data Response Source

Represents an HTTP response.




rspHeaders :: Headers
rspHttpVersion :: !HttpVersion
rspContentLength :: !(Maybe Int64)

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.

rspBody :: ResponseBody
rspStatus :: !Int

Returns the HTTP status code.

rspStatusReason :: !ByteString

Returns the HTTP status explanation string.



:: ByteString

parameter name to look up

-> Request

HTTP request

-> Maybe [ByteString] 

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.

rqModifyParams :: (Params -> Params) -> Request -> RequestSource

Modifies the parameters mapping (which is a Map ByteString ByteString) in a Request using the given function.



:: ByteString

parameter name

-> [ByteString]

parameter values

-> Request


-> Request 

Writes a key-value pair to the parameters mapping within the given request.



:: (forall a. Enumerator a)

new response body enumerator

-> Response

response to modify

-> Response 

Sets an HTTP response body to the given Enumerator value.



:: Int

HTTP response integer code

-> ByteString

HTTP response explanation

-> Response

Response to be modified

-> Response 

Sets the HTTP response status.

modifyResponseBody :: (forall a. Enumerator a -> Enumerator a) -> Response -> ResponseSource

Modifies a response body.

setContentType :: ByteString -> Response -> ResponseSource

Sets the Content-Type in the Response headers.



:: Cookie

cookie value

-> Response

response to modify

-> Response 

Adds an HTTP Cookie to the Response headers.

setContentLength :: Int64 -> Response -> ResponseSource

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.

clearContentLength :: Response -> ResponseSource

Removes any Content-Length set in the Response.

formatHttpTime :: CTime -> IO ByteStringSource

Converts a CTime into an HTTP timestamp.

formatLogTime :: CTime -> IO ByteStringSource

Converts a CTime into common log entry format.

parseHttpTime :: ByteString -> IO CTimeSource

Converts an HTTP timestamp into a CTime.