snap-core-0.2.16: Snap: A Haskell Web Framework (Core)ContentsIndex
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.Types.

Synopsis
type Enumerator a = Enumerator IO a
type Headers = Map CIByteString [ByteString]
class HasHeaders a where
updateHeaders :: (Headers -> Headers) -> a -> a
headers :: a -> Headers
addHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
setHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
getHeaders :: HasHeaders a => CIByteString -> a -> Maybe [ByteString]
getHeader :: HasHeaders a => CIByteString -> a -> Maybe ByteString
deleteHeader :: HasHeaders a => CIByteString -> a -> a
data Method
= GET
| HEAD
| POST
| PUT
| DELETE
| TRACE
| OPTIONS
| CONNECT
type HttpVersion = (Int, Int)
data Cookie = Cookie {
cookieName :: !ByteString
cookieValue :: !ByteString
cookieExpires :: !(Maybe UTCTime)
cookieDomain :: !(Maybe ByteString)
cookiePath :: !(Maybe ByteString)
}
type Params = Map ByteString [ByteString]
data SomeEnumerator = SomeEnumerator (forall a. Enumerator a)
data Request = Request {
rqServerName :: !ByteString
rqServerPort :: !Int
rqRemoteAddr :: !ByteString
rqRemotePort :: !Int
rqLocalAddr :: !ByteString
rqLocalPort :: !Int
rqLocalHostname :: !ByteString
rqIsSecure :: !Bool
rqHeaders :: Headers
rqBody :: IORef SomeEnumerator
rqContentLength :: !(Maybe Int)
rqMethod :: !Method
rqVersion :: !HttpVersion
rqCookies :: [Cookie]
rqSnapletPath :: !ByteString
rqPathInfo :: !ByteString
rqContextPath :: !ByteString
rqURI :: !ByteString
rqQueryString :: !ByteString
rqParams :: Params
}
data ResponseBody
= Enum (forall a. Enumerator a)
| SendFile FilePath (Maybe (Int64, Int64))
rspBodyMap :: (forall a. Enumerator a -> Enumerator a) -> ResponseBody -> ResponseBody
rspBodyToEnum :: ResponseBody -> Enumerator a
data Response = Response {
rspHeaders :: Headers
rspHttpVersion :: !HttpVersion
rspContentLength :: !(Maybe Int64)
rspBody :: ResponseBody
rspStatus :: !Int
rspStatusReason :: !ByteString
rspTransformingRqBody :: !Bool
}
rqParam :: ByteString -> Request -> Maybe [ByteString]
rqModifyParams :: (Params -> Params) -> Request -> Request
rqSetParam :: ByteString -> [ByteString] -> Request -> Request
emptyResponse :: Response
setResponseBody :: (forall a. Enumerator a) -> Response -> Response
setResponseStatus :: Int -> ByteString -> Response -> Response
setResponseCode :: Int -> Response -> Response
modifyResponseBody :: (forall a. Enumerator a -> Enumerator a) -> Response -> Response
setContentType :: ByteString -> Response -> Response
addCookie :: Cookie -> Response -> Response
setContentLength :: Int64 -> Response -> Response
clearContentLength :: Response -> Response
formatHttpTime :: CTime -> IO ByteString
formatLogTime :: CTime -> IO ByteString
parseHttpTime :: ByteString -> IO CTime
parseToCompletion :: Parser a -> ByteString -> Maybe a
pUrlEscaped :: Parser ByteString
urlDecode :: ByteString -> Maybe ByteString
urlEncode :: ByteString -> ByteString
hexd :: Word8 -> Builder
finish :: Result a -> Result a
fromStr :: String -> ByteString
toStr :: ByteString -> String
statusReasonMap :: IntMap ByteString
Documentation
type Enumerator a = Enumerator IO a
type Headers = Map CIByteString [ByteString]
A type alias for a case-insensitive key-value mapping.
class HasHeaders a where
A typeclass for datatypes which contain HTTP headers.
Methods
updateHeaders :: (Headers -> Headers) -> a -> a
Modify the datatype's headers.
headers :: a -> Headers
Retrieve the headers from a datatype that has headers.
show/hide Instances
addHeader :: HasHeaders a => CIByteString -> ByteString -> a -> a
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 -> 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.
getHeaders :: HasHeaders a => CIByteString -> a -> Maybe [ByteString]
Gets all of the values for a given header.
getHeader :: 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.
deleteHeader :: HasHeaders a => CIByteString -> a -> a
Clears a header value from a HasHeaders datatype.
data Method
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
show/hide Instances
type HttpVersion = (Int, Int)
data Cookie
A datatype representing an HTTP cookie.
Constructors
Cookie
cookieName :: !ByteStringThe name of the cookie.
cookieValue :: !ByteStringThe 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.
show/hide Instances
type Params = Map ByteString [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&param=bar2"), looking up "param" in the mapping will give you ["bar1", "bar2"].
data SomeEnumerator
An existential wrapper for the Enumerator type
Constructors
SomeEnumerator (forall a. Enumerator a)
data Request
Contains all of the information about an incoming HTTP request.
Constructors
Request
rqServerName :: !ByteStringThe server name of the request, as it came in from the request's Host: header.
rqServerPort :: !IntReturns the port number the HTTP server is listening on.
rqRemoteAddr :: !ByteStringThe remote IP address.
rqRemotePort :: !IntThe remote TCP port number.
rqLocalAddr :: !ByteStringThe local IP address for this request.
rqLocalPort :: !IntReturns the port number the HTTP server is listening on.
rqLocalHostname :: !ByteStringReturns the HTTP server's idea of its local hostname.
rqIsSecure :: !BoolReturns 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 :: !MethodReturns the HTTP request method.
rqVersion :: !HttpVersionReturns 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 :: !ByteStringHandlers 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 :: !ByteStringThe "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 :: !ByteStringReturns the URI requested by the client.
rqQueryString :: !ByteStringReturns the HTTP query string for this Request.
rqParams :: ParamsReturns the Params mapping for this Request. "Parameters" are automatically decoded from the query string and POST body and entered into this mapping.
show/hide Instances
data ResponseBody
Constructors
Enum (forall a. Enumerator a)output body is enumerator
SendFile FilePath (Maybe (Int64, Int64))output body is sendfile(), optional second argument is a byte range to send
rspBodyMap :: (forall a. Enumerator a -> Enumerator a) -> ResponseBody -> ResponseBody
rspBodyToEnum :: ResponseBody -> Enumerator a
data Response
Represents an HTTP response.
Constructors
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 :: !IntReturns the HTTP status code.
rspStatusReason :: !ByteStringReturns the HTTP status explanation string.
rspTransformingRqBody :: !BoolIf true, we are transforming the request body with transformRequestBody
show/hide Instances
rqParam
:: ByteStringparameter name to look up
-> RequestHTTP 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 -> Request
Modifies the parameters mapping (which is a Map ByteString ByteString) in a Request using the given function.
rqSetParam
:: ByteStringparameter name
-> [ByteString]parameter values
-> Requestrequest
-> Request
Writes a key-value pair to the parameters mapping within the given request.
emptyResponse :: Response
An empty Response.
setResponseBody
:: (forall a. Enumerator a)new response body enumerator
-> Responseresponse to modify
-> Response
Sets an HTTP response body to the given Enumerator value.
setResponseStatus
:: IntHTTP response integer code
-> ByteStringHTTP response explanation
-> ResponseResponse to be modified
-> Response
Sets the HTTP response status. Note: normally you would use setResponseCode unless you needed a custom response explanation.
setResponseCode
:: IntHTTP response integer code
-> ResponseResponse to be modified
-> Response
Sets the HTTP response code.
modifyResponseBody :: (forall a. Enumerator a -> Enumerator a) -> Response -> Response
Modifies a response body.
setContentType :: ByteString -> Response -> Response
Sets the Content-Type in the Response headers.
addCookie
:: Cookiecookie value
-> Responseresponse to modify
-> Response
Adds an HTTP Cookie to the Response headers.
setContentLength :: Int64 -> 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.

clearContentLength :: Response -> Response
Removes any Content-Length set in the Response.
formatHttpTime :: CTime -> IO ByteString
Converts a CTime into an HTTP timestamp.
formatLogTime :: CTime -> IO ByteString
Converts a CTime into common log entry format.
parseHttpTime :: ByteString -> IO CTime
Converts an HTTP timestamp into a CTime.
parseToCompletion :: Parser a -> ByteString -> Maybe a
pUrlEscaped :: Parser ByteString
urlDecode :: ByteString -> Maybe ByteString
Decodes an URL-escaped string (see http://tools.ietf.org/html/rfc2396.html#section-2.4)
urlEncode :: ByteString -> ByteString
URL-escapes a string (see http://tools.ietf.org/html/rfc2396.html#section-2.4)
hexd :: Word8 -> Builder
finish :: Result a -> Result a
fromStr :: String -> ByteString
toStr :: ByteString -> String
statusReasonMap :: IntMap ByteString
Produced by Haddock version 2.7.2