0.0.2

kb_lib/src/ws_client.rs

@@ -0,0 +1,91 @@
+// 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(),
+        ))
+    }
+}