Add address query parameter to ws server (#1739)

<!-- Describe your change here -->

To filter transaction server outputs by given address.

Fixes #1719
---

<!-- Consider each and tick it off one way or the other -->
* [x] CHANGELOG updated or not needed
* [x] Documentation updated or not needed
* [x] Haddocks updated or not needed
* [x] No new TODOs introduced or explained herafter

Author: ffakenz

CHANGELOG.md

@@ -48,7 +48,7 @@ changes.
 
 - Update mithril to `2442.0`
 
-
+- New websocket URL parameter `?address=...` to filter `SnapshotConfirmed`, `TxValid` and `TxInvalid` server outputs by address.
 
 ## [0.19.0] - 2024-09-13
 

docs/docs/api-behavior.md

@@ -20,6 +20,7 @@ There are some options for API clients to control the server outputs. Server out
 
 + `history=no` -> Prevents historical outputs display. All server outputs are recorded and when a client re-connects these outputs are replayed unless `history=no` query param is used.
 + `snapshot-utxo=no` -> In case of a `SnapshotConfirmed` message the `utxo` field in the inner `Snapshot` will be omitted.
++ `address=$address` -> In the case of a `TxValid` or a `TxInvalid` message, it will be filtered if its `transaction` address does not contain a reference to the provided. In the case of a `SnapshotConfirmed` message, it will be filtered if its `confirmed` transactions do not contain an address that references the one provided.
 
 ## Replay of past server outputs
 

hydra-cluster/hydra-cluster.cabal

@@ -151,6 +151,7 @@ test-suite tests
     Test.GeneratorSpec
     Test.Hydra.Cluster.CardanoCliSpec
     Test.Hydra.Cluster.FaucetSpec
+    Test.Hydra.Cluster.HydraClientSpec
     Test.Hydra.Cluster.MithrilSpec
     Test.Hydra.Cluster.Utils
     Test.OfflineChainSpec

hydra-cluster/src/HydraNode.hs

@@ -88,6 +88,14 @@ output tag pairs = object $ ("tag" .= tag) : pairs
 waitFor :: HasCallStack => Tracer IO HydraNodeLog -> NominalDiffTime -> [HydraClient] -> Aeson.Value -> IO ()
 waitFor tracer delay nodes v = waitForAll tracer delay nodes [v]
 
+-- | Wait up to some time and succeed if no API server output matches the given predicate.
+waitNoMatch :: HasCallStack => NominalDiffTime -> HydraClient -> (Aeson.Value -> Maybe a) -> IO ()
+waitNoMatch delay client match = do
+  result <- try (void $ waitMatch delay client match) :: IO (Either SomeException ())
+  case result of
+    Left _ -> pure () -- Success: waitMatch failed to find a match
+    Right _ -> failure "waitNoMatch: A match was found when none was expected"
+
 -- | Wait up to some time for an API server output to match the given predicate.
 waitMatch :: HasCallStack => NominalDiffTime -> HydraClient -> (Aeson.Value -> Maybe a) -> IO a
 waitMatch delay client@HydraClient{tracer, hydraNodeId} match = do
@@ -406,7 +414,7 @@ withConnectionToNode tracer hydraNodeId =
   port = fromInteger $ 4_000 + toInteger hydraNodeId
 
 withConnectionToNodeHost :: forall a. Tracer IO HydraNodeLog -> Int -> Host -> Maybe String -> (HydraClient -> IO a) -> IO a
-withConnectionToNodeHost tracer hydraNodeId apiHost@Host{hostname, port} queryParams action = do
+withConnectionToNodeHost tracer hydraNodeId apiHost@Host{hostname, port} mQueryParams action = do
   connectedOnce <- newIORef False
   tryConnect connectedOnce (200 :: Int)
  where
@@ -424,9 +432,9 @@ withConnectionToNodeHost tracer hydraNodeId apiHost@Host{hostname, port} queryPa
                     , Handler $ retryOrThrow (Proxy @HandshakeException)
                     ]
 
-  historyMode = fromMaybe "/" queryParams
+  queryParams = fromMaybe "/" mQueryParams
 
-  doConnect connectedOnce = runClient (T.unpack hostname) (fromInteger . toInteger $ port) historyMode $
+  doConnect connectedOnce = runClient (T.unpack hostname) (fromInteger . toInteger $ port) queryParams $
     \connection -> do
       atomicWriteIORef connectedOnce True
       traceWith tracer (NodeStarted hydraNodeId)

hydra-cluster/test/Test/EndToEndSpec.hs

@@ -638,7 +638,7 @@ timedTx tmpDir tracer node@RunningNode{networkId, nodeSocket} hydraScriptsTxId =
     -- Second submission: now valid
     send n1 $ input "NewTx" ["transaction" .= tx]
     waitFor hydraTracer 3 [n1] $
-      output "TxValid" ["transactionId" .= txId tx, "headId" .= headId]
+      output "TxValid" ["transactionId" .= txId tx, "headId" .= headId, "transaction" .= tx]
 
     confirmedTransactions <- waitMatch 3 n1 $ \v -> do
       guard $ v ^? key "tag" == Just "SnapshotConfirmed"
@@ -693,7 +693,7 @@ initAndClose tmpDir tracer clusterIx hydraScriptsTxId node@RunningNode{nodeSocke
             aliceExternalSk
     send n1 $ input "NewTx" ["transaction" .= tx]
     waitFor hydraTracer 10 [n1, n2, n3] $
-      output "TxValid" ["transactionId" .= txId tx, "headId" .= headId]
+      output "TxValid" ["transactionId" .= txId tx, "headId" .= headId, "transaction" .= tx]
 
     -- The expected new utxo set is the created payment to bob,
     -- alice's remaining utxo in head and whatever bot has