osiris/PREDEFINED_INSTANCES.md

OSIRIS Predefined Instances ✅

OSIRIS runner now supports predefined instances that are automatically available in your Rhai scripts without needing to create them manually.

🎉 Status: FULLY OPERATIONAL

✅ CLI argument parsing for instances
✅ Automatic instance creation
✅ Global scope injection
✅ Multiple instances support
✅ Test script working

🚀 Quick Start

Define Instances via CLI

cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai

Use Them Directly in Scripts

// No need to create instances - they're already available!
freezone.put_note(my_note);
my.put_note(my_note);

📝 Complete Example

Command Line

cargo run --bin runner --features rhai-support -- test1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai

Script (scripts/predefined_instances.rhai)

print("=== Predefined Instances Example ===");

// freezone and my are already available!
print(`Using: ${freezone.name()}`);
print(`Using: ${my.name()}`);

// Create a note
let my_note = note("notes")
    .title("Test Note")
    .content("Using predefined instances!");

// Use them directly - no setup needed!
freezone.put_note(my_note);
my.put_note(my_note);

// Query each instance
let ids1 = freezone.query("notes", "title", "Test Note");
let ids2 = my.query("notes", "title", "Test Note");

Output

🚀 OSIRIS Runner
Runner ID: test1
HeroDB: redis://localhost:6379 (DB 1)
  Instance: freezone → redis://localhost:6379 (DB 1)
  Instance: my → redis://localhost:6379 (DB 2)

📝 Executing script...

─────────────────────────────────────
=== Predefined Instances Example ===

Using predefined instance: freezone
Using predefined instance: my

Creating note...
Note created: Predefined Instance Test

Storing in freezone...
✓ Stored in freezone: 61ea54fe-504d-4f43-be50-6548a82338dd

Storing in my...
✓ Stored in my: 61ea54fe-504d-4f43-be50-6548a82338dd

✅ Script completed successfully!

🎯 CLI Arguments

--instance (or -i)

Define a predefined instance that will be available in your script.

Format: name:url:db_id

Examples:

# Single instance
--instance freezone:redis://localhost:6379:1

# Multiple instances
--instance freezone:redis://localhost:6379:1 \
--instance my:redis://localhost:6379:2 \
--instance production:redis://prod.example.com:6379:1

# Different hosts
--instance local:redis://localhost:6379:1 \
--instance remote:redis://remote.example.com:6379:1

Parameters:

