utxorpc-client 0.0.1.0 → 0.0.1.1

raw patch · 6 files changed

+189/−76 lines, 6 filesdep +textPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependencies added: text

API changes (from Hackage documentation)

Files

• README.md +7/−26
• example/Main.hs +8/−6
• quick-start/Main.hs +18/−7
• src/Utxorpc/Client.hs +133/−20
• src/Utxorpc/Types.hs +13/−12
• utxorpc-client.cabal +10/−5

@@ -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.

@@ -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) 

@@ -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)

@@ -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] <hostName> <port> <tlsEnabled> <useGzip> [<headerKey>:<headerValue> [...]]+--             > 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

@@ -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   }

@@ -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 <dominic.j.mayhew@gmail.com>+                TxPipe <registrant@txpipe.io> 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