an HTTP request

an HTTP Response

An alias for ServerPartT IO

configuration to be used with serve function

a reasonable default ServerConfig

ServerConfig { port      = 8000
             , ramQuota  = 1 * 10^6
             , diskQuota = 20 * 10^6
             , tmpDir    = "/tmp/"
             }

start the server and handle requests using the supplied ServerPart

Guard against the request method

Example:

handler :: ServerPart Response
handler =
    do method [GET, HEAD]
       ...

HTTP request method

instances of this class provide a variety of ways to match on the Request method.

Examples:

method GET                  -- match GET or HEAD
method [GET, POST]          -- match GET, HEAD or POST
method HEAD                 -- match HEAD /but not/ GET
method (== GET)             -- match GET or HEAD
method (not . (==) DELETE)  -- match any method except DELETE
method ()                   -- match any method

As you can see, GET implies that HEAD should match as well. This is to make it harder to write an application that uses HTTP incorrectly. Happstack handles HEAD requests automatically, but we still need to make sure our handlers don't mismatch or a HEAD will result in a 404.

If you must, you can still do something like this to match GET without HEAD:

guardRq ((== GET) . rqMethod)

Pop a path element and run the supplied handler if it matches the given string.

handler :: ServerPart Response
handler = dir "foo" $ dir "bar" $ subHandler

The path element can not contain '/'. See also dirs.

Pop a path element and parse it using the fromReqURI in the FromReqURI class.

This class is used by path to parse a path component into a value.

The instances for number types (Int, Float, etc) use readM to parse the path component.

The instance for String, on the other hand, returns the unmodified path component.

See the following section of the Happstack Crash Course for detailed instructions using and extending FromReqURI:

http://www.happstack.com/docs/crashcourse/RouteFilters.html#FromReqURI

guard which only succeeds if there are no remaining path segments

Often used if you want to explicitly assign a route for /

Guard using an arbitrary function on the Request.

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

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

main = serve Nothing $ 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).

Respond with 200 OK.

main = serve Nothing $ ok "Everything is OK"

Respond with 500 Internal Server Error.

main = serve Nothing $ internalServerError "Sorry, there was an internal server error."

Respond with 401 Unauthorized.

main = serve Nothing $ unauthorized "You are not authorized."

Respond with 404 Not Found.

main = serve Nothing $ notFound "What you are looking for has not been found."

Respond with 303 See Other.

main = serve Nothing $ 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.

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 = serve Nothing $ do setResponseCode 200
                          return "Everything is OK"

Gets the first matching named input parameter as a lazy ByteString

Searches the QUERY_STRING followed by the Request body.

see also: lookBSs

Gets all matches for the named input parameter as lazy ByteStrings

Searches the QUERY_STRING followed by the Request body.

see also: lookBS

Gets the first matching named input parameter as a lazy Text

Searches the QUERY_STRING followed by the Request body.

This function assumes the underlying octets are UTF-8 encoded.

see also: lookTexts

Gets all matches for the named input parameter as lazy Texts

Searches the QUERY_STRING followed by the Request body.

This function assumes the underlying octets are UTF-8 encoded.

see also: lookText

Gets the first matching named file

Files can only appear in the request body. Additionally, the form must set enctype="multipart/form-data".

This function returns a tuple consisting of:

1. The temporary location of the uploaded file
2. The local filename supplied by the browser
3. The content-type supplied by the browser

NOTE: You must move the file from the temporary location before the Response is sent. The temporary files are automatically removed after the Response is sent.

A MIME media type value. The Show instance is derived automatically. Use showContentType to obtain the standard string representation. See http://www.ietf.org/rfc/rfc2046.txt for more information about MIME media types.

a type for HTTP cookies. Usually created using mkCookie.

Specify the lifetime of a cookie.

Note that we always set the max-age and expires headers because internet explorer does not honor max-age. You can specific MaxAge or Expires and the other will be calculated for you. Choose which ever one makes your life easiest.

Creates a cookie with a default version of 1, empty domain, a path of "/", secure == False and httpOnly == False

see also: addCookie

Add the list Cookie to the Response.

Expire the named cookie immediately and set the cookie value to ""

main = serve Nothing $
  do expireCookie "name"
     ok $ "The cookie has been expired."

gets the named cookie as a string

Add headers into the response. This method does not overwrite any existing header of the same name, hence the name addHeaderM. If you want to replace a header use setHeaderM.

Set a header into the response. This will replace an existing header of the same name. Use addHeaderM if you want to add more than one header of the same name.

Get a header out of the request.

see serveDirectory

Serve files and directories from a directory and its subdirectories using sendFile.

Usage:

serveDirectory EnableBrowsing ["index.html"] "path/to/files/on/disk"

If the requested path does not match a file or directory on the disk, then serveDirectory calls mzero.

If the requested path is a file then the file is served normally.

If the requested path is a directory, then the result depends on what the first two arguments to the function are.

The first argument controls whether directory browsing is enabled.

The second argument is a list of index files (such as index.html).

When a directory is requested, serveDirectory will first try to find one of the index files (in the order they are listed). If that fails, it will show a directory listing if EnableBrowsing is set, otherwise it will return forbidden "Directory index forbidden".

Here is an explicit list of all the possible outcomes when the argument is a (valid) directory:

DisableBrowsing, empty index file list

This will always return, forbidden "Directory index forbidden"

DisableBrowsing, non-empty index file list

1. If an index file is found it will be shown.
2. Otherwise returns, forbidden "Directory index forbidden"

EnableBrowsing, empty index file list

Always shows a directory index.

EnableBrowsing, non-empty index file list

1. If an index file is found it will be shown
2. Otherwise shows a directory index

see also: serveFile

Serve a single, specified file. The name of the file being served is specified explicity. It is not derived automatically from the Request url.

example 1:

Serve as a specific content-type:

serveFile (asContentType "image/jpeg") "/srv/data/image.jpg"

example 2:

Serve guessing the content-type from the extension:

serveFile (guessContentTypeM mimeTypes) "/srv/data/image.jpg"

If the specified path does not exist or is not a file, this function will return mzero.

WARNING: No security checks are performed.

NOTE: alias for serveFileUsing filePathSendFile

returns a specific content type, completely ignoring the FilePath argument.

Use this with serveFile if you want to explicitly specify the content-type.

see also: serveFile

a Map from file extensions to content-types

example:

myMimeMap :: MimeMap
myMimeMap = Map.fromList [("gz","application/x-gzip"), ... ]

see also: mimeTypes

try to guess the content-type of a file based on its extension

defaults to "application/octet-stream" if no match was found.

Useful as an argument to serveFile

see also: serveFile, mimeTypes

Ready collection of common mime types. Except for the first two entries, the mappings come from http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/conf/mime.types?view=co

Monads that also support choice and failure.

The sum of a collection of actions, generalizing concat. As of base 4.8.0.0, msum is just asum, specialized to MonadPlus.