Skip to content

feat(orchestrator): status-aware guards, per-host results, and inter-task data #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
retr0h merged 12 commits into from
Mar 2, 2026
Merged

feat(orchestrator): status-aware guards, per-host results, and inter-task data #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
507cae3
feat(orchestrator): add Status field to Result struct
retr0h Mar 2, 2026
22a0156
feat(orchestrator): store Result in results map for all task paths
retr0h Mar 2, 2026
06c489d
feat(orchestrator): add HostResult type to Result
retr0h Mar 2, 2026
a92775c
feat(orchestrator): extract per-host results and handle non-zero exit
retr0h Mar 2, 2026
8a6a689
feat(orchestrator): add TaskFnWithResults and Data on TaskResult
retr0h Mar 2, 2026
924a1a3
docs: update README and example for new orchestrator features
retr0h Mar 2, 2026
e1d1e29
docs: enhance examples/all with inter-task data passing
retr0h Mar 2, 2026
1835e01
fix(orchestrator): allow When guards on tasks with failed deps
retr0h Mar 2, 2026
eb88995
fix(orchestrator): remove changed key from result Data map
retr0h Mar 2, 2026
a2d355f
feat(orchestrator): add HostResults to TaskResult and SetName
retr0h Mar 2, 2026
475b953
feat(orchestrator): add WhenWithReason for custom guard skip messages
retr0h Mar 2, 2026
b71fdfb
test(orchestrator): add tests for SetName and WhenWithReason
retr0h Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 38 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,57 +24,59 @@ Typed Go client for every OSAPI endpoint. See the
[client docs](docs/osapi/README.md) for targeting, options, and quick
start.

| Service | Operations | Docs | Source |
| ------- | ---------- | ---- | ------ |
| Node | Hostname, disk, memory, load, uptime, OS info, status | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Network | DNS get/update, ping | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Command | exec, shell | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Job | Create, get, list, delete, retry, stats | [docs](docs/osapi/job.md) | [`job.go`](pkg/osapi/job.go) |
| Agent | List, get (discovery + heartbeat data) | [docs](docs/osapi/agent.md) | [`agent.go`](pkg/osapi/agent.go) |
| Health | Liveness, readiness, status | [docs](docs/osapi/health.md) | [`health.go`](pkg/osapi/health.go) |
| Audit | List, get, export | [docs](docs/osapi/audit.md) | [`audit.go`](pkg/osapi/audit.go) |
| Metrics | Prometheus text | [docs](docs/osapi/metrics.md) | [`metrics.go`](pkg/osapi/metrics.go) |
| Service | Operations | Docs | Source |
| ------- | ----------------------------------------------------- | ----------------------------- | ------------------------------------ |
| Node | Hostname, disk, memory, load, uptime, OS info, status | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Network | DNS get/update, ping | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Command | exec, shell | [docs](docs/osapi/node.md) | [`node.go`](pkg/osapi/node.go) |
| Job | Create, get, list, delete, retry, stats | [docs](docs/osapi/job.md) | [`job.go`](pkg/osapi/job.go) |
| Agent | List, get (discovery + heartbeat data) | [docs](docs/osapi/agent.md) | [`agent.go`](pkg/osapi/agent.go) |
| Health | Liveness, readiness, status | [docs](docs/osapi/health.md) | [`health.go`](pkg/osapi/health.go) |
| Audit | List, get, export | [docs](docs/osapi/audit.md) | [`audit.go`](pkg/osapi/audit.go) |
| Metrics | Prometheus text | [docs](docs/osapi/metrics.md) | [`metrics.go`](pkg/osapi/metrics.go) |

## Orchestration

DAG-based task execution on top of the client. See the
[orchestration docs](docs/orchestration/README.md) for hooks, error
strategies, and adding new operations.

