136 lines
3.5 KiB
Markdown
136 lines
3.5 KiB
Markdown
# 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:
|
|
```bash
|
|
cargo build --bin circles_client --release
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Create a `.env` file in the `cmd/` directory:
|
|
```bash
|
|
# cmd/.env
|
|
PRIVATE_KEY=your_actual_private_key_hex_here
|
|
```
|
|
|
|
Or set the environment variable directly:
|
|
```bash
|
|
export PRIVATE_KEY=your_actual_private_key_hex_here
|
|
```
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
cargo install trunk
|
|
```
|
|
|
|
2. Build the WASM version:
|
|
```bash
|
|
trunk build --release
|
|
```
|
|
|
|
3. Serve the application:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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 |