Safe Haskell	None
Language	Haskell2010

Snap.Http.Server.Types

Contents

ServerConfig
- getters/setters
PerSessionData
- getters
HTTP lifecycle
Hooks
Handlers
Socket types

Description

Types used by the Snap HTTP Server.

Synopsis

data ServerConfig hookState
data PerSessionData
emptyServerConfig :: ServerConfig a
getDefaultTimeout :: ServerConfig hookState -> Int
getIsSecure :: ServerConfig hookState -> Bool
getLocalHostname :: ServerConfig hookState -> ByteString
getLogAccess :: ServerConfig hookState -> Request -> Response -> Word64 -> IO ()
getLogError :: ServerConfig hookState -> Builder -> IO ()
getNumAcceptLoops :: ServerConfig hookState -> Int
getOnDataFinished :: ServerConfig hookState -> DataFinishedHook hookState
getOnEscape :: ServerConfig hookState -> EscapeSnapHook hookState
getOnException :: ServerConfig hookState -> ExceptionHook hookState
getOnNewRequest :: ServerConfig hookState -> NewRequestHook hookState
getOnParse :: ServerConfig hookState -> ParseHook hookState
getOnUserHandlerFinished :: ServerConfig hookState -> UserHandlerFinishedHook hookState
setDefaultTimeout :: Int -> ServerConfig hookState -> ServerConfig hookState
setIsSecure :: Bool -> ServerConfig hookState -> ServerConfig hookState
setLocalHostname :: ByteString -> ServerConfig hookState -> ServerConfig hookState
setLogAccess :: (Request -> Response -> Word64 -> IO ()) -> ServerConfig hookState -> ServerConfig hookState
setLogError :: (Builder -> IO ()) -> ServerConfig hookState -> ServerConfig hookState
setNumAcceptLoops :: Int -> ServerConfig hookState -> ServerConfig hookState
setOnDataFinished :: DataFinishedHook hookState -> ServerConfig hookState -> ServerConfig hookState
setOnEscape :: EscapeSnapHook hookState -> ServerConfig hookState -> ServerConfig hookState
setOnException :: ExceptionHook hookState -> ServerConfig hookState -> ServerConfig hookState
setOnNewRequest :: NewRequestHook hookState -> ServerConfig hookState -> ServerConfig hookState
setOnParse :: ParseHook hookState -> ServerConfig hookState -> ServerConfig hookState
setOnUserHandlerFinished :: UserHandlerFinishedHook hookState -> ServerConfig hookState -> ServerConfig hookState
getTwiddleTimeout :: PerSessionData -> (Int -> Int) -> IO ()
isNewConnection :: PerSessionData -> IO Bool
getLocalAddress :: PerSessionData -> ByteString
getLocalPort :: PerSessionData -> Int
getRemoteAddress :: PerSessionData -> ByteString
getRemotePort :: PerSessionData -> Int
type DataFinishedHook hookState = IORef hookState -> Request -> Response -> IO ()
type EscapeSnapHook hookState = IORef hookState -> IO ()
type ExceptionHook hookState = IORef hookState -> SomeException -> IO ()
type ParseHook hookState = IORef hookState -> Request -> IO ()
type NewRequestHook hookState = PerSessionData -> IO hookState
type UserHandlerFinishedHook hookState = IORef hookState -> Request -> Response -> IO ()
type SendFileHandler = Buffer -> Builder -> FilePath -> Word64 -> Word64 -> IO ()
type ServerHandler hookState = ServerConfig hookState -> PerSessionData -> Request -> IO (Request, Response)
data AcceptFunc
data SocketConfig
- = StartListening ByteString Int
- | PreBound Socket

Documentation

data ServerConfig hookState Source #

Data and services that all HTTP response handlers share.

data PerSessionData Source #

All of the things a session needs to service a single HTTP request.

ServerConfig

emptyServerConfig :: ServerConfig a Source #

getters/setters

getDefaultTimeout :: ServerConfig hookState -> Int Source #

getIsSecure :: ServerConfig hookState -> Bool Source #

getLocalHostname :: ServerConfig hookState -> ByteString Source #

getLogAccess :: ServerConfig hookState -> Request -> Response -> Word64 -> IO () Source #

getLogError :: ServerConfig hookState -> Builder -> IO () Source #

getNumAcceptLoops :: ServerConfig hookState -> Int Source #

getOnDataFinished :: ServerConfig hookState -> DataFinishedHook hookState Source #

getOnEscape :: ServerConfig hookState -> EscapeSnapHook hookState Source #

getOnException :: ServerConfig hookState -> ExceptionHook hookState Source #

getOnNewRequest :: ServerConfig hookState -> NewRequestHook hookState Source #

