baobab/reference_osis_actor/README.md

Object Storage and Indexing System (OSIS) Actor

The OSIS Actor is responsible for storing and indexing objects in the system. It implements the actor interface to process jobs in a blocking, synchronized manner.

Job Processing Behavior

The OSISActor processes jobs sequentially with the following characteristics:

• Blocking Processing: Each job is processed completely before the next job begins
• Synchronized Execution: Jobs are executed one at a time in the order they are received
• No Concurrency: Unlike async actors, OSIS ensures no parallel job execution
• Deterministic Order: Job completion follows the exact order of job submission

This design ensures data consistency and prevents race conditions when performing storage and indexing operations.

Usage

use actor_osis::{OSISActor, spawn_osis_actor};

// Create an OSIS actor with builder pattern
let actor = OSISActor::builder()
    .db_path("/path/to/database")
    .redis_url("redis://localhost:6379")
    .build()
    .expect("Failed to build OSISActor");

// Or spawn directly with convenience function
let handle = spawn_osis_actor(
    "/path/to/database".to_string(),
    "redis://localhost:6379".to_string(),
    shutdown_rx,
);

Actor Properties

• Actor ID: "osis" (constant)
• Actor Type: "OSIS"
• Processing Model: Sequential, blocking
• Script Engine: Rhai with OSIS-specific DSL extensions

Canonical Redis queues and verification

The project uses canonical dispatch queues per script type. For OSIS, the work queue is:

• hero:q:work:type:osis

Consumer behavior:

• The in-repo actor derives ScriptType=OSIS from its actor_id containing "osis" and BLPOPs hero:q:work:type:osis.
• This repo’s OSIS actor has been updated so its actor_id is "osis", ensuring it consumes the canonical queue.

Quick verification (redis-cli):

• List work queues:
  • KEYS hero:q:work:type:*
• Check OSIS queue length:
  • LLEN hero:q:work:type:osis
• Inspect a specific job (replace {job_id} with the printed id):
  • HGET hero:job:{job_id} status
  • HGET hero:job:{job_id} output

Run options:

• Option A: Run the example which spawns the OSIS actor and dispatches jobs to the canonical queue.

  1. Start Redis (if not already): redis-server
  2. In this repo:
     • cargo run --example actor
  3. Observe the console: job IDs will be printed as they are created and dispatched.
  4. In a separate terminal, verify with redis-cli:
     • LLEN hero:q:work:type:osis (will briefly increment, then return to 0 as the actor consumes)
     • HGET hero:job:{job_id} status (should transition to started then finished)
     • HGET hero:job:{job_id} output (should contain the script result)

• Option B: Run the standalone actor binary and dispatch from another process that pushes to the canonical type queue.

  1. Start the actor:
     • cargo run --bin actor_osis
  2. From any producer, LPUSH hero:q:work:type:osis {job_id} after persisting the job hash hero:job:{job_id}.
  3. Use the same redis-cli checks above to confirm consumption and completion.

Notes:

• Hash-only result model is the default. The job result is written to hero:job:{job_id}.output and status=finished.
• Reply queues (hero:q:reply:{job_id}) are optional and not required for OSIS to function.