• name - Instance name (will be available as a variable in scripts)
• url - HeroDB connection URL (redis://host:port)
• db_id - Database ID (0-15 typically)

📚 Use Cases

1. Multi-Tenant Setup

cargo run --bin runner --features rhai-support -- runner1 \
  --instance tenant1:redis://localhost:6379:1 \
  --instance tenant2:redis://localhost:6379:2 \
  --instance tenant3:redis://localhost:6379:3 \
  --script-file process_tenants.rhai

// Script automatically has tenant1, tenant2, tenant3 available
tenant1.put_note(note1);
tenant2.put_note(note2);
tenant3.put_note(note3);

2. Environment Separation

cargo run --bin runner --features rhai-support -- runner1 \
  --instance dev:redis://dev:6379:1 \
  --instance staging:redis://staging:6379:1 \
  --instance prod:redis://prod:6379:1 \
  --script-file deploy.rhai

// Test in dev first
dev.put_note(test_note);

// Then staging
staging.put_note(test_note);

// Finally production
prod.put_note(test_note);

3. Data Migration

cargo run --bin runner --features rhai-support -- runner1 \
  --instance source:redis://old-server:6379:1 \
  --instance target:redis://new-server:6379:1 \
  --script-file migrate.rhai

// Migrate data from source to target
let ids = source.query("notes", "tags:tag", "migrate=true");
for id in ids {
    let note = source.get_note("notes", id);
    target.put_note(note);
}

4. Freezone + Personal OSIRIS

cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://freezone.io:6379:1 \
  --instance my:redis://localhost:6379:1 \
  --script-file sync.rhai

// Your exact use case!
let my_note = note("notes")
    .title("Shared Note")
    .content("Available in both instances");

freezone.put_note(my_note);
my.put_note(my_note);

🏗️ Architecture

┌─────────────────────────────────────┐
│   CLI Arguments                     │
│   --instance freezone:redis:...:1   │
│   --instance my:redis:...:2         │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   OsirisConfig                      │
│   Parse and validate instances      │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   Engine + Scope                    │
│   Create instances and inject       │
│   into Rhai scope as constants      │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│   Rhai Script                       │
│   freezone.put_note(...)            │
│   my.put_note(...)                  │
└─────────────────────────────────────┘

✨ Features

1. Zero Boilerplate

No need to create instances in scripts - they're already there!

// Before (manual creation)
let freezone = osiris("freezone", "redis://localhost:6379", 1);
let my = osiris("my", "redis://localhost:6379", 2);

// After (predefined)
// Just use them!
freezone.put_note(note);
my.put_note(note);

2. Type Safety

Instances are strongly typed and validated at startup.

3. Configuration as Code

Instance configuration is explicit in the command line.

4. Multiple Instances

Support unlimited predefined instances.

5. Named Access

Access instances by their meaningful names.

🔧 Advanced Usage

Combining Predefined and Dynamic Instances

# Predefined instances
cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file script.rhai

// Use predefined instances
freezone.put_note(note1);
my.put_note(note2);

// Create additional dynamic instances
let temp = osiris("temp", "redis://localhost:6379", 3);
temp.put_note(note3);

Environment Variables

You can use environment variables in your shell:

export FREEZONE_URL="redis://freezone.io:6379"
export MY_URL="redis://localhost:6379"

cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:${FREEZONE_URL}:1 \
  --instance my:${MY_URL}:1 \
  --script-file script.rhai

Configuration File (Future Enhancement)

# osiris.toml
[instances]
freezone = { url = "redis://localhost:6379", db_id = 1 }
my = { url = "redis://localhost:6379", db_id = 2 }

cargo run --bin runner --features rhai-support -- runner1 \
  --config osiris.toml \
  --script-file script.rhai

💡 Best Practices

1. Use Descriptive Names

# Good
--instance production:redis://prod:6379:1
--instance staging:redis://staging:6379:1

# Less clear
--instance db1:redis://prod:6379:1
--instance db2:redis://staging:6379:1

2. Consistent Naming

Use the same instance names across all your scripts for consistency.

3. Document Your Instances

Add comments in your scripts explaining what each instance is for:

// freezone: Public shared OSIRIS instance
// my: Personal local OSIRIS instance

freezone.put_note(public_note);
my.put_note(private_note);

4. Separate Databases

Use different database IDs for different purposes:

--instance notes:redis://localhost:6379:1 \
--instance events:redis://localhost:6379:2 \
--instance cache:redis://localhost:6379:3

🧪 Testing

Test Script

cargo run --bin runner --features rhai-support -- test1 \
  --instance freezone:redis://localhost:6379:1 \
  --instance my:redis://localhost:6379:2 \
  --script-file scripts/predefined_instances.rhai

Expected Output

✓ Instance: freezone → redis://localhost:6379 (DB 1)
✓ Instance: my → redis://localhost:6379 (DB 2)
✓ Stored in freezone: 61ea54fe-504d-4f43-be50-6548a82338dd
✓ Stored in my: 61ea54fe-504d-4f43-be50-6548a82338dd
✅ Script completed successfully!

🎉 Success!

Predefined instances are fully operational and ready for:

• ✅ Zero-boilerplate scripts
• ✅ Multi-tenant systems
• ✅ Environment separation
• ✅ Data migration
• ✅ Freezone + personal OSIRIS
• ✅ Production use

Your exact use case is now supported:

cargo run --bin runner --features rhai-support -- runner1 \
  --instance freezone:redis://freezone.io:6379:1 \
  --instance my:redis://localhost:6379:1 \
  --script-file my_script.rhai

// Just use them!
freezone.put_note(my_note);
my.put_note(my_note);