baobab/core/actor/README.md

Actor

The actor crate defines the trait Actor is

and implements a standalone actor service that listens for Rhai script execution tasks from a Redis queue, executes them, and posts results back to Redis. It is designed to be spawned as a separate OS process by an orchestrator like the launcher crate.

Features

• Redis Queue Consumption: Listens to a specific Redis list (acting as a task queue) for incoming task IDs. The queue is determined by the --circle-public-key argument.
• Rhai Script Execution: Executes Rhai scripts retrieved from Redis based on task IDs.
• Task State Management: Updates task status (processing, completed, error) and stores results in Redis hashes.
• Script Scope Injection: Automatically injects two important constants into the Rhai script's scope:
  • CONTEXT_ID: The public key of the actor's own circle.
  • CALLER_ID: The public key of the entity that requested the script execution.
• Asynchronous Operations: Built with tokio for non-blocking Redis communication.
• Graceful Error Handling: Captures errors during script execution and stores them for the client.

Core Components

• actor_lib (Library Crate):
  • Args: A struct (using clap) for parsing command-line arguments: --redis-url and --circle-public-key.
  • run_actor_loop(engine: Engine, args: Args): The main asynchronous function that:
    • Connects to Redis.
    • Continuously polls the designated Redis queue (rhai_tasks:<circle_public_key>) using BLPOP.
    • Upon receiving a task_id, it fetches the task details from a Redis hash.
    • It injects CALLER_ID and CONTEXT_ID into the script's scope.
    • It executes the script and updates the task status in Redis with the output or error.

How It Works

1. The actor executable is launched by an external process (e.g., launcher), which passes the required command-line arguments.

   # This is typically done programmatically by a parent process.
   /path/to/actor --redis-url redis://127.0.0.1/ --circle-public-key 02...abc
   

2. The run_actor_loop connects to Redis and starts listening to its designated task queue (e.g., rhai_tasks:02...abc).
3. A rhai_supervisor submits a task by pushing a task_id to this queue and storing the script and other details in a Redis hash.
4. The actor's BLPOP command picks up the task_id.
5. The actor retrieves the script from the corresponding rhai_task_details:<task_id> hash.
6. It updates the task's status to "processing".
7. The Rhai script is executed within a scope that contains both CONTEXT_ID and CALLER_ID.
8. After execution, the status is updated to "completed" (with output) or "error" (with an error message).
9. The actor then goes back to listening for the next task.

Prerequisites

• A running Redis instance accessible by the actor.
• An orchestrator process (like launcher) to spawn the actor.
• A rhai_supervisor (or another system) to populate the Redis queues.

Building and Running

The actor is intended to be built as a dependency and run by another program.

1. Build the actor:

   # From the root of the baobab project
   cargo build --package actor
   

   The binary will be located at target/debug/actor.

2. Running the actor: The actor is not typically run manually. The launcher crate is responsible for spawning it with the correct arguments. If you need to run it manually for testing, you must provide the required arguments:

   ./target/debug/actor --redis-url redis://127.0.0.1/ --circle-public-key <a_valid_hex_public_key>
   

Dependencies

Key dependencies include:

• redis: For asynchronous Redis communication.
• rhai: The Rhai script engine.
• clap: For command-line argument parsing.
• tokio: For the asynchronous runtime.
• log, env_logger: For logging.