supervisor/examples/osiris_openrpc/README.md

OSIRIS + OpenRPC Comprehensive Example

This example demonstrates the complete workflow of using Hero Supervisor with OSIRIS runners via OpenRPC.

What This Example Does

1. Builds and starts Hero Supervisor with OpenRPC server enabled
2. Builds the OSIRIS runner binary
3. Connects an OpenRPC client to the supervisor
4. Registers and starts an OSIRIS runner
5. Dispatches multiple jobs via OpenRPC:
   • Create a Note
   • Create an Event
   • Query stored data
   • Test access control (expected to fail)
6. Monitors job execution and results
7. Gracefully shuts down all components

Prerequisites

IMPORTANT: Redis must be running before starting this example!

# Start Redis (if not already running)
redis-server

Other requirements:

• Redis server running on localhost:6379
• Rust toolchain installed
• Both supervisor and runner_rust crates available

Running the Example

cargo run --example osiris_openrpc

Job Scripts

The example uses separate Rhai script files for each job:

• note.rhai - Creates and stores a Note object
• event.rhai - Creates and stores an Event object
• query.rhai - Queries and retrieves stored objects
• access_denied.rhai - Tests access control (should fail)

Architecture

┌─────────────────┐
│   This Example  │
│   (OpenRPC      │
│    Client)      │
└────────┬────────┘
         │ JSON-RPC
         ↓
┌─────────────────┐
│   Supervisor    │
│  (OpenRPC       │
│   Server)       │
└────────┬────────┘
         │ Redis Queue
         ↓
┌─────────────────┐
│ OSIRIS Runner   │
│  (Rhai Engine   │
│   + HeroDB)     │
└─────────────────┘

Key Features Demonstrated

• Automatic binary building using escargot
• OpenRPC communication between client and supervisor
• Runner registration with configuration
• Job dispatching with signatories
• Context-based access control in OSIRIS
• Typed object storage (Note, Event)
• Graceful shutdown and cleanup

Expected Output

The example will:

1. ✅ Create a Note successfully
2. ✅ Create an Event successfully
3. ✅ Query and retrieve stored objects
4. ✅ Deny access for unauthorized participants
5. ✅ Clean up all resources

Troubleshooting

Redis Connection Error:

• Ensure Redis is running: redis-server

Build Errors:

• Ensure both supervisor and runner_rust crates are available
• Check that all dependencies are up to date

OpenRPC Connection Error:

• Port 3030 might be in use
• Check supervisor logs for startup issues