mu-rpc-0.5.0.0: Protocol-independent declaration of services and servers.
Safe HaskellNone
LanguageHaskell2010

Mu.Server

Description

A server (represented by ServerT) is a sequence of handlers (represented by HandlersT), one for each operation in the corresponding Mu service declaration.

In general, you can declare a server by naming each of the methods with their handlers:

server :: MonadServer m => ServerT MyService m _
server = singleService ( method @"m1" h1
                       , method @"m2" h2
                       , ... )

or by position:

server :: MonadServer m => ServerT MyService m _
server = Server (h1 :<|>: h2 :<|>: ... :<|>: H0)

where each of h1, h2, ... handles each method in MyService in the order they were declared.

In both cases, the _ in the type allows GHC to fill in the boring and long type you would need to write there otherwise.

Implementation note: exceptions raised in handlers produce an error to be sent as response to the client. We recommend you to catch exceptions and return custom ServerErrors instead.

Synopsis

Servers and handlers

type MonadServer m = (MonadError ServerError m, MonadIO m) Source #

Constraint for monads that can be used as servers

type ServiceChain snm = Mappings snm Type Source #

Defines a mapping between outcome of a service, and its representation as Haskell type.

noContext :: b -> a1 -> a2 -> b Source #

To declare that the function doesn't use its context.

wrapServer :: forall chn info p m topHs. (forall a. RpcInfo info -> m a -> m a) -> ServerT chn info p m topHs -> ServerT chn info p m topHs Source #

Definitions by name

