Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
Functions to create http-clients from the same code as server or API schema
Synopsis
- class MapRequest a => ToClient a where
- toClient :: Server m -> a
- clientArity :: Int
- newtype Client a = Client (ClientConfig -> CaptureMap -> Request -> IO (RespOr AnyMedia ByteString a))
- data ClientConfig = ClientConfig {}
- runClient :: ClientConfig -> Client a -> IO (RespOr AnyMedia ByteString a)
- data a :| b = a :| b
- class FromClient a where
- type ClientResult a :: Type
- fromClient :: a -> ClientResult a
- getRespOrValue :: RespOr media ByteString a -> Either ByteString a
- newtype Client' a = Client' (ReaderT ClientConfig IO a)
- runClient' :: ClientConfig -> Client' a -> IO a
- class Monad m => MonadIO (m :: Type -> Type) where
- type ClientOr a = Client' (Either ByteString a)
Documentation
class MapRequest a => ToClient a where Source #
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.
toClient :: Server m -> a Source #
converts to client function
clientArity :: Int Source #
how many routes client has
Instances
The client monad. All errors are unified to Lazy.ByteString.
Client (ClientConfig -> CaptureMap -> Request -> IO (RespOr AnyMedia ByteString a)) |
Instances
MonadIO Client Source # | |
Defined in Mig.Client | |
Applicative Client Source # | |
Functor Client Source # | |
Monad Client Source # | |
(ToRespBody (RespMedia a) (RespError a), IsResp a) => FromClient (Send method Client a) Source # | |
Defined in Mig.Client type ClientResult (Send method Client a) Source # fromClient :: Send method Client a -> ClientResult (Send method Client a) Source # | |
(IsMethod method, FromReqBody (RespMedia a) (RespBody a), IsResp a) => ToClient (Send method Client a) Source # | |
type ClientResult (Send method Client a) Source # | |
Defined in Mig.Client |
data ClientConfig Source #
Config to run the clients
Instances
MonadReader ClientConfig Client' Source # | |
Defined in Mig.Client ask :: Client' ClientConfig # local :: (ClientConfig -> ClientConfig) -> Client' a -> Client' a # reader :: (ClientConfig -> a) -> Client' a # |
runClient :: ClientConfig -> Client a -> IO (RespOr AnyMedia ByteString a) Source #
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.
a :| b |
class FromClient a where Source #
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.
type ClientResult a :: Type Source #
fromClient :: a -> ClientResult a Source #
Instances
getRespOrValue :: RespOr media ByteString a -> Either ByteString a Source #
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
Client' (ReaderT ClientConfig IO a) |
Instances
MonadIO Client' Source # | |
Defined in Mig.Client | |
Applicative Client' Source # | |
Functor Client' Source # | |
Monad Client' Source # | |
MonadReader ClientConfig Client' Source # | |
Defined in Mig.Client ask :: Client' ClientConfig # local :: (ClientConfig -> ClientConfig) -> Client' a -> Client' a # reader :: (ClientConfig -> a) -> Client' a # |
runClient' :: ClientConfig -> Client' a -> IO a Source #
Runs the client call
class Monad m => MonadIO (m :: Type -> Type) where #
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:
Lift a computation from the IO
monad.
This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations
(i.e. IO
is the base monad for the stack).
Example
import Control.Monad.Trans.State -- from the "transformers" library printState :: Show s => StateT s IO () printState = do state <- get liftIO $ print state
Had we omitted
, we would have ended up with this error:liftIO
• Couldn't match type ‘IO’ with ‘StateT s IO’ Expected type: StateT s IO () Actual type: IO ()
The important part here is the mismatch between StateT s IO ()
and
.IO
()
Luckily, we know of a function that takes an
and returns an IO
a(m a)
:
,
enabling us to run the program and see the expected results:liftIO
> evalStateT printState "hello" "hello" > evalStateT printState 3 3
Instances
MonadIO IO | Since: base-4.9.0.0 |
Defined in Control.Monad.IO.Class | |
MonadIO Client Source # | |
Defined in Mig.Client | |
MonadIO Client' Source # | |
Defined in Mig.Client | |
MonadIO Q | |
Defined in Language.Haskell.TH.Syntax | |
(Functor f, MonadIO m) => MonadIO (FreeT f m) | |
Defined in Control.Monad.Trans.Free | |
(Error e, MonadIO m) => MonadIO (ErrorT e m) | |
Defined in Control.Monad.Trans.Error | |
MonadIO m => MonadIO (ReaderT r m) | |
Defined in Control.Monad.Trans.Reader | |
MonadIO m => MonadIO (Send method m) | |
Defined in Mig.Core.Types.Route |