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

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

- class HasHeaders a where
  - updateHeaders :: (Headers -> Headers) -> a -> a
  - headers :: a -> Headers
- addHeader :: HasHeaders a => CI ByteString -> ByteString -> a -> a
- setHeader :: HasHeaders a => CI ByteString -> ByteString -> a -> a
- getHeaders :: HasHeaders a => CI ByteString -> a -> Maybe [ByteString]
- getHeader :: HasHeaders a => CI ByteString -> a -> Maybe ByteString
- listHeaders :: HasHeaders a => a -> [(CI ByteString, ByteString)]
- deleteHeader :: HasHeaders a => CI ByteString -> 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)
  - cookieSecure :: !Bool
  - cookieHttpOnly :: !Bool
  }
- type Params = Map ByteString [ByteString]
- newtype SomeEnumerator = SomeEnumerator (forall a. Enumerator ByteString IO 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 Builder IO a)
  - | SendFile FilePath (Maybe (Int64, Int64))
- rspBodyMap :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> ResponseBody -> ResponseBody
- rspBodyToEnum :: ResponseBody -> Enumerator Builder IO a
- data Response = Response {
  - rspHeaders :: Headers
  - rspCookies :: Map ByteString Cookie
  - 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 Builder IO a) -> Response -> Response
- setResponseStatus :: Int -> ByteString -> Response -> Response
- setResponseCode :: Int -> Response -> Response
- modifyResponseBody :: (forall a. Enumerator Builder IO a -> Enumerator Builder IO a) -> Response -> Response
- setContentType :: ByteString -> Response -> Response
- addResponseCookie :: Cookie -> Response -> Response
- getResponseCookie :: ByteString -> Response -> Maybe Cookie
- getResponseCookies :: Response -> [Cookie]
- deleteResponseCookie :: ByteString -> Response -> Response
- modifyResponseCookie :: ByteString -> (Cookie -> Cookie) -> Response -> Response
- setContentLength :: Int64 -> Response -> Response
- clearContentLength :: Response -> Response
- formatHttpTime :: CTime -> IO ByteString
- formatLogTime :: CTime -> IO ByteString
- parseHttpTime :: ByteString -> IO CTime
- fromStr :: String -> ByteString
- toStr :: ByteString -> String
- statusReasonMap :: IntMap ByteString

# Documentation

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.

Instances

HasHeaders Headers |
HasHeaders Response |
HasHeaders Request |

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

Gets all of the values for a given header.

getHeader :: HasHeaders a => CI ByteString -> 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.

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

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

Instances

Eq Method |
Ord Method |
Read Method |
Show Method |

type HttpVersion = (Int, Int)

data Cookie

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?

Instances

Eq Cookie |
Show Cookie |

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

newtype SomeEnumerator

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

Constructors

SomeEnumerator (forall a. Enumerator ByteString IO a) |

data Request

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.

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
                           , let q = rqQueryString r
                             in if S.null q
                                  then ""
                                  else S.append "?" q
                           ]

  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` (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 `Params` mapping for this `Request`. "Parameters" are automatically decoded from the query string and `POST` body and entered into this mapping.

Instances

Show Request |
HasHeaders Request |

data ResponseBody

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

rspBodyToEnum :: ResponseBody -> Enumerator Builder IO a

data Response

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`

Instances

Show Response |
HasHeaders Response |

rqParam

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.

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

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

rqSetParam

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

An empty `Response`.

setResponseBody

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

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

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

Modifies a response body.

setContentType :: ByteString -> Response -> Response

Sets the `Content-Type` in the `Response` headers.

addResponseCookie

Arguments

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

Adds an HTTP `Cookie` to `Response` headers.

getResponseCookie

Arguments

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

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

getResponseCookies

Arguments

:: Response | response to query
-> [Cookie] |

Returns a list of `Cookie`s present in `Response`

deleteResponseCookie

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

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

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

fromStr :: String -> ByteString

toStr :: ByteString -> String

statusReasonMap :: IntMap ByteString