v0.3.14-pre.003

crates/ksp-onchain-transport-lib/src/ws_session.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/ws_session.rs
-// version: 14
+// version: 15
 
 use futures_util::SinkExt; // rust-rules: trait-import
 use futures_util::StreamExt; // rust-rules: trait-import
@@ -10,6 +10,43 @@ const HELIUS_WS_HEARTBEAT_INTERVAL: std::time::Duration = std::time::Duration::f
 
 type WsPhysicalStream = tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
 
+/// Cloneable latest-value observer for one physical WebSocket session snapshot.
+///
+/// The observer exposes only the already-safe [`crate::WsSessionSnapshot`] projection and keeps the internal Tokio watch channel private. Cloning it does
+/// not create another socket, actor, reconnect loop or subscription registry.
+#[derive(Clone)]
+pub struct WsSessionSnapshotSource {
+    receiver: tokio::sync::watch::Receiver<crate::WsSessionSnapshot>,
+}
+
+impl crate::WsSessionSnapshotSource {
+    fn new(receiver: tokio::sync::watch::Receiver<crate::WsSessionSnapshot>) -> Self {
+        return Self { receiver };
+    }
+
+    /// Returns the current safe physical-session snapshot without waiting for another actor transition.
+    #[must_use]
+    pub fn current(&self) -> crate::WsSessionSnapshot {
+        return (*self.receiver.borrow()).clone();
+    }
+
+    /// Waits for one newer safe physical-session snapshot.
+    ///
+    /// `None` means the owning WebSocket actor dropped the latest-value publisher and no further snapshot can arrive.
+    pub async fn wait_for_change(&mut self) -> std::option::Option<crate::WsSessionSnapshot> {
+        return match self.receiver.changed().await {
+            std::result::Result::Ok(()) => std::option::Option::Some((*self.receiver.borrow_and_update()).clone()),
+            std::result::Result::Err(_) => std::option::Option::None,
+        };
+    }
+}
+
+impl std::fmt::Debug for crate::WsSessionSnapshotSource {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.debug_struct("WsSessionSnapshotSource").field("current", &self.current()).finish();
+    }
+}
+
 /// Shareable handle for one explicitly created physical WebSocket session.
 ///
 /// The handle never exposes the sensitive endpoint URL or the underlying socket. All socket I/O is owned by one internal actor task and all caller
@@ -124,6 +161,12 @@ impl WsSession {
         return self.snapshot_rx.borrow().clone();
     }
 
+    /// Returns a cloneable latest-value observer for safe physical-session snapshots.
+    #[must_use]
+    pub fn snapshot_source(&self) -> crate::WsSessionSnapshotSource {
+        return crate::WsSessionSnapshotSource::new(self.snapshot_rx.clone());
+    }
+
     /// Returns the latest observable physical-session state.
     #[must_use]
     pub fn state(&self) -> crate::WsSessionState {