// file: crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
// version: 7

/// 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. Subscription wrappers are implemented beside their wire owners in the
/// `ws_accounts`, `ws_blocks`, `ws_cluster` and `ws_transactions` modules.
///
/// ```compile_fail
/// async fn unsupported_helius_transaction(
///     session: &ksp_onchain_transport_lib::SolanaStandardWsSession,
///     request: &ksp_onchain_transport_lib::HeliusTransactionSubscribeRequest,
/// ) {
///     let _ = session.transaction_subscribe(request).await;
/// }
/// ```
#[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 a cloneable latest-value observer for safe physical-session snapshots from the shared actor.
    #[must_use]
    pub fn snapshot_source(&self) -> crate::WsSessionSnapshotSource {
        return self.inner.snapshot_source();
    }

    /// 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;
    }

    /// Returns the crate-private shared physical session used by domain-specific facade wrappers.
    pub(crate) fn physical_session(&self) -> &crate::WsSession {
        return &self.inner;
    }
}

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.
///
/// The facade exposes the seven standard Solana subscription families that the current Helius method pages support or document as available plus the
/// Helius-specific typed
/// `transactionSubscribe` lifecycle. Transaction notifications, reconnect/resubscribe, unsubscribe races and bounded backpressure all delegate to the same
/// shared [`crate::WsSession`] actor; the facade owns no second socket, registry or queue. 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_block(session: &ksp_onchain_transport_lib::HeliusLaserStreamWsSession) {
///     let _ = session.block_subscribe().await;
/// }
/// ```
///
/// ```compile_fail
/// async fn unsupported_vote(session: &ksp_onchain_transport_lib::HeliusLaserStreamWsSession) {
///     let _ = session.vote_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 a cloneable latest-value observer for safe physical-session snapshots from the shared actor.
    #[must_use]
    pub fn snapshot_source(&self) -> crate::WsSessionSnapshotSource {
        return self.inner.snapshot_source();
    }

    /// 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;
    }

    /// Returns the crate-private shared physical session used by domain-specific facade wrappers.
    pub(crate) fn physical_session(&self) -> &crate::WsSession {
        return &self.inner;
    }
}

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_helius_standard.rs"]
mod helius_standard_tests;

#[cfg(test)]
#[path = "../unit_tests/ws_protocol_session.rs"]
mod tests;