Servant.Server

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

Run a wai application from an API

serve :: HasServer api '[] => Proxy api -> Server api -> Application

serve allows you to implement an API and produce a wai Application.

Example:

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

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

myApi :: Proxy MyApi
myApi = Proxy

app :: Application
app = serve myApi server

main :: IO ()
main = Network.Wai.Handler.Warp.run 8080 app

serveWithContext :: (HasServer api context, ServerContext context) => Proxy api -> Context context -> Server api -> Application

Like serve, but allows you to pass custom context.

defaultErrorFormatters will always be appended to the end of the passed context, but if you pass your own formatter, it will override the default one.

serveWithContextT :: forall api context m. (HasServer api context, ServerContext context) => Proxy api -> Context context -> (forall x. m x -> Handler x) -> ServerT api m -> Application

A general serve function that allows you to pass a custom context and hoisting function to apply on all routes.

type ServerContext context = HasContextEntry (context .++ DefaultErrorFormatters) ErrorFormatters

Constraints that need to be satisfied on a context for it to be passed to serveWithContext.

Typically, this will add default context entries to the context. You shouldn't typically need to worry about these constraints, but if you write a helper function that wraps serveWithContext, you might need to include this constraint.

Construct a wai Application from an API

toApplication :: RoutingApplication -> Application

Handlers for all standard combinators

class HasServer api context where

Associated Types

type ServerT api (m :: * -> *) :: *

The type of a server for this API, given a monad to run effects in.

Note that the result kind is *, so it is not a monad transformer, unlike what the T in the name might suggest.

Methods

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

hoistServerWithContext :: Proxy api -> Proxy context -> (forall x. m x -> n x) -> ServerT api m -> ServerT api n

Instances

HasServer EmptyAPI context

The server for an EmptyAPI is emptyServer.

type MyApi = "nothing" :> EmptyApi

server :: Server MyApi
server = emptyServer

Defined in Servant.Server.Internal

Associated Types

type ServerT EmptyAPI m

Methods

route :: Proxy EmptyAPI -> Context context -> Delayed env (Server EmptyAPI) -> Router env

hoistServerWithContext :: Proxy EmptyAPI -> Proxy context -> (forall x. m x -> n x) -> ServerT EmptyAPI m -> ServerT EmptyAPI n

HasServer Raw context

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"

Defined in Servant.Server.Internal

Associated Types

type ServerT Raw m

Methods

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

hoistServerWithContext :: Proxy Raw -> Proxy context -> (forall x. m x -> n x) -> ServerT Raw m -> ServerT Raw n

HasServer RawM context

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"

Defined in Servant.Server.Internal

Associated Types

type ServerT RawM m

Methods

route :: Proxy RawM -> Context context -> Delayed env (Server RawM) -> Router env

hoistServerWithContext :: Proxy RawM -> Proxy context -> (forall x. m x -> n x) -> ServerT RawM m -> ServerT RawM n

(TypeError (NoInstanceFor (HasServer api context)) :: Constraint) => HasServer (api :: k) context

Defined in Servant.Server.Internal

Associated Types

type ServerT api m

Methods

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

hoistServerWithContext :: Proxy api -> Proxy context -> (forall x. m x -> n x) -> ServerT api m -> ServerT api n

