142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
# 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
|