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

Copyright(c) Happstack.com 2010; (c) HAppS Inc 2007
MaintainerHappstack team <happs@googlegroups.com>
PortabilityGHC-only, Windows, Linux, FreeBSD, OS X
Safe HaskellNone




Happstack.Server provides a self-contained HTTP server and a rich collection of types and functions for routing Requests, generating Responses, working with query parameters, form data, and cookies, serving files and more.

A very simple, "Hello World!" web app looks like:

import Happstack.Server
main = simpleHTTP nullConf $ ok "Hello World!"

By default the server will listen on port 8000. Run the app and point your browser at: http://localhost:8000/

At the core of the Happstack server we have the simpleHTTP function which starts the HTTP server:

simpleHTTP :: ToMessage a => Conf -> ServerPart a -> IO ()

and we have the user supplied ServerPart (also known as, ServerPartT IO), which generates a Response for each incoming Request.

A trivial HTTP app server might just take a user supplied function like:

myApp :: Request -> IO Response

For each incoming Request the server would fork a new thread, run myApp to generate a Response, and then send the Response back to the client. But, that would be a pretty barren wasteland to work in.

The model for ServerPart is essential the same, except we use the much richer ServerPart monad instead of the IO monad.

For in-depth documentation and runnable examples I highly recommend The Happstack Crash Course http://happstack.com/docs/crashcourse/index.html.


HTTP Server

parseConfig :: [String] -> Either [String] Conf Source #

Parse command line options into a Conf.

simpleHTTP :: ToMessage a => Conf -> ServerPartT IO a -> IO () Source #

start the server, and handle requests using the supplied ServerPart.

This function will not return, though it may throw an exception.

NOTE: The server will only listen on IPv4 due to portability issues in the Network module. For IPv6 support, use simpleHTTPWithSocket with custom socket.

simpleHTTP' :: (ToMessage b, Monad m, Functor m) => (UnWebT m a -> UnWebT IO b) -> Conf -> ServerPartT m a -> IO () Source #

A combination of simpleHTTP'' and mapServerPartT. See mapServerPartT for a discussion of the first argument of this function.

NOTE: This function always binds to IPv4 ports until Network module is fixed to support IPv6 in a portable way. Use simpleHTTPWithSocket with custom socket if you want different behaviour.

simpleHTTP'' :: (ToMessage b, Monad m, Functor m) => ServerPartT m b -> Request -> m Response Source #

Generate a result from a ServerPartT and a Request. This is mainly used by CGI (and fast-cgi) wrappers.

simpleHTTPWithSocket :: ToMessage a => Socket -> Conf -> ServerPartT IO a -> IO () Source #

Run simpleHTTP with a previously bound socket. Useful if you want to run happstack as user on port 80. Use something like this:

import System.Posix.User (setUserID, UserEntry(..), getUserEntryForName)

main = do
    let conf = nullConf { port = 80 }
    socket <- bindPort conf
    -- do other stuff as root here
    getUserEntryForName "www" >>= setUserID . userID
    -- finally start handling incoming requests
    tid <- forkIO $ simpleHTTPWithSocket socket Nothing conf impl

Note: It's important to use the same conf (or at least the same port) for bindPort and simpleHTTPWithSocket.

see also: bindPort, bindIPv4

simpleHTTPWithSocket' :: (ToMessage b, Monad m, Functor m) => (UnWebT m a -> UnWebT IO b) -> Socket -> Conf -> ServerPartT m a -> IO () Source #

Like simpleHTTP' with a socket.

bindPort :: Conf -> IO Socket Source #

Bind port and return the socket for use with simpleHTTPWithSocket. This function always binds to IPv4 ports until Network module is fixed to support IPv6 in a portable way.

bindIPv4 Source #


:: String

IP address to bind to (must be an IP address and not a host name)

-> Int

port number to bind to

-> IO Socket 

Bind to ip and port and return the socket for use with simpleHTTPWithSocket.

import Happstack.Server

main = do let conf = nullConf
              addr = ""
          s <- bindIPv4 addr (port conf)
          simpleHTTPWithSocket s conf $ ok $ toResponse $
            "now listening on ip addr " ++ addr ++
            " and port " ++ show (port conf)

waitForTermination :: IO () Source #

Wait for a signal. On unix, a signal is sigINT or sigTERM (aka Control-C).

On windows, the signal is entering: e return

Request Routing

Creating Responses

Looking up values in Query String, Request Body, and Cookies

Create and Set Cookies (see also Happstack.Server.RqData)

File Serving

HTTP Realm Authentication

Error Handling


Web-related Monads

Output Validation

HTTP Types