Servant.Server

This module lets you implement Servers for defined APIs. You'll most likely just need serve.

Run a snap handler from an API

serveSnap :: forall layout m. (HasServer layout '[] m, MonadSnap m) => Proxy layout -> Server layout '[] m -> m ()

serveSnapWithContext :: forall layout context m. (HasServer layout context m, MonadSnap m) => Proxy layout -> Context context -> Server layout context m -> m ()

Handlers for all standard combinators

class HasServer api context (m :: * -> *) where

Minimal complete definition

route

Associated Types

type ServerT api context m :: *

Methods

route :: MonadSnap m => Proxy api -> Context context -> Delayed m env (Server api context m) -> Router m env

Instances

HasServer * Raw context m

Just pass the request to the underlying application and serve its response.

Example:

type MyApi = "images" :> Raw

server :: Server MyApi
server = serveDirectory "/var/www/images"

Associated Types

type ServerT Raw (context :: Raw) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy Raw context -> Context m -> Delayed m env (Server Raw context m m) -> Router m env

(HasServer * a ctx m, HasServer * b ctx m) => HasServer * ((:<|>) a b) ctx m

A server for a :<|> b first tries to match the request against the route represented by a and if it fails tries b. You must provide a request handler for each route.

type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
        :<|> "books" :> ReqBody Book :> Post '[JSON] Book -- POST /books

server :: Server MyApi
server = listAllBooks :<|> postBook
  where listAllBooks = ...
        postBook book = ...

Associated Types

type ServerT (a :<|> b) (ctx :: a :<|> b) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy (a :<|> b) ctx -> Context m -> Delayed m env (Server (a :<|> b) ctx m m) -> Router m env

(HasServer k1 api context m, KnownSymbol realm, HasContextEntry context (BasicAuthCheck m usr)) => HasServer * ((:>) * k1 (BasicAuth realm usr) api) context m

Associated Types

type ServerT ((* :> k1) (BasicAuth realm usr) api) (context :: (* :> k1) (BasicAuth realm usr) api) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (BasicAuth realm usr) api) context -> Context m -> Delayed m env (Server ((* :> k1) (BasicAuth realm usr) api) context m m) -> Router m env

HasServer k1 api context m => HasServer * ((:>) * k1 RemoteHost api) context m

Associated Types

type ServerT ((* :> k1) RemoteHost api) (context :: (* :> k1) RemoteHost api) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) RemoteHost api) context -> Context m -> Delayed m env (Server ((* :> k1) RemoteHost api) context m m) -> Router m env

HasServer k1 api context m => HasServer * ((:>) * k1 IsSecure api) context m

Associated Types

type ServerT ((* :> k1) IsSecure api) (context :: (* :> k1) IsSecure api) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) IsSecure api) context -> Context m -> Delayed m env (Server ((* :> k1) IsSecure api) context m m) -> Router m env

HasServer k1 api context m => HasServer * ((:>) * k1 HttpVersion api) context m

Associated Types

type ServerT ((* :> k1) HttpVersion api) (context :: (* :> k1) HttpVersion api) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) HttpVersion api) context -> Context m -> Delayed m env (Server ((* :> k1) HttpVersion api) context m m) -> Router m env

(AllCTUnrender list a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (ReqBody * list a) sublayout) context m

If you use ReqBody in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by ReqBody. The Content-Type header is inspected, and the list provided is used to attempt deserialization. If the request does not have a Content-Type header, it is treated as application/octet-stream. This lets servant worry about extracting it from the request and turning it into a value of the type you specify.

All it asks is for a FromJSON instance.

Example:

type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book

server :: Server MyApi
server = postBook
  where postBook :: Book -> EitherT ServantErr IO Book
        postBook book = ...insert into your db...

Associated Types

type ServerT ((* :> k1) (ReqBody * list a) sublayout) (context :: (* :> k1) (ReqBody * list a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (ReqBody * list a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (ReqBody * list a) sublayout) context m m) -> Router m env

(KnownSymbol sym, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (QueryFlag sym) sublayout) context m

If you use QueryFlag "published" in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Bool.

Example:

type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooks
  where getBooks :: Bool -> EitherT ServantErr IO [Book]
        getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...

Associated Types

type ServerT ((* :> k1) (QueryFlag sym) sublayout) (context :: (* :> k1) (QueryFlag sym) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (QueryFlag sym) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (QueryFlag sym) sublayout) context m m) -> Router m env

(KnownSymbol sym, FromHttpApiData a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (QueryParams * sym a) sublayout) context m

If you use QueryParams "authors" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type [Text].

This lets servant worry about looking up 0 or more values in the query string associated to authors and turning each of them into a value of the type you specify.

You can control how the individual values are converted from Text to your type by simply providing an instance of FromText for your type.

Example:

type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: [Text] -> EitherT ServantErr IO [Book]
        getBooksBy authors = ...return all books by these authors...

Associated Types

type ServerT ((* :> k1) (QueryParams * sym a) sublayout) (context :: (* :> k1) (QueryParams * sym a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (QueryParams * sym a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (QueryParams * sym a) sublayout) context m m) -> Router m env

(KnownSymbol sym, FromHttpApiData a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (QueryParam * sym a) sublayout) context m

If you use QueryParam "author" Text in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of type Maybe Text.

This lets servant worry about looking it up in the query string and turning it into a value of the type you specify, enclosed in Maybe, because it may not be there and servant would then hand you Nothing.

You can control how it'll be converted from Text to your type by simply providing an instance of FromText for your type.

Example:

type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]

server :: Server MyApi
server = getBooksBy
  where getBooksBy :: Maybe Text -> EitherT ServantErr IO [Book]
        getBooksBy Nothing       = ...return all books...
        getBooksBy (Just author) = ...return books by the given author...

