rename docs directory to horus for collection name

This commit is contained in:
Timur Gordon
2025-11-14 11:09:40 +01:00
parent 2c24b120de
commit dc7ca26c6d
15 changed files with 0 additions and 0 deletions

View File

@@ -1,179 +0,0 @@
# Job Format
Jobs are the fundamental unit of work in Horus.
## Structure
```rust
pub struct Job {
pub id: String, // Unique job identifier
pub runner_id: String, // Target runner ID
pub payload: String, // Job payload (script/command)
pub timeout: Option<u64>, // Timeout in seconds
pub env_vars: HashMap<String, String>, // Environment variables
pub signatures: Vec<Signature>, // Cryptographic signatures
pub created_at: i64, // Creation timestamp
pub status: JobStatus, // Current status
}
```
## Job Status
```rust
pub enum JobStatus {
Pending, // Queued, not yet started
Running, // Currently executing
Completed, // Finished successfully
Failed, // Execution failed
Timeout, // Exceeded timeout
Cancelled, // Manually cancelled
}
```
## Signature Format
```rust
pub struct Signature {
pub public_key: String, // Signer's public key
pub signature: String, // Cryptographic signature
pub algorithm: String, // Signature algorithm (e.g., "ed25519")
}
```
## Creating a Job
### Minimal Job
```rust
use hero_job::Job;
let job = Job::new(
"my-runner",
"print('Hello World')".to_string(),
);
```
### With Timeout
```rust
let job = Job::builder()
.runner_id("my-runner")
.payload("long_running_task()")
.timeout(300) // 5 minutes
.build();
```
### With Environment Variables
```rust
use std::collections::HashMap;
let mut env_vars = HashMap::new();
env_vars.insert("API_KEY".to_string(), "secret".to_string());
env_vars.insert("ENV".to_string(), "production".to_string());
let job = Job::builder()
.runner_id("my-runner")
.payload("deploy_app()")
.env_vars(env_vars)
.build();
```
### With Signature
```rust
use hero_job::{Job, Signature};
let job = Job::builder()
.runner_id("my-runner")
.payload("important_task()")
.signature(Signature {
public_key: "ed25519:abc123...".to_string(),
signature: "sig:xyz789...".to_string(),
algorithm: "ed25519".to_string(),
})
.build();
```
## Payload Format
The payload format depends on the target runner:
### Hero Runner
Heroscript content:
```heroscript
!!git.list
print("Repositories listed")
!!docker.ps
```
### SAL Runner
Rhai script with SAL modules:
```rhai
let files = os.list_dir("/tmp");
for file in files {
print(file);
}
```
### Osiris Runner
Rhai script with Osiris database:
```rhai
let users = osiris.model("users");
let user = users.create(#{
name: "Alice",
email: "alice@example.com"
});
```
## Job Result
```rust
pub struct JobResult {
pub job_id: String,
pub status: JobStatus,
pub output: String, // Stdout
pub error: Option<String>, // Stderr or error message
pub exit_code: Option<i32>,
pub started_at: Option<i64>,
pub completed_at: Option<i64>,
}
```
## Best Practices
### Timeouts
- Always set timeouts for jobs
- Default: 60 seconds
- Long-running jobs: Set appropriate timeout
- Infinite jobs: Use separate monitoring
### Environment Variables
- Don't store secrets in env vars in production
- Use vault/secret management instead
- Keep env vars minimal
- Document required variables
### Signatures
- Always sign jobs in production
- Use strong algorithms (ed25519)
- Rotate keys regularly
- Store private keys securely
### Payloads
- Keep payloads concise
- Validate input data
- Handle errors gracefully
- Log important operations
## Validation
Jobs are validated before execution:
1. **Structure**: All required fields present
2. **Signature**: Valid cryptographic signature
3. **Runner**: Target runner exists and available
4. **Payload**: Non-empty payload
5. **Timeout**: Reasonable timeout value
Invalid jobs are rejected before execution.