utxorpc-server 0.0.1.0 → 0.0.1.1

raw patch · 3 files changed

+76/−7 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

example/Main.hs +1/−1
src/Utxorpc/Server.hs +67/−3
utxorpc-server.cabal +8/−3

example/Main.hs view

@@ -24,7 +24,7 @@ main :: IO () main = do   args <- getArgs-  let port = maybe 3000 (read . drop 2) $ find ("-p" `isPrefixOf`) args+  let port = maybe 3000 (read . drop 3) $ find ("-p=" `isPrefixOf`) args   putStrLn $ "Starting server on port " ++ show port   if "--katip" `elem` args     then runKatipExample defaultTlsSettings (setPort port defaultSettings) [gzip]

src/Utxorpc/Server.hs view

@@ -1,14 +1,31 @@ {-# LANGUAGE NamedFieldPuns #-} {-# LANGUAGE RankNTypes #-} +-- |+-- Module        : Utxorpc.Server+-- Description   : Run a UTxO RPC service.+-- Run UTxO RPC service from a set of method handlers.+-- Provide a @'UtxorpcServiceLogger'@ to perform automated logging. module Utxorpc.Server-  ( runUtxorpc,+  ( -- * How to use this library+    -- $use++    -- ** Server Stream Methods+    -- $streaming++    -- ** Logging+    -- $logging++    -- * Running a service+    runUtxorpc,     ServiceConfig (..),     UtxorpcHandlers (..),     BuildHandlers (..),     SubmitHandlers (..),     SyncHandlers (..),     WatchHandlers (..),++    -- * Logging     UtxorpcServiceLogger (..),     RequestLogger,     ReplyLogger,@@ -31,7 +48,7 @@ -- | Run a UTxO RPC service from a @'ServiceConfig'@. runUtxorpc ::   (MonadIO m) =>-  -- | Configuration info and method handlers. See @'ServiceConfig'@ for type information.+  -- | Configuration info and method handlers.   ServiceConfig m a b c d e ->   IO () runUtxorpc@@ -49,7 +66,12 @@       (Utxorpc.Server.serviceHandlers logger unlift handlers)       compression --- | Configuration info and method handlers. See @'UtxorpcHandlers'@ for type info.+-- | 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. data ServiceConfig m a b c d e = ServiceConfig   { -- | warp-tls settings for using TLS.     tlsSettings :: TLSSettings,@@ -101,3 +123,45 @@       <> Submit.serviceHandlers logger unlift submitHandlers       <> Sync.serviceHandlers logger unlift syncHandlers       <> Watch.serviceHandlers logger unlift watchHandlers++-- $use+-- 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`.++-- $streaming+-- 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`](https://github.com/utxorpc/haskell-sdk/tree/main/server/example).++-- $example+-- [`/example`](https://github.com/utxorpc/haskell-sdk/tree/main/server/example) shows how to use the SDK by creating a u5c service with simple handlers that+-- execute a log function and return default (i.e., empty) replies. It demonstrates how to use the SDK+-- without dealing with implementation details of the handlers. It uses one of the following two loggers:+--+--     1. `/example/SimpleLogger.hs` is a simple logger implementation that prints human-readable output.+--+--     1. `/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 server-example -- --katip -p=443

utxorpc-server.cabal view

@@ -1,14 +1,19 @@ cabal-version: 3.0  name:           utxorpc-server-version:        0.0.1.0+version:        0.0.1.1 synopsis:       An SDK for UTxO RPC services.-description:    This SDK includes helper functions for creating a UTxO RPC service with automated logging.+description:    An SDK to reduce boilerplate, improve ease-of-use, and support logging for `utxorpc`.+                To get started, see the documentation for `Utxorpc.Server` 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/haskell-sdk#readme bug-reports:    https://github.com/utxorpc/haskell-sdk/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