update api, fix tests and examples

examples/README.md

@@ -0,0 +1,182 @@
+# Hero Supervisor Examples
+
+This directory contains examples demonstrating the new job API functionality and workflows.
+
+## Examples Overview
+
+### 1. `job_api_examples.rs` - Comprehensive API Demo
+Complete demonstration of all new job API methods:
+- **Fire-and-forget execution** using `job.run`
+- **Asynchronous processing** with `jobs.create`, `job.start`, `job.status`, `job.result`
+- **Batch job processing** for multiple jobs
+- **Job listing** with `jobs.list`
+
+**Run with:**
+```bash
+cargo run --example job_api_examples
+```
+
+### 2. `simple_job_workflow.rs` - Basic Workflow
+Simple example showing the basic job lifecycle:
+1. Create job with `jobs.create`
+2. Start job with `job.start`
+3. Monitor with `job.status`
+4. Get result with `job.result`
+
+**Run with:**
+```bash
+cargo run --example simple_job_workflow
+```
+
+### 3. `integration_test.rs` - Integration Tests
+Comprehensive integration tests validating:
+- Complete job lifecycle
+- Immediate job execution
+- Job listing functionality
+- Authentication error handling
+- Nonexistent job operations
+
+**Run with:**
+```bash
+cargo test --test integration_test
+```
+
+## Prerequisites
+
+Before running the examples, ensure:
+
+1. **Redis is running:**
+   ```bash
+   docker run -d -p 6379:6379 redis:alpine
+   ```
+
+2. **Supervisor is running:**
+   ```bash
+   ./target/debug/supervisor --config examples/supervisor/config.toml
+   ```
+
+3. **Runners are configured** in your config.toml:
+   ```toml
+   [[actors]]
+   id = "osis_runner_1"
+   name = "osis_runner_1"
+   binary_path = "/path/to/osis_runner"
+   db_path = "/tmp/osis_db"
+   redis_url = "redis://localhost:6379"
+   process_manager = "simple"
+   ```
+
+## API Convention Summary
+
+The examples demonstrate the new job API convention:
+
+### General Operations (`jobs.`)
+- `jobs.create` - Create a job without queuing it
+- `jobs.list` - List all job IDs in the system
+
+### Specific Operations (`job.`)
+- `job.run` - Run a job immediately and return result
+- `job.start` - Start a previously created job
+- `job.status` - Get current job status (non-blocking)
+- `job.result` - Get job result (blocking until complete)
+
+## Workflow Patterns
+
+### Pattern 1: Fire-and-Forget
+```rust
+let result = client.job_run(secret, job).await?;
+match result {
+    JobResult::Success { success } => println!("Output: {}", success),
+    JobResult::Error { error } => println!("Error: {}", error),
+}
+```
+
+### Pattern 2: Asynchronous Processing
+```rust
+// Create and start
+let job_id = client.jobs_create(secret, job).await?;
+client.job_start(secret, &job_id).await?;
+
+// Monitor (non-blocking)
+loop {
+    let status = client.job_status(&job_id).await?;
+    if status.status == "completed" { break; }
+    sleep(Duration::from_secs(1)).await;
+}
+
+// Get result
+let result = client.job_result(&job_id).await?;
+```
+
+### Pattern 3: Batch Processing
+```rust
+// Create all jobs
+let mut job_ids = Vec::new();
+for job_spec in job_specs {
+    let job_id = client.jobs_create(secret, job_spec).await?;
+    job_ids.push(job_id);
+}
+
+// Start all jobs
+for job_id in &job_ids {
+    client.job_start(secret, job_id).await?;
+}
+
+// Collect results
+for job_id in &job_ids {
+    let result = client.job_result(job_id).await?;
+    // Process result...
+}
+```
+
+## Error Handling
+
+The examples demonstrate proper error handling for:
+- **Authentication errors** - Invalid secrets
+- **Job not found errors** - Nonexistent job IDs
+- **Connection errors** - Supervisor not available
+- **Execution errors** - Job failures
+
+## Authentication
+
+Examples use different secret types:
+- **Admin secrets**: Full system access
+- **User secrets**: Job operations only (used in examples)
+- **Register secrets**: Runner registration only
+
+Configure secrets in your supervisor config:
+```toml
+admin_secrets = ["admin-secret-123"]
+user_secrets = ["user-secret-456"]
+register_secrets = ["register-secret-789"]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection refused**
+   - Ensure supervisor is running on localhost:3030
+   - Check supervisor logs for errors
+
+2. **Authentication failed**
+   - Verify secret is configured in supervisor
+   - Check secret type matches operation requirements
+
+3. **Job execution failed**
+   - Ensure runners are properly configured and running
+   - Check runner logs for execution errors
+   - Verify job payload is valid for the target runner
+
+4. **Redis connection failed**
+   - Ensure Redis is running on localhost:6379
+   - Check Redis connectivity from supervisor
+
+### Debug Mode
+
+Run examples with debug logging:
+```bash
+RUST_LOG=debug cargo run --example job_api_examples
+```
+
+This will show detailed API calls and responses for troubleshooting.