diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,32 +1,13 @@ # UTxO RPC Client SDK -An SDK for clients of the [UTxO RPC](https://utxorpc.org/) specification. - -The goal of this SDK is to reduce boilerplate and increase ease of use of the UTxO RPC spec. This SDK provides convenience methods for creating a connection to a UTxO RPC service and for calling each each method in the UTxO RPC specification. Automated logging of each event in a gRPC call is also supported. - -## How to Use - -Use the SDK through one of the client-creating functions in `Utxorpc.Client`. -1. `simpleUtxorpcClient` -- connect to a service using the bare minimum required information. - 1. See `/quick-start/Main.hs`. -1. `utxorpcClient` -- connect to a service using the provided `UtxorpcInfo`. - 1. See `/example/Main.hs` -1. `UtxorpcClientWith` -- for fine grained control, provide a `GrpcClientConfig` (from `http2-client-grpc`) - -Each of these functions provides a record type hosting functions for each method in UTxO RPC, as well as a method to close the connection. - -## Logging +> [!IMPORTANT] +> This package is currently pre-release. Until this package reaches v0.1.0.0 it is subject to breaking changes without change in major version. -This SDK supports automated logging through the `UtxorpcClientLogger` type. It is a record hosting user-defined logging functions for each of the following events: -1. Request sent. -1. Reply received. -1. Server stream data received. -1. Server stream ended. +An SDK for clients of the [UTxO RPC](https://utxorpc.org/) specification. -For more information, see `Utxorpc.Logged` and `/example`. +The goal of this SDK is to reduce boilerplate and increase ease of use of the UTxO RPC spec. This SDK provides functions for creating a connected UTxO RPC client and for calling each each RPC in the UTxO RPC specification. Automated logging of each event in a gRPC call is also supported. -## Examples +To get started, please see the documentation for [`Utxorpc.Client`](https://hackage.haskell.org/package/utxorpc-client). -There are two provided examples: -1. `/quick-start` shows the bare minimum required to make a single unary request. -1. `/example` shows a more involved example. `/example/SimpleLogger.hs` is a simple logger implementation that prints human-readable output, and `/example/KatipLogger.hs` is a more involved logger that demonstrates how to use logging functions that run in a transformer stack. +> [!NOTE] +> This SDK depends on package versions that are not on Hackage. Consult [`stack.yaml`](https://github.com/utxorpc/haskell-sdk/) or [`cabal.project`](https://github.com/utxorpc/haskell-sdk/) for help configuring your project's dependencies. diff --git a/example/Main.hs b/example/Main.hs --- a/example/Main.hs +++ b/example/Main.hs @@ -14,14 +14,16 @@ import SimpleLogger (simpleLogger) import System.Environment (getArgs) import UnliftIO (MonadIO, bracket, stdout, throwString) -import Utxorpc.Client (UtxorpcClientLogger, UtxorpcInfo (..), utxorpcClient) -import Utxorpc.Types - ( BuildClientImpl (getChainTip), +import Utxorpc.Client + ( BuildClient (..), ServerStreamReply, - SubmitClientImpl (watchMempool), - SyncClientImpl (fetchBlock), + SubmitClient (..), + SyncClient (..), UnaryReply, - UtxorpcClient (buildClient, submitClient, syncClient), + UtxorpcClient (..), + UtxorpcClientLogger, + UtxorpcInfo (..), + utxorpcClient, ) import "http2-client" Network.HTTP2.Client (ClientError, TooMuchConcurrency) diff --git a/quick-start/Main.hs b/quick-start/Main.hs --- a/quick-start/Main.hs +++ b/quick-start/Main.hs @@ -1,19 +1,25 @@ +{-# LANGUAGE LambdaCase #-} +{-# LANGUAGE OverloadedStrings #-} + module Main (main) where -import Control.Exception (throwIO) +import Control.Exception (bracket, throwIO) import Control.Lens.Operators ((&), (.~)) -import qualified Data.ByteString.Char8 as BS +import Control.Monad (void) import Data.ProtoLens (Message (..)) +import qualified Data.Text.Encoding as T +import Proto.Utxorpc.V1alpha.Sync.Sync (FetchBlockRequest) import Proto.Utxorpc.V1alpha.Sync.Sync_Fields (hash, index, ref) import UnliftIO.Exception (throwString) -import Utxorpc.Client (simpleUtxorpcClient) -import Utxorpc.Types (fetchBlock, syncClient) +import Utxorpc.Client (close, fetchBlock, simpleUtxorpcClient, syncClient) main :: IO () main = do -- Connect to a UTxO RPC service - eClient <- simpleUtxorpcClient "hostname" 443 True - case eClient of + let mkClient = simpleUtxorpcClient "127.0.0.1" 3000 True + -- Bracket making a request with closing the client connection + bracket mkClient closeClient $ \case + -- Panic if connection could not be established Left clientErr -> throwIO clientErr Right client -> do -- Make a unary request @@ -24,12 +30,17 @@ print fetchBlockResponse err -> throwString $ show err where + fetchBlockRequest :: FetchBlockRequest fetchBlockRequest = defMessage & ref .~ [ defMessage & index .~ 40608434 & hash - .~ BS.pack + .~ T.encodeUtf8 "3e4947072df1ed22a0518cb717c2904ebf0952b0c33292b402fae25d9562022e" ] + + -- Close the client connection if it was established + closeClient (Left _) = return () + closeClient (Right client) = void (close client) diff --git a/src/Utxorpc/Client.hs b/src/Utxorpc/Client.hs --- a/src/Utxorpc/Client.hs +++ b/src/Utxorpc/Client.hs @@ -7,13 +7,43 @@ -- | -- Module : Utxorpc.Client -- Description : Create a connected UTxO RPC client. --- Create a UTxO RPC client connected to a UTxO RPC service. The @'UtxorpcClient'@ provides functions for each of the methods in the UTxO RPC specification. +-- Create a UTxO RPC client connected to a UTxO RPC service. -- Provide a UtxorpcClientLogger to perform automated logging. module Utxorpc.Client - ( UtxorpcInfo (..), - utxorpcClient, + ( -- * How to use this library + -- $use + + -- ** Building Messages + -- $messages + + -- ** Server Stream Methods + -- $streaming + + -- ** Logging + -- $logging + + -- ** Examples + -- $examples + + -- * Creating a @'UtxorpcClient'@ + UtxorpcInfo (..), simpleUtxorpcClient, + utxorpcClient, utxorpcClientWith, + + -- * The @'UtxorpcClient'@ + UtxorpcClient (..), + BuildClient (..), + SubmitClient (..), + SyncClient (..), + WatchClient (..), + + -- ** RPC call function types + ServerStreamCall, + ServerStreamReply, + UnaryReply, + + -- * Logging UtxorpcClientLogger (..), RequestLogger, ReplyLogger, @@ -43,7 +73,7 @@ import "http2-client" Network.HTTP2.Client (ClientError, HostName, PortNumber, runClientIO) -- | Configuration info for a UTxO RPC Client. --- For more fine-grained control, use @'GrpcClientConfig'@ and @'UtxorpcClientWith'@ +-- For more fine-grained control, use @'GrpcClientConfig'@ and @'utxorpcClientWith'@ data UtxorpcInfo m = UtxorpcInfo { -- | Host name of the service. _hostName :: HostName, @@ -114,19 +144,19 @@ fromGrpc :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> UtxorpcClient fromGrpc logger client = UtxorpcClient - (buildClientImpl logger client) - (submitClientImpl logger client) - (syncClientImpl logger client) - (watchClientImpl logger client) + (mkBuildClient logger client) + (mkSubmitClient logger client) + (mkSyncClient logger client) + (mkWatchClient logger client) (runClientIO $ Network.GRPC.Client.Helpers.close client) {-------------------------------------- BUILD --------------------------------------} -buildClientImpl :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> BuildClientImpl -buildClientImpl logger client = - BuildClientImpl +mkBuildClient :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> BuildClient +mkBuildClient logger client = + BuildClient (loggedUnary logger getChainTipRPC client) (loggedUnary logger getChainParamRPC client) (loggedUnary logger getUtxoByAddressRPC client) @@ -152,9 +182,9 @@ SUBMIT --------------------------------------} -submitClientImpl :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> SubmitClientImpl -submitClientImpl logger client = - SubmitClientImpl +mkSubmitClient :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> SubmitClient +mkSubmitClient logger client = + SubmitClient (loggedUnary logger submitTxRPC client) (loggedUnary logger readMempoolRPC client) (loggedSStream logger waitForTxRPC client) @@ -176,9 +206,9 @@ SYNC --------------------------------------} -syncClientImpl :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> SyncClientImpl -syncClientImpl logger client = - SyncClientImpl +mkSyncClient :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> SyncClient +mkSyncClient logger client = + SyncClient (loggedUnary logger fetchBlockRPC client) (loggedUnary logger dumpHistoryRPC client) (loggedSStream logger followTipRPC client) @@ -196,9 +226,92 @@ WATCH --------------------------------------} -watchClientImpl :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> WatchClientImpl -watchClientImpl logger client = - WatchClientImpl $ loggedSStream logger watchTxRPC client +mkWatchClient :: Maybe (UtxorpcClientLogger m) -> GrpcClient -> WatchClient +mkWatchClient logger client = + WatchClient $ loggedSStream logger watchTxRPC client watchTxRPC :: RPC WatchService "watchTx" watchTxRPC = RPC + +-- $use +-- 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](https://github.com/utxorpc/haskell-sdk/tree/main/client/quick-start)@. +-- +-- 2. @'utxorpcClient'@ ➤ connect to a service using a @'UtxorpcInfo'@ record. +-- +-- 1. See @[example](https://github.com/utxorpc/haskell-sdk/tree/main/client/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 + +-- $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" +-- ] +-- @ + +-- $streaming +-- 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 @'Utxorpc.Logged'@ and the examples. + +-- $examples +-- There are two examples included in the [project](https://github.com/utxorpc/haskell-sdk). +-- 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 +-- 2. `/example` shows a more involved example that uses one of the following two logger implementations: +-- +-- 1. `/example/SimpleLogger.hs` is a simple logger implementation that prints human-readable output. +-- +-- > stack run client-example +-- > Usage: [--katip] [: [...]] +-- > stack run client-example -- "localhost" 443 True False +-- +-- 2. `/example/KatipLogger.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 diff --git a/src/Utxorpc/Types.hs b/src/Utxorpc/Types.hs --- a/src/Utxorpc/Types.hs +++ b/src/Utxorpc/Types.hs @@ -7,10 +7,10 @@ -- The types in this module are required to call methods of a `UtxorpcClient`. module Utxorpc.Types ( UtxorpcClient (..), - BuildClientImpl (..), - SubmitClientImpl (..), - SyncClientImpl (..), - WatchClientImpl (..), + BuildClient (..), + SubmitClient (..), + SyncClient (..), + WatchClient (..), ServerStreamCall, ServerStreamReply, UnaryReply, @@ -52,16 +52,17 @@ ---------------------------------------} -- | Methods for each module in UTxO RPC. +-- -- >>> fetchBlock (buildClient client) defMessage data UtxorpcClient = UtxorpcClient { -- | Build module service methods. - buildClient :: BuildClientImpl, + buildClient :: BuildClient, -- | Submit module service methods. - submitClient :: SubmitClientImpl, + submitClient :: SubmitClient, -- | Sync module service methods. - syncClient :: SyncClientImpl, + syncClient :: SyncClient, -- | Watch module service methods. - watchClient :: WatchClientImpl, + watchClient :: WatchClient, -- | Closes the gRPC connection. close :: IO (Either ClientError ()) } @@ -71,7 +72,7 @@ ---------------------------------------} -- | Methods of the Build module -data BuildClientImpl = BuildClientImpl +data BuildClient = BuildClient { getChainTip :: GetChainTipRequest -> UnaryReply GetChainTipResponse, getChainParam :: GetChainParamRequest -> UnaryReply GetChainParamResponse, getUtxoByAddress :: GetUtxoByAddressRequest -> UnaryReply GetUtxoByAddressResponse, @@ -84,7 +85,7 @@ ---------------------------------------} -- | Methods of the Submit module -data SubmitClientImpl = SubmitClientImpl +data SubmitClient = SubmitClient { submitTx :: SubmitTxRequest -> UnaryReply SubmitTxResponse, readMempool :: ReadMempoolRequest -> UnaryReply ReadMempoolResponse, waitForTx :: ServerStreamCall WaitForTxRequest WaitForTxResponse, @@ -96,7 +97,7 @@ ---------------------------------------} -- | Methods of the Sync module -data SyncClientImpl = SyncClientImpl +data SyncClient = SyncClient { fetchBlock :: FetchBlockRequest -> UnaryReply FetchBlockResponse, dumpHistory :: DumpHistoryRequest -> UnaryReply DumpHistoryResponse, followTip :: ServerStreamCall FollowTipRequest FollowTipResponse @@ -107,6 +108,6 @@ ---------------------------------------} -- | Methods of the watch module -newtype WatchClientImpl = WatchClientImpl +newtype WatchClient = WatchClient { watchTx :: ServerStreamCall WatchTxRequest WatchTxResponse } diff --git a/utxorpc-client.cabal b/utxorpc-client.cabal --- a/utxorpc-client.cabal +++ b/utxorpc-client.cabal @@ -1,14 +1,19 @@ cabal-version: 3.0 name: utxorpc-client -version: 0.0.1.0 +version: 0.0.1.1 synopsis: An SDK for clients of the UTxO RPC specification. -description: This SDK includes helper functions for creating a UTxO gRPC client, calling UTxO RPC methods, and logging every interaction. +description: An SDK to reduce boilerplate, improve ease-of-use, and support logging for `utxorpc`. + To get started, see the documentation for `Utxorpc.Client` below. + Consult the README for help with dependency configurations. + WARNING: This package is currently pre-release. Any version < 0.1.0.0 is subject to breaking + changes without change in major version. category: Network, Blockchain, Cardano homepage: https://github.com/utxorpc/utxorpc-client#readme bug-reports: https://github.com/utxorpc/utxorpc-client/issues author: Dominic Mayhew -maintainer: dominic.j.mayhew@gmail.com +maintainer: Dominic Mayhew + TxPipe license: Apache-2.0 license-file: LICENSE build-type: Simple @@ -21,8 +26,8 @@ library exposed-modules: Utxorpc.Client - Utxorpc.Types other-modules: + Utxorpc.Types Utxorpc.Logged hs-source-dirs: src @@ -106,9 +111,9 @@ -Wunused-packages build-depends: , base >=4.7 && <5 - , bytestring < 0.13 , lens < 5.3 , proto-lens < 0.8 + , text < 2.2 , unliftio < 0.3 , utxorpc >= 0.0.3.0 && < 0.1 , utxorpc-client