Servant.Client

servant-client-0.20.2: Automatic derivation of querying functions for servant

Safe Haskell | None
Language | Haskell2010

Servant.Client

Description

This module provides `client` which can automatically generate querying functions for each endpoint just from the type representing your API.

Synopsis

- client :: HasClient ClientM api => Proxy api -> Client ClientM api
- data ClientM a
- runClientM :: ClientM a -> ClientEnv -> IO (Either ClientError a)
- data ClientEnv = ClientEnv {
  - manager :: Manager
  - baseUrl :: BaseUrl
  - cookieJar :: Maybe (TVar CookieJar)
  - makeClientRequest :: BaseUrl -> Request -> IO Request
  - middleware :: ClientMiddleware
  }
- mkClientEnv :: Manager -> BaseUrl -> ClientEnv
- defaultMakeClientRequest :: BaseUrl -> Request -> IO Request
- hoistClient :: HasClient ClientM api => Proxy api -> (forall a. m a -> n a) -> Client m api -> Client n api
- module Servant.Client.Core.Reexport

# Documentation

client :: HasClient ClientM api => Proxy api -> Client ClientM api #

Generates a set of client functions for an API.

Example:

    type API = Capture "no" Int :> Get '[JSON] Int
           :<|> Get '[JSON] [Bool]

    api :: Proxy API
    api = Proxy

    getInt :: Int -> ClientM Int
    getBools :: ClientM [Bool]
    getInt :<|> getBools = client api

data ClientM a #

`ClientM` is the monad in which client functions run. Contains the `Manager` and `BaseUrl` used for requests in the reader environment.

#### Instances

Instances details

MonadIO ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods liftIO :: IO a -> ClientM a #
MonadCatch ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods catch :: (HasCallStack, Exception e) => ClientM a -> (e -> ClientM a) -> ClientM a #
MonadMask ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods mask :: HasCallStack => ((forall a. ClientM a -> ClientM a) -> ClientM b) -> ClientM b # uninterruptibleMask :: HasCallStack => ((forall a. ClientM a -> ClientM a) -> ClientM b) -> ClientM b # generalBracket :: HasCallStack => ClientM a -> (a -> ExitCase b -> ClientM c) -> (a -> ClientM b) -> ClientM (b, c) #
MonadThrow ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods throwM :: (HasCallStack, Exception e) => e -> ClientM a #
Applicative ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods pure :: a -> ClientM a # (<*>) :: ClientM (a -> b) -> ClientM a -> ClientM b # liftA2 :: (a -> b -> c) -> ClientM a -> ClientM b -> ClientM c # (*>) :: ClientM a -> ClientM b -> ClientM b # (<*) :: ClientM a -> ClientM b -> ClientM a #
Functor ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods fmap :: (a -> b) -> ClientM a -> ClientM b # (<$) :: a -> ClientM b -> ClientM a #
Monad ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods (>>=) :: ClientM a -> (a -> ClientM b) -> ClientM b # (>>) :: ClientM a -> ClientM b -> ClientM b # return :: a -> ClientM a #
Alt ClientM # | Try clients in order, last error is preserved.
Instance details Defined in Servant.Client.Internal.HttpClient Methods (<!>) :: ClientM a -> ClientM a -> ClientM a # some :: Applicative ClientM => ClientM a -> ClientM [a] # many :: Applicative ClientM => ClientM a -> ClientM [a] #
RunClient ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods runRequestAcceptStatus :: Maybe [Status] -> Request -> ClientM Response # throwClientError :: ClientError -> ClientM a #
MonadBaseControl IO ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Associated Types
type StM ClientM a |
Instance details Defined in Servant.Client.Internal.HttpClient type StM ClientM a = Either ClientError a
Methods liftBaseWith :: (RunInBase ClientM IO -> IO a) -> ClientM a # restoreM :: StM ClientM a -> ClientM a #
MonadError ClientError ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods throwError :: ClientError -> ClientM a # catchError :: ClientM a -> (ClientError -> ClientM a) -> ClientM a #
MonadReader ClientEnv ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods ask :: ClientM ClientEnv # local :: (ClientEnv -> ClientEnv) -> ClientM a -> ClientM a # reader :: (ClientEnv -> a) -> ClientM a #
MonadBase IO ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods liftBase :: IO α -> ClientM α #
Generic (ClientM a) # |
Instance details Defined in Servant.Client.Internal.HttpClient Associated Types
type Rep (ClientM a) |
Instance details Defined in Servant.Client.Internal.HttpClient type Rep (ClientM a) = Rep (ReaderT ClientEnv (ExceptT ClientError IO) a)
Methods from :: ClientM a -> Rep (ClientM a) x # to :: Rep (ClientM a) x -> ClientM a #
type StM ClientM a # |
Instance details Defined in Servant.Client.Internal.HttpClient type StM ClientM a = Either ClientError a
type Rep (ClientM a) # |
Instance details Defined in Servant.Client.Internal.HttpClient type Rep (ClientM a) = Rep (ReaderT ClientEnv (ExceptT ClientError IO) a)