getOnParse :: ServerConfig hookState -> ParseHook hookState Source #

getOnUserHandlerFinished :: ServerConfig hookState -> UserHandlerFinishedHook hookState Source #

setDefaultTimeout :: Int -> ServerConfig hookState -> ServerConfig hookState Source #

setIsSecure :: Bool -> ServerConfig hookState -> ServerConfig hookState Source #

setLocalHostname :: ByteString -> ServerConfig hookState -> ServerConfig hookState Source #

setLogAccess :: (Request -> Response -> Word64 -> IO ()) -> ServerConfig hookState -> ServerConfig hookState Source #

setLogError :: (Builder -> IO ()) -> ServerConfig hookState -> ServerConfig hookState Source #

setNumAcceptLoops :: Int -> ServerConfig hookState -> ServerConfig hookState Source #

setOnDataFinished :: DataFinishedHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

setOnEscape :: EscapeSnapHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

setOnException :: ExceptionHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

setOnNewRequest :: NewRequestHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

setOnParse :: ParseHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

setOnUserHandlerFinished :: UserHandlerFinishedHook hookState -> ServerConfig hookState -> ServerConfig hookState Source #

PerSessionData

getters

getTwiddleTimeout :: PerSessionData -> (Int -> Int) -> IO () Source #

isNewConnection :: PerSessionData -> IO Bool Source #

getLocalAddress :: PerSessionData -> ByteString Source #

getLocalPort :: PerSessionData -> Int Source #

getRemoteAddress :: PerSessionData -> ByteString Source #

getRemotePort :: PerSessionData -> Int Source #

HTTP lifecycle

Request / Response lifecycle for "normal" requests (i.e. without errors):

accept a new connection, set it up (e.g. with SSL)
create a PerSessionData object
Enter the SessionHandler, which:
calls the NewRequestHook, making a new hookState object.
parses the HTTP request. If the session is over, we stop here.
calls the ParseHook
enters the ServerHandler, which is provided by another part of the framework
the server handler passes control to the user handler
a Response is produced, and the UserHandlerFinishedHook is called.
the Response is written to the client
the DataFinishedHook is called.
we go to #3.

Hooks

At various critical points in the HTTP lifecycle, the Snap server will call user-defined "hooks" that can be used for instrumentation or tracing of the process of building the HTTP response. The first hook called, the NewRequestHook, will generate a "hookState" object (having some user-defined abstract type), and this object will be passed to the rest of the hooks as the server handles the process of responding to the HTTP request.

For example, you could pass a set of hooks to the Snap server that measured timings for each URI handled by the server to produce online statistics and metrics using something like statsd (https://github.com/etsy/statsd).

type DataFinishedHook hookState = IORef hookState -> Request -> Response -> IO () Source #

The DataFinishedHook is called once the server has finished sending the HTTP response to the client.

type EscapeSnapHook hookState = IORef hookState -> IO () Source #

The EscapeSnapHook is called if the user handler escapes the HTTP session, e.g. for websockets.

type ExceptionHook hookState = IORef hookState -> SomeException -> IO () Source #

The ExceptionHook is called if an exception reaches the toplevel of the server, i.e. if an exception leaks out of the user handler or if an exception is raised during the sending of the HTTP response data.

type ParseHook hookState = IORef hookState -> Request -> IO () Source #

The ParseHook is called after the HTTP Request has been parsed by the server, but before the user handler starts running.

type NewRequestHook hookState = PerSessionData -> IO hookState Source #

The NewRequestHook is called once processing for an HTTP request begins, i.e. after the connection has been accepted and we know that there's data available to read from the socket. The IORef passed to the hook initially contains a bottom value that will throw an exception if evaluated.

type UserHandlerFinishedHook hookState = IORef hookState -> Request -> Response -> IO () Source #

The UserHandlerFinishedHook is called once the user handler has finished running, but before the data for the HTTP response starts being sent to the client.

Handlers

type SendFileHandler Source #

Arguments

= Buffer	builder buffer
-> Builder	status line and headers
-> FilePath	file to send
-> Word64	start offset
-> Word64	number of bytes
-> IO ()

A SendFileHandler is called if the user handler requests that a file be sent using sendfile() on systems that support it (Linux, Mac OSX, and FreeBSD).

type ServerHandler hookState Source #

Arguments

= ServerConfig hookState	global server config
-> PerSessionData	per-connection data
-> Request	HTTP request object
-> IO (Request, Response)

This function, provided to the web server internals from the outside, is responsible for producing a Response once the server has parsed the Request.

data AcceptFunc Source #

Socket types

data SocketConfig Source #

Either the server should start listening on the given interface / port combination, or the server should start up with a Socket that has already had bind() and listen() called on it.

Constructors

StartListening ByteString Int
PreBound Socket