388 lines
9.7 KiB
Markdown
388 lines
9.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```rhai
|
|
// No need to create instances - they're already available!
|
|
freezone.put_note(my_note);
|
|
my.put_note(my_note);
|
|
```
|
|
|
|
## 📝 Complete Example
|
|
|
|
### Command Line
|
|
|
|
```bash
|
|
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)
|
|
|
|
```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:**
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```rhai
|
|
// Script automatically has tenant1, tenant2, tenant3 available
|
|
tenant1.put_note(note1);
|
|
tenant2.put_note(note2);
|
|
tenant3.put_note(note3);
|
|
```
|
|
|
|
### 2. **Environment Separation**
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```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**
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```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**
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```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!
|
|
|
|
```rhai
|
|
// 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
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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)
|
|
|
|
```toml
|
|
# osiris.toml
|
|
[instances]
|
|
freezone = { url = "redis://localhost:6379", db_id = 1 }
|
|
my = { url = "redis://localhost:6379", db_id = 2 }
|
|
```
|
|
|
|
```bash
|
|
cargo run --bin runner --features rhai-support -- runner1 \
|
|
--config osiris.toml \
|
|
--script-file script.rhai
|
|
```
|
|
|
|
## 💡 Best Practices
|
|
|
|
### 1. **Use Descriptive Names**
|
|
```bash
|
|
# 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:
|
|
|
|
```rhai
|
|
// 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:
|
|
|
|
```bash
|
|
--instance notes:redis://localhost:6379:1 \
|
|
--instance events:redis://localhost:6379:2 \
|
|
--instance cache:redis://localhost:6379:3
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
### Test Script
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```rhai
|
|
// Just use them!
|
|
freezone.put_note(my_note);
|
|
my.put_note(my_note);
|
|
```
|