happstack-server-7.0.3: Web related tools and services.

Safe Haskell | None

Happstack.Server.Response

Contents

- Converting values to a `Response`
- Setting the Response Code
- Handling if-modified-since

Description

Functions and classes related to generating a `Response` and setting the response code. For detailed instruction see the Happstack Crash Course: http://happstack.com/docs/crashcourse/HelloWorld.html#response_code

Synopsis

- class ToMessage a where
  - toContentType :: a -> ByteString
  - toMessage :: a -> ByteString
  - toResponse :: a -> Response
- flatten :: (ToMessage a, Functor f) => f a -> f Response
- toResponseBS :: ByteString -> ByteString -> Response
- ok :: FilterMonad Response m => a -> m a
- noContent :: FilterMonad Response m => a -> m a
- internalServerError :: FilterMonad Response m => a -> m a
- badGateway :: FilterMonad Response m => a -> m a
- badRequest :: FilterMonad Response m => a -> m a
- unauthorized :: FilterMonad Response m => a -> m a
- forbidden :: FilterMonad Response m => a -> m a
- notFound :: FilterMonad Response m => a -> m a
- prettyResponse :: Response -> String
- requestEntityTooLarge :: FilterMonad Response m => a -> m a
- seeOther :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res
- found :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res
- movedPermanently :: (FilterMonad Response m, ToSURI a) => a -> res -> m res
- tempRedirect :: (FilterMonad Response m, ToSURI a) => a -> res -> m res
- setResponseCode :: FilterMonad Response m => Int -> m ()
- resp :: FilterMonad Response m => Int -> b -> m b
- ifModifiedSince :: CalendarTime -> Request -> Response -> Response

# Converting values to a `Response`

class ToMessage a where

`toResponse` will convert a value into a `Response` body, set the `content-type`, and set the default response code for that type.

`happstack-server` Example:

     main = simpleHTTP nullConf $ toResponse "hello, world!"

will generate a `Response` with the content-type `text/plain`, the response code `200 OK`, and the body: `hello, world!`.

`simpleHTTP` will call `toResponse` automatically, so the above can be shortened to:

     main = simpleHTTP nullConf $ "hello, world!"

`happstack-lite` Example:

     main = serve Nothing $ toResponse "hello, world!"

Minimal definition: `toMessage` (and usually `toContentType`).

Methods

toContentType :: a -> ByteString

toMessage :: a -> ByteString

toResponse :: a -> Response

Instances

ToMessage Integer |
ToMessage String |
ToMessage () |
ToMessage Text |
ToMessage Text |
ToMessage ByteString |
ToMessage ByteString |
ToMessage Html |
ToMessage Html |
ToMessage Html |
ToMessage Response |
ToMessage a => ToMessage (Maybe a) |

flatten :: (ToMessage a, Functor f) => f a -> f Response

alias for: `fmap toResponse`

turns `m a` into `m `Response`` using `toResponse`.

     main = simpleHTTP nullConf $ flatten $ do return "flatten me."

toResponseBS

Arguments

:: ByteString | content-type
-> ByteString | response body
-> Response |

A low-level function to build a `Response` from a content-type and a `ByteString`.

Creates a `Response` in a manner similar to the `ToMessage` class, but without requiring an instance declaration.

example:

     import Data.ByteString.Char8 as C
     import Data.ByteString.Lazy.Char8 as L
     import Happstack.Server

     main = simpleHTTP nullConf $ ok $ toResponseBS (C.pack "text/plain") (L.pack "hello, world")

(note: `pack` and `pack` only work for ascii. For unicode strings you would need to use `utf8-string`, `text`, or something similar to create a valid `ByteString`).

# Setting the Response Code

ok :: FilterMonad Response m => a -> m a

Respond with `200 OK`.

     main = simpleHTTP nullConf $ ok "Everything is OK"

noContent :: FilterMonad Response m => a -> m a

Respond with `204 No Content`

A `204 No Content` response may not contain a message-body. If you try to supply one, it will be dutifully ignored.

     main = simpleHTTP nullConf $ noContent "This will be ignored."

internalServerError :: FilterMonad Response m => a -> m a

Respond with `500 Internal Server Error`.

     main = simpleHTTP nullConf $ internalServerError "Sorry, there was an internal server error."

badGateway :: FilterMonad Response m => a -> m a

Responds with `502 Bad Gateway`.

     main = simpleHTTP nullConf $ badGateway "Bad Gateway."

badRequest :: FilterMonad Response m => a -> m a

Respond with `400 Bad Request`.

     main = simpleHTTP nullConf $ badRequest "Bad Request."

unauthorized :: FilterMonad Response m => a -> m a

Respond with `401 Unauthorized`.

     main = simpleHTTP nullConf $ unauthorized "You are not authorized."

forbidden :: FilterMonad Response m => a -> m a

Respond with `403 Forbidden`.

     main = simpleHTTP nullConf $ forbidden "Sorry, it is forbidden."

notFound :: FilterMonad Response m => a -> m a

Respond with `404 Not Found`.

     main = simpleHTTP nullConf $ notFound "What you are looking for has not been found."

prettyResponse :: Response -> String

A nicely formatted rendering of a `Response`

requestEntityTooLarge :: FilterMonad Response m => a -> m a

Respond with `413 Request Entity Too Large`.

     main = simpleHTTP nullConf $ requestEntityTooLarge "That's too big for me to handle."

seeOther :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res

Respond with `303 See Other`.

     main = simpleHTTP nullConf $ seeOther "http://example.org/" "What you are looking for is now at http://example.org/"

NOTE: The second argument of `seeOther` is the message body which will sent to the browser. According to the HTTP 1.1 spec,

    the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

This is because pre-HTTP/1.1 user agents do not support 303. However, in practice you can probably just use `""` as the second argument.

found :: (FilterMonad Response m, ToSURI uri) => uri -> res -> m res

Respond with `302 Found`.

You probably want `seeOther`. This method is not in popular use anymore, and is generally treated like 303 by most user-agents anyway.

movedPermanently :: (FilterMonad Response m, ToSURI a) => a -> res -> m res

Respond with `301 Moved Permanently`.

     main = simpleHTTP nullConf $ movedPermanently "http://example.org/" "What you are looking for is now at http://example.org/"

tempRedirect :: (FilterMonad Response m, ToSURI a) => a -> res -> m res

Respond with `307 Temporary Redirect`.

     main = simpleHTTP nullConf $ tempRedirect "http://example.org/" "What you are looking for is temporarily at http://example.org/"

setResponseCode

Arguments

:: FilterMonad Response m |
=> Int | response code
-> m () |

Set an arbitrary return code in your response.

A filter for setting the response code. Generally you will use a helper function like `ok` or `seeOther`.

     main = simpleHTTP nullConf $ do setResponseCode 200
                                     return "Everything is OK"

see also: `resp`

resp

Arguments

:: FilterMonad Response m |
=> Int | response code
-> b | value to return
-> m b |

Same as ``setResponseCode` status >> return val`.

Use this if you want to set a response code that does not already have a helper function.

     main = simpleHTTP nullConf $ resp 200 "Everything is OK"

# Handling if-modified-since

ifModifiedSince

Arguments

:: CalendarTime | mod-time for the `Response` (MUST NOT be later than server's time of message origination)
-> Request | incoming request (used to check for if-modified-since)
-> Response | Response to send if there are modifications
-> Response |

Honor an `if-modified-since` header in a `Request`. If the `Request` includes the `if-modified-since` header and the `Response` has not been modified, then return 304 (Not Modified), otherwise return the `Response`.