Documentation

Creates http-client from server definition.

The result adapts to decalred types. It creates so many client functions as the arity of the tuple in the result. The server can have more handlers than in the result Routes from result definition and server definition are matched in the same order as they are declared.

The type of the client is derived from the type signature of the result. The information on paths for handlers is derived from server definition.

To use the same code for both client and server it is convenient to declare signatures for handlers as type synonyms parameterized by server monad. And in the server implementation monad is going to be something IO-based but in client handlers it will be Client-monad.

For example for a server:

type Hello m = Capture "name" Text -> Get m (Resp Text)
type Add m = Query "a" Int -> Query "b" Int -> Get m (Resp Int)

server :: Server IO
server = "api" /.
  mconcat
   [ "hello" /. helloHandler
   , "add" /. addHandler
   ]

helloHandler :: Hello IO
helloHandler (Capture name) = Send $ pure $ ok $ "Hello " <> name

addHandler :: Add IO
addHandler (Query a) (Query b) = Send $ pure $ ok (a + b)

We can define the client and reuse type signatures that we have defined in the server code:

helloClient :: Hello Client
addClient :: Add Client

helloClient :| addClient = toClient server

If there is no definition for server. For example if we write implementation for some external server or API provided by third party we can use recursive definition in the server. For example if there is no haskell implementation for the server in the previous example. But we know the API of the application we can define client with recursive definition:

type Hello m = Capture "name" Text -> Get m (Resp Text)
type Add m = Query "a" Int -> Query "b" Int -> Get m (Resp Int)

helloClient :: Hello Client
addClient :: Add Client

helloClient :| addClient = toClient server

server :: Server Client
server = "api" /.
  mconcat
   [ "hello" /. helloClient
   , "add" /. addClient
   ]

The code does not get stuck into recursion loop because implementation of the route handlers is not needed to create client functions. The function toClient takes into account only type-signatures of the handlers and paths.

The client monad. All errors are unified to Lazy.ByteString.

Config to run the clients

Runs client. It calls client handler and fetches the result.

Infix synonym for pair. It can be useful to stack together many client functions in the output of toClient function.

Class to strip away all newtype wrappers that serve for API-definition. For example it converts the types signature for client function:

Capture "foo" Text -> Header "bar" Int -> Get Client (Resp a)

to the version without HTTP-newtype wrappers:

Text -> Int -> Client' (Resp a)

The instances are defined for all HTTP-newtype wrappers. Also we can use function getRespOrValue if we do not need the http information of response.

If we need only value from the server and not HTTP-info (status, or headers) we can omit that data with this function

ClientConfig in ReaderT IO monad. It encapsulates typical execution of client functions

Runs the client call

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Helper type-synonym for convenience