From 691a34ae1f71b14b6298d0f5d6e7024e68922206 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 4 Mar 2026 16:47:50 -0800 Subject: [PATCH] docs(readme): update examples and add targeting section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update example paths from deleted examples/discovery/ and examples/all/ to the new examples/osapi/ and examples/orchestration/ directories. Add a Targeting subsection documenting _any, _all, hostname, and label selector parameters along with agent facts. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 242fa41..6b3489c 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,22 @@ start. | 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) | +### Targeting + +Most operations accept a `target` parameter to control which agents receive +the request: + +| Target | Behavior | +| ----------- | ------------------------------------------- | +| `_any` | Send to any available agent (load balanced) | +| `_all` | Broadcast to every agent | +| `hostname` | Send to a specific host | +| `key:value` | Send to agents matching a label | + +Agents expose labels (used for targeting) and extended system facts via +`client.Agent.Get()`. Facts come from agent-side providers and include OS, +hardware, and network details. + ## 🔀 Orchestration DAG-based task execution on top of the client. See the @@ -74,13 +90,38 @@ strategies, and adding new operations. 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 | +### SDK Client + +| Example | What it shows | +| ------------------------------------------------- | --------------------------------------- | +| [agent](examples/osapi/agent/main.go) | Agent discovery, details, and facts | +| [audit](examples/osapi/audit/main.go) | Audit log listing, get, and export | +| [command](examples/osapi/command/main.go) | Command exec and shell execution | +| [health](examples/osapi/health/main.go) | Liveness, readiness, and status checks | +| [job](examples/osapi/job/main.go) | Job create, get, list, delete, and retry | +| [metrics](examples/osapi/metrics/main.go) | Prometheus metrics retrieval | +| [network](examples/osapi/network/main.go) | DNS get/update and ping | +| [node](examples/osapi/node/main.go) | Hostname, disk, memory, load, uptime | + +### Orchestration + +| Example | What it shows | +| ------------------------------------------------------------------ | ---------------------------------------------- | +| [basic](examples/orchestration/basic/main.go) | Simple DAG with dependencies | +| [broadcast](examples/orchestration/broadcast/main.go) | Multi-target operations with per-host results | +| [error-strategy](examples/orchestration/error-strategy/main.go) | StopAll vs Continue error handling | +| [guards](examples/orchestration/guards/main.go) | When predicates for conditional execution | +| [hooks](examples/orchestration/hooks/main.go) | Lifecycle callbacks for logging and progress | +| [only-if-changed](examples/orchestration/only-if-changed/main.go) | Skip tasks when dependencies report no changes | +| [only-if-failed](examples/orchestration/only-if-failed/main.go) | Run tasks only when a dependency fails | +| [parallel](examples/orchestration/parallel/main.go) | Automatic parallelism for independent tasks | +| [result-decode](examples/orchestration/result-decode/main.go) | Decode result data into typed structs | +| [retry](examples/orchestration/retry/main.go) | Retry error strategy with configurable attempts | +| [task-func](examples/orchestration/task-func/main.go) | Custom Go functions with SDK client access | +| [task-func-results](examples/orchestration/task-func-results/main.go) | Cross-task data flow via Results.Get() | ```bash -cd examples/discovery +cd examples/osapi/node OSAPI_TOKEN="" go run main.go ```