baobab/interfaces/websocket/client

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:

[dependencies]
circle_client_ws = { path = "../client_ws" }

Basic Example (Self-Managing Connection)

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

// 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:

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 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