334 lines
7.1 KiB
Markdown
334 lines
7.1 KiB
Markdown
# Hero Supervisor Job API Convention
|
|
|
|
## Overview
|
|
|
|
The Hero Supervisor OpenRPC API follows a consistent naming convention for job-related operations:
|
|
|
|
- **`jobs.`** - General job operations (plural)
|
|
- **`job.`** - Specific job operations (singular)
|
|
|
|
This convention provides a clear distinction between operations that work with multiple jobs or create new jobs versus operations that work with a specific existing job.
|
|
|
|
## API Methods
|
|
|
|
### General Job Operations (`jobs.`)
|
|
|
|
#### `jobs.create`
|
|
Creates a new job without immediately queuing it to a runner.
|
|
|
|
**Parameters:**
|
|
- `secret` (string): Authentication secret (admin or user)
|
|
- `job` (Job object): Complete job specification
|
|
|
|
**Returns:**
|
|
- `job_id` (string): Unique identifier of the created job
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "jobs.create",
|
|
"params": {
|
|
"secret": "your-secret",
|
|
"job": {
|
|
"id": "job-123",
|
|
"caller_id": "client-1",
|
|
"context_id": "context-1",
|
|
"payload": "print('Hello World')",
|
|
"executor": "osis",
|
|
"runner": "osis-runner-1",
|
|
"timeout": 300,
|
|
"env_vars": {},
|
|
"created_at": "2023-01-01T00:00:00Z",
|
|
"updated_at": "2023-01-01T00:00:00Z"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `jobs.list`
|
|
Lists all jobs in the system with full details.
|
|
|
|
**Parameters:** None
|
|
|
|
**Returns:**
|
|
- `jobs` (array of Job objects): List of all jobs with complete information
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "jobs.list",
|
|
"params": []
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
[
|
|
{
|
|
"id": "job-123",
|
|
"caller_id": "client-1",
|
|
"context_id": "context-1",
|
|
"payload": "print('Hello World')",
|
|
"executor": "osis",
|
|
"runner": "osis-runner-1",
|
|
"timeout": 300,
|
|
"env_vars": {},
|
|
"created_at": "2023-01-01T00:00:00Z",
|
|
"updated_at": "2023-01-01T00:00:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Specific Job Operations (`job.`)
|
|
|
|
#### `job.run`
|
|
Runs a job immediately on the appropriate runner and returns the result.
|
|
|
|
**Parameters:**
|
|
- `secret` (string): Authentication secret (admin or user)
|
|
- `job` (Job object): Complete job specification
|
|
|
|
**Returns:**
|
|
- `result` (JobResult): Either success or error result
|
|
|
|
**JobResult Format:**
|
|
```json
|
|
// Success case
|
|
{
|
|
"success": "Job completed successfully with output..."
|
|
}
|
|
|
|
// Error case
|
|
{
|
|
"error": "Job failed with error message..."
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.run",
|
|
"params": {
|
|
"secret": "your-secret",
|
|
"job": { /* job object */ }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `job.start`
|
|
Starts a previously created job by queuing it to its assigned runner.
|
|
|
|
**Parameters:**
|
|
- `secret` (string): Authentication secret (admin or user)
|
|
- `job_id` (string): ID of the job to start
|
|
|
|
**Returns:** `null` (void)
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.start",
|
|
"params": {
|
|
"secret": "your-secret",
|
|
"job_id": "job-123"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `job.status`
|
|
Gets the current status of a job.
|
|
|
|
**Parameters:**
|
|
- `job_id` (string): ID of the job to check
|
|
|
|
**Returns:**
|
|
- `status` (JobStatusResponse): Current job status information
|
|
|
|
**JobStatusResponse Format:**
|
|
```json
|
|
{
|
|
"job_id": "job-123",
|
|
"status": "running",
|
|
"created_at": "2023-01-01T00:00:00Z",
|
|
"started_at": "2023-01-01T00:00:05Z",
|
|
"completed_at": null
|
|
}
|
|
```
|
|
|
|
**Status Values:**
|
|
- `created` - Job has been created but not queued
|
|
- `queued` - Job has been queued to a runner
|
|
- `running` - Job is currently executing
|
|
- `completed` - Job finished successfully
|
|
- `failed` - Job failed with an error
|
|
- `timeout` - Job timed out
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.status",
|
|
"params": ["job-123"]
|
|
}
|
|
```
|
|
|
|
#### `job.result`
|
|
Gets the result of a completed job. This method blocks until the result is available.
|
|
|
|
**Parameters:**
|
|
- `job_id` (string): ID of the job to get results for
|
|
|
|
**Returns:**
|
|
- `result` (JobResult): Either success or error result
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.result",
|
|
"params": ["job-123"]
|
|
}
|
|
```
|
|
|
|
#### `job.stop`
|
|
Stops a running job.
|
|
|
|
**Parameters:**
|
|
- `secret` (string): Authentication secret (admin or user)
|
|
- `job_id` (string): ID of the job to stop
|
|
|
|
**Returns:** `null` (void)
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.stop",
|
|
"params": {
|
|
"secret": "your-secret",
|
|
"job_id": "job-123"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `job.delete`
|
|
Deletes a job from the system.
|
|
|
|
**Parameters:**
|
|
- `secret` (string): Authentication secret (admin or user)
|
|
- `job_id` (string): ID of the job to delete
|
|
|
|
**Returns:** `null` (void)
|
|
|
|
**Usage:**
|
|
```json
|
|
{
|
|
"method": "job.delete",
|
|
"params": {
|
|
"secret": "your-secret",
|
|
"job_id": "job-123"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Workflow Examples
|
|
|
|
### Fire-and-Forget Job
|
|
```javascript
|
|
// Create and immediately run a job
|
|
const result = await client.job_run(secret, jobSpec);
|
|
if (result.success) {
|
|
console.log("Job completed:", result.success);
|
|
} else {
|
|
console.error("Job failed:", result.error);
|
|
}
|
|
```
|
|
|
|
### Asynchronous Job Processing
|
|
```javascript
|
|
// 1. Create the job
|
|
const jobId = await client.jobs_create(secret, jobSpec);
|
|
|
|
// 2. Start the job
|
|
await client.job_start(secret, jobId);
|
|
|
|
// 3. Poll for completion (non-blocking)
|
|
let status;
|
|
do {
|
|
status = await client.job_status(jobId);
|
|
if (status.status === 'running') {
|
|
await sleep(1000); // Wait 1 second
|
|
}
|
|
} while (status.status === 'running' || status.status === 'queued');
|
|
|
|
// 4. Get the result
|
|
const result = await client.job_result(jobId);
|
|
```
|
|
|
|
### Batch Job Management
|
|
```javascript
|
|
// Create multiple jobs
|
|
const jobIds = [];
|
|
for (const jobSpec of jobSpecs) {
|
|
const jobId = await client.jobs_create(secret, jobSpec);
|
|
jobIds.push(jobId);
|
|
}
|
|
|
|
// Start all jobs
|
|
for (const jobId of jobIds) {
|
|
await client.job_start(secret, jobId);
|
|
}
|
|
|
|
// Monitor progress
|
|
const results = [];
|
|
for (const jobId of jobIds) {
|
|
const result = await client.job_result(jobId); // Blocks until complete
|
|
results.push(result);
|
|
}
|
|
|
|
// Optional: Stop or delete jobs if needed
|
|
for (const jobId of jobIds) {
|
|
await client.job_stop(secret, jobId); // Stop running job
|
|
await client.job_delete(secret, jobId); // Delete from system
|
|
}
|
|
```
|
|
|
|
## Authentication
|
|
|
|
All job operations require authentication using one of the following secret types:
|
|
|
|
- **Admin secrets**: Full access to all operations
|
|
- **User secrets**: Access to job operations (`jobs.create`, `job.run`, `job.start`)
|
|
- **Register secrets**: Only access to runner registration
|
|
|
|
## Error Handling
|
|
|
|
All methods return standard JSON-RPC error responses for:
|
|
|
|
- **Authentication errors** (-32602): Invalid or missing secrets
|
|
- **Job not found errors** (-32000): Job ID doesn't exist
|
|
- **Internal errors** (-32603): Server-side processing errors
|
|
|
|
## Migration from Legacy API
|
|
|
|
### Old → New Method Names
|
|
|
|
| Legacy Method | New Method | Notes |
|
|
|---------------|------------|-------|
|
|
| `run_job` | `job.run` | Same functionality, new naming |
|
|
| `list_jobs` | `jobs.list` | Same functionality, new naming |
|
|
| `create_job` | `jobs.create` | Enhanced to not auto-queue |
|
|
|
|
### New Methods Added
|
|
|
|
- `job.start` - Start a created job
|
|
- `job.stop` - Stop a running job
|
|
- `job.delete` - Delete a job from the system
|
|
- `job.status` - Get job status (non-blocking)
|
|
- `job.result` - Get job result (blocking)
|
|
|
|
### API Changes
|
|
|
|
- **Job struct**: Replaced `job_type` field with `executor`
|
|
- **jobs.list**: Now returns full Job objects instead of just job IDs
|
|
- **Enhanced job lifecycle**: Added stop and delete operations
|
|
|
|
This provides much more granular control over job lifecycle management.
|