v0.2.8-pre.002

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

@@ -0,0 +1,182 @@
+// file: crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
+// version: 1
+
+/// Typed facade for one standard Solana WebSocket physical session.
+///
+/// The facade delegates to the same [`crate::WsSession`] actor used by the compatibility API. It owns no socket, registry, reconnect loop or queue of its
+/// own and therefore does not duplicate the physical WebSocket runtime.
+#[derive(Clone)]
+pub struct SolanaStandardWsSession {
+    inner: crate::WsSession,
+}
+
+impl SolanaStandardWsSession {
+    /// Opens one standard Solana WebSocket session through the shared physical actor.
+    pub async fn connect(endpoint: crate::WsEndpointSettings) -> ksp_core_lib::Result<Self> {
+        let connected = crate::WsSession::connect_for_protocol(endpoint, crate::WsProtocolKind::SolanaStandard).await;
+        return match connected {
+            std::result::Result::Ok(inner) => std::result::Result::Ok(Self { inner }),
+            std::result::Result::Err(error) => std::result::Result::Err(error),
+        };
+    }
+
+    /// Returns the stable local session identity.
+    #[must_use]
+    pub const fn id(&self) -> crate::WsSessionId {
+        return self.inner.id();
+    }
+
+    /// Returns the latest safe runtime snapshot published by the shared actor.
+    #[must_use]
+    pub fn snapshot(&self) -> crate::WsSessionSnapshot {
+        return self.inner.snapshot();
+    }
+
+    /// Returns the latest observable physical-session state.
+    #[must_use]
+    pub fn state(&self) -> crate::WsSessionState {
+        return self.inner.state();
+    }
+
+    /// Explicitly closes the shared physical session under its configured close timeout.
+    pub async fn close(&self) -> ksp_core_lib::Result<()> {
+        return self.inner.close().await;
+    }
+
+    /// Subscribes to changes for one Solana account through standard `accountSubscribe`.
+    pub async fn account_subscribe(
+        &self,
+        account: &ksp_core_lib::Pubkey,
+        config: std::option::Option<&crate::SolanaAccountSubscribeConfig>,
+    ) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaRpcResponse<crate::SolanaAccount>>> {
+        return self.inner.account_subscribe(account, config).await;
+    }
+
+    /// Subscribes to unstable standard Solana block notifications through `blockSubscribe`.
+    pub async fn block_subscribe(
+        &self,
+        filter: &crate::SolanaBlockSubscribeFilter,
+        config: std::option::Option<&crate::SolanaBlockSubscribeConfig>,
+    ) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaRpcResponse<crate::SolanaBlockNotification>>> {
+        return self.inner.block_subscribe(filter, config).await;
+    }
+
+    /// Subscribes to Solana transaction logs through standard `logsSubscribe`.
+    pub async fn logs_subscribe(
+        &self,
+        filter: &crate::SolanaLogsSubscribeFilter,
+        config: std::option::Option<&crate::SolanaCommitmentConfig>,
+    ) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaRpcResponse<crate::SolanaLogsNotification>>> {
+        return self.inner.logs_subscribe(filter, config).await;
+    }
+
+    /// Subscribes to account changes owned by one Solana program through standard `programSubscribe`.
+    pub async fn program_subscribe(
+        &self,
+        program_id: &ksp_core_lib::Pubkey,
+        config: std::option::Option<&crate::SolanaProgramSubscribeConfig>,
+    ) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaProgramNotification>> {
+        return self.inner.program_subscribe(program_id, config).await;
+    }
+
+    /// Subscribes to standard Solana root-slot notifications through `rootSubscribe`.
+    pub async fn root_subscribe(&self) -> ksp_core_lib::Result<crate::WsSubscription<u64>> {
+        return self.inner.root_subscribe().await;
+    }
+
+    /// Subscribes to one Solana transaction signature through standard `signatureSubscribe`.
+    pub async fn signature_subscribe(
+        &self,
+        signature: &str,
+        config: std::option::Option<&crate::SolanaSignatureSubscribeConfig>,
+    ) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaRpcResponse<crate::SolanaSignatureNotification>>> {
+        return self.inner.signature_subscribe(signature, config).await;
+    }
+
+    /// Subscribes to standard Solana slot-processing notifications through `slotSubscribe`.
+    pub async fn slot_subscribe(&self) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaSlotNotification>> {
+        return self.inner.slot_subscribe().await;
+    }
+
+    /// Subscribes to unstable standard Solana slot-lifecycle notifications through `slotsUpdatesSubscribe`.
+    pub async fn slots_updates_subscribe(&self) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaSlotUpdate>> {
+        return self.inner.slots_updates_subscribe().await;
+    }
+
+    /// Subscribes to unstable pre-consensus gossip vote notifications through `voteSubscribe`.
+    pub async fn vote_subscribe(&self) -> ksp_core_lib::Result<crate::WsSubscription<crate::SolanaVoteNotification>> {
+        return self.inner.vote_subscribe().await;
+    }
+}
+
+impl std::fmt::Debug for SolanaStandardWsSession {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.debug_struct("SolanaStandardWsSession").field("id", &self.id()).field("snapshot", &self.snapshot()).finish();
+    }
+}
+
+/// Typed facade for one Helius LaserStream WebSocket physical session.
+///
+/// `0.2.8-pre.002` intentionally exposes only physical-session lifecycle through this facade. The six Helius-supported standard subscription wrappers are
+/// added in the next tranche after exact delegation and API-absence canaries are established. No public inner handle is exposed, so callers cannot bypass
+/// the provider-specific surface by recovering a generic [`crate::WsSession`].
+///
+/// ```compile_fail
+/// async fn unsupported(session: &ksp_onchain_transport_lib::HeliusLaserStreamWsSession) {
+///     let _ = session.block_subscribe().await;
+/// }
+/// ```
+///
+/// ```compile_fail
+/// fn no_escape_hatch(session: ksp_onchain_transport_lib::HeliusLaserStreamWsSession) {
+///     let _ = session.into_inner();
+/// }
+/// ```
+#[derive(Clone)]
+pub struct HeliusLaserStreamWsSession {
+    inner: crate::WsSession,
+}
+
+impl HeliusLaserStreamWsSession {
+    /// Opens one Helius LaserStream WebSocket session through the shared physical actor.
+    pub async fn connect(endpoint: crate::WsEndpointSettings) -> ksp_core_lib::Result<Self> {
+        let connected = crate::WsSession::connect_for_protocol(endpoint, crate::WsProtocolKind::HeliusLaserStream).await;
+        return match connected {
+            std::result::Result::Ok(inner) => std::result::Result::Ok(Self { inner }),
+            std::result::Result::Err(error) => std::result::Result::Err(error),
+        };
+    }
+
+    /// Returns the stable local session identity.
+    #[must_use]
+    pub const fn id(&self) -> crate::WsSessionId {
+        return self.inner.id();
+    }
+
+    /// Returns the latest safe runtime snapshot published by the shared actor.
+    #[must_use]
+    pub fn snapshot(&self) -> crate::WsSessionSnapshot {
+        return self.inner.snapshot();
+    }
+
+    /// Returns the latest observable physical-session state.
+    #[must_use]
+    pub fn state(&self) -> crate::WsSessionState {
+        return self.inner.state();
+    }
+
+    /// Explicitly closes the shared physical session under its configured close timeout.
+    pub async fn close(&self) -> ksp_core_lib::Result<()> {
+        return self.inner.close().await;
+    }
+}
+
+impl std::fmt::Debug for HeliusLaserStreamWsSession {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.debug_struct("HeliusLaserStreamWsSession").field("id", &self.id()).field("snapshot", &self.snapshot()).finish();
+    }
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/ws_protocol_session.rs"]
+mod tests;