first commit
This commit is contained in:
Timur Gordon
328
RUNNER.md
Normal file
328
RUNNER.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# OSIRIS Runner - Standalone Binary ✅
|
||||
|
||||
The OSIRIS runner is a standalone binary that executes Rhai scripts with full OSIRIS object support.
|
||||
|
||||
## 🎉 Status: FULLY OPERATIONAL
|
||||
|
||||
```
|
||||
✅ Binary created at src/bin/runner/
|
||||
✅ Rhai engine with OSIRIS objects
|
||||
✅ Note and Event support
|
||||
✅ Automatic indexing
|
||||
✅ Query functionality
|
||||
✅ Test scripts working
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Run a Script File
|
||||
|
||||
```bash
|
||||
cargo run --bin runner --features rhai-support -- runner1 --script-file scripts/test_note.rhai
|
||||
```
|
||||
|
||||
### Run Inline Script
|
||||
|
||||
```bash
|
||||
cargo run --bin runner --features rhai-support -- runner1 \
|
||||
--script 'let note = note("test").title("Hi"); print(note.get_title());'
|
||||
```
|
||||
|
||||
## 📝 Example Output
|
||||
|
||||
```
|
||||
🚀 OSIRIS Runner
|
||||
Runner ID: test1
|
||||
HeroDB: redis://localhost:6379 (DB 1)
|
||||
|
||||
📝 Executing script...
|
||||
|
||||
─────────────────────────────────────
|
||||
=== OSIRIS Note Test ===
|
||||
|
||||
Creating note...
|
||||
Note created: Test from OSIRIS Runner
|
||||
Storing note...
|
||||
✓ Note stored with ID: 46a064c7-9062-4858-a390-c11f0d5877a7
|
||||
|
||||
Retrieving note...
|
||||
✓ Retrieved: Test from OSIRIS Runner
|
||||
Content: This note was created using the OSIRIS standalone runner!
|
||||
|
||||
Querying notes by tag...
|
||||
✓ Found notes:
|
||||
- 2c54e1ec-bed9-41ea-851c-f7313abbd7cd
|
||||
- 392f3f7f-47e7-444f-ba11-db38d74b12af
|
||||
- 46a064c7-9062-4858-a390-c11f0d5877a7
|
||||
=== Test Complete ===
|
||||
─────────────────────────────────────
|
||||
|
||||
✅ Script completed successfully!
|
||||
```
|
||||
|
||||
## 📖 Usage
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```
|
||||
OSIRIS Rhai Script Runner
|
||||
|
||||
Usage: runner [OPTIONS] <RUNNER_ID>
|
||||
|
||||
Arguments:
|
||||
<RUNNER_ID> Runner ID
|
||||
|
||||
Options:
|
||||
-r, --redis-url <REDIS_URL>
|
||||
HeroDB URL [default: redis://localhost:6379]
|
||||
-d, --db-id <DB_ID>
|
||||
HeroDB database ID [default: 1]
|
||||
-s, --script <SCRIPT>
|
||||
Script to execute in single-job mode (optional)
|
||||
-f, --script-file <SCRIPT_FILE>
|
||||
Script file to execute
|
||||
-h, --help
|
||||
Print help
|
||||
-V, --version
|
||||
Print version
|
||||
```
|
||||
|
||||
### Script Examples
|
||||
|
||||
#### Create and Store a Note
|
||||
|
||||
```rhai
|
||||
// scripts/test_note.rhai
|
||||
let note = note("notes")
|
||||
.title("My Note")
|
||||
.content("This is the content")
|
||||
.tag("project", "osiris")
|
||||
.tag("priority", "high");
|
||||
|
||||
let id = put_note(note);
|
||||
print(`Stored: ${id}`);
|
||||
|
||||
let retrieved = get_note("notes", id);
|
||||
print(`Title: ${retrieved.get_title()}`);
|
||||
```
|
||||
|
||||
#### Create and Store an Event
|
||||
|
||||
```rhai
|
||||
// scripts/test_event.rhai
|
||||
let event = event("calendar", "Team Meeting")
|
||||
.description("Weekly sync")
|
||||
.location("Conference Room A")
|
||||
.category("meetings");
|
||||
|
||||
let id = put_event(event);
|
||||
print(`Event stored: ${id}`);
|
||||
```
|
||||
|
||||
#### Query by Index
|
||||
|
||||
```rhai
|
||||
let ids = query("notes", "tags:tag", "project=osiris");
|
||||
print("Found notes:");
|
||||
for id in ids {
|
||||
let note = get_note("notes", id);
|
||||
print(` - ${note.get_title()}`);
|
||||
}
|
||||
```
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ OSIRIS Runner Binary │
|
||||
│ (osiris/src/bin/runner/) │
|
||||
├─────────────────────────────────────┤
|
||||
│ ├── main.rs │
|
||||
│ │ - CLI argument parsing │
|
||||
│ │ - Script loading │
|
||||
│ │ - Execution orchestration │
|
||||
│ └── engine.rs │
|
||||
│ - Engine factory │
|
||||
│ - OSIRIS integration │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ OSIRIS Rhai Support │
|
||||
│ (osiris/src/rhai_support/) │
|
||||
├─────────────────────────────────────┤
|
||||
│ ├── note_rhai.rs │
|
||||
│ │ - Note CustomType │
|
||||
│ │ - Builder methods │
|
||||
│ ├── event_rhai.rs │
|
||||
│ │ - Event CustomType │
|
||||
│ │ - Builder methods │
|
||||
│ └── engine.rs │
|
||||
│ - OsirisRhaiEngine │
|
||||
│ - Async → Sync bridge │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ OSIRIS Core │
|
||||
│ (osiris/src/) │
|
||||
├─────────────────────────────────────┤
|
||||
│ ├── objects/ │
|
||||
│ │ - Note, Event │
|
||||
│ │ - #[derive(DeriveObject)] │
|
||||
│ ├── store/ │
|
||||
│ │ - GenericStore │
|
||||
│ │ - Automatic indexing │
|
||||
│ └── index/ │
|
||||
│ - FieldIndex │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ HeroDB │
|
||||
│ (Redis-compatible storage) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🎯 Features
|
||||
|
||||
### 1. **Fluent Builder Pattern**
|
||||
```rhai
|
||||
let note = note("ns")
|
||||
.title("Title")
|
||||
.content("Content")
|
||||
.tag("key", "value");
|
||||
```
|
||||
|
||||
### 2. **Automatic Indexing**
|
||||
Fields marked with `#[index]` are automatically indexed:
|
||||
```rust
|
||||
#[derive(DeriveObject)]
|
||||
pub struct Note {
|
||||
pub base_data: BaseData,
|
||||
|
||||
#[index]
|
||||
pub title: Option<String>, // Indexed!
|
||||
|
||||
pub content: Option<String>, // Not indexed
|
||||
|
||||
#[index]
|
||||
pub tags: BTreeMap<String, String>, // Indexed!
|
||||
}
|
||||
```
|
||||
|
||||
### 3. **Type-Safe Operations**
|
||||
- Compile-time type checking
|
||||
- Runtime validation
|
||||
- Clear error messages
|
||||
|
||||
### 4. **Query Support**
|
||||
```rhai
|
||||
// Query by any indexed field
|
||||
let ids = query("namespace", "field_name", "value");
|
||||
|
||||
// Query by tag
|
||||
let ids = query("notes", "tags:tag", "project=osiris");
|
||||
|
||||
// Query by title
|
||||
let ids = query("notes", "title", "My Note");
|
||||
```
|
||||
|
||||
## 📚 Available Functions
|
||||
|
||||
### Note API
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `note(ns)` | Create new note |
|
||||
| `.title(s)` | Set title (chainable) |
|
||||
| `.content(s)` | Set content (chainable) |
|
||||
| `.tag(k, v)` | Add tag (chainable) |
|
||||
| `.mime(s)` | Set MIME type (chainable) |
|
||||
| `put_note(note)` | Store note, returns ID |
|
||||
| `get_note(ns, id)` | Retrieve note by ID |
|
||||
| `.get_id()` | Get note ID |
|
||||
| `.get_title()` | Get note title |
|
||||
| `.get_content()` | Get note content |
|
||||
| `.to_json()` | Serialize to JSON |
|
||||
|
||||
### Event API
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `event(ns, title)` | Create new event |
|
||||
| `.description(s)` | Set description (chainable) |
|
||||
| `.location(s)` | Set location (chainable) |
|
||||
| `.category(s)` | Set category (chainable) |
|
||||
| `.all_day(b)` | Set all-day flag (chainable) |
|
||||
| `put_event(event)` | Store event, returns ID |
|
||||
| `get_event(ns, id)` | Retrieve event by ID |
|
||||
| `.get_id()` | Get event ID |
|
||||
| `.get_title()` | Get event title |
|
||||
| `.to_json()` | Serialize to JSON |
|
||||
|
||||
### Query API
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `query(ns, field, value)` | Query by indexed field, returns array of IDs |
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test Scripts Included
|
||||
|
||||
1. **`scripts/test_note.rhai`** - Complete note workflow
|
||||
2. **`scripts/test_event.rhai`** - Complete event workflow
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
# Test notes
|
||||
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai
|
||||
|
||||
# Test events
|
||||
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_event.rhai
|
||||
```
|
||||
|
||||
## 🔧 Building
|
||||
|
||||
### Development Build
|
||||
|
||||
```bash
|
||||
cargo build --bin runner --features rhai-support
|
||||
```
|
||||
|
||||
### Release Build
|
||||
|
||||
```bash
|
||||
cargo build --bin runner --features rhai-support --release
|
||||
```
|
||||
|
||||
### Run Without Cargo
|
||||
|
||||
```bash
|
||||
# After building
|
||||
./target/release/runner runner1 --script-file scripts/test_note.rhai
|
||||
```
|
||||
|
||||
## 📦 Integration with runner_rust
|
||||
|
||||
The OSIRIS runner can also be integrated into the runner_rust infrastructure for distributed task execution. See `runner_rust/src/engine/osiris.rs` for the integration.
|
||||
|
||||
## ✅ Verification
|
||||
|
||||
Run this to verify everything works:
|
||||
|
||||
```bash
|
||||
cargo run --bin runner --features rhai-support -- test1 --script-file scripts/test_note.rhai
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
✅ Script completed successfully!
|
||||
```
|
||||
|
||||
## 🎉 Success!
|
||||
|
||||
The OSIRIS runner is **fully operational** and ready for:
|
||||
- ✅ Standalone script execution
|
||||
- ✅ Integration with runner_rust
|
||||
- ✅ Production use
|
||||
- ✅ Custom object types (via derive macro)
|
||||
Reference in New Issue
Block a user