Safe Haskell	None

Snap.Internal.Http.Types

Description

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.Core.

Synopsis

Documentation

set_c_locale :: IO ()Source

c_parse_http_time :: CString -> IO CTime Source

c_format_http_time :: CTime -> CString -> IO ()Source

c_format_log_time :: CTime -> CString -> IO ()Source

class HasHeaders a whereSource

A typeclass for datatypes which contain HTTP headers.

Methods

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

Modify the datatype's headers.

headers :: a -> Headers Source

Retrieve the headers from a datatype that has headers.

Instances

HasHeaders Headers
HasHeaders Response
HasHeaders Request

addHeader :: HasHeaders a => CI ByteString -> 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 => CI ByteString -> 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 => CI ByteString -> a -> Maybe [ByteString]Source

Gets all of the values for a given header.

getHeader :: HasHeaders a => CI ByteString -> a -> Maybe ByteString Source

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

listHeaders :: HasHeaders a => a -> [(CI ByteString, ByteString)]Source

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

deleteHeader :: HasHeaders a => CI ByteString -> a -> aSource

Clears a header value from a HasHeaders datatype.

data Method Source

Enumerates the HTTP method values (see http://tools.ietf.org/html/rfc2068.html#section-5.1.1).

Constructors

GET
HEAD
POST
PUT
DELETE
TRACE
OPTIONS
CONNECT
PATCH
Method ByteString

Instances

Eq Method
Ord Method
Read Method
Show Method

type HttpVersion = (Int, Int)Source

data Cookie Source

A datatype representing an HTTP cookie.

Constructors

Cookie
Fields 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. cookieSecure :: !Bool Tag as secure cookie? cookieHttpOnly :: !Bool HttpOnly?

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

newtype SomeEnumerator Source

An existential wrapper for the 'Enumerator ByteString IO a' type

Constructors

SomeEnumerator (forall a. Enumerator ByteString IO a)

data Request Source

Contains all of the information about an incoming HTTP request.

Constructors

Request

Fields

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.

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.

rqPathInfo :: !ByteString

Handlers can 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".

The following identity holds:

 rqURI r == S.concat [ rqContextPath r
                     , rqPathInfo r
                     , let q = rqQueryString r
                       in if S.null q
                            then ""
                            else S.append "?" q
                     ]

rqContextPath :: !ByteString

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.

rqURI :: !ByteString

Returns the URI requested by the client.

rqQueryString :: !ByteString

Returns the HTTP query string for this Request.

rqParams :: Params

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.

rqQueryParams :: Params

The parameter mapping decoded from the URI's query string.

rqPostParams :: Params

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.

Instances

Show Request
HasHeaders Request
Monad m => MonadState Request (RequestBuilder m)

data ResponseBody Source

Constructors

Enum (forall a. Enumerator Builder IO a)	output body is a `Builder` enumerator
SendFile FilePath (Maybe (Int64, Int64))	output body is sendfile(), optional second argument is a byte range to send

rspBodyMap :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> ResponseBody -> ResponseBody Source

rspBodyToEnum :: ResponseBody -> Enumerator Builder IO aSource

data Response Source

Represents an HTTP response.

Constructors

Response

Fields

rspHeaders :: Headers
rspCookies :: Map ByteString Cookie
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.
rspTransformingRqBody :: !Bool: If true, we are transforming the request body with transformRequestBody
rspOutputBuffering :: !Bool: 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.

Instances

Show Response
HasHeaders Response

rqParam Source

Arguments

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

rqPostParam Source

Arguments

:: ByteString	parameter name to look up
-> Request	HTTP request
-> Maybe [ByteString]

Looks up the value(s) for the given named parameter in the POST parameters mapping.

rqQueryParam Source

Arguments

:: ByteString	parameter name to look up
-> Request	HTTP request
-> Maybe [ByteString]

Looks up the value(s) for the given named parameter in the query parameters mapping.

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

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

rqSetParam Source

Arguments

:: ByteString	parameter name
-> [ByteString]	parameter values
-> Request	request
-> Request

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

emptyResponse :: Response Source

An empty Response.

setResponseBody Source

Arguments

:: (forall a. Enumerator Builder IO a)	new response body enumerator
-> Response	response to modify
-> Response

Sets an HTTP response body to the given Enumerator value.

setResponseStatus Source

Arguments

:: Int	HTTP response integer code
-> ByteString	HTTP response explanation
-> Response	Response to be modified
-> Response

Sets the HTTP response status. Note: normally you would use setResponseCode unless you needed a custom response explanation.

setResponseCode Source

Arguments

:: Int	HTTP response integer code
-> Response	Response to be modified
-> Response

Sets the HTTP response code.

modifyResponseBody :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> Response -> Response Source

Modifies a response body.

setContentType :: ByteString -> Response -> Response Source

Sets the Content-Type in the Response headers.

addResponseCookie Source

Arguments

:: Cookie	cookie value
-> Response	response to modify
-> Response

Adds an HTTP Cookie to Response headers.

getResponseCookie Source

Arguments

:: ByteString	cookie name
-> Response	response to query
-> Maybe Cookie

Gets an HTTP Cookie with the given name from Response headers.

getResponseCookies Source

Arguments

:: Response	response to query
-> [Cookie]

Returns a list of Cookies present in Response

deleteResponseCookie Source

Arguments

:: ByteString	cookie name
-> Response	response to modify
-> Response

Deletes an HTTP Cookie from the Response headers. Please note this does not necessarily erase the cookie from the client browser.

modifyResponseCookie Source

Arguments

:: ByteString	cookie name
-> (Cookie -> Cookie)	modifier function
-> Response	response to modify
-> Response

Modifies an HTTP Cookie with given name in Response headers. Nothing will happen if a matching Cookie can not be found in Response.

setContentLength :: Int64 -> Response -> Response Source

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 -> Response Source

Removes any Content-Length set in the Response.

getBufferingMode :: Response -> Bool Source

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.

setBufferingMode Source

Arguments

:: Bool	if True, buffer the output, if False, send output immediately
-> Response
-> Response

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.

formatHttpTime :: CTime -> IO ByteString Source

Converts a CTime into an HTTP timestamp.

formatLogTime :: CTime -> IO ByteString Source

Converts a CTime into common log entry format.

parseHttpTime :: ByteString -> IO CTime Source

Converts an HTTP timestamp into a CTime.

fromStr :: String -> ByteString Source

toStr :: ByteString -> String Source

statusReasonMap :: IntMap ByteString Source