From d946622738f6aa6aa4f4ed17ae7a8aa751ab4dc0 Mon Sep 17 00:00:00 2001 From: Ismail Akram Date: Sun, 11 Jan 2026 01:57:48 +0500 Subject: [PATCH] README --- README.md | 258 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 256 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc651c5..5a50425 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,257 @@ -# wcli +# wcli - WAMP Command Line Interface -WAMP CLI Tool +A command-line tool for interacting with WAMP (Web Application Messaging Protocol) routers. Supports calling procedures, publishing events, registering procedures, and subscribing to topics. + +## Installation + +```bash +cargo build --release +``` + +## Global Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--url ` | Router URL to connect to | `ws://localhost:8080/ws` | +| `--realm ` | Realm to join | `realm1` | +| `--serializer ` | Serializer (json, msgpack, cbor) | `json` | +| `--authid ` | Authentication ID | - | +| `--authrole ` | Authentication role | - | +| `--ticket ` | Ticket for ticket authentication | - | +| `--secret ` | Secret for Challenge-Response Auth | - | +| `--private-key ` | ed25519 private key for cryptosign | - | + +--- + +## Commands + +### Call Procedure + +Call a remote procedure with arguments. + +```bash +# Basic call +wcli call com.example.add 1 2 + +# Call with keyword arguments +wcli call com.example.greet -k name=Alice -k age=30 + +# Call with options +wcli call com.example.fetch -o timeout=5000 + +# Stress testing: call 100 times across 10 parallel sessions +wcli call com.example.ping --repeat 100 --parallel 10 --concurrency 5 +``` + +**Options:** +- `-k, --kwarg KEY=VALUE` - Keyword argument (repeatable) +- `-o, --option KEY=VALUE` - WAMP call option (repeatable) +- `--repeat N` - Number of calls per session (default: 1) +- `--parallel N` - Number of parallel sessions (default: 1) +- `--concurrency N` - Maximum concurrent sessions (default: 1) + +--- + +### Register Procedure + +Register a procedure and handle incoming invocations. + +```bash +# Register a procedure +wcli register com.example.echo + +# The handler prints received args/kwargs as JSON and echoes them back +# Press Ctrl+C to exit +``` + +--- + +### Subscribe to Topic + +Subscribe to a topic and receive events. + +```bash +# Subscribe to a topic +wcli subscribe com.example.events + +# Multiple parallel subscribers +wcli subscribe com.example.events --parallel 10 + +# With concurrency limit +wcli subscribe com.example.events --parallel 100 --concurrency 10 +``` + +**Options:** +- `--parallel N` - Number of parallel sessions to subscribe (default: 1) +- `--concurrency N` - Maximum concurrent sessions (default: 1) + +--- + +### Publish to Topic + +Publish events to a topic. + +```bash +# Basic publish +wcli publish com.example.events "Hello, World!" + +# Publish with arguments +wcli publish com.example.events 42 true "message" + +# Publish with keyword arguments +wcli publish com.example.events -k user=Alice -k action=login + +# Request acknowledgement from the broker +wcli publish com.example.events "data" --acknowledge + +# Stress testing: publish 1000 events +wcli publish com.example.events "test" --repeat 1000 --parallel 10 +``` + +**Options:** +- `-k, --kwarg KEY=VALUE` - Keyword argument (repeatable) +- `-o, --option KEY=VALUE` - WAMP publish option (repeatable) +- `--acknowledge` - Request acknowledgement from broker +- `--repeat N` - Number of publishes per session (default: 1) +- `--parallel N` - Number of parallel sessions (default: 1) +- `--concurrency N` - Maximum concurrent sessions (default: 1) + +--- + +### Generate Keypair + +Generate an ed25519 keypair for cryptosign authentication. + +```bash +# Generate and display keypair +wcli keygen + +# Output: +# Public Key: 74bcb0f9636780f5a5d7bf319f5441b654203aad17aef92e01f70d161381da9d +# Private Key: ae742323f8da546407cc0abef409c714ba7e747e534e82632670dbf938a2b755 + +# Save keypair to files (key and key.pub) +wcli keygen -O + +# Save with custom filename (my_keys and my_keys.pub) +wcli keygen -O my_keys +``` + +--- + +## Authentication + +wcli supports multiple authentication methods. The priority order is: +1. **Cryptosign** (if `--private-key` is provided) +2. **WAMP-CRA** (if `--secret` is provided) +3. **Ticket** (if `--ticket` is provided) +4. **Anonymous** (default) + +### Ticket Authentication + +```bash +wcli --authid alice --ticket my-secret-ticket call com.example.protected +``` + +### WAMP-CRA (Challenge-Response Authentication) + +```bash +wcli --authid alice --secret my-secret-password call com.example.protected +``` + +### Cryptosign Authentication + +```bash +# First, generate a keypair +wcli keygen -O + +# Use the private key for authentication +wcli --authid alice --private-key ae742323f8da546407cc0abef409c714ba7e747e534e82632670dbf938a2b755 call com.example.protected + +# Or read from file +wcli --authid alice --private-key "$(cat key)" call com.example.protected +``` + +### With Authrole + +```bash +wcli --authid alice --authrole admin --ticket my-ticket call com.example.admin_only +``` + +--- + +## Serializers + +wcli supports three serialization formats: + +### JSON (Default) + +```bash +wcli --serializer json call com.example.echo "hello" +``` + +### MessagePack + +More efficient binary serialization. + +```bash +wcli --serializer msgpack call com.example.echo "hello" +``` + +### CBOR + +Concise Binary Object Representation. + +```bash +wcli --serializer cbor call com.example.echo "hello" +``` + +--- + +## Argument Types + +Arguments are automatically parsed as: +- **Integer**: `42`, `-10` +- **Float**: `3.14`, `-0.5` +- **Boolean**: `true`, `false` +- **String**: `hello`, `"hello world"` + +To force a value to be a string (e.g., the number `123` as a string), use quotes: + +```bash +wcli call com.example.echo "'123'" +wcli call com.example.echo '"true"' +``` + +--- + +## Examples + +### Complete Workflow + +```bash +# Terminal 1: Register a procedure +wcli register com.example.add + +# Terminal 2: Call the procedure +wcli call com.example.add 5 3 + +# Terminal 1: Subscribe to events +wcli subscribe com.example.notifications + +# Terminal 2: Publish an event +wcli publish com.example.notifications "New message!" -k from=system +``` + +### Custom Router + +```bash +wcli --url ws://router.example.com:8080/ws --realm production call com.api.status +``` + +### Stress Testing + +```bash +# 10 parallel sessions, each making 100 calls, max 5 concurrent +wcli call com.example.ping --parallel 10 --repeat 100 --concurrency 5 +```