Server type. It is a function fron request to response. Some servers does not return valid value. We use it to find right path.

Example:

server :: Server IO
server =
  "api" /. "v1" /.
     mconcat
       [ "foo" /. (\(Query @"name" arg) -> Get  @Json (handleFoo arg)
       , "bar" /. Post @Json handleBar
       ]

handleFoo :: Int -> IO Text
handleBar :: IO Text

Note that server is monoid and it can be constructed with Monoid functions and path constructor (/.). To pass inputs for handler we can use special newtype wrappers:

• Query - for required query parameters
• Optional - for optional query parameters
• Capture - for parsing elements of URI
• Body - fot JSON-body input
• RawBody - for raw ByteString input
• Header - for headers

To distinguish by HTTP-method we use corresponding constructors: Get, Post, Put, etc. Let's discuss the structure of the constructor. Let's take Get for example:

newtype Get ty m a = Get (m a)

Let's look at the arguments of he type

• ty - type of the response. it can be: Text, Html, Json, ByteString
• m - underlying server monad
• a - result type. It should be convertible to the type of the response.

also result can be wrapped to special data types to modify Http-response. we have wrappers:

• SetStatus - to set status
• AddHeaders - to append headers
• Either (Error err) - to response with errors

Type tag of Json-response.

Get method. Note that we can not use body input with Get-method, use Post for that. So with Get we can use only URI inputs (Query, Optional, Capture)

Post method

Put method

Delete method

Patch method

Options method

Path constructor (right associative). Example:

server :: Server IO
server =
  "api" /. "v1" /.
     mconcat
       [ "foo" /. Get  @Json handleFoo
       , "bar" /. Post @Json handleBar
       ]

handleFoo, handleBar :: IO Text

Mandatary query parameter. Name is encoded as type-level string. Example:

"api" /. handleFoo

handleFoo :: Query "name" Int -> Server IO
handleFoo (Query arg) = ...

Optional query parameter. Name is encoded as type-level string. Example:

"api" /. handleFoo

handleFoo :: Optional "name" -> Server IO
handleFoo (Optional maybeArg) = ...

Reads Json body (lazy). We can limit the body size with server config. Example:

"api" /. "search" /. (\(Body request) -> handleSearch request)

Reads raw body as lazy bytestring. We can limit the body size with server config. Example:

"api" /. "upload" /. (\(RawBody content) -> handleUpload content)

Reads input header. Example:

"api" /. (\(Header @"Trace-Id" traceId) -> Post @Json (handleFoo traceId))

handleFoo :: Maybe ByteString -> IO FooResponse

Parse raw form body. It includes named form arguments and file info. Note that we can not use FormBody and JSON-body at the same time. They occupy the same field in the HTTP-request.

It reads form as plain JSON-object where name of the form's field becomes a field of JSON-object and every value is Text.

For example if submit a form with fields: name, password, date. We can read it in the data type:

data User = User
 { name :: Text
 , passord :: Text
 , date :: Text
 }

Note that we can not use FormBody and JSON-body at the same time. They occupy the same field in the HTTP-request.

Reads current path info

Attach headers to response. It can be used inside any ToXxxResp value. Example:

"api" /. handleFoo

handleFoo :: Get Text IO (AddHeaders Text)
handleFoo = Get $ pure $ AddHeaders headers "Hello foo"

Set status to response. It can be ised inside any ToXxxResp value. Example:

"api" /. handleFoo

handleFoo :: Get Text IO (SetStatus Text)
handleFoo = Get $ pure $ SetStatus status500 "Bad request"

Sets status for response of the server

Adds headers for response of the server

Errors

Handle errors

Run server on port

Server config

Convert server to WAI-application

Class contains types which can be converted to IO-based server to run as with WAI-interface.

We can run plain IO-servers and ReaderT over IO based servers. Readers can be wrapped in newtypes. In that case we can derive automatically HasServer instance.

Render reader server to IO-based server

Values convertible to Text (lazy)

Values convertible to Json

Values convertible to Html

Aything convertible from text

Values convertible to lazy text

Bad request response

Class ToServer contains anything convertible to Server m. We use it for flexuble composition of servers from functions with arbitrary number of arguments. Arguments can be of specific types: Query, Body, Optional, Capture, Header, etc. We use type-level strings to encode query-names. Example:

"api" /. "foo" /.
    (\(Query @"argA" argA) (Optional @"argB" argB) (Body jsonRequest) -> Post @Json $ handleFoo argA argB jsonRequest)

handleFoo :: Int -> Maybe Text -> FooRequest -> IO FooResponse
handleFoo = ...

Note that we can use any amount of arguments. And type of the input is decoded fron newtype wrapper which is used with argument of the handler function.

Also we can return pure errors with Either. Anything which can be returned from function can be wrapped to Either (Error err).

For example in previous case we can use function which returns errors as values:

type ServerError = Error Text

handleFoo :: Int -> Maybe Text -> FooRequest -> IO (Either ServerError FooResponse)
handleFoo = ...

the result of error response is automatically matched with normal response of the server and standard Error type lets us pass status to response and some details.

Appends action to the server