singleService :: (ToNamedList p nl, ToHandlers chn info () methods m hs nl, MappingRight chn sname ~ ()) => p -> ServerT chn info ('Package pname '['Service sname methods]) m '[hs] Source #

Defines a server for a package with a single service. Intended to be used with a tuple of methods:

singleService (method @"m1" h1, method @"m2" h2)

method :: forall n a p. p -> Named n (a -> () -> p) Source #

Declares the handler for a method in the service. Intended to be used with TypeApplications:

method @"myMethod" myHandler

methodWithInfo :: forall n p info. (RpcInfo info -> p) -> Named n (RpcInfo info -> () -> p) Source #

Declares the handler for a method in the service, which is passed additional information about the call. Intended to be used with TypeApplications:

methodWithInfo @"myMethod" myHandler

resolver :: (ToNamedList p nl, ToServices chn info ss m hs nl) => p -> ServerT chn info ('Package pname ss) m hs Source #

Combines the implementation of several GraphQL objects, which means a whole Mu service for a GraphQL server. Intented to be used with a tuple of objects:

resolver (object @"o1" ..., object @"o2" ...)

object :: forall sname p nl chn info ms m hs. (ToNamedList p nl, ToHandlers chn info (MappingRight chn sname) ms m hs nl) => p -> Named sname (HandlersT chn info (MappingRight chn sname) ms m hs) Source #

Defines the implementation of a single GraphQL object, which translates as a single Mu service. Intended to be used with TypeApplications and a tuple of fields:

object @"myObject" (field @"f1" h1, fielf @"f2" h2)

Note: for the root objects in GraphQL (query, mutation, subscription) use method instead of object.

union :: forall sname chn m elts. (MappingRight chn sname -> m (UnionChoice chn elts)) -> Named sname (MappingRight chn sname -> m (UnionChoice chn elts)) Source #

field :: forall n h info. h -> Named n (RpcInfo info -> h) Source #

Declares the handler for a field in an object. Intended to be used with TypeApplications:

field @"myField" myHandler

fieldWithInfo :: forall n h info. (RpcInfo info -> h) -> Named n (RpcInfo info -> h) Source #

Declares the handler for a field in an object, which is passed additional information about the call. Intended to be used with TypeApplications:

fieldWithInfo @"myField" myHandler

data UnionChoice chn elts where Source #

Constructors

UnionChoice :: (InUnion elt elts, Typeable elt) => Proxy elt -> MappingRight chn elt -> UnionChoice chn elts 

unionChoice :: forall elt elts chn. (InUnion elt elts, Typeable elt) => MappingRight chn elt -> UnionChoice chn elts Source #

data NamedList (hs :: [(Symbol, *)]) where Source #

Heterogeneous list in which each element is tagged with a type-level name.

Constructors

N0 :: NamedList '[] 
(:|:) :: Named n h -> NamedList hs -> NamedList ('(n, h) ': hs) infixr 4 

Definitions by position

type SingleServerT = ServerT '[] Source #

A server for a single service, like most RPC ones.

pattern Server :: MappingRight chn sname ~ () => HandlersT chn info () methods m hs -> ServerT chn info ('Package pname '['Service sname methods]) m '[hs] Source #

data ServerT (chn :: ServiceChain snm) (info :: Type) (s :: Package snm mnm anm (TypeRef snm)) (m :: Type -> Type) (hs :: [[Type]]) where Source #

Definition of a complete server for a set of services, with possible references between them.

Constructors

Services :: ServicesT chn info s m hs -> ServerT chn info ('Package pname s) m hs 

data ServicesT (chn :: ServiceChain snm) (info :: Type) (s :: [Service snm mnm anm (TypeRef snm)]) (m :: Type -> Type) (hs :: [[Type]]) where Source #

Definition of a complete server for a service.

Constructors

S0 :: ServicesT chn info '[] m '[] 
(:<&>:) :: ServiceT chn info svc m hs -> ServicesT chn info rest m hss -> ServicesT chn info (svc ': rest) m (hs ': hss) infixr 3 

data ServiceT chn info svc m hs where Source #

Definition of different kinds of services.

Constructors

ProperSvc :: HandlersT chn info (MappingRight chn sname) methods m hs -> ServiceT chn info ('Service sname methods) m hs 
OneOfSvc :: (MappingRight chn sname -> m (UnionChoice chn elts)) -> ServiceT chn info ('OneOf sname elts) m '[] 

data HandlersT (chn :: ServiceChain snm) (info :: Type) (inh :: *) (methods :: [Method snm mnm anm (TypeRef snm)]) (m :: Type -> Type) (hs :: [Type]) where Source #

HandlersT is a sequence of handlers. Note that the handlers for your service must appear in the same order as they are defined.

In general you can choose any type you want for your handlers, due to the following restrictions:

  • Haskell types must be convertible to the corresponding schema type. In other words, they must implement FromSchema if they are inputs, and ToSchema if they are outputs.
  • Normal returns are represented by returning the corresponding Haskell type.
  • Input streams turn into Conduit () t m (), where t is the Haskell type for that schema type.
  • Output streams turn into an additional argument of type Conduit t Void m (). This stream should be connected to a source to get the elements.

Constructors

H0 :: HandlersT chn info inh '[] m '[] 
Hmore :: Handles chn args ret m h => Proxy args -> Proxy ret -> (RpcInfo info -> inh -> h) -> HandlersT chn info inh ms m hs -> HandlersT chn info inh ('Method name args ret ': ms) m (h ': hs) 

Bundled Patterns

pattern (:<||>:) :: Handles chn args ret m h => (RpcInfo info -> inh -> h) -> HandlersT chn info inh ms m hs -> HandlersT chn info inh ('Method name args ret ': ms) m (h ': hs) infixr 4 
pattern (:<|>:) :: Handles chn args ret m h => h -> HandlersT chn info () ms m hs -> HandlersT chn info () ('Method name args ret ': ms) m (h ': hs) infixr 4 

Simple servers using only IO

type ServerErrorIO = ExceptT ServerError IO Source #

Simplest monad which satisfies MonadServer.

type ServerIO info srv = ServerT '[] info srv ServerErrorIO Source #

Simple ServerT which uses only IO and errors, and whose service has no back-references.

Errors which might be raised

serverError :: MonadError ServerError m => ServerError -> m a Source #

Stop the current handler, returning an error to the client.

data ServerError Source #

Errors raised in a handler.

data ServerErrorCode Source #

Possible types of errors. Some of these are handled in a special way by different transpoprt layers.

Instances

Instances details
Eq ServerErrorCode Source # 
Instance details

Defined in Mu.Server

Show ServerErrorCode Source # 
Instance details

Defined in Mu.Server

Useful when you do not want to deal with errors

alwaysOk :: MonadIO m => IO a -> m a Source #

Wrapper for handlers which do not use errors. Remember that any exception raised in IO is propagated to the client.

For internal use

class Handles (chn :: ServiceChain snm) (args :: [Argument snm anm (TypeRef snm)]) (ret :: Return snm (TypeRef snm)) (m :: Type -> Type) (h :: Type) Source #

Defines a relation for handling.

Minimal complete definition

wrapHandler

Instances

Instances details
(MonadError ServerError m, handler ~ m ()) => Handles (chn :: ServiceChain snm) ('[] :: [Argument snm anm (TypeRef snm)]) ('RetNothing :: Return snm (TypeRef snm)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy '[] -> Proxy 'RetNothing -> (forall a. m a -> m a) -> handler -> handler

(MonadError ServerError m, ToRef chn ref v, handler ~ (ConduitT v Void m () -> m ())) => Handles (chn :: ServiceChain snm) ('[] :: [Argument snm anm (TypeRef snm)]) ('RetStream ref :: Return snm (TypeRef snm)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy '[] -> Proxy ('RetStream ref) -> (forall a. m a -> m a) -> handler -> handler

(MonadError ServerError m, ToRef chn ref v, handler ~ m v) => Handles (chn :: ServiceChain snm) ('[] :: [Argument snm anm (TypeRef snm)]) ('RetSingle ref :: Return snm (TypeRef snm)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy '[] -> Proxy ('RetSingle ref) -> (forall a. m a -> m a) -> handler -> handler

(MonadError ServerError m, ToRef chn eref e, ToRef chn vref v, handler ~ m (Either e v)) => Handles (chn :: ServiceChain snm) ('[] :: [Argument snm anm (TypeRef snm)]) ('RetThrows eref vref :: Return snm (TypeRef snm)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy '[] -> Proxy ('RetThrows eref vref) -> (forall a. m a -> m a) -> handler -> handler

(MonadError ServerError m, FromRef chn ref t, Handles chn args ret m h, handler ~ (ConduitT () t m () -> h)) => Handles (chn :: ServiceChain serviceName) (('ArgStream aname ref :: Argument serviceName anm (TypeRef serviceName)) ': args :: [Argument serviceName anm (TypeRef serviceName)]) (ret :: Return serviceName (TypeRef serviceName)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy ('ArgStream aname ref ': args) -> Proxy ret -> (forall a. m a -> m a) -> handler -> handler

(FromRef chn ref t, Handles chn args ret m h, handler ~ (t -> h)) => Handles (chn :: ServiceChain serviceName) (('ArgSingle aname ref :: Argument serviceName anm (TypeRef serviceName)) ': args :: [Argument serviceName anm (TypeRef serviceName)]) (ret :: Return serviceName (TypeRef serviceName)) m handler Source # 
Instance details

Defined in Mu.Server

Methods

wrapHandler :: Proxy '(chn, m) -> Proxy ('ArgSingle aname ref ': args) -> Proxy ret -> (forall a. m a -> m a) -> handler -> handler

class FromRef (chn :: ServiceChain snm) (ref :: TypeRef snm) (t :: Type) Source #

Defines whether a given type t can be obtained from the TypeRef ref.

Instances

Instances details
(FromRef chn ref t, Maybe t ~ s) => FromRef (chn :: ServiceChain serviceName) ('OptionalRef ref :: TypeRef serviceName) s Source # 
Instance details

Defined in Mu.Server

(FromRef chn ref t, [t] ~ s) => FromRef (chn :: ServiceChain serviceName) ('ListRef ref :: TypeRef serviceName) s Source # 
Instance details

Defined in Mu.Server

MappingRight chn ref ~ t => FromRef (chn :: Mappings serviceName Type) ('ObjectRef ref :: TypeRef serviceName) t Source # 
Instance details

Defined in Mu.Server

t ~ s => FromRef (chn :: ServiceChain snm) ('PrimitiveRef t :: TypeRef snm) s Source # 
Instance details

Defined in Mu.Server

t ~ s => FromRef (chn :: ServiceChain snm) ('RegistryRef subject t last :: TypeRef snm) s Source # 
Instance details

Defined in Mu.Server

FromSchema sch sty t => FromRef (chn :: ServiceChain snm) ('SchemaRef sch sty :: TypeRef snm) t Source # 
Instance details

Defined in Mu.Server

class ToRef (chn :: ServiceChain snm) (ref :: TypeRef snm) (t :: Type) Source #

Defines whether a given type t can be turned into the TypeRef ref.

Instances

Instances details
(ToRef chn ref t, Maybe t ~ s) => ToRef (chn :: ServiceChain serviceName) ('OptionalRef ref :: TypeRef serviceName) s Source # 
Instance details

Defined in Mu.Server

(ToRef chn ref t, [t] ~ s) => ToRef (chn :: ServiceChain serviceName) ('ListRef ref :: TypeRef serviceName) s Source # 
Instance details

Defined in Mu.Server

MappingRight chn ref ~ t => ToRef (chn :: Mappings serviceName Type) ('ObjectRef ref :: TypeRef serviceName) t Source # 
Instance details

Defined in Mu.Server

t ~ s => ToRef (chn :: ServiceChain snm) ('PrimitiveRef t :: TypeRef snm) s Source # 
Instance details

Defined in Mu.Server

t ~ s => ToRef (chn :: ServiceChain snm) ('RegistryRef subject t last :: TypeRef snm) s Source # 
Instance details

Defined in Mu.Server

ToSchema sch sty t => ToRef (chn :: ServiceChain snm) ('SchemaRef sch sty :: TypeRef snm) t Source # 
Instance details

Defined in Mu.Server