Safe Haskell	Safe-Inferred
Language	Haskell2010

Utxorpc.Server

Contents

How to use this library
- Server Stream Methods
- Logging
Running a service
Logging

Description

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

Synopsis

runUtxorpc :: MonadIO m => ServiceConfig m a b c d e -> IO ()
data ServiceConfig m a b c d e = ServiceConfig {
- tlsSettings :: TLSSettings
- warpSettings :: Settings
- handlers :: UtxorpcHandlers m a b c d e
- logger :: Maybe (UtxorpcServiceLogger m)
- unlift :: forall x. m x -> IO x
- compression :: [Compression]
}
data UtxorpcHandlers m a b c d e = UtxorpcHandlers {
- queryHandlers :: Maybe (QueryHandlers m a)
- submitHandlers :: Maybe (SubmitHandlers m b c)
- syncHandlers :: Maybe (SyncHandlers m d)
- watchHandlers :: Maybe (WatchHandlers m e)
}
data QueryHandlers m a = QueryHandlers {
}
data SubmitHandlers m a b = SubmitHandlers {
}
data SyncHandlers m a = SyncHandlers {
}
newtype WatchHandlers m a = WatchHandlers {
- watchTx :: ServerStreamHandler m WatchTxRequest WatchTxResponse a
}
data UtxorpcServiceLogger m = UtxorpcServiceLogger {
- requestLogger :: RequestLogger m
- replyLogger :: ReplyLogger m
- serverStreamLogger :: ServerStreamLogger m
- serverStreamEndLogger :: ServerStreamEndLogger m
}
type RequestLogger m = forall i. Show i => ByteString -> Request -> UUID -> i -> m ()
type ReplyLogger m = forall o. Show o => ByteString -> Request -> UUID -> o -> m ()
type ServerStreamLogger m = forall o. Show o => ByteString -> Request -> (UUID, Int) -> o -> m ()
type ServerStreamEndLogger m = ByteString -> Request -> (UUID, Int) -> m ()

How to use this library

To run a UTxO RPC service:

Create a UtxorpcHandlers record, containing handler for each method in one or more modules in the specification.
Create a ServiceConfig record, containing server settings (e.g., TLS settings), the handlers, and (optionally), a logger.
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:

Request received.
Unary reply sent.
Server stream data sent.
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

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 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 queryHandlers :: Maybe (QueryHandlers m a) Handlers for the Query module. submitHandlers :: Maybe (SubmitHandlers m b c) Handlers for the Submit module. syncHandlers :: Maybe (SyncHandlers m d) Handlers for the Sync module. watchHandlers :: Maybe (WatchHandlers m e) Handlers for the Watch module.

data QueryHandlers m a Source #

Constructors

QueryHandlers
Fields readParams :: UnaryHandler m ReadParamsRequest ReadParamsResponse readUtxos :: UnaryHandler m ReadUtxosRequest ReadUtxosResponse searchUtxos :: UnaryHandler m SearchUtxosRequest SearchUtxosResponse streamUtxos :: ServerStreamHandler m ReadUtxosRequest ReadUtxosResponse a

data SubmitHandlers m a b Source #

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 Source #

Constructors

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

newtype WatchHandlers m a Source #

Constructors

WatchHandlers
Fields watchTx :: ServerStreamHandler m WatchTxRequest WatchTxResponse a

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.

Constructors

UtxorpcServiceLogger
Fields requestLogger :: RequestLogger m replyLogger :: ReplyLogger m serverStreamLogger :: ServerStreamLogger m serverStreamEndLogger :: ServerStreamEndLogger m

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.