runClientM :: ClientM a -> ClientEnv -> IO (Either ClientError a) #

data ClientEnv #

The environment in which a request is run. The `baseUrl` and `makeClientRequest` function are used to create a `http-client` request. Cookies are then added to that request if a `CookieJar` is set on the environment. Finally the request is executed with the `manager`. The `makeClientRequest` function can be used to modify the request to execute and set values which are not specified on a `servant` `Request` like `responseTimeout` or `redirectCount`

Constructors

ClientEnv |
Fields manager :: Manager baseUrl :: BaseUrl cookieJar :: Maybe (TVar CookieJar) makeClientRequest :: BaseUrl -> Request -> IO Request this function can be used to customize the creation of `http-client` requests from `servant` requests. Default value: `defaultMakeClientRequest` Note that: 1. `makeClientRequest` exists to allow overriding operational semantics e.g. `responseTimeout` per request, If you need global modifications, you should use `managerModifyRequest` 2. the `cookieJar`, if defined, is being applied after `makeClientRequest` is called. middleware :: ClientMiddleware

#### Instances

Instances details

MonadReader ClientEnv ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient Methods ask :: ClientM ClientEnv # local :: (ClientEnv -> ClientEnv) -> ClientM a -> ClientM a # reader :: (ClientEnv -> a) -> ClientM a #
MonadReader ClientEnv ClientM # |
Instance details Defined in Servant.Client.Internal.HttpClient.Streaming Methods ask :: ClientM ClientEnv # local :: (ClientEnv -> ClientEnv) -> ClientM a -> ClientM a # reader :: (ClientEnv -> a) -> ClientM a #

mkClientEnv :: Manager -> BaseUrl -> ClientEnv #

`ClientEnv` smart constructor.

defaultMakeClientRequest :: BaseUrl -> Request -> IO Request #

Create a `http-client` `Request` from a `servant` `Request` The `host`, `path` and `port` fields are extracted from the `BaseUrl` otherwise the body, headers and query string are derived from the `servant` `Request`

hoistClient :: HasClient ClientM api => Proxy api -> (forall a. m a -> n a) -> Client m api -> Client n api #

Change the monad the client functions live in, by supplying a conversion function (a natural transformation to be precise).

For example, assuming you have some `manager :: `Manager`` and `baseurl :: `BaseUrl`` around:

    type API = Get '[JSON] Int :<|> Capture "n" Int :> Post '[JSON] Int
    api :: Proxy API
    api = Proxy
    getInt :: IO Int
    postInt :: Int -> IO Int
    getInt :<|> postInt = hoistClient api (flip runClientM cenv) (client api)
      where cenv = mkClientEnv manager baseurl

module Servant.Client.Core.Reexport