OSAPI Orchestrator

A Go package for orchestrating operations across OSAPI-managed hosts — typed operations, chaining, conditions, and result decoding built on top of the osapi-sdk engine.

📦 Install

go install github.com/osapi-io/osapi-orchestrator@latest

As a library dependency:

go get github.com/osapi-io/osapi-orchestrator

✨ Features

Typed constructors, typed results, and chainable step methods. See the usage docs for full details, examples, and per-operation reference.

Typed Operations

Every OSAPI operation has a strongly typed constructor — no raw maps or string constants.

Method	Operation	Docs	Source
HealthCheck	Liveness probe	docs	ops.go
NodeHostnameGet	node.hostname.get	docs	ops.go
NodeStatusGet	node.status.get	docs	ops.go
NodeUptimeGet	node.uptime.get	docs	ops.go
NodeDiskGet	node.disk.get	docs	ops.go
NodeMemoryGet	node.memory.get	docs	ops.go
NodeLoadGet	node.load.get	docs	ops.go
NetworkDNSGet	network.dns.get	docs	ops.go
NetworkDNSUpdate	network.dns.update	docs	ops.go
NetworkPingDo	network.ping.do	docs	ops.go
CommandExec	command.exec.execute	docs	ops.go
CommandShell	command.shell.execute	docs	ops.go

Typed Results

Decode step results into typed structs instead of digging through map[string]any. See result_types.go.

Struct	Fields
HostnameResult	Hostname, Labels
DiskResult	Disks (slice of DiskUsage)
MemoryResult	Total, Free, Cached
LoadResult	Load1, Load5, Load15
CommandResult	Stdout, Stderr, ExitCode, DurationMs, Error
PingResult	PacketsSent, PacketsReceived, PacketLoss, Error
DNSConfigResult	DNSServers, SearchDomains
DNSUpdateResult	Success, Message, Error

Step Chaining

Declare ordering, conditions, and error handling with chainable methods. See step.go.

o.CommandExec("_any", "whoami").
    After(health, hostname).
    Retry(2).
    OnlyIfChanged().
    When(func(r orchestrator.Results) bool {
        var h orchestrator.HostnameResult
        r.Decode("get-hostname", &h)
        return h.Hostname != ""
    }).
    OnError(orchestrator.Continue)

Method	What it does
After	Run after the given steps complete
Retry	Retry on failure up to N times
OnlyIfChanged	Skip unless a dependency reported changes
OnlyIfFailed	Skip unless at least one dependency failed
OnlyIfAllChanged	Skip unless all dependencies reported changes
When	Guard — only run if predicate returns true
OnError	Set error strategy (StopAll or Continue)

Custom Steps

Use TaskFunc to create custom steps that receive completed results from prior steps — useful for decision logic, aggregation, or conditional branching:

o.TaskFunc("summarize", func(ctx context.Context, r orchestrator.Results) (*sdk.Result, error) {
    var h orchestrator.HostnameResult
    r.Decode("get-hostname", &h)

    return &sdk.Result{
        Changed: true,
        Data:    map[string]any{"summary": h.Hostname},
    }, nil
}).After(hostname)

Configuration

Pass options to New to configure behavior:

o := orchestrator.New(url, token, orchestrator.WithVerbose())

Option	What it does
WithVerbose()	Show stdout, stderr, and response data for all tasks

Post-Execution Results

After Run() completes, decode individual task results from the report:

report, err := o.Run()

var cmd orchestrator.CommandResult
err = report.Decode("run-uptime", &cmd)
fmt.Println(cmd.Stdout)

Status Inspection

Inside When guards, inspect the status of completed dependencies:

step.When(func(r orchestrator.Results) bool {
    return r.Status("health-check") == orchestrator.TaskStatusChanged
})

Constant	Meaning
TaskStatusUnknown	Step not found or has not run
TaskStatusChanged	Step ran and reported changes
TaskStatusUnchanged	Step ran with no changes
TaskStatusSkipped	Step was skipped
TaskStatusFailed	Step failed

Broadcast Results

When targeting _all or label selectors, access per-host results:

hrs := results.HostResults("deploy")
for _, hr := range hrs {
    fmt.Printf("host=%s changed=%v error=%s\n", hr.Hostname, hr.Changed, hr.Error)

    var cmd orchestrator.CommandResult
    hr.Decode(&cmd)
}

📋 Examples

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

Example	What it shows
all	Fleet discovery, custom steps, guards, recovery, verbose mode, and result decoding

cd examples/all
OSAPI_TOKEN="<jwt>" go run main.go                # normal output
OSAPI_TOKEN="<jwt>" OSAPI_VERBOSE=1 go run main.go  # verbose output

🤝 Contributing

See the Development guide for prerequisites, setup, and conventions. See the Contributing guide before submitting a PR.

📄 License

The MIT License.