(HasServer (ToServantApi api) context, forall (m :: Type -> Type). Generic (api (AsServerT m)), forall (m :: Type -> Type). GServer api m, ErrorIfNoGeneric api) => HasServer (NamedRoutes api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (NamedRoutes api) m

Methods

route :: Proxy (NamedRoutes api) -> Context context -> Delayed env (Server (NamedRoutes api)) -> Router env

hoistServerWithContext :: Proxy (NamedRoutes api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (NamedRoutes api) m -> ServerT (NamedRoutes api) n

(HasServer a context, HasServer b context) => HasServer (a :<|> b :: Type) context

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

Defined in Servant.Server.Internal

Associated Types

type ServerT (a :<|> b) m

Methods

route :: Proxy (a :<|> b) -> Context context -> Delayed env (Server (a :<|> b)) -> Router env

hoistServerWithContext :: Proxy (a :<|> b) -> Proxy context -> (forall x. m x -> n x) -> ServerT (a :<|> b) m -> ServerT (a :<|> b) n

ReflectMethod method => HasServer (NoContentVerb method :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (NoContentVerb method) m

Methods

route :: Proxy (NoContentVerb method) -> Context context -> Delayed env (Server (NoContentVerb method)) -> Router env

hoistServerWithContext :: Proxy (NoContentVerb method) -> Proxy context -> (forall x. m x -> n x) -> ServerT (NoContentVerb method) m -> ServerT (NoContentVerb method) n

(TypeError (HasServerArrowTypeError a b) :: Constraint) => HasServer (a -> b :: Type) context

This instance prevents from accidentally using -> instead of :>

>>> serve (Proxy :: Proxy (Capture "foo" Int -> Get '[JSON] Int)) (error "...")
...
...No instance HasServer (a -> b).
...Maybe you have used '->' instead of ':>' between
...Capture' '[] "foo" Int
...and
...Verb 'GET 200 '[JSON] Int
...

>>> undefined :: Server (Capture "foo" Int -> Get '[JSON] Int)
...
...No instance HasServer (a -> b).
...Maybe you have used '->' instead of ':>' between
...Capture' '[] "foo" Int
...and
...Verb 'GET 200 '[JSON] Int
...

Defined in Servant.Server.Internal

Associated Types

type ServerT (a -> b) m

Methods

route :: Proxy (a -> b) -> Context context -> Delayed env (Server (a -> b)) -> Router env

hoistServerWithContext :: Proxy (a -> b) -> Proxy context -> (forall x. m x -> n x) -> ServerT (a -> b) m -> ServerT (a -> b) n

(TypeError (PartialApplication (HasServer :: k -> [Type] -> Constraint) arr) :: Constraint) => HasServer (arr :> sub :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (arr :> sub) m

Methods

route :: Proxy (arr :> sub) -> Context context -> Delayed env (Server (arr :> sub)) -> Router env

hoistServerWithContext :: Proxy (arr :> sub) -> Proxy context -> (forall x. m x -> n x) -> ServerT (arr :> sub) m -> ServerT (arr :> sub) n

HasServer api context => HasServer (Vault :> api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (Vault :> api) m

Methods

route :: Proxy (Vault :> api) -> Context context -> Delayed env (Server (Vault :> api)) -> Router env

hoistServerWithContext :: Proxy (Vault :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Vault :> api) m -> ServerT (Vault :> api) n

(KnownSymbol path, HasServer api context) => HasServer (path :> api :: Type) context

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

Defined in Servant.Server.Internal

Associated Types

type ServerT (path :> api) m

Methods

route :: Proxy (path :> api) -> Context context -> Delayed env (Server (path :> api)) -> Router env

hoistServerWithContext :: Proxy (path :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (path :> api) m -> ServerT (path :> api) n

HasServer api context => HasServer (HttpVersion :> api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (HttpVersion :> api) m

Methods

route :: Proxy (HttpVersion :> api) -> Context context -> Delayed env (Server (HttpVersion :> api)) -> Router env

hoistServerWithContext :: Proxy (HttpVersion :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (HttpVersion :> api) m -> ServerT (HttpVersion :> api) n

(KnownSymbol realm, HasServer api context, HasContextEntry context (BasicAuthCheck usr)) => HasServer (BasicAuth realm usr :> api :: Type) context

Basic Authentication

Defined in Servant.Server.Internal

Associated Types

type ServerT (BasicAuth realm usr :> api) m

Methods

route :: Proxy (BasicAuth realm usr :> api) -> Context context -> Delayed env (Server (BasicAuth realm usr :> api)) -> Router env

hoistServerWithContext :: Proxy (BasicAuth realm usr :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (BasicAuth realm usr :> api) m -> ServerT (BasicAuth realm usr :> api) n

(KnownSymbol capture, FromHttpApiData a, Typeable a, HasServer api context, SBoolI (FoldLenient mods), HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (Capture' mods capture a :> api :: Type) context

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 FromHttpApiData for your type.

Example:

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

server :: Server MyApi
server = getBook
  where getBook :: Text -> Handler Book
        getBook isbn = ...

Defined in Servant.Server.Internal

Associated Types

type ServerT (Capture' mods capture a :> api) m

Methods

route :: Proxy (Capture' mods capture a :> api) -> Context context -> Delayed env (Server (Capture' mods capture a :> api)) -> Router env

hoistServerWithContext :: Proxy (Capture' mods capture a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Capture' mods capture a :> api) m -> ServerT (Capture' mods capture a :> api) n

(KnownSymbol capture, FromHttpApiData a, Typeable a, HasServer api context, HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (CaptureAll capture a :> api :: Type) context

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

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

Example:

type MyApi = "src" :> CaptureAll "segments" Text :> Get '[JSON] SourceFile

server :: Server MyApi
server = getSourceFile
  where getSourceFile :: [Text] -> Handler Book
        getSourceFile pathSegments = ...

Defined in Servant.Server.Internal

Associated Types

type ServerT (CaptureAll capture a :> api) m

Methods

route :: Proxy (CaptureAll capture a :> api) -> Context context -> Delayed env (Server (CaptureAll capture a :> api)) -> Router env

hoistServerWithContext :: Proxy (CaptureAll capture a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (CaptureAll capture a :> api) m -> ServerT (CaptureAll capture a :> api) n

HasServer api ctx => HasServer (Description desc :> api :: Type) ctx

Ignore Description in server handlers.

Defined in Servant.Server.Internal

Associated Types

type ServerT (Description desc :> api) m

Methods

route :: Proxy (Description desc :> api) -> Context ctx -> Delayed env (Server (Description desc :> api)) -> Router env

hoistServerWithContext :: Proxy (Description desc :> api) -> Proxy ctx -> (forall x. m x -> n x) -> ServerT (Description desc :> api) m -> ServerT (Description desc :> api) n

HasServer api ctx => HasServer (Summary desc :> api :: Type) ctx

Ignore Summary in server handlers.

Defined in Servant.Server.Internal

Associated Types

type ServerT (Summary desc :> api) m

Methods

route :: Proxy (Summary desc :> api) -> Context ctx -> Delayed env (Server (Summary desc :> api)) -> Router env

hoistServerWithContext :: Proxy (Summary desc :> api) -> Proxy ctx -> (forall x. m x -> n x) -> ServerT (Summary desc :> api) m -> ServerT (Summary desc :> api) n

(HasServer api context, HasContextEntry context (AuthHandler Request (AuthServerData (AuthProtect tag)))) => HasServer (AuthProtect tag :> api :: Type) context

Known orphan instance.

Defined in Servant.Server.Experimental.Auth

Associated Types

type ServerT (AuthProtect tag :> api) m

Methods

route :: Proxy (AuthProtect tag :> api) -> Context context -> Delayed env (Server (AuthProtect tag :> api)) -> Router env

hoistServerWithContext :: Proxy (AuthProtect tag :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (AuthProtect tag :> api) m -> ServerT (AuthProtect tag :> api) n

(AtLeastOneFragment api, FragmentUnique (Fragment a1 :> api), HasServer api context) => HasServer (Fragment a1 :> api :: Type) context

Ignore Fragment in server handlers. See https://ietf.org/rfc/rfc2616.html#section-15.1.3 for more details.

Example:

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

server :: Server MyApi
server = getBooks
  where getBooks :: Handler [Book]
        getBooks = ...return all books...

Defined in Servant.Server.Internal

Associated Types

type ServerT (Fragment a1 :> api) m

Methods

route :: Proxy (Fragment a1 :> api) -> Context context -> Delayed env (Server (Fragment a1 :> api)) -> Router env

hoistServerWithContext :: Proxy (Fragment a1 :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Fragment a1 :> api) m -> ServerT (Fragment a1 :> api) n

(KnownSymbol sym, FromHttpApiData a, HasServer api context, SBoolI (FoldRequired mods), SBoolI (FoldLenient mods), HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (Header' mods sym a :> api :: Type) context

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 FromHttpApiData instance.

Example:

newtype Referer = Referer Text
  deriving (Eq, Show, FromHttpApiData)

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

server :: Server MyApi
server = viewReferer
  where viewReferer :: Referer -> Handler referer
        viewReferer referer = return referer

Defined in Servant.Server.Internal

Associated Types

type ServerT (Header' mods sym a :> api) m

Methods

route :: Proxy (Header' mods sym a :> api) -> Context context -> Delayed env (Server (Header' mods sym a :> api)) -> Router env

hoistServerWithContext :: Proxy (Header' mods sym a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Header' mods sym a :> api) m -> ServerT (Header' mods sym a :> api) n

HasServer api context => HasServer (IsSecure :> api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (IsSecure :> api) m

Methods

route :: Proxy (IsSecure :> api) -> Context context -> Delayed env (Server (IsSecure :> api)) -> Router env

hoistServerWithContext :: Proxy (IsSecure :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (IsSecure :> api) m -> ServerT (IsSecure :> api) n

(KnownSymbol sym, HasServer api context) => HasServer (QueryFlag sym :> api :: Type) context

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 -> Handler [Book]
        getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...

Defined in Servant.Server.Internal

Associated Types

type ServerT (QueryFlag sym :> api) m

Methods

route :: Proxy (QueryFlag sym :> api) -> Context context -> Delayed env (Server (QueryFlag sym :> api)) -> Router env

hoistServerWithContext :: Proxy (QueryFlag sym :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (QueryFlag sym :> api) m -> ServerT (QueryFlag sym :> api) n

(KnownSymbol sym, FromHttpApiData a, HasServer api context, SBoolI (FoldRequired mods), SBoolI (FoldLenient mods), HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (QueryParam' mods sym a :> api :: Type) context

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 FromHttpApiData for your type.

Example:

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

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

Defined in Servant.Server.Internal

Associated Types

type ServerT (QueryParam' mods sym a :> api) m

Methods

route :: Proxy (QueryParam' mods sym a :> api) -> Context context -> Delayed env (Server (QueryParam' mods sym a :> api)) -> Router env

hoistServerWithContext :: Proxy (QueryParam' mods sym a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (QueryParam' mods sym a :> api) m -> ServerT (QueryParam' mods sym a :> api) n

(KnownSymbol sym, FromHttpApiData a, HasServer api context, HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (QueryParams sym a :> api :: Type) context

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 FromHttpApiData for your type.

Example:

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

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

Defined in Servant.Server.Internal

Associated Types

type ServerT (QueryParams sym a :> api) m

Methods

route :: Proxy (QueryParams sym a :> api) -> Context context -> Delayed env (Server (QueryParams sym a :> api)) -> Router env

hoistServerWithContext :: Proxy (QueryParams sym a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (QueryParams sym a :> api) m -> ServerT (QueryParams sym a :> api) n

HasServer api context => HasServer (RemoteHost :> api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (RemoteHost :> api) m

Methods

route :: Proxy (RemoteHost :> api) -> Context context -> Delayed env (Server (RemoteHost :> api)) -> Router env

hoistServerWithContext :: Proxy (RemoteHost :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (RemoteHost :> api) m -> ServerT (RemoteHost :> api) n

(AllCTUnrender list a, HasServer api context, SBoolI (FoldLenient mods), HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters) => HasServer (ReqBody' mods list a :> api :: Type) context

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 (as specified in RFC 7231 section 3.1.1.5). 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 -> Handler Book
        postBook book = ...insert into your db...

Defined in Servant.Server.Internal

Associated Types

type ServerT (ReqBody' mods list a :> api) m

Methods

route :: Proxy (ReqBody' mods list a :> api) -> Context context -> Delayed env (Server (ReqBody' mods list a :> api)) -> Router env

hoistServerWithContext :: Proxy (ReqBody' mods list a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (ReqBody' mods list a :> api) m -> ServerT (ReqBody' mods list a :> api) n

(FramingUnrender framing, FromSourceIO chunk a, MimeUnrender ctype chunk, HasServer api context) => HasServer (StreamBody' mods framing ctype a :> api :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (StreamBody' mods framing ctype a :> api) m

Methods

route :: Proxy (StreamBody' mods framing ctype a :> api) -> Context context -> Delayed env (Server (StreamBody' mods framing ctype a :> api)) -> Router env

hoistServerWithContext :: Proxy (StreamBody' mods framing ctype a :> api) -> Proxy context -> (forall x. m x -> n x) -> ServerT (StreamBody' mods framing ctype a :> api) m -> ServerT (StreamBody' mods framing ctype a :> api) n

(HasServer api ctx, HasContextEntry ctx (Acquire a)) => HasServer (WithResource a :> api :: Type) ctx

If you use WithResource in one of the endpoints for your API Servant will provide the handler for this endpoint an argument of the specified type. The lifespan of this resource will be automatically managed by Servant. This resource will be created before the handler starts and it will be destoyed after it ends. A new resource is created for each request to the endpoint.

Defined in Servant.Server.Internal

Associated Types

type ServerT (WithResource a :> api) m

Methods

route :: Proxy (WithResource a :> api) -> Context ctx -> Delayed env (Server (WithResource a :> api)) -> Router env

hoistServerWithContext :: Proxy (WithResource a :> api) -> Proxy ctx -> (forall x. m x -> n x) -> ServerT (WithResource a :> api) m -> ServerT (WithResource a :> api) n

(TypeError (NoInstanceForSub (HasServer :: k2 -> [Type] -> Constraint) ty) :: Constraint) => HasServer (ty :> sub :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (ty :> sub) m

Methods

route :: Proxy (ty :> sub) -> Context context -> Delayed env (Server (ty :> sub)) -> Router env

hoistServerWithContext :: Proxy (ty :> sub) -> Proxy context -> (forall x. m x -> n x) -> ServerT (ty :> sub) m -> ServerT (ty :> sub) n

(ReflectMethod method, AllMime contentTypes, All (IsServerResourceWithStatus contentTypes) as, Unique (Statuses as)) => HasServer (UVerb method contentTypes as :: Type) context

Defined in Servant.Server.UVerb

Associated Types

type ServerT (UVerb method contentTypes as) m

Methods

route :: Proxy (UVerb method contentTypes as) -> Context context -> Delayed env (Server (UVerb method contentTypes as)) -> Router env

hoistServerWithContext :: Proxy (UVerb method contentTypes as) -> Proxy context -> (forall x. m x -> n x) -> ServerT (UVerb method contentTypes as) m -> ServerT (UVerb method contentTypes as) n

(HasContextEntry context (NamedContext name subContext), HasServer subApi subContext) => HasServer (WithNamedContext name subContext subApi :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (WithNamedContext name subContext subApi) m

Methods

route :: Proxy (WithNamedContext name subContext subApi) -> Context context -> Delayed env (Server (WithNamedContext name subContext subApi)) -> Router env

hoistServerWithContext :: Proxy (WithNamedContext name subContext subApi) -> Proxy context -> (forall x. m x -> n x) -> ServerT (WithNamedContext name subContext subApi) m -> ServerT (WithNamedContext name subContext subApi) n

(AllCTRender ctypes a, ReflectMethod method, KnownNat status, GetHeaders (Headers h a)) => HasServer (Verb method status ctypes (Headers h a) :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (Verb method status ctypes (Headers h a)) m

Methods

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

hoistServerWithContext :: Proxy (Verb method status ctypes (Headers h a)) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Verb method status ctypes (Headers h a)) m -> ServerT (Verb method status ctypes (Headers h a)) n

(AllCTRender ctypes a, ReflectMethod method, KnownNat status) => HasServer (Verb method status ctypes a :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (Verb method status ctypes a) m

Methods

route :: Proxy (Verb method status ctypes a) -> Context context -> Delayed env (Server (Verb method status ctypes a)) -> Router env

hoistServerWithContext :: Proxy (Verb method status ctypes a) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Verb method status ctypes a) m -> ServerT (Verb method status ctypes a) n

(MimeRender ctype chunk, ReflectMethod method, KnownNat status, FramingRender framing, ToSourceIO chunk a, GetHeaders (Headers h a)) => HasServer (Stream method status framing ctype (Headers h a) :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (Stream method status framing ctype (Headers h a)) m

Methods

route :: Proxy (Stream method status framing ctype (Headers h a)) -> Context context -> Delayed env (Server (Stream method status framing ctype (Headers h a))) -> Router env

hoistServerWithContext :: Proxy (Stream method status framing ctype (Headers h a)) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Stream method status framing ctype (Headers h a)) m -> ServerT (Stream method status framing ctype (Headers h a)) n

(MimeRender ctype chunk, ReflectMethod method, KnownNat status, FramingRender framing, ToSourceIO chunk a) => HasServer (Stream method status framing ctype a :: Type) context

Defined in Servant.Server.Internal

Associated Types

type ServerT (Stream method status framing ctype a) m

Methods

route :: Proxy (Stream method status framing ctype a) -> Context context -> Delayed env (Server (Stream method status framing ctype a)) -> Router env

hoistServerWithContext :: Proxy (Stream method status framing ctype a) -> Proxy context -> (forall x. m x -> n x) -> ServerT (Stream method status framing ctype a) m -> ServerT (Stream method status framing ctype a) n

type Server api = ServerT api Handler

data EmptyServer

Singleton type representing a server that serves an empty API.

Instances

Bounded EmptyServer

Defined in Servant.Server.Internal

Methods

minBound :: EmptyServer

maxBound :: EmptyServer

Enum EmptyServer

Defined in Servant.Server.Internal

Methods

succ :: EmptyServer -> EmptyServer

pred :: EmptyServer -> EmptyServer

toEnum :: Int -> EmptyServer

fromEnum :: EmptyServer -> Int

enumFrom :: EmptyServer -> [EmptyServer]

enumFromThen :: EmptyServer -> EmptyServer -> [EmptyServer]

enumFromTo :: EmptyServer -> EmptyServer -> [EmptyServer]

enumFromThenTo :: EmptyServer -> EmptyServer -> EmptyServer -> [EmptyServer]

Show EmptyServer

Defined in Servant.Server.Internal

Methods

showsPrec :: Int -> EmptyServer -> ShowS

show :: EmptyServer -> String

showList :: [EmptyServer] -> ShowS

Eq EmptyServer

Defined in Servant.Server.Internal

Methods

(==) :: EmptyServer -> EmptyServer -> Bool

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

emptyServer :: ServerT EmptyAPI m

Server for EmptyAPI

newtype Handler a

Constructors

Handler

Fields

• runHandler' :: ExceptT ServerError IO a

Instances

MonadFail Handler

Defined in Servant.Server.Internal.Handler

Methods

fail :: String -> Handler a

MonadIO Handler

Defined in Servant.Server.Internal.Handler

Methods

liftIO :: IO a -> Handler a

Applicative Handler

Defined in Servant.Server.Internal.Handler

Methods

pure :: a -> Handler a

(<*>) :: Handler (a -> b) -> Handler a -> Handler b

liftA2 :: (a -> b -> c) -> Handler a -> Handler b -> Handler c

(*>) :: Handler a -> Handler b -> Handler b

(<*) :: Handler a -> Handler b -> Handler a

Functor Handler

Defined in Servant.Server.Internal.Handler

Methods

fmap :: (a -> b) -> Handler a -> Handler b

(<$) :: a -> Handler b -> Handler a

Monad Handler

Defined in Servant.Server.Internal.Handler

Methods

(>>=) :: Handler a -> (a -> Handler b) -> Handler b

(>>) :: Handler a -> Handler b -> Handler b

return :: a -> Handler a

MonadCatch Handler

Defined in Servant.Server.Internal.Handler

Methods

catch :: Exception e => Handler a -> (e -> Handler a) -> Handler a

MonadMask Handler

Defined in Servant.Server.Internal.Handler

Methods

mask :: ((forall a. Handler a -> Handler a) -> Handler b) -> Handler b

uninterruptibleMask :: ((forall a. Handler a -> Handler a) -> Handler b) -> Handler b

generalBracket :: Handler a -> (a -> ExitCase b -> Handler c) -> (a -> Handler b) -> Handler (b, c)

MonadThrow Handler

Defined in Servant.Server.Internal.Handler

Methods

throwM :: Exception e => e -> Handler a

MonadBaseControl IO Handler

Defined in Servant.Server.Internal.Handler

Associated Types

type StM Handler a

Methods

liftBaseWith :: (RunInBase Handler IO -> IO a) -> Handler a

restoreM :: StM Handler a -> Handler a

MonadError ServerError Handler

Defined in Servant.Server.Internal.Handler

Methods

throwError :: ServerError -> Handler a

catchError :: Handler a -> (ServerError -> Handler a) -> Handler a

MonadBase IO Handler

Defined in Servant.Server.Internal.Handler

Methods

liftBase :: IO α -> Handler α

Generic (Handler a)

Defined in Servant.Server.Internal.Handler

Associated Types

type Rep (Handler a) :: Type -> Type

Methods

from :: Handler a -> Rep (Handler a) x

to :: Rep (Handler a) x -> Handler a

type StM Handler a

Defined in Servant.Server.Internal.Handler

type StM Handler a = Either ServerError a

type Rep (Handler a)

Defined in Servant.Server.Internal.Handler

type Rep (Handler a) = D1 ('MetaData "Handler" "Servant.Server.Internal.Handler" "servant-server-0.20-Ke8t2mWvR03Cf4fvKIQLiS" 'True) (C1 ('MetaCons "Handler" 'PrefixI 'True) (S1 ('MetaSel ('Just "runHandler'") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ExceptT ServerError IO a))))

runHandler :: Handler a -> IO (Either ServerError a)

Debugging the server layout

layout :: HasServer api '[] => Proxy api -> Text

The function layout produces a textual description of the internal router layout for debugging purposes. Note that the router layout is determined just by the API, not by the handlers.

Example:

For the following API

type API =
       "a" :> "d" :> Get '[JSON] NoContent
  :<|> "b" :> Capture "x" Int :> Get '[JSON] Bool
  :<|> "c" :> Put '[JSON] Bool
  :<|> "a" :> "e" :> Get '[JSON] Int
  :<|> "b" :> Capture "x" Int :> Put '[JSON] Bool
  :<|> Raw

we get the following output:

/
├─ a/
│  ├─ d/
│  │  └─•
│  └─ e/
│     └─•
├─ b/
│  └─ <x::Int>/
│     ├─•
│     ┆
│     └─•
├─ c/
│  └─•
┆
└─ <raw>

Explanation of symbols:

├

Normal lines reflect static branching via a table.

a/

Nodes reflect static path components.

─•

Leaves reflect endpoints.

<x::Int>/

This is a delayed capture of a single path component named x, of expected type Int.

<raw>

This is a part of the API we do not know anything about.

┆

Dashed lines suggest a dynamic choice between the part above and below. If there is a success for fatal failure in the first part, that one takes precedence. If both parts fail, the "better" error code will be returned.

layoutWithContext :: HasServer api context => Proxy api -> Context context -> Text

Variant of layout that takes an additional Context.

Enter / hoisting server

hoistServer :: HasServer api '[] => Proxy api -> (forall x. m x -> n x) -> ServerT api m -> ServerT api n

Hoist server implementation.

Sometimes our cherished Handler monad isn't quite the type you'd like for your handlers. Maybe you want to thread some configuration in a Reader monad. Or have your types ensure that your handlers don't do any IO. Use hoistServer (a successor of now deprecated enter).

With hoistServer, you can provide a function, to convert any number of endpoints from one type constructor to another. For example

Note: Server Raw can also be entered. It will be retagged.

>>> import Control.Monad.Reader
>>> type ReaderAPI = "ep1" :> Get '[JSON] Int :<|> "ep2" :> Get '[JSON] String :<|> Raw :<|> EmptyAPI
>>> let readerApi = Proxy :: Proxy ReaderAPI
>>> let readerServer = return 1797 :<|> ask :<|> Tagged (error "raw server") :<|> emptyServer :: ServerT ReaderAPI (Reader String)
>>> let nt x = return (runReader x "hi")
>>> let mainServer = hoistServer readerApi nt readerServer :: Server ReaderAPI

Functions based on mmorph

tweakResponse :: (RouteResult Response -> RouteResult Response) -> Router env -> Router env

Apply a transformation to the response of a Router.

Context

data Context contextTypes where

Contexts are used to pass values to combinators. (They are not meant to be used to pass parameters to your handlers, i.e. they should not replace any custom ReaderT-monad-stack that you're using with hoistServer.) If you don't use combinators that require any context entries, you can just use serve as always.

If you are using combinators that require a non-empty Context you have to use serveWithContext and pass it a Context that contains all the values your combinators need. A Context is essentially a heterogeneous list and accessing the elements is being done by type (see getContextEntry). The parameter of the type Context is a type-level list reflecting the types of the contained context entries. To create a Context with entries, use the operator (:.):

>>> :type True :. () :. EmptyContext
True :. () :. EmptyContext :: Context '[Bool, ()]

Constructors

EmptyContext :: Context '[]

(:.) :: x -> Context xs -> Context (x ': xs) infixr 5

Instances

(Show a, Show (Context as)) => Show (Context (a ': as))

Defined in Servant.Server.Internal.Context

Methods

showsPrec :: Int -> Context (a ': as) -> ShowS

show :: Context (a ': as) -> String

showList :: [Context (a ': as)] -> ShowS

Show (Context ('[] :: [Type]))

Defined in Servant.Server.Internal.Context

Methods

showsPrec :: Int -> Context '[] -> ShowS

show :: Context '[] -> String

showList :: [Context '[]] -> ShowS

(Eq a, Eq (Context as)) => Eq (Context (a ': as))

Defined in Servant.Server.Internal.Context

Methods

(==) :: Context (a ': as) -> Context (a ': as) -> Bool

(/=) :: Context (a ': as) -> Context (a ': as) -> Bool

Eq (Context ('[] :: [Type]))

Defined in Servant.Server.Internal.Context

Methods

(==) :: Context '[] -> Context '[] -> Bool

(/=) :: Context '[] -> Context '[] -> Bool

class HasContextEntry (context :: [*]) (val :: *) where

This class is used to access context entries in Contexts. getContextEntry returns the first value where the type matches:

>>> getContextEntry (True :. False :. EmptyContext) :: Bool
True

If the Context does not contain an entry of the requested type, you'll get an error:

>>> getContextEntry (True :. False :. EmptyContext) :: String
...
...No instance for ...HasContextEntry '[] [Char]...
...

Methods

getContextEntry :: Context context -> val

Instances

HasContextEntry xs val => HasContextEntry (notIt ': xs) val

Defined in Servant.Server.Internal.Context

Methods

getContextEntry :: Context (notIt ': xs) -> val

HasContextEntry (val ': xs) val

Defined in Servant.Server.Internal.Context

Methods

getContextEntry :: Context (val ': xs) -> val

type family (l1 :: [*]) .++ (l2 :: [*]) where ...

Append two type-level lists.

Hint: import it as

import Servant.Server (type (.++))

Equations

'[] .++ a = a

(a ': as) .++ b = a ': (as .++ b)

(.++) :: Context l1 -> Context l2 -> Context (l1 .++ l2)

Append two contexts.

NamedContext

data NamedContext (name :: Symbol) (subContext :: [*])

Normally context entries are accessed by their types. In case you need to have multiple values of the same type in your Context and need to access them, we provide NamedContext. You can think of it as sub-namespaces for Contexts.

Constructors

NamedContext (Context subContext)

descendIntoNamedContext :: forall context name subContext. HasContextEntry context (NamedContext name subContext) => Proxy (name :: Symbol) -> Context context -> Context subContext

descendIntoNamedContext allows you to access NamedContexts. Usually you won't have to use it yourself but instead use a combinator like WithNamedContext.

This is how descendIntoNamedContext works:

>>> :set -XFlexibleContexts
>>> let subContext = True :. EmptyContext
>>> :type subContext
subContext :: Context '[Bool]
>>> let parentContext = False :. (NamedContext subContext :: NamedContext "subContext" '[Bool]) :. EmptyContext
>>> :type parentContext
parentContext :: Context '[Bool, NamedContext "subContext" '[Bool]]
>>> descendIntoNamedContext (Proxy :: Proxy "subContext") parentContext :: Context '[Bool]
True :. EmptyContext

Basic Authentication

newtype BasicAuthCheck usr

Datatype wrapping a function used to check authentication.

Constructors

BasicAuthCheck

Fields

• unBasicAuthCheck :: BasicAuthData -> IO (BasicAuthResult usr)

Instances

Functor BasicAuthCheck

Defined in Servant.Server.Internal.BasicAuth

Methods

fmap :: (a -> b) -> BasicAuthCheck a -> BasicAuthCheck b

(<$) :: a -> BasicAuthCheck b -> BasicAuthCheck a

Generic (BasicAuthCheck usr)

Defined in Servant.Server.Internal.BasicAuth

Associated Types

type Rep (BasicAuthCheck usr) :: Type -> Type

Methods

from :: BasicAuthCheck usr -> Rep (BasicAuthCheck usr) x

to :: Rep (BasicAuthCheck usr) x -> BasicAuthCheck usr

type Rep (BasicAuthCheck usr)

Defined in Servant.Server.Internal.BasicAuth

type Rep (BasicAuthCheck usr) = D1 ('MetaData "BasicAuthCheck" "Servant.Server.Internal.BasicAuth" "servant-server-0.20-Ke8t2mWvR03Cf4fvKIQLiS" 'True) (C1 ('MetaCons "BasicAuthCheck" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasicAuthCheck") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (BasicAuthData -> IO (BasicAuthResult usr)))))

data BasicAuthResult usr

servant-server's current implementation of basic authentication is not immune to certain kinds of timing attacks. Decoding payloads does not take a fixed amount of time.

The result of authentication/authorization

Constructors

Unauthorized

BadPassword

NoSuchUser

Authorized usr

Instances

Functor BasicAuthResult

Defined in Servant.Server.Internal.BasicAuth

Methods

fmap :: (a -> b) -> BasicAuthResult a -> BasicAuthResult b

(<$) :: a -> BasicAuthResult b -> BasicAuthResult a

Generic (BasicAuthResult usr)

Defined in Servant.Server.Internal.BasicAuth

Associated Types

type Rep (BasicAuthResult usr) :: Type -> Type

Methods

from :: BasicAuthResult usr -> Rep (BasicAuthResult usr) x

to :: Rep (BasicAuthResult usr) x -> BasicAuthResult usr

Read usr => Read (BasicAuthResult usr)

Defined in Servant.Server.Internal.BasicAuth

Methods

readsPrec :: Int -> ReadS (BasicAuthResult usr)

readList :: ReadS [BasicAuthResult usr]

readPrec :: ReadPrec (BasicAuthResult usr)

readListPrec :: ReadPrec [BasicAuthResult usr]

Show usr => Show (BasicAuthResult usr)

Defined in Servant.Server.Internal.BasicAuth

Methods

showsPrec :: Int -> BasicAuthResult usr -> ShowS

show :: BasicAuthResult usr -> String

showList :: [BasicAuthResult usr] -> ShowS

Eq usr => Eq (BasicAuthResult usr)

Defined in Servant.Server.Internal.BasicAuth

Methods

(==) :: BasicAuthResult usr -> BasicAuthResult usr -> Bool

(/=) :: BasicAuthResult usr -> BasicAuthResult usr -> Bool

type Rep (BasicAuthResult usr)

Defined in Servant.Server.Internal.BasicAuth

type Rep (BasicAuthResult usr) = D1 ('MetaData "BasicAuthResult" "Servant.Server.Internal.BasicAuth" "servant-server-0.20-Ke8t2mWvR03Cf4fvKIQLiS" 'False) ((C1 ('MetaCons "Unauthorized" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "BadPassword" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "NoSuchUser" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Authorized" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 usr))))

General Authentication

Default error type

data ServerError

Constructors

ServerError

Fields

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

Instances

Exception ServerError

Defined in Servant.Server.Internal.ServerError

Methods

toException :: ServerError -> SomeException

fromException :: SomeException -> Maybe ServerError

displayException :: ServerError -> String

Read ServerError

Defined in Servant.Server.Internal.ServerError

Methods

readsPrec :: Int -> ReadS ServerError

readList :: ReadS [ServerError]

readPrec :: ReadPrec ServerError

readListPrec :: ReadPrec [ServerError]

Show ServerError

Defined in Servant.Server.Internal.ServerError

Methods

showsPrec :: Int -> ServerError -> ShowS

show :: ServerError -> String

showList :: [ServerError] -> ShowS

Eq ServerError

Defined in Servant.Server.Internal.ServerError

Methods

(==) :: ServerError -> ServerError -> Bool

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

MonadError ServerError Handler

Defined in Servant.Server.Internal.Handler

Methods

throwError :: ServerError -> Handler a

catchError :: Handler a -> (ServerError -> Handler a) -> Handler a

3XX

err300 :: ServerError

err300 Multiple Choices

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err300 { errBody = "I can't choose." }

err301 :: ServerError

err301 Moved Permanently

Example:

failingHandler :: Handler ()
failingHandler = throwError err301

err302 :: ServerError

err302 Found

Example:

failingHandler :: Handler ()
failingHandler = throwError err302

err303 :: ServerError

err303 See Other

Example:

failingHandler :: Handler ()
failingHandler = throwError err303

err304 :: ServerError

err304 Not Modified

Example:

failingHandler :: Handler ()
failingHandler = throwError err304

err305 :: ServerError

err305 Use Proxy

Example:

failingHandler :: Handler ()
failingHandler = throwError err305

err307 :: ServerError

err307 Temporary Redirect

Example:

failingHandler :: Handler ()
failingHandler = throwError err307

4XX

err400 :: ServerError

err400 Bad Request

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err400 { errBody = "Your request makes no sense to me." }

err401 :: ServerError

err401 Unauthorized

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err401 { errBody = "Your credentials are invalid." }

err402 :: ServerError

err402 Payment Required

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err402 { errBody = "You have 0 credits. Please give me $$$." }

err403 :: ServerError

err403 Forbidden

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err403 { errBody = "Please login first." }

err404 :: ServerError

err404 Not Found

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err404 { errBody = "Are you lost?" }

err405 :: ServerError

err405 Method Not Allowed

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err405 { errBody = "Your account privileges does not allow for this.  Please pay $$$." }

err406 :: ServerError

err406 Not Acceptable

Example:

failingHandler :: Handler ()
failingHandler = throwError err406

err407 :: ServerError

err407 Proxy Authentication Required

Example:

failingHandler :: Handler ()
failingHandler = throwError err407

err409 :: ServerError

err409 Conflict

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err409 { errBody = "Transaction conflicts with 59879cb56c7c159231eeacdd503d755f7e835f74" }

err410 :: ServerError

err410 Gone

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err410 { errBody = "I know it was here at some point, but.. I blame bad luck." }

err411 :: ServerError

err411 Length Required

Example:

failingHandler :: Handler ()
failingHandler = throwError err411

err412 :: ServerError

err412 Precondition Failed

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err412 { errBody = "Precondition fail: x < 42 && y > 57" }

err413 :: ServerError

err413 Request Entity Too Large

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err413 { errBody = "Request exceeded 64k." }

err414 :: ServerError

err414 Request-URI Too Large

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err414 { errBody = "Maximum length is 64." }

err415 :: ServerError

err415 Unsupported Media Type

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err415 { errBody = "Supported media types:  gif, png" }

err416 :: ServerError

err416 Request range not satisfiable

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err416 { errBody = "Valid range is [0, 424242]." }

err417 :: ServerError

err417 Expectation Failed

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err417 { errBody = "I found a quux in the request.  This isn't going to work." }

err418 :: ServerError

err418 Expectation Failed

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err418 { errBody = "Apologies, this is not a webserver but a teapot." }

err422 :: ServerError

err422 Unprocessable Entity

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err422 { errBody = "I understood your request, but can't process it." }

5XX

err500 :: ServerError

err500 Internal Server Error

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err500 { errBody = "Exception in module A.B.C:55.  Have a great day!" }

err501 :: ServerError

err501 Not Implemented

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err501 { errBody = "/v1/foo is not supported with quux in the request." }

err502 :: ServerError

err502 Bad Gateway

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err502 { errBody = "Tried gateway foo, bar, and baz.  None responded." }

err503 :: ServerError

err503 Service Unavailable

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err503 { errBody = "We're rewriting in PHP." }

err504 :: ServerError

err504 Gateway Time-out

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err504 { errBody = "Backend foobar did not respond in 5 seconds." }

err505 :: ServerError

err505 HTTP Version not supported

Example usage:

failingHandler :: Handler ()
failingHandler = throwError $ err505 { errBody = "I support HTTP/4.0 only." }

Formatting of errors from combinators

You can configure how Servant will render errors that occur while parsing the request.

type ErrorFormatter = TypeRep -> Request -> String -> ServerError

A custom formatter for errors produced by parsing combinators like ReqBody or Capture.

A TypeRep argument described the concrete combinator that raised the error, allowing formatter to customize the message for different combinators.

A full Request is also passed so that the formatter can react to Accept header, for example.

type NotFoundErrorFormatter = Request -> ServerError

This formatter does not get neither TypeRep nor error message.

data ErrorFormatters

A collection of error formatters for different situations.

If you need to override one of them, use defaultErrorFormatters with record update syntax.

bodyParserErrorFormatter :: ErrorFormatters -> ErrorFormatter

Format error from parsing the request body.

urlParseErrorFormatter :: ErrorFormatters -> ErrorFormatter

Format error from parsing url parts or query parameters.

headerParseErrorFormatter :: ErrorFormatters -> ErrorFormatter

Format error from parsing request headers.

notFoundErrorFormatter :: ErrorFormatters -> NotFoundErrorFormatter

Format error for not found URLs.

type DefaultErrorFormatters = '[ErrorFormatters]

Context that contains default error formatters.

defaultErrorFormatters :: ErrorFormatters

Default formatters will just return HTTP 400 status code with error message as response body.

getAcceptHeader :: Request -> AcceptHeader

Re-exports

type Application = Request -> (Response -> IO ResponseReceived) -> IO ResponseReceived

The WAI application.

Note that, since WAI 3.0, this type is structured in continuation passing style to allow for proper safe resource handling. This was handled in the past via other means (e.g., ResourceT). As a demonstration:

app :: Application
app req respond = bracket_
    (putStrLn "Allocating scarce resource")
    (putStrLn "Cleaning up")
    (respond $ responseLBS status200 [] "Hello World")

newtype Tagged (s :: k) b

A Tagged s b value is a value b with an attached phantom type s. This can be used in place of the more traditional but less safe idiom of passing in an undefined value with the type, because unlike an (s -> b), a Tagged s b can't try to use the argument s as a real value.

Moreover, you don't have to rely on the compiler to inline away the extra argument, because the newtype is "free"

Tagged has kind k -> * -> * if the compiler supports PolyKinds, therefore there is an extra k showing in the instance haddocks that may cause confusion.

Constructors

Tagged

Fields

• unTagged :: b

Instances

Bifoldable (Tagged :: TYPE LiftedRep -> Type -> Type)

Defined in Data.Tagged

Methods

bifold :: Monoid m => Tagged m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Tagged a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Tagged a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Tagged a b -> c

Bifunctor (Tagged :: Type -> Type -> Type)

Defined in Data.Tagged

Methods

bimap :: (a -> b) -> (c -> d) -> Tagged a c -> Tagged b d

first :: (a -> b) -> Tagged a c -> Tagged b c

second :: (b -> c) -> Tagged a b -> Tagged a c

Bitraversable (Tagged :: Type -> Type -> Type)

Defined in Data.Tagged

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Tagged a b -> f (Tagged c d)

Eq2 (Tagged :: Type -> Type -> Type)

Defined in Data.Tagged

Methods

liftEq2 :: (a -> b -> Bool) -> (c -> d -> Bool) -> Tagged a c -> Tagged b d -> Bool

Ord2 (Tagged :: Type -> Type -> Type)

Defined in Data.Tagged

Methods

liftCompare2 :: (a -> b -> Ordering) -> (c -> d -> Ordering) -> Tagged a c -> Tagged b d -> Ordering

Read2 (Tagged :: Type -> Type -> Type)

Defined in Data.Tagged

Methods

liftReadsPrec2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> Int -> ReadS (Tagged a b)

liftReadList2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> ReadS [Tagged a b]

liftReadPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec (Tagged a b)

liftReadListPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec [Tagged a b]

Show2 (Tagged :: TYPE LiftedRep -> Type -> Type)

Defined in Data.Tagged

Methods

liftShowsPrec2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> Int -> Tagged a b -> ShowS

liftShowList2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> [Tagged a b] -> ShowS

Generic1 (Tagged s :: Type -> Type)

Defined in Data.Tagged

Associated Types

type Rep1 (Tagged s) :: k -> Type

Methods

from1 :: forall (a :: k). Tagged s a -> Rep1 (Tagged s) a

to1 :: forall (a :: k). Rep1 (Tagged s) a -> Tagged s a

Foldable (Tagged s)

Defined in Data.Tagged

Methods

fold :: Monoid m => Tagged s m -> m

foldMap :: Monoid m => (a -> m) -> Tagged s a -> m

foldMap' :: Monoid m => (a -> m) -> Tagged s a -> m

foldr :: (a -> b -> b) -> b -> Tagged s a -> b

foldr' :: (a -> b -> b) -> b -> Tagged s a -> b

foldl :: (b -> a -> b) -> b -> Tagged s a -> b

foldl' :: (b -> a -> b) -> b -> Tagged s a -> b

foldr1 :: (a -> a -> a) -> Tagged s a -> a

foldl1 :: (a -> a -> a) -> Tagged s a -> a

toList :: Tagged s a -> [a]

null :: Tagged s a -> Bool

length :: Tagged s a -> Int

elem :: Eq a => a -> Tagged s a -> Bool

maximum :: Ord a => Tagged s a -> a

minimum :: Ord a => Tagged s a -> a

sum :: Num a => Tagged s a -> a

product :: Num a => Tagged s a -> a

Eq1 (Tagged s)

Defined in Data.Tagged

Methods

liftEq :: (a -> b -> Bool) -> Tagged s a -> Tagged s b -> Bool

Ord1 (Tagged s)

Defined in Data.Tagged

Methods

liftCompare :: (a -> b -> Ordering) -> Tagged s a -> Tagged s b -> Ordering

Read1 (Tagged s)

Defined in Data.Tagged

Methods

liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (Tagged s a)

liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [Tagged s a]

liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (Tagged s a)

liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [Tagged s a]

Show1 (Tagged s)

Defined in Data.Tagged

Methods

liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> Tagged s a -> ShowS

liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [Tagged s a] -> ShowS

Traversable (Tagged s)

Defined in Data.Tagged

Methods

traverse :: Applicative f => (a -> f b) -> Tagged s a -> f (Tagged s b)

sequenceA :: Applicative f => Tagged s (f a) -> f (Tagged s a)

mapM :: Monad m => (a -> m b) -> Tagged s a -> m (Tagged s b)

sequence :: Monad m => Tagged s (m a) -> m (Tagged s a)

Applicative (Tagged s)

Defined in Data.Tagged

Methods

pure :: a -> Tagged s a

(<*>) :: Tagged s (a -> b) -> Tagged s a -> Tagged s b

liftA2 :: (a -> b -> c) -> Tagged s a -> Tagged s b -> Tagged s c

(*>) :: Tagged s a -> Tagged s b -> Tagged s b

(<*) :: Tagged s a -> Tagged s b -> Tagged s a

Functor (Tagged s)

Defined in Data.Tagged

Methods

fmap :: (a -> b) -> Tagged s a -> Tagged s b

(<$) :: a -> Tagged s b -> Tagged s a

Monad (Tagged s)

Defined in Data.Tagged

Methods

(>>=) :: Tagged s a -> (a -> Tagged s b) -> Tagged s b

(>>) :: Tagged s a -> Tagged s b -> Tagged s b

return :: a -> Tagged s a

(Data s, Data b) => Data (Tagged s b)

Defined in Data.Tagged

Methods

gfoldl :: (forall d b0. Data d => c (d -> b0) -> d -> c b0) -> (forall g. g -> c g) -> Tagged s b -> c (Tagged s b)

gunfold :: (forall b0 r. Data b0 => c (b0 -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Tagged s b)

toConstr :: Tagged s b -> Constr

dataTypeOf :: Tagged s b -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Tagged s b))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Tagged s b))

gmapT :: (forall b0. Data b0 => b0 -> b0) -> Tagged s b -> Tagged s b

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Tagged s b -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Tagged s b -> r

gmapQ :: (forall d. Data d => d -> u) -> Tagged s b -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Tagged s b -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Tagged s b -> m (Tagged s b)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Tagged s b -> m (Tagged s b)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Tagged s b -> m (Tagged s b)

IsString a => IsString (Tagged s a)

Defined in Data.Tagged

Methods

fromString :: String -> Tagged s a

Storable a => Storable (Tagged s a)

Defined in Data.Tagged

Methods

sizeOf :: Tagged s a -> Int

alignment :: Tagged s a -> Int

peekElemOff :: Ptr (Tagged s a) -> Int -> IO (Tagged s a)

pokeElemOff :: Ptr (Tagged s a) -> Int -> Tagged s a -> IO ()

peekByteOff :: Ptr b -> Int -> IO (Tagged s a)

pokeByteOff :: Ptr b -> Int -> Tagged s a -> IO ()

peek :: Ptr (Tagged s a) -> IO (Tagged s a)

poke :: Ptr (Tagged s a) -> Tagged s a -> IO ()

(Semigroup a, Monoid a) => Monoid (Tagged s a)

Defined in Data.Tagged

Methods

mempty :: Tagged s a

mappend :: Tagged s a -> Tagged s a -> Tagged s a

mconcat :: [Tagged s a] -> Tagged s a

Semigroup a => Semigroup (Tagged s a)

Defined in Data.Tagged

Methods

(<>) :: Tagged s a -> Tagged s a -> Tagged s a

sconcat :: NonEmpty (Tagged s a) -> Tagged s a

stimes :: Integral b => b -> Tagged s a -> Tagged s a

Bits a => Bits (Tagged s a)

Defined in Data.Tagged

Methods

(.&.) :: Tagged s a -> Tagged s a -> Tagged s a

(.|.) :: Tagged s a -> Tagged s a -> Tagged s a

xor :: Tagged s a -> Tagged s a -> Tagged s a

complement :: Tagged s a -> Tagged s a

shift :: Tagged s a -> Int -> Tagged s a

rotate :: Tagged s a -> Int -> Tagged s a

zeroBits :: Tagged s a

bit :: Int -> Tagged s a

setBit :: Tagged s a -> Int -> Tagged s a

clearBit :: Tagged s a -> Int -> Tagged s a

complementBit :: Tagged s a -> Int -> Tagged s a

testBit :: Tagged s a -> Int -> Bool

bitSizeMaybe :: Tagged s a -> Maybe Int

bitSize :: Tagged s a -> Int

isSigned :: Tagged s a -> Bool

shiftL :: Tagged s a -> Int -> Tagged s a

unsafeShiftL :: Tagged s a -> Int -> Tagged s a

shiftR :: Tagged s a -> Int -> Tagged s a

unsafeShiftR :: Tagged s a -> Int -> Tagged s a

rotateL :: Tagged s a -> Int -> Tagged s a

rotateR :: Tagged s a -> Int -> Tagged s a

popCount :: Tagged s a -> Int

FiniteBits a => FiniteBits (Tagged s a)

Defined in Data.Tagged

Methods

finiteBitSize :: Tagged s a -> Int

countLeadingZeros :: Tagged s a -> Int

countTrailingZeros :: Tagged s a -> Int

Bounded b => Bounded (Tagged s b)

Defined in Data.Tagged

Methods

minBound :: Tagged s b

maxBound :: Tagged s b

Enum a => Enum (Tagged s a)

Defined in Data.Tagged

Methods

succ :: Tagged s a -> Tagged s a

pred :: Tagged s a -> Tagged s a

toEnum :: Int -> Tagged s a

fromEnum :: Tagged s a -> Int

enumFrom :: Tagged s a -> [Tagged s a]

enumFromThen :: Tagged s a -> Tagged s a -> [Tagged s a]

enumFromTo :: Tagged s a -> Tagged s a -> [Tagged s a]

enumFromThenTo :: Tagged s a -> Tagged s a -> Tagged s a -> [Tagged s a]

Floating a => Floating (Tagged s a)

Defined in Data.Tagged

Methods

pi :: Tagged s a

exp :: Tagged s a -> Tagged s a

log :: Tagged s a -> Tagged s a

sqrt :: Tagged s a -> Tagged s a

(**) :: Tagged s a -> Tagged s a -> Tagged s a

logBase :: Tagged s a -> Tagged s a -> Tagged s a

sin :: Tagged s a -> Tagged s a

cos :: Tagged s a -> Tagged s a

tan :: Tagged s a -> Tagged s a

asin :: Tagged s a -> Tagged s a

acos :: Tagged s a -> Tagged s a

atan :: Tagged s a -> Tagged s a

sinh :: Tagged s a -> Tagged s a

cosh :: Tagged s a -> Tagged s a

tanh :: Tagged s a -> Tagged s a

asinh :: Tagged s a -> Tagged s a

acosh :: Tagged s a -> Tagged s a

atanh :: Tagged s a -> Tagged s a

log1p :: Tagged s a -> Tagged s a

expm1 :: Tagged s a -> Tagged s a

log1pexp :: Tagged s a -> Tagged s a

log1mexp :: Tagged s a -> Tagged s a

RealFloat a => RealFloat (Tagged s a)

Defined in Data.Tagged

Methods

floatRadix :: Tagged s a -> Integer

floatDigits :: Tagged s a -> Int

floatRange :: Tagged s a -> (Int, Int)

decodeFloat :: Tagged s a -> (Integer, Int)

encodeFloat :: Integer -> Int -> Tagged s a

exponent :: Tagged s a -> Int

significand :: Tagged s a -> Tagged s a

scaleFloat :: Int -> Tagged s a -> Tagged s a

isNaN :: Tagged s a -> Bool

isInfinite :: Tagged s a -> Bool

isDenormalized :: Tagged s a -> Bool

isNegativeZero :: Tagged s a -> Bool

isIEEE :: Tagged s a -> Bool

atan2 :: Tagged s a -> Tagged s a -> Tagged s a

Generic (Tagged s b)

Defined in Data.Tagged

Associated Types

type Rep (Tagged s b) :: Type -> Type

Methods

from :: Tagged s b -> Rep (Tagged s b) x

to :: Rep (Tagged s b) x -> Tagged s b

Ix b => Ix (Tagged s b)

Defined in Data.Tagged

Methods

range :: (Tagged s b, Tagged s b) -> [Tagged s b]

index :: (Tagged s b, Tagged s b) -> Tagged s b -> Int

unsafeIndex :: (Tagged s b, Tagged s b) -> Tagged s b -> Int

inRange :: (Tagged s b, Tagged s b) -> Tagged s b -> Bool

rangeSize :: (Tagged s b, Tagged s b) -> Int

unsafeRangeSize :: (Tagged s b, Tagged s b) -> Int

Num a => Num (Tagged s a)

Defined in Data.Tagged

Methods

(+) :: Tagged s a -> Tagged s a -> Tagged s a

(-) :: Tagged s a -> Tagged s a -> Tagged s a

(*) :: Tagged s a -> Tagged s a -> Tagged s a

negate :: Tagged s a -> Tagged s a

abs :: Tagged s a -> Tagged s a

signum :: Tagged s a -> Tagged s a

fromInteger :: Integer -> Tagged s a

Read b => Read (Tagged s b)

Defined in Data.Tagged

Methods

readsPrec :: Int -> ReadS (Tagged s b)

readList :: ReadS [Tagged s b]

readPrec :: ReadPrec (Tagged s b)

readListPrec :: ReadPrec [Tagged s b]

Fractional a => Fractional (Tagged s a)

Defined in Data.Tagged

Methods

(/) :: Tagged s a -> Tagged s a -> Tagged s a

recip :: Tagged s a -> Tagged s a

fromRational :: Rational -> Tagged s a

Integral a => Integral (Tagged s a)

Defined in Data.Tagged

Methods

quot :: Tagged s a -> Tagged s a -> Tagged s a

rem :: Tagged s a -> Tagged s a -> Tagged s a

div :: Tagged s a -> Tagged s a -> Tagged s a

mod :: Tagged s a -> Tagged s a -> Tagged s a

quotRem :: Tagged s a -> Tagged s a -> (Tagged s a, Tagged s a)

divMod :: Tagged s a -> Tagged s a -> (Tagged s a, Tagged s a)

toInteger :: Tagged s a -> Integer

Real a => Real (Tagged s a)

Defined in Data.Tagged

Methods

toRational :: Tagged s a -> Rational

RealFrac a => RealFrac (Tagged s a)

Defined in Data.Tagged

Methods

properFraction :: Integral b => Tagged s a -> (b, Tagged s a)

truncate :: Integral b => Tagged s a -> b

round :: Integral b => Tagged s a -> b

ceiling :: Integral b => Tagged s a -> b

floor :: Integral b => Tagged s a -> b

Show b => Show (Tagged s b)

Defined in Data.Tagged

Methods

showsPrec :: Int -> Tagged s b -> ShowS

show :: Tagged s b -> String

showList :: [Tagged s b] -> ShowS

NFData b => NFData (Tagged s b)

Defined in Data.Tagged

Methods

rnf :: Tagged s b -> ()

Eq b => Eq (Tagged s b)

Defined in Data.Tagged

Methods

(==) :: Tagged s b -> Tagged s b -> Bool

(/=) :: Tagged s b -> Tagged s b -> Bool

Ord b => Ord (Tagged s b)

Defined in Data.Tagged

Methods

compare :: Tagged s b -> Tagged s b -> Ordering

(<) :: Tagged s b -> Tagged s b -> Bool

(<=) :: Tagged s b -> Tagged s b -> Bool

(>) :: Tagged s b -> Tagged s b -> Bool

(>=) :: Tagged s b -> Tagged s b -> Bool

max :: Tagged s b -> Tagged s b -> Tagged s b

min :: Tagged s b -> Tagged s b -> Tagged s b

FromFormKey a => FromFormKey (Tagged b a)

Defined in Web.Internal.FormUrlEncoded

Methods

parseFormKey :: Text -> Either Text (Tagged b a)

ToFormKey a => ToFormKey (Tagged b a)

Defined in Web.Internal.FormUrlEncoded

Methods

toFormKey :: Tagged b a -> Text

FromHttpApiData a => FromHttpApiData (Tagged b a)

Note: this instance is not polykinded

Defined in Web.Internal.HttpApiData

Methods

parseUrlPiece :: Text -> Either Text (Tagged b a)

parseHeader :: ByteString -> Either Text (Tagged b a)

parseQueryParam :: Text -> Either Text (Tagged b a)

ToHttpApiData a => ToHttpApiData (Tagged b a)

Note: this instance is not polykinded

Defined in Web.Internal.HttpApiData

Methods

toUrlPiece :: Tagged b a -> Text

toEncodedUrlPiece :: Tagged b a -> Builder

toHeader :: Tagged b a -> ByteString

toQueryParam :: Tagged b a -> Text

toEncodedQueryParam :: Tagged b a -> Builder

type Rep1 (Tagged s :: Type -> Type)

Defined in Data.Tagged

type Rep1 (Tagged s :: Type -> Type) = D1 ('MetaData "Tagged" "Data.Tagged" "tagged-0.8.7-CfQyyzPJiVxDvLyBwZ09N0" 'True) (C1 ('MetaCons "Tagged" 'PrefixI 'True) (S1 ('MetaSel ('Just "unTagged") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))

type Rep (Tagged s b)

Defined in Data.Tagged

type Rep (Tagged s b) = D1 ('MetaData "Tagged" "Data.Tagged" "tagged-0.8.7-CfQyyzPJiVxDvLyBwZ09N0" 'True) (C1 ('MetaCons "Tagged" 'PrefixI 'True) (S1 ('MetaSel ('Just "unTagged") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 b)))

module Servant.Server.UVerb