snap-server-1.1.2.1: A web server for the Snap Framework

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 #

Data and services that all HTTP response handlers share.

data PerSessionData #

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

# ServerConfig

emptyServerConfig :: ServerConfig a #

## getters/setters

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 #

# PerSessionData

## getters

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

isNewConnection :: PerSessionData -> IO Bool #

getLocalAddress :: PerSessionData -> ByteString #

getLocalPort :: PerSessionData -> Int #

getRemoteAddress :: PerSessionData -> ByteString #

getRemotePort :: PerSessionData -> Int #

# HTTP lifecycle

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

1. accept a new connection, set it up (e.g. with SSL)
2. create a `PerSessionData` object
3. Enter the `SessionHandler`, which:
4. calls the `NewRequestHook`, making a new hookState object.
5. parses the HTTP request. If the session is over, we stop here.
6. calls the `ParseHook`
7. enters the `ServerHandler`, which is provided by another part of the framework
8. the server handler passes control to the user handler
9. a `Response` is produced, and the `UserHandlerFinishedHook` is called.
10. the `Response` is written to the client
11. the `DataFinishedHook` is called.
12. 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 () #

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

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

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

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

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 () #

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 #

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 () #

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 #

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 #

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 #

# Socket types

data SocketConfig #

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 |