// file: kb_lib/src/ws_client.rs

//! Generic asynchronous WebSocket client skeleton.
//!
//! This module prepares the shape of the future Solana WebSocket transport.
//! The actual transport loop, split read/write tasks, request tracking,
//! subscribe registry, and notification routing are scheduled for `0.1.x`
//! and `0.2.x` / `0.3.x`.

/// Generic asynchronous WebSocket client placeholder.
#[derive(Clone, Debug)]
pub struct WsClient {
    endpoint: crate::KbWsEndpointConfig,
    next_request_id: std::sync::Arc<std::sync::atomic::AtomicU64>,
    state: std::sync::Arc<tokio::sync::RwLock<crate::KbConnectionState>>,
}

impl WsClient {
    /// Creates a new WebSocket client bound to a named endpoint configuration.
    pub fn new(endpoint: crate::KbWsEndpointConfig) -> Result<Self, crate::KbError> {
        if endpoint.name.trim().is_empty() {
            return Err(crate::KbError::Config(
                "ws client endpoint name must not be empty".to_string(),
            ));
        }
        Ok(Self {
            endpoint,
            next_request_id: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(1)),
            state: std::sync::Arc::new(tokio::sync::RwLock::new(
                crate::KbConnectionState::Disconnected,
            )),
        })
    }

    /// Returns the endpoint name of this client.
    pub fn endpoint_name(&self) -> &str {
        &self.endpoint.name
    }

    /// Returns the endpoint URL of this client.
    pub fn endpoint_url(&self) -> &str {
        &self.endpoint.url
    }

    /// Returns the endpoint configuration of this client.
    pub fn endpoint_config(&self) -> &crate::KbWsEndpointConfig {
        &self.endpoint
    }

    /// Returns the next request identifier and increments the internal counter.
    pub fn next_request_id(&self) -> u64 {
        self.next_request_id
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed)
    }

    /// Returns the current connection state.
    pub async fn connection_state(&self) -> crate::KbConnectionState {
        let state_guard = self.state.read().await;
        *state_guard
    }

    /// Connects the client to its remote WebSocket endpoint.
    pub async fn connect(&self) -> Result<(), crate::KbError> {
        Err(crate::KbError::NotImplemented(
            "WsClient::connect is scheduled for version 0.1.x".to_string(),
        ))
    }

    /// Sends a text frame through the WebSocket connection.
    pub async fn send_text(&self, _text: std::string::String) -> Result<(), crate::KbError> {
        Err(crate::KbError::NotImplemented(
            "WsClient::send_text is scheduled for version 0.1.x".to_string(),
        ))
    }

    /// Sends a JSON value through the WebSocket connection.
    pub async fn send_json_value(&self, _value: &serde_json::Value) -> Result<(), crate::KbError> {
        Err(crate::KbError::NotImplemented(
            "WsClient::send_json_value is scheduled for version 0.2.x".to_string(),
        ))
    }

    /// Disconnects the client from its remote endpoint.
    ///
    /// The final implementation will unsubscribe with timeout before close.
    pub async fn disconnect(&self) -> Result<(), crate::KbError> {
        Err(crate::KbError::NotImplemented(
            "WsClient::disconnect is scheduled for version 0.1.x / 0.3.x".to_string(),
        ))
    }
}