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:

Connection Establishment: WebSocket connection to the server
Authentication Flow: secp256k1 challenge-response authentication
Keep-Alive Monitoring: Periodic health checks to ensure connection stability
Automatic Reconnection: Transparent reconnection on connection failures
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

4.5 KiB Raw Blame History