Network.Colchis

This module defines the client monad and the type signatures for transports and prototocols.

Client

type JSONClient s m r = Client (s, Value) Value (ExceptT JSONClientError m) r

Emits requests consisting in Values paired with some metadata. The metadata is usually the method name.

Receives Value responses.

type JSONClientError = (Value, Text, Value)

(request associated with the error, error message, response that caused the error)

call :: (ToJSON a, FromJSON r, Monad m) => s -> a -> JSONClient s m r

Protocol

type Protocol s m e = forall r. (s, Value) -> Proxy Value Value (s, Value) Value (ExceptT e m) r

A bidirectional Proxy waiting for a request, ready to be composed with +>> or >+>.

Protocols format incoming requests from downstream before sending them upstream. They also extract the values from returning protocol responses and send them downstream.

Protocols isolate clients from the specific details of each protocol.

Transport

type Transport t m = MonadIO m => forall r. Value -> Server Value Value (t m) r

A pipes Server waiting for a request, ready to be composed with +>> or >+>.

Transports send requests over the wire and receive the responses.

Running clients

runJSONClient :: (MonadTrans t, MFunctor t, MonadIO m, Monad (t m)) => Transport t m -> Protocol s m e -> JSONClient s m r -> t m (Either e (Either JSONClientError r))

The return value lives inside the monad associated to the transport layer. The run function that peels off that layer depends on the transport. See for example runTcp for the tcp transport.

Utils

These functions can be used to manipulate requests flowing upstream.

umap :: Monad m => (b' -> a') -> b' -> Proxy a' x b' x m r

Apply a function to all requests flowing upstream in a bidirectional pipe. Returns a function that can be composed with +>> or >+>.

umapM :: Monad m => (b' -> m a') -> b' -> Proxy a' x b' x m r

Apply a monadic function to all requests flowing upstream in a bidirectional pipe. Returns a function that can be composed with +>> or >+>.

Re-exported

When the function that runs the transport layer requires the underlying monad to be whittled down to IO, hoist (along with a suitable monad morphism) can come in handy.

hoist :: MFunctor t => forall m b n. Monad m => (forall a. m a -> n a) -> t m b -> t n b

Lift a monad morphism from m to n into a monad morphism from (t m) to (t n)