initial commit

interfaces/websocket/client/README.md

@@ -0,0 +1,141 @@
+# Circle WebSocket Client
+
+A Rust library for connecting to Circle WebSocket servers with authentication support and self-managing connection lifecycle.
+
+## Features
+
+- **Cross-platform WebSocket client** (native and WASM)
+- **secp256k1 cryptographic authentication** with automatic challenge-response flow
+- **JSON-RPC 2.0 protocol support** for server communication
+- **Self-managing connections** with automatic keep-alive and reconnection
+- **Async/await interface** with modern Rust async patterns
+- **Built on tokio-tungstenite** for reliable WebSocket connections (native)
+- **Built on gloo-net** for WASM browser compatibility
+
+## Architecture
+
+Each `CircleWsClient` is completely self-managing:
+
+- **Automatic Connection Management**: Handles WebSocket connection establishment
+- **Built-in Authentication**: Seamless secp256k1 authentication when private keys are provided
+- **Keep-Alive Monitoring**: Periodic health checks to detect connection issues
+- **Transparent Reconnection**: Automatic reconnection with exponential backoff on failures
+- **Connection Status Tracking**: Real-time connection state monitoring
+
+## Usage
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+circle_client_ws = { path = "../client_ws" }
+```
+
+### Basic Example (Self-Managing Connection)
+
+```rust
+use circle_client_ws::CircleWsClientBuilder;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create client with private key
+    let private_key = "your_private_key_hex";
+    let mut client = CircleWsClientBuilder::new("ws://localhost:8080".to_string())
+        .with_keypair(private_key.to_string())
+        .build();
+    
+    // Connect - this handles authentication, keep-alive, and reconnection automatically
+    client.connect().await?;
+    
+    // Check connection status
+    println!("Connected: {}", client.is_connected());
+    
+    // Execute scripts on the server
+    let result = client.play("\"Hello from client!\"".to_string()).await?;
+    println!("Script result: {:?}", result);
+    
+    // Client automatically maintains connection in the background
+    // No manual keep-alive or reconnection logic needed
+    
+    Ok(())
+}
+```
+
+### Self-Managing Features
+
+The client automatically handles:
+
+1. **Connection Establishment**: WebSocket connection to the server
+2. **Authentication Flow**: secp256k1 challenge-response authentication
+3. **Keep-Alive Monitoring**: Periodic health checks to ensure connection stability
+4. **Automatic Reconnection**: Transparent reconnection on connection failures
+5. **Resource Management**: Proper cleanup when the client is dropped
+
+### Connection Status Monitoring
+
+```rust
+// Check if the client is currently connected
+if client.is_connected() {
+    println!("Client is connected and healthy");
+} else {
+    println!("Client is disconnected or reconnecting");
+}
+
+// Get detailed connection status
+let status = client.get_connection_status();
+println!("Connection status: {}", status);
+```
+
+### WASM Usage
+
+For WASM applications, the client works seamlessly in browsers:
+
+```rust
+use circle_client_ws::CircleWsClientBuilder;
+use wasm_bindgen_futures::spawn_local;
+
+// In a WASM context
+spawn_local(async move {
+    let mut client = CircleWsClientBuilder::new("ws://localhost:8080".to_string())
+        .build();
+    
+    // Self-managing connection works the same in WASM
+    if let Ok(_) = client.connect().await {
+        // Client automatically handles keep-alive and reconnection
+        let result = client.play("\"WASM client connected!\"".to_string()).await;
+        // Handle result...
+    }
+});
+```
+
+## Binary Tool
+
+A command-line binary is also available for interactive use and script execution. See [`cmd/README.md`](cmd/README.md) for details.
+
+## Platform Support
+
+- **Native**: Full support on all Rust-supported platforms with tokio-tungstenite
+- **WASM**: Browser support with gloo-net WebSocket bindings
+
+## Dependencies
+
+### Core Dependencies
+- `serde`: JSON serialization and deserialization
+- `uuid`: Request ID generation for JSON-RPC
+- `futures-util`: Async utilities for WebSocket handling
+- `thiserror`: Error handling and propagation
+
+### Platform-Specific Dependencies
+
+#### Native (tokio-based)
+- `tokio-tungstenite`: Robust WebSocket implementation
+- `tokio`: Async runtime for connection management
+
+#### WASM (browser-based)
+- `gloo-net`: WebSocket bindings for browsers
+- `gloo-timers`: Timer utilities for keep-alive functionality
+- `wasm-bindgen-futures`: Async support in WASM
+
+### Cryptographic Dependencies (optional)
+- `secp256k1`: Elliptic curve cryptography for authentication
+- `sha3`: Hashing for cryptographic operations