| Feature | Description | Source |
| ------- | ----------- | ------ |
| DAG execution | Dependency-based ordering with automatic parallelism | [`plan.go`](pkg/orchestrator/plan.go) |
| Op tasks | Declarative OSAPI operations with target routing and params | [`task.go`](pkg/orchestrator/task.go) |
| TaskFunc | Custom Go functions with SDK client access | [`task.go`](pkg/orchestrator/task.go) |
| Hooks | 8 lifecycle callbacks — consumer-controlled logging | [`options.go`](pkg/orchestrator/options.go) |
| Error strategies | StopAll, Continue (skip dependents), Retry(n) | [`options.go`](pkg/orchestrator/options.go) |
| Guards | `When` predicates, `OnlyIfChanged` conditional execution | [`task.go`](pkg/orchestrator/task.go) |
| Changed detection | Read-only ops return false, mutators reflect actual state | [`runner.go`](pkg/orchestrator/runner.go) |
| Result access | `Results.Get()` for cross-task data flow | [`result.go`](pkg/orchestrator/result.go) |
| Feature | Description | Source |
| ------------------- | ------------------------------------------------------------------------- | ------------------------------------------- |
| DAG execution | Dependency-based ordering with automatic parallelism | [`plan.go`](pkg/orchestrator/plan.go) |
| Op tasks | Declarative OSAPI operations with target routing and params | [`task.go`](pkg/orchestrator/task.go) |
| TaskFunc | Custom Go functions with SDK client access | [`task.go`](pkg/orchestrator/task.go) |
| TaskFuncWithResults | Custom functions that receive completed results from prior tasks | [`task.go`](pkg/orchestrator/task.go) |
| Hooks | 8 lifecycle callbacks — consumer-controlled logging | [`options.go`](pkg/orchestrator/options.go) |
| Error strategies | StopAll, Continue (skip dependents), Retry(n) | [`options.go`](pkg/orchestrator/options.go) |
| Guards | `When` predicates, `OnlyIfChanged` conditional execution | [`task.go`](pkg/orchestrator/task.go) |
| Changed detection | Read-only ops return false, mutators reflect actual state | [`runner.go`](pkg/orchestrator/runner.go) |
| Result access | `Results.Get()` for cross-task data flow, `Status` for outcome inspection | [`result.go`](pkg/orchestrator/result.go) |
| Broadcast results | Per-host `HostResult` data for multi-target operations | [`result.go`](pkg/orchestrator/result.go) |

### Operations

| Operation | Description | Idempotent | Docs |
| --------- | ----------- | ---------- | ---- |
| `node.hostname.get` | Get system hostname | Read-only | [docs](docs/orchestration/node-hostname.md) |
| `node.status.get` | Get node status | Read-only | [docs](docs/orchestration/node-status.md) |
| `node.disk.get` | Get disk usage | Read-only | [docs](docs/orchestration/node-disk.md) |
| `node.memory.get` | Get memory stats | Read-only | [docs](docs/orchestration/node-memory.md) |
| `node.load.get` | Get load averages | Read-only | [docs](docs/orchestration/node-load.md) |
| `network.dns.get` | Get DNS configuration | Read-only | [docs](docs/orchestration/network-dns-get.md) |
| `network.dns.update` | Update DNS servers | Yes | [docs](docs/orchestration/network-dns-update.md) |
| `network.ping.do` | Ping a host | Read-only | [docs](docs/orchestration/network-ping.md) |
| `command.exec.execute` | Execute a command | No | [docs](docs/orchestration/command-exec.md) |
| `command.shell.execute` | Execute a shell string | No | [docs](docs/orchestration/command-shell.md) |
| Operation | Description | Idempotent | Docs |
| ----------------------- | ---------------------- | ---------- | ------------------------------------------------ |
| `node.hostname.get` | Get system hostname | Read-only | [docs](docs/orchestration/node-hostname.md) |
| `node.status.get` | Get node status | Read-only | [docs](docs/orchestration/node-status.md) |
| `node.disk.get` | Get disk usage | Read-only | [docs](docs/orchestration/node-disk.md) |
| `node.memory.get` | Get memory stats | Read-only | [docs](docs/orchestration/node-memory.md) |
| `node.load.get` | Get load averages | Read-only | [docs](docs/orchestration/node-load.md) |
| `network.dns.get` | Get DNS configuration | Read-only | [docs](docs/orchestration/network-dns-get.md) |
| `network.dns.update` | Update DNS servers | Yes | [docs](docs/orchestration/network-dns-update.md) |
| `network.ping.do` | Ping a host | Read-only | [docs](docs/orchestration/network-ping.md) |
| `command.exec.execute` | Execute a command | No | [docs](docs/orchestration/command-exec.md) |
| `command.shell.execute` | Execute a shell string | No | [docs](docs/orchestration/command-shell.md) |

## Examples

Each example is a standalone Go program you can read and run.

| Example | What it shows |
| ------- | ------------- |
| [discovery](examples/discovery/main.go) | Runnable DAG that discovers fleet info: health check, agent listing, and status in parallel |
| [all](examples/all/main.go) | Every feature: hooks, Op tasks, TaskFunc, dependencies, guards, Levels(), error strategies, reporting |
| Example | What it shows |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [discovery](examples/discovery/main.go) | Runnable DAG that discovers fleet info: health check, agent listing, and status in parallel |
| [all](examples/all/main.go) | Every feature: hooks, Op tasks, TaskFunc, dependencies, guards, Levels(), error strategies, reporting |

```bash
cd examples/discovery
Expand Down
Loading