Utxorpc.Server

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

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.
1. Unary reply sent.
1. Server stream data sent.
1. Server stream ended.

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

Running a service

runUtxorpc

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

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

• tlsSettings :: TLSSettings

  warp-tls settings for using TLS.

• warpSettings :: Settings

  warp settings

• handlers :: UtxorpcHandlers m a b c d e

  A handler for each method in the UTxO RPC specification.

• logger :: Maybe (UtxorpcServiceLogger m)

  Log each RPC event.

• unlift :: forall x. m x -> IO x

  An unlift function for the handlers and logger. Allows the handler and logger to be run in any monad, but they must be the same monad.

• compression :: [Compression]

  A list of compressions to accept and use.

data UtxorpcHandlers m a b c d e

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

• buildHandlers :: BuildHandlers m a

  Handlers for the Build module.

• submitHandlers :: SubmitHandlers m b c

  Handlers for the Submit module.

• syncHandlers :: SyncHandlers m d

  Handlers for the Sync module.

• watchHandlers :: WatchHandlers m e

  Handlers for the Watch module.

data BuildHandlers m a

Constructors

BuildHandlers

Fields

• getChainTip :: UnaryHandler m GetChainTipRequest GetChainTipResponse
• getChainParam :: UnaryHandler m GetChainParamRequest GetChainParamResponse
• getUtxoByAddress :: UnaryHandler m GetUtxoByAddressRequest GetUtxoByAddressResponse
• getUtxoByRef :: UnaryHandler m GetUtxoByRefRequest GetUtxoByRefResponse
• holdUtxo :: ServerStreamHandler m HoldUtxoRequest HoldUtxoResponse a

data SubmitHandlers m a b

Constructors

SubmitHandlers

Fields

• submitTx :: UnaryHandler m SubmitTxRequest SubmitTxResponse
• readMempool :: UnaryHandler m ReadMempoolRequest ReadMempoolResponse
• waitForTx :: ServerStreamHandler m WaitForTxRequest WaitForTxResponse a
• watchMempool :: ServerStreamHandler m WatchMempoolRequest WatchMempoolResponse b

data SyncHandlers m a

Constructors

SyncHandlers

Fields

• fetchBlock :: UnaryHandler m FetchBlockRequest FetchBlockResponse
• dumpHistory :: UnaryHandler m DumpHistoryRequest DumpHistoryResponse
• followTip :: ServerStreamHandler m FollowTipRequest FollowTipResponse a

newtype WatchHandlers m a

Constructors

WatchHandlers

Fields

• watchTx :: ServerStreamHandler m WatchTxRequest WatchTxResponse a

Logging

data UtxorpcServiceLogger m

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.

Constructors

UtxorpcServiceLogger

Fields

• requestLogger :: RequestLogger m
• replyLogger :: ReplyLogger m
• serverStreamLogger :: ServerStreamLogger m
• serverStreamEndLogger :: ServerStreamEndLogger m

type RequestLogger m

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

Arguments

 = forall o. Show o

=> ByteString

The RPC path

-> Request

Request metadata

-> UUID

-> o

The reply message

-> m ()

Log outgoing replies.

type ServerStreamLogger m

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

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.