utxorpc-server-0.0.1.1: An SDK for UTxO RPC services.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Utxorpc.Server

Description

Run UTxO RPC service from a set of method handlers. Provide a UtxorpcServiceLogger to perform automated logging.

Synopsis

How to use this library

To run a UTxO RPC service:

  1. Create a UtxorpcHandlers record, containing a handler for each method in the specification.
  2. Create a ServiceConfig record, containing server settings (e.g., TLS settings), the handlers, and (optionally), a logger.
  3. Call runUtxorpc with the ServiceConfig.

Server Stream Methods

To implement a server stream method, provide a ServerStreamHandler. Given request metadata and a record of the relevant Message instance, a ServerStreamHanlder produces an initial stream state and a streaming function, which folds over the stream state. The stream is closed when the streaming function produces a Nothing.

Logging

Automated logging is supported through the UtxorpcServiceLogger type. It is a record of one user-defined logging function for each of the following events:

  1. Request received.
  2. Unary reply sent.
  3. Server stream data sent.
  4. Server stream ended.

For more information, see ServiceConfig, UtxorpcServiceLogger, and the example.

Running a service

runUtxorpc Source #

Arguments

:: MonadIO m 
=> ServiceConfig m a b c d e

Configuration info and method handlers.

-> IO () 

Run a UTxO RPC service from a ServiceConfig.

data ServiceConfig m a b c d e Source #

Configuration info and method handlers. Note that the handlers and logger run in the same monad. The monadic actions of the logger and handlers for a single call are combined, and unlift runs the combined action in IO. This means that changes to the monadic state made by the request logger (e.g., adding a namespace) are seen by the handlers and other logging functions for that specific call.

Constructors

ServiceConfig 

Fields

data UtxorpcHandlers m a b c d e Source #

A handler for each method in the UTxO RPC specification. ServerStreamHandlers require a type variable representing the "stream state" (a value that the stream processes/folds over). The type variables here (other than m) are the type variables of each stream handler in the record.

Constructors

UtxorpcHandlers 

Fields

Logging

data UtxorpcServiceLogger m Source #

A record of logging functions that runs in the same monad as the request handlers. Monadic state is passed along throughout the lifecycle of responding to a request. This means that changes to the monadic state in the request logger is seen by the stream logger, stream handler and logger, and reply logger. An unlift function to run the monad in IO is provided to runUtxorpc.

type RequestLogger m Source #

Arguments

 = forall i. Show i 
=> ByteString

The RPC path

-> Request

Request metadata

-> UUID

A UUID generated for this request and passed to stream and reply loggers.

-> i

The request message

-> m () 

Log incoming requests.

type ReplyLogger m Source #

Arguments

 = forall o. Show o 
=> ByteString

The RPC path

-> Request

Request metadata

-> UUID 
-> o

The reply message

-> m () 

Log outgoing replies.

type ServerStreamLogger m Source #

Arguments

 = forall o. Show o 
=> ByteString

The RPC path

-> Request

Request metadata

-> (UUID, Int)

The UUID generated for the request that generated this stream, and the 0-based index of the message in the stream.

-> o

The stream message

-> m () 

Log outgoing server stream messages.

type ServerStreamEndLogger m Source #

Arguments

 = ByteString

The RPC path

-> Request

Request metadata

-> (UUID, Int)

The UUID generated for the request that generated this stream, and the 0-based index of the message in the stream.

-> m () 

Log the end of a server stream.