diff --git a/CHANGELOG.md b/CHANGELOG.md index 544ab59d9e3..8c287e27365 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,10 @@ changes. bleeding-edge from `master` branch is available at https://hydra.family/head-protocol/unstable. +- API clients can decide if they want to: + + Skip observing history of events before they connected + + View the transactions in the server output encoded as CBOR + ## [0.9.0] - 2023-03-02 :dragon_face: Renamed the repository from `hydra-poc` to [`hydra`](https://github.com/input-output-hk/hydra)! diff --git a/docs/core-concepts/behavior.md b/docs/core-concepts/behavior.md index 845aa4e85ee..8fcc2d2531e 100644 --- a/docs/core-concepts/behavior.md +++ b/docs/core-concepts/behavior.md @@ -18,4 +18,11 @@ A special case is the `RolledBack` output. This means that the chain rolled back ## Replay of past server outputs -When a `hydra-node` restarts, it will load it's history from persistence and replay previous server outputs to enable clients to re-establish their state upon re-connection. If that happens, obviously some of these outputs are not relevant anymore. One example of this is the `PeerConnected` and `PeerDisconnected`. To make it possible to determine the end of replayed history, client applications can use the `Greetings`, which will be emitted on every `hydra-node` start. See the `hydra-tui` example client for how this is handled. \ No newline at end of file +When a `hydra-node` restarts, by default it will load it's history from persistence and replay previous server outputs to enable clients to re-establish their state upon re-connection. If that happens, obviously some of these outputs are not relevant anymore. One example of this is the `PeerConnected` and `PeerDisconnected`. To make it possible to determine the end of replayed history, client applications can use the `Greetings`, which will be emitted on every `hydra-node` start. See the `hydra-tui` example client for how this is handled. + +Clients can optionally decide to skip history outputs and receive only the `Greetings` and following ones. In order to do that they can use query param `history=no`. + +They can also decide to be served with transactions encoded as CBOR by using query param `tx-output=cbor`. + +For example if the client wants to connect to a local `hydra-node` and doesn't want to view the server history but also want to have the +transactions encoded as CBOR (base16) they would connect using default port `4001` and the full path `ws://localhost:4001/?history=0&tx-output=cbor`. diff --git a/hydra-node/json-schemas/api.yaml b/hydra-node/json-schemas/api.yaml index cf3b504877d..552d5caf341 100644 --- a/hydra-node/json-schemas/api.yaml +++ b/hydra-node/json-schemas/api.yaml @@ -6,7 +6,9 @@ info: WebSocket API for administrating & interacting with Hydra Heads: multi-party isomorphic state-channels for Cardano. Once started, a Hydra node provides an API in the forms of JSON messages over WebSocket. An Hydra node is an event-driven application where users (a.k.a you) are one possible source of inputs. Other sources can be mainly other Hydra nodes in the network, or transactions observed on the layer 1 (e.g. a closing transaction). - Therefore, once connected, clients receive a stream of outputs as they arrive. They can interact with their node by pushing events to it, some are local, and some will have consequences on the rest of the head. + Therefore, once connected, clients receive a stream of outputs as they arrive. Clients get to decide (using query parameters) if they want to observe the history of outputs and the transaction format. + For example if client provides a path that looks like this `/?history=0&tx-output=cbor` the server will not serve prior history of server outputs and the transaction fields in the json will be encoded as CBOR. + They can interact with their node by pushing events to it, some are local, and some will have consequences on the rest of the head. See [the documentation](https://hydra.family/head-protocol/core-concepts/behavior/) for more details on the overall API behavior. > By default, a Hydra node listens for TCP WebSocket connections on port `tcp/4001` . This can be changed using `--port`. diff --git a/hydra-node/src/Hydra/API/Server.hs b/hydra-node/src/Hydra/API/Server.hs index f216066ce9d..33657c17d94 100644 --- a/hydra-node/src/Hydra/API/Server.hs +++ b/hydra-node/src/Hydra/API/Server.hs @@ -142,12 +142,12 @@ runAPIServer host port party tracer history callback responseChannel = do traceWith tracer NewAPIConnection -- api client can decide if they want to see the past history of server outputs - serveHistory <- shouldServeHistory queryParams - if serveHistory - then forwardHistory con - else forwardGreetingOnly con + dontServeHistory <- shouldNotServeHistory queryParams + if dontServeHistory + then forwardGreetingOnly con + else forwardHistory con - -- api client can decides if they want tx's to be displayed as CBOR instead of plain json + -- api client can decide if they want tx's to be displayed as CBOR instead of plain json txDisplay <- decideOnTxDisplay queryParams withPingThread con 30 (pure ()) $ @@ -171,9 +171,9 @@ runAPIServer host port party tracer history callback responseChannel = do True -> TxCBOR False -> TxJSON - shouldServeHistory qp = do + shouldNotServeHistory qp = do k <- mkQueryKey "history" - v <- mkQueryValue "1" + v <- mkQueryValue "0" pure $ (QueryParam k v) `elem` qp onIOException ioException = diff --git a/hydra-node/test/Hydra/API/ServerSpec.hs b/hydra-node/test/Hydra/API/ServerSpec.hs index b2fda607d78..7eac2f6f098 100644 --- a/hydra-node/test/Hydra/API/ServerSpec.hs +++ b/hydra-node/test/Hydra/API/ServerSpec.hs @@ -167,9 +167,7 @@ spec = parallel $ do -- if client doesn't specify anything they will get tx encoded as JSON withClient port defaultPath $ \conn -> do sendOutput txValidMessage - -- receive greetings + one more message received :: [ByteString] <- replicateM 2 (receiveData conn) - -- make sure tx output is valid tx cbor (received List.!! 1) ^? key "transaction" . nonNull `shouldBe` Just (toJSON tx)