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

Example:

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

myApi :: Proxy MyApi
myApi = Proxy

app :: Application
app = serve myApi server

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

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/
│  └─ <capture>/
│     ├─•
│     ┆
│     └─•
├─ c/
│  └─•
┆
└─ <raw>

Explanation of symbols:

├

Normal lines reflect static branching via a table.

a/

Nodes reflect static path components.

─•

Leaves reflect endpoints.

<capture>/

This is a delayed capture of a path component.

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

Variant of layout that takes an additional Context.

A natural transformation from m to n. Used to enter particular datatypes.

Like lift.

Like logWriterTSNat, but for strict WriterT.

Log the contents of WriterT with the function provided as the first argument, and return the value of the WriterT computation

Like mmorph's hoist.

Like mmorph's embed.

Like mmorph's squash.

Like mmorph's generalize.

Apply a transformation to the response of a Router.

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 Enter.) 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 heterogenous 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, ()]

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])
...

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.

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

Datatype wrapping a function used to check authentication.

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

The result of authentication/authorization

err300 Multiple Choices

Example:

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

err301 Moved Permanently

Example:

failingHandler :: Handler ()
failingHandler = throwError err301

err302 Found

Example:

failingHandler :: Handler ()
failingHandler = throwError err302

err303 See Other

Example:

failingHandler :: Handler ()
failingHandler = throwError err303

err304 Not Modified

Example:

failingHandler :: Handler ()
failingHandler = throwError err304

err305 Use Proxy

Example:

failingHandler :: Handler ()
failingHandler = throwError err305

err307 Temporary Redirect

Example:

failingHandler :: Handler ()
failingHandler = throwError err307

err400 Bad Request

Example:

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

err401 Unauthorized

Example:

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

err402 Payment Required

Example:

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

err403 Forbidden

Example:

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

err404 Not Found

Example:

failingHandler :: Handler ()
failingHandler = throwError $ err404 { errBody = "(╯°□°）╯︵ ┻━┻)." }

err405 Method Not Allowed

Example:

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

err406 Not Acceptable

Example:

failingHandler :: Handler ()
failingHandler = throwError err406

err407 Proxy Authentication Required

Example:

failingHandler :: Handler ()
failingHandler = throwError err407

err409 Conflict

Example:

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

err410 Gone

Example:

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

err411 Length Required

Example:

failingHandler :: Handler ()
failingHandler = throwError err411

err412 Precondition Failed

Example:

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

err413 Request Entity Too Large

Example:

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

err414 Request-URI Too Large

Example:

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

err415 Unsupported Media Type

Example:

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

err416 Request range not satisfiable

Example:

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

err417 Expectation Failed

Example:

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

err500 Internal Server Error

Example:

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

err501 Not Implemented

Example:

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

err502 Bad Gateway

Example:

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

err503 Service Unavailable

Example:

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

err504 Gateway Time-out

Example:

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

err505 HTTP Version not supported

Example usage:

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

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")