hero/interfaces/websocket/client/cmd/README.md

Circles WebSocket Client

A WebSocket client for connecting to Circles servers with authentication support. Available in both CLI and WebAssembly (WASM) versions.

CLI Usage

Installation

Build the CLI binary:

cargo build --bin circles_client --release

Configuration

Create a .env file in the cmd/ directory:

# cmd/.env
PRIVATE_KEY=your_actual_private_key_hex_here

Or set the environment variable directly:

export PRIVATE_KEY=your_actual_private_key_hex_here

Usage

# Basic usage - connects and enters interactive mode
circles_client ws://localhost:8080

# Execute a single Rhai script
circles_client -s "print('Hello from Rhai!')" ws://localhost:8080

# Execute a script from file
circles_client -f script.rhai ws://localhost:8080

# Increase verbosity (can be used multiple times)
circles_client -v ws://localhost:8080
circles_client -vv ws://localhost:8080

Features

• Authentication: Automatically loads private key and completes secp256k1 authentication flow
• Script Execution: Supports both inline scripts (-s) and script files (-f)
• Interactive Mode: When no script is provided, enters interactive REPL mode
• Verbosity Control: Use -v flags to increase logging detail
• Cross-platform: Works on all platforms supported by Rust and tokio-tungstenite

WebAssembly (WASM) Usage

Build and Serve

1. Install Trunk:

cargo install trunk

2. Build the WASM version:

trunk build --release

3. Serve the application:

trunk serve

The application will be available at http://localhost:8080

Usage in Browser

1. Open the served page in your browser
2. Enter the WebSocket server URL
3. Choose either:
   • Execute a Rhai script directly
   • Enter interactive mode (type 'exit' or 'quit' to leave)

Features

• Browser Integration: Uses browser's WebSocket implementation
• Interactive Mode: Browser-based input/output using prompts
• Error Handling: Browser console logging
• Cross-browser: Works in all modern browsers supporting WebAssembly

Common Features

Both versions share the same core functionality:

• WebSocket Connection: Connects to Circles WebSocket server
• Authentication: Handles secp256k1 authentication
• Script Execution: Executes Rhai scripts
• Interactive Mode: Provides REPL-like interface
• Error Handling: Comprehensive error reporting
• Logging: Detailed logging at different verbosity levels

Interactive Mode

When run without -s or -f flags, the client enters interactive mode where you can:

• Enter Rhai scripts line by line
• Type exit or quit to close the connection
• Use Ctrl+C to terminate

Examples

# Connect to local development server
circles_client ws://localhost:8080

# Connect to secure WebSocket with verbose logging
circles_client -v wss://circles.example.com/ws

# Execute a simple calculation
circles_client -s "let result = 2 + 2; print(result);" ws://localhost:8080

# Load and execute a complex script
circles_client -f examples/complex_script.rhai ws://localhost:8080

Error Handling

The client provides clear error messages for common issues:

• Missing or invalid private key
• Connection failures
• Authentication errors
• Script execution errors

Dependencies

• tokio-tungstenite: WebSocket client implementation
• secp256k1: Cryptographic authentication
• clap: Command-line argument parsing
• env_logger: Logging infrastructure
• dotenv: Environment variable loading