hero/core/worker/cmd/README.md

Rhai Worker Binary

A command-line worker for executing Rhai scripts from Redis task queues.

Binary: worker

Installation

Build the binary:

cargo build --bin worker --release

Usage

# Basic usage - requires circle public key
worker --circle-public-key <CIRCLE_PUBLIC_KEY>

# Custom Redis URL
worker -c <CIRCLE_PUBLIC_KEY> --redis-url redis://localhost:6379/1

# Custom worker ID and database path
worker -c <CIRCLE_PUBLIC_KEY> --worker-id my_worker --db-path /tmp/worker_db

# Preserve tasks for debugging/benchmarking
worker -c <CIRCLE_PUBLIC_KEY> --preserve-tasks

# Remove timestamps from logs
worker -c <CIRCLE_PUBLIC_KEY> --no-timestamp

# Increase verbosity
worker -c <CIRCLE_PUBLIC_KEY> -v    # Debug logging
worker -c <CIRCLE_PUBLIC_KEY> -vv   # Full debug
worker -c <CIRCLE_PUBLIC_KEY> -vvv  # Trace logging

Command-Line Options

Option	Short	Default	Description
--circle-public-key	-c	Required	Circle public key to listen for tasks
--redis-url	-r	redis://localhost:6379	Redis connection URL
--worker-id	-w	worker_1	Unique worker identifier
--preserve-tasks		false	Preserve task details after completion
--db-path		worker_rhai_temp_db	Database path for Rhai engine
--no-timestamp		false	Remove timestamps from log output
--verbose	-v		Increase verbosity (stackable)

Features

• Task Queue Processing: Listens to Redis queues for Rhai script execution tasks
• Performance Optimized: Configured for maximum Rhai engine performance
• Graceful Shutdown: Supports shutdown signals for clean termination
• Flexible Logging: Configurable verbosity and timestamp control
• Database Integration: Uses heromodels for data persistence
• Task Cleanup: Optional task preservation for debugging/benchmarking

How It Works

1. Queue Listening: Worker listens on Redis queue rhailib:{circle_public_key}
2. Task Processing: Receives task IDs, fetches task details from Redis
3. Script Execution: Executes Rhai scripts with configured engine
4. Result Handling: Updates task status and sends results to reply queues
5. Cleanup: Optionally cleans up task details after completion

Configuration Examples

Development Worker

# Simple development worker
worker -c dev_circle_123

# Development with verbose logging (no timestamps)
worker -c dev_circle_123 -v --no-timestamp

Production Worker

# Production worker with custom configuration
worker \
  --circle-public-key prod_circle_456 \
  --redis-url redis://redis-server:6379/0 \
  --worker-id prod_worker_1 \
  --db-path /var/lib/worker/db \
  --preserve-tasks

Benchmarking Worker

# Worker optimized for benchmarking
worker \
  --circle-public-key bench_circle_789 \
  --preserve-tasks \
  --no-timestamp \
  -vv

Error Handling

The worker provides clear error messages for:

• Missing or invalid circle public key
• Redis connection failures
• Script execution errors
• Database access issues

Dependencies

• rhailib_engine: Rhai engine with heromodels integration
• redis: Redis client for task queue management
• rhai: Script execution engine
• clap: Command-line argument parsing
• env_logger: Logging infrastructure