# 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