runner_rust/README_OSIRIS.md

OSIRIS Rhai Engine Integration

This module provides Rhai scripting support for OSIRIS objects, allowing you to create, store, and retrieve Notes, Events, and other OSIRIS objects using Rhai scripts.

Setup

1. Add OSIRIS Dependency

Add to Cargo.toml:

[dependencies]
osiris = { path = "../osiris", features = ["rhai-support"] }

2. Update the Engine

Uncomment the OSIRIS integration code in src/engine/osiris.rs:

use osiris::rhai_support::{register_note_api, register_event_api, OsirisRhaiEngine};

pub fn create_osiris_engine(
    herodb_url: &str,
    db_id: u16,
) -> Result<Engine, Box<dyn std::error::Error>> {
    let mut engine = Engine::new();
    
    // Create OSIRIS engine wrapper
    let osiris_engine = OsirisRhaiEngine::new(herodb_url, db_id)?;
    
    // Register Note API
    register_note_api(&mut engine);
    
    // Register Event API  
    register_event_api(&mut engine);
    
    // Register OSIRIS storage methods
    osiris_engine.register_in_engine(&mut engine);
    
    Ok(engine)
}

Usage

Rhai Script Example

// Create a note with builder pattern
let note = note("notes")
    .title("My Note")
    .content("This is the content")
    .tag("topic", "rust")
    .tag("project", "osiris")
    .mime("text/plain");

// Store the note
let id = put_note(note);
print(`Note stored with ID: ${id}`);

// Retrieve the note
let retrieved = get_note("notes", id);
print(`Title: ${retrieved.get_title()}`);
print(`Content: ${retrieved.get_content()}`);

// Query by tag
let ids = query("notes", "tags:tag", "project=osiris");
print(`Found ${ids.len()} notes`);

for note_id in ids {
    let n = get_note("notes", note_id);
    print(`  - ${n.get_title()}`);
}

Rust Example

use runner_rust::engine::osiris::run_osiris_script;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let script = r#"
        let note = note("notes")
            .title("Hello from Rhai")
            .content("This works!")
            .tag("source", "rhai");
        
        let id = put_note(note);
        print(`Stored: ${id}`);
    "#;
    
    run_osiris_script(script, "redis://localhost:6379", 1)?;
    Ok(())
}

Available Functions

Note Functions

• note(namespace: String) -> Note - Create a new note
• .title(title: String) -> Note - Set title (chainable)
• .content(content: String) -> Note - Set content (chainable)
• .tag(key: String, value: String) -> Note - Add tag (chainable)
• .mime(mime: String) -> Note - Set MIME type (chainable)
• put_note(note: Note) -> String - Store note, returns ID
• get_note(ns: String, id: String) -> Note - Retrieve note by ID
• .get_id() -> String - Get note ID
• .get_title() -> String - Get note title
• .get_content() -> String - Get note content
• .to_json() -> String - Serialize to JSON

Event Functions

• event(namespace: String, title: String) -> Event - Create a new event
• .description(desc: String) -> Event - Set description (chainable)
• .location(location: String) -> Event - Set location (chainable)
• .category(category: String) -> Event - Set category (chainable)
• .all_day(all_day: bool) -> Event - Set all-day flag (chainable)
• put_event(event: Event) -> String - Store event, returns ID
• get_event(ns: String, id: String) -> Event - Retrieve event by ID
• .get_id() -> String - Get event ID
• .get_title() -> String - Get event title
• .to_json() -> String - Serialize to JSON

Query Functions

• query(ns: String, field: String, value: String) -> Array - Query by indexed field
  • Returns array of IDs matching the query
  • Example: query("notes", "tags:tag", "project=osiris")

Examples

See:

• examples/osiris_script.rhai - Complete Rhai script example
• examples/osiris_example.rs - Rust integration example

Running Examples

# Start HeroDB first
cd /path/to/herodb
cargo run --release -- --dir ./data --admin-secret mysecret --port 6379

# Run the example
cd /path/to/runner_rust
cargo run --example osiris_example

Architecture

Rhai Script
    ↓
OSIRIS Rhai Engine (runner_rust/src/engine/osiris.rs)
    ↓
OSIRIS Rhai Support (osiris/src/rhai_support/)
    ├── note_rhai.rs (Note CustomType + builder API)
    ├── event_rhai.rs (Event CustomType + builder API)
    └── engine.rs (OsirisRhaiEngine wrapper)
    ↓
OSIRIS Core (osiris/src/)
    ├── objects/ (Note, Event)
    ├── store/ (GenericStore, HeroDbClient)
    └── index/ (FieldIndex)
    ↓
HeroDB (Redis-compatible storage)

Benefits

1. Fluent Builder Pattern: Chain method calls for clean, readable scripts
2. Type Safety: Rhai's type system ensures correct usage
3. Async Bridge: Sync Rhai scripts can use async OSIRIS operations
4. Automatic Indexing: Objects are automatically indexed based on #[index] attributes
5. Familiar Syntax: Rhai syntax is similar to JavaScript/Rust

Next Steps

1. Add osiris dependency to Cargo.toml
2. Uncomment the integration code in src/engine/osiris.rs
3. Run the examples
4. Create your own Rhai scripts!