Associated Types

type ServerT ((* :> k1) (QueryParam * sym a) sublayout) (context :: (* :> k1) (QueryParam * sym a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (QueryParam * sym a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (QueryParam * sym a) sublayout) context m m) -> Router m env

(KnownSymbol sym, FromHttpApiData a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (Header sym a) sublayout) context m

If you use Header in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by Header. This lets servant worry about extracting it from the request and turning it into a value of the type you specify.

All it asks is for a FromText instance.

Example:

newtype Referer = Referer Text
  deriving (Eq, Show, FromText, ToText)

           -- GET /view-my-referer
type MyApi = "view-my-referer" :> Header "Referer" Referer :> Get '[JSON] Referer

server :: Server MyApi
server = viewReferer
  where viewReferer :: Referer -> EitherT ServantErr IO referer
        viewReferer referer = return referer

Associated Types

type ServerT ((* :> k1) (Header sym a) sublayout) (context :: (* :> k1) (Header sym a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (Header sym a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (Header sym a) sublayout) context m m) -> Router m env

(FromHttpApiData a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (CaptureAll * capture a) sublayout) context m

Associated Types

type ServerT ((* :> k1) (CaptureAll * capture a) sublayout) (context :: (* :> k1) (CaptureAll * capture a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (CaptureAll * capture a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (CaptureAll * capture a) sublayout) context m m) -> Router m env

(FromHttpApiData a, HasServer k1 sublayout context m) => HasServer * ((:>) * k1 (Capture * capture a) sublayout) context m

If you use Capture in one of the endpoints for your API, this automatically requires your server-side handler to be a function that takes an argument of the type specified by the Capture. This lets servant worry about getting it from the URL and turning it into a value of the type you specify.

You can control how it'll be converted from Text to your type by simply providing an instance of FromText for your type.

Example:

type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book

server :: Server MyApi
server = getBook
  where getBook :: Text -> EitherT ServantErr IO Book
        getBook isbn = ...

Associated Types

type ServerT ((* :> k1) (Capture * capture a) sublayout) (context :: (* :> k1) (Capture * capture a) sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((* :> k1) (Capture * capture a) sublayout) context -> Context m -> Delayed m env (Server ((* :> k1) (Capture * capture a) sublayout) context m m) -> Router m env

(KnownSymbol path, HasServer k1 sublayout context m) => HasServer * ((:>) Symbol k1 path sublayout) context m

Make sure the incoming request starts with "/path", strip it and pass the rest of the request path to sublayout.

Associated Types

type ServerT ((Symbol :> k1) path sublayout) (context :: (Symbol :> k1) path sublayout) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy ((Symbol :> k1) path sublayout) context -> Context m -> Delayed m env (Server ((Symbol :> k1) path sublayout) context m m) -> Router m env

(AllCTRender ctypes a, ReflectMethod k1 method, KnownNat status, GetHeaders (Headers h a)) => HasServer * (Verb k1 * method status ctypes (Headers h a)) context m

Associated Types

type ServerT (Verb k1 * method status ctypes (Headers h a)) (context :: Verb k1 * method status ctypes (Headers h a)) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy (Verb k1 * method status ctypes (Headers h a)) context -> Context m -> Delayed m env (Server (Verb k1 * method status ctypes (Headers h a)) context m m) -> Router m env

(AllCTRender ctypes a, ReflectMethod k1 method, KnownNat status) => HasServer * (Verb k1 * method status ctypes a) context m

Associated Types

type ServerT (Verb k1 * method status ctypes a) (context :: Verb k1 * method status ctypes a) (m :: [*]) (m :: * -> *) :: *

Methods

route :: MonadSnap m => Proxy (Verb k1 * method status ctypes a) context -> Context m -> Delayed m env (Server (Verb k1 * method status ctypes a) context m m) -> Router m env

type Server api context m = ServerT api context m

Reexports

module Servant.Server.Internal.BasicAuth

module Servant.Server.Internal.Context

Basic functions and datatypes

Default error type

data ServantErr

Constructors

ServantErr

Fields

• errHTTPCode :: Int
• errReasonPhrase :: String
• errBody :: ByteString
• errHeaders :: [Header]

Instances

Eq ServantErr

Methods

(==) :: ServantErr -> ServantErr -> Bool

(/=) :: ServantErr -> ServantErr -> Bool

Read ServantErr

Methods

readsPrec :: Int -> ReadS ServantErr

readList :: ReadS [ServantErr]

readPrec :: ReadPrec ServantErr

readListPrec :: ReadPrec [ServantErr]

Show ServantErr

Methods

showsPrec :: Int -> ServantErr -> ShowS

show :: ServantErr -> String

showList :: [ServantErr] -> ShowS

throwError :: MonadSnap m => ServantErr -> m a

Terminate request handling with a ServantErr via finishWith

3XX

err300 :: ServantErr

err301 :: ServantErr

err302 :: ServantErr

err303 :: ServantErr

err304 :: ServantErr

err305 :: ServantErr

err307 :: ServantErr

4XX

err400 :: ServantErr

err401 :: ServantErr

err402 :: ServantErr

err403 :: ServantErr

err404 :: ServantErr

err405 :: ServantErr

err406 :: ServantErr

err407 :: ServantErr

err409 :: ServantErr

err410 :: ServantErr

err411 :: ServantErr

err412 :: ServantErr

err413 :: ServantErr

err414 :: ServantErr

err415 :: ServantErr

err416 :: ServantErr

err417 :: ServantErr

5XX

err500 :: ServantErr

err501 :: ServantErr

err502 :: ServantErr

err503 :: ServantErr

err504 :: ServantErr

err505 :: ServantErr