hero/core/dispatcher/cmd/README.md

Rhai Client Binary

A command-line client for executing Rhai scripts on remote workers via Redis.

Binary: client

Installation

Build the binary:

cargo build --bin client --release

Usage

# Basic usage - requires caller and circle keys
client --caller-key <CALLER_KEY> --circle-key <CIRCLE_KEY>

# Execute inline script
client -c <CALLER_KEY> -k <CIRCLE_KEY> --script "print('Hello World!')"

# Execute script from file
client -c <CALLER_KEY> -k <CIRCLE_KEY> --file script.rhai

# Use specific worker (defaults to circle key)
client -c <CALLER_KEY> -k <CIRCLE_KEY> -w <WORKER_KEY> --script "2 + 2"

# Custom Redis and timeout
client -c <CALLER_KEY> -k <CIRCLE_KEY> --redis-url redis://localhost:6379/1 --timeout 60

# Remove timestamps from logs
client -c <CALLER_KEY> -k <CIRCLE_KEY> --no-timestamp

# Increase verbosity
client -c <CALLER_KEY> -k <CIRCLE_KEY> -v --script "debug_info()"

Command-Line Options

Option	Short	Default	Description
--caller-key	-c	Required	Caller public key (your identity)
--circle-key	-k	Required	Circle public key (execution context)
--worker-key	-w	circle-key	Worker public key (target worker)
--redis-url	-r	redis://localhost:6379	Redis connection URL
--script	-s		Rhai script to execute
--file	-f		Path to Rhai script file
--timeout	-t	30	Timeout for script execution (seconds)
--no-timestamp		false	Remove timestamps from log output
--verbose	-v		Increase verbosity (stackable)

Execution Modes

Inline Script Execution

# Execute a simple calculation
client -c caller_123 -k circle_456 -s "let result = 2 + 2; print(result);"

# Execute with specific worker
client -c caller_123 -k circle_456 -w worker_789 -s "get_user_data()"

Script File Execution

# Execute script from file
client -c caller_123 -k circle_456 -f examples/data_processing.rhai

# Execute with custom timeout
client -c caller_123 -k circle_456 -f long_running_script.rhai -t 120

Interactive Mode

# Enter interactive REPL mode (when no script or file provided)
client -c caller_123 -k circle_456

# Interactive mode with verbose logging
client -c caller_123 -k circle_456 -v --no-timestamp

Interactive Mode

When no script (-s) or file (-f) is provided, the client enters interactive mode:

🔗 Starting Rhai Client
📋 Configuration:
   Caller Key: caller_123
   Circle Key: circle_456
   Worker Key: circle_456
   Redis URL: redis://localhost:6379
   Timeout: 30s

✅ Connected to Redis at redis://localhost:6379
🎮 Entering interactive mode
Type Rhai scripts and press Enter to execute. Type 'exit' or 'quit' to close.
rhai> let x = 42; print(x);
Status: completed
Output: 42
rhai> exit
👋 Goodbye!

Configuration Examples

Development Usage

# Simple development client
client -c dev_user -k dev_circle

# Development with clean logs
client -c dev_user -k dev_circle --no-timestamp -v

Production Usage

# Production client with specific worker
client \
  --caller-key prod_user_123 \
  --circle-key prod_circle_456 \
  --worker-key prod_worker_789 \
  --redis-url redis://redis-cluster:6379/0 \
  --timeout 300 \
  --file production_script.rhai

Batch Processing

# Process multiple scripts
for script in scripts/*.rhai; do
  client -c batch_user -k batch_circle -f "$script" --no-timestamp
done

Key Concepts

• Caller Key: Your identity - used for authentication and tracking
• Circle Key: Execution context - defines the environment/permissions
• Worker Key: Target worker - which worker should execute the script (defaults to circle key)

Error Handling

The client provides clear error messages for:

• Missing required keys
• Redis connection failures
• Script execution timeouts
• Worker unavailability
• Script syntax errors

Dependencies

• rhai_dispatcher: Core client library for Redis-based script execution
• redis: Redis client for task queue communication
• clap: Command-line argument parsing
• env_logger: Logging infrastructure
• tokio: Async runtime