utxorpc-client-0.0.1.1: An SDK for clients of the UTxO RPC specification.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Utxorpc.Client

Description

Create a UTxO RPC client connected to a UTxO RPC service. Provide a UtxorpcClientLogger to perform automated logging.

Synopsis

How to use this library

Call any method of a UTxO RPC service through the functions contained in a UtxorpcClient. Obtain a client by calling one of the client-creating functions:

  1. simpleUtxorpcClient ➤ connect to a service using the bare minimum required information.

    1. See quick-start.
  2. utxorpcClient ➤ connect to a service using a UtxorpcInfo record.

    1. See example.
  3. utxorpcClientWith ➤ provide a GrpcClientConfig for fine grained configuration.

Access the functions of a UtxorpcClient through record access:

fetchBlock (syncClient client)

Close the connection throught client's close function:

close client

Building Messages

To call a UTxO RPC method, you will need a record of the relevant Message instance. Build a Message with defMessage and set its fields with lens operators.

import Control.Lens.Operators ((&), (.~))
import Data.ProtoLens.Message (Message (defMessage))
import qualified Data.Text.Encoding as T
import Proto.Utxorpc.V1.Sync.Sync (FetchBlockRequest)
import Proto.Utxorpc.V1.Sync.Sync_Fields (hash, index)

fetchBlockRequest :: FetchBlockRequest
fetchBlockRequest =
defMessage
    & ref .~
    [ defMessage
        & index .~ 116541970
        & hash .~ T.encodeUtf8 "9d5abce5b1a7d94b141a597fd621a1ff9dcd46579ff1939664364311cd1be338"
    ]

Server Stream Methods

Note that calling a server-stream method requires an input-stream function and initial input-stream state. The input-stream function is of type (a -> HeaderList -> o -> IO a), where a is the initial input-stream state and o is the type of message streamed by the server. The input-stream function folds over its state until the stream is closed.

Logging

This SDK supports automated logging through the UtxorpcClientLogger type. It is a record of one user-defined logging function for each of the following events:

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

For more information, see Logged and the examples.

Examples

There are two examples included in the project. There are two provided examples:

  1. `/quick-start` shows the bare minimum required to make a single unary request.
stack run client-quick-start -- -p 443
  1. `/example` shows a more involved example that uses one of the following two logger implementations:

    1. `exampleSimpleLogger.hs` is a simple logger implementation that prints human-readable output.

      stack run client-example
      Usage: [--katip] <hostName> <port> <tlsEnabled> <useGzip> [<headerKey>:<headerValue> [...]]
      stack run client-example -- "localhost" 443 True False
    2. `exampleKatipLogger.hs` is a more involved logger that demonstrates how to use logging functions that run in a transformer stack. Run the example with `--katip` to use this logger.

      stack run client-example -- --katip "localhost" 443 True False

Creating a UtxorpcClient

data UtxorpcInfo m Source #

Configuration info for a UTxO RPC Client. For more fine-grained control, use GrpcClientConfig and utxorpcClientWith

Constructors

UtxorpcInfo 

Fields

simpleUtxorpcClient Source #

Arguments

:: HostName

Host name of the service.

-> PortNumber

Port number of the service.

-> UseTlsOrNot

Whether or not to use TLS.

-> IO (Either ClientError UtxorpcClient) 

Make a connection to a UTxO RPC service with the minimum required information. No compression is used, no headers are added, and no logging is performed. For more configurability, use utxorpcClient or utxorpcClientWith.

utxorpcClient :: UtxorpcInfo m -> IO (Either ClientError UtxorpcClient) Source #

Connect to a UTxO RPC service from a UtxorpcInfo. Provides more configurability than simpleUtxorpcClient but less than utxorpcClientWith.

utxorpcClientWith :: GrpcClientConfig -> Maybe (UtxorpcClientLogger m) -> IO (Either ClientError UtxorpcClient) Source #

Connect to a UTxO RPC from a GrpcClientConfig. For a simpler interface with less configurability, use utxorpcClient or simpleUtxorpcClient.

The UtxorpcClient

data UtxorpcClient Source #

Methods for each module in UTxO RPC.

>>> fetchBlock (buildClient client) defMessage

Constructors

UtxorpcClient 

Fields

newtype WatchClient Source #

Methods of the watch module

RPC call function types

type ServerStreamCall i o Source #

Arguments

 = forall a. a

The initial state for the stream processing function.

-> i

The request message to send to the service.

-> (a -> HeaderList -> o -> IO a)

The stream processing function. It is a fold over some state a with stream messages o.

-> ServerStreamReply a

The final state of the stream processing function, or an error.

Type definition for functions that make calls to server stream methods. Note that the stream state, a, can be different for each call.

type ServerStreamReply a = IO (Either ClientError (Either TooMuchConcurrency (a, HeaderList, HeaderList))) Source #

The type returned by calls to server stream methods. a is the final state of the stream processing function.

type UnaryReply o = IO (Either ClientError (Either TooMuchConcurrency (RawReply o))) Source #

The type returned by calls to unary service methods.

Logging

data UtxorpcClientLogger m Source #

Logging functions to log requests, replies, server stream messages, and server stream endings. A UUID is generated for each request and passed downstream to the other logging functions.

Constructors

UtxorpcClientLogger 

Fields

type RequestLogger m Source #

Arguments

 = forall i. (Show i, Message i) 
=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> UUID

Generated for this request, and passed to other logging functions for other RPC events generated by this request. E.g., A unary request and its reply both have the same UUID.

-> i

The request message being sent.

-> m () 

Log outgoing requests of all types (i.e., unary requests and server stream requests).

type ReplyLogger m Source #

Arguments

 = forall o. (Show o, Message o) 
=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> UUID

Generated for the request that this reply is associated with.

-> Either ClientError (Either TooMuchConcurrency (RawReply o))

Message received from the service (with headers) or an error.

-> m () 

Log unary replies.

type ServerStreamLogger m Source #

Arguments

 = forall o. (Show o, Message o) 
=> ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> (UUID, Int)

The UUID was generated for the request that caused this reply, the Int is the index of this message in the stream.

-> o

Message received from the service.

-> m () 

Log server stream messages.

type ServerStreamEndLogger m Source #

Arguments

 = ByteString

The RPC path

-> GrpcClient

Included because it contains useful information such as the server address.

-> (UUID, Int)

The UUID was generated for the request that caused this reply, the Int is the total number of messages received in the stream.

-> (HeaderList, HeaderList)

Headers and Trailers.

-> m ()