engine

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package engine provides DAG-based task orchestration primitives.

Index

Constants

This section is empty.

Variables

View Source 
var Continue = ErrorStrategy{/* contains filtered or unexported fields */}

Continue skips dependents of the failed task but continues independent tasks.

View Source 
var StopAll = ErrorStrategy{/* contains filtered or unexported fields */}

StopAll cancels all remaining tasks on first failure.

Functions

func StructToMap 

func StructToMap(
	v any,
) map[string]any

StructToMap converts a struct to map[string]any using its JSON tags. Returns nil if v is nil or cannot be marshaled.

Types

type ErrorStrategy 

type ErrorStrategy struct {
	// contains filtered or unexported fields
}

ErrorStrategy defines how the runner handles task failures.

func Retry 

func Retry(
	n int,
	opts ...RetryOption,
) ErrorStrategy

Retry returns a strategy that retries a failed task n times before failing. Options configure backoff behavior.

func (ErrorStrategy) RetryCount 

func (e ErrorStrategy) RetryCount() int

RetryCount returns the number of retries for this strategy.

func (ErrorStrategy) String 

func (e ErrorStrategy) String() string

String returns a human-readable representation of the strategy.

type GuardFn 

type GuardFn func(results Results) bool

GuardFn is a predicate that determines if a task should run.

type Hooks 

type Hooks struct {
	BeforePlan  func(summary PlanSummary)
	AfterPlan   func(report *Report)
	BeforeLevel func(level int, tasks []*Task, parallel bool)
	AfterLevel  func(level int, results []TaskResult)
	BeforeTask  func(task *Task)
	AfterTask   func(task *Task, result TaskResult)
	OnRetry     func(task *Task, attempt int, err error)
	OnSkip      func(task *Task, reason string)
}

Hooks provides consumer-controlled callbacks for plan execution events. All fields are optional — nil callbacks are skipped. The SDK performs no logging; hooks are the only output mechanism.

type HostResult 

type HostResult struct {
	Hostname    string
	Status      string
	Changed     bool
	Error       string
	Data        map[string]any
	JobDuration time.Duration
}

HostResult represents a single host's response within a broadcast operation.

type Plan 

type Plan struct {
	// contains filtered or unexported fields
}

Plan is a DAG of tasks with dependency edges.

func NewPlan 

func NewPlan(
	client *osapiclient.Client,
	opts ...PlanOption,
) *Plan

NewPlan creates a new plan bound to an OSAPI client.

func (*Plan) Client 

func (p *Plan) Client() *osapiclient.Client

Client returns the OSAPI client bound to this plan.

func (*Plan) Config 

func (p *Plan) Config() PlanConfig

Config returns the plan configuration.

func (*Plan) Explain 

func (p *Plan) Explain() string

Explain returns a human-readable representation of the execution plan showing levels, parallelism, dependencies, and guards.

func (*Plan) Levels 

func (p *Plan) Levels() ([][]*Task, error)

Levels returns the levelized DAG -- tasks grouped into execution levels where all tasks in a level can run concurrently. Returns an error if the plan fails validation.

func (*Plan) Run 

func (p *Plan) Run(
	ctx context.Context,
) (*Report, error)

Run validates the plan, resolves the DAG, and executes tasks.

func (*Plan) TaskFunc 

func (p *Plan) TaskFunc(
	name string,
	fn TaskFn,
) *Task

TaskFunc creates a functional task, adds it to the plan, and returns it.

func (*Plan) TaskFuncWithResults 

func (p *Plan) TaskFuncWithResults(
	name string,
	fn TaskFnWithResults,
) *Task

TaskFuncWithResults creates a functional task that receives completed results from prior tasks, adds it to the plan, and returns it.

func (*Plan) Tasks 

func (p *Plan) Tasks() []*Task

Tasks returns all tasks in the plan.

func (*Plan) Validate 

func (p *Plan) Validate() error

Validate checks the plan for errors: duplicate names and cycles.

type PlanConfig 

type PlanConfig struct {
	OnErrorStrategy ErrorStrategy
	Hooks           *Hooks
}

PlanConfig holds plan-level configuration.

type PlanOption 

type PlanOption func(*PlanConfig)

PlanOption is a functional option for NewPlan.

func OnError 

func OnError(
	strategy ErrorStrategy,
) PlanOption

OnError returns a PlanOption that sets the default error strategy.

func WithHooks 

func WithHooks(
	hooks Hooks,
) PlanOption

WithHooks attaches lifecycle callbacks to plan execution.

type PlanSummary 

type PlanSummary struct {
	TotalTasks int
	Steps      []StepSummary
}

PlanSummary describes the execution plan before it runs.

type Report 

type Report struct {
	Tasks    []TaskResult
	Duration time.Duration
}

Report is the aggregate output of a plan execution.

func (*Report) Summary 

func (r *Report) Summary() string

Summary returns a human-readable summary of the report.

type Result 

type Result struct {
	JobID       string
	Changed     bool
	Data        map[string]any
	Status      Status
	JobDuration time.Duration
	HostResults []HostResult
}

Result is the outcome of a single task execution.

func CollectionResult 

func CollectionResult[T any](
	col client.Collection[T],
	rawJSON []byte,
	toHostResult func(T) HostResult,
) (*Result, error)

CollectionResult builds a Result from a Collection response. It iterates all results, applies the toHostResult mapper to build per-host details, and auto-populates HostResult.Data via StructToMap when the mapper leaves it nil. Changed is true if any host reported a change.

When rawJSON is non-nil, it is unmarshaled into Result.Data to provide the full response for downstream consumers (e.g., guards or Results.Decode). Pass resp.RawJSON() for this, or nil to skip.

type Results 

type Results map[string]*Result

Results is a map of task name to Result, used for conditional logic.

func (Results) Get 

func (r Results) Get(
	name string,
) *Result

Get returns the Result for the named task, or nil if not found.

type RetryOption 

type RetryOption func(*ErrorStrategy)

RetryOption configures retry behavior.

func WithRetryBackoff 

func WithRetryBackoff(
	initial time.Duration,
	maxInterval time.Duration,
) RetryOption

WithRetryBackoff enables exponential backoff between retry attempts with the given initial and maximum intervals.

type Status 

type Status string

Status represents the outcome of a task execution. 

const (
	// StatusPending and StatusRunning are reserved for future
	// streaming status support. The runner does not currently
	// assign these — tasks go directly to a terminal status.
	StatusPending   Status = "pending"
	StatusRunning   Status = "running"
	StatusChanged   Status = "changed"
	StatusUnchanged Status = "unchanged"
	StatusSkipped   Status = "skipped"
	StatusFailed    Status = "failed"
)

Task execution statuses.

type StepSummary 

type StepSummary struct {
	Tasks    []string
	Parallel bool
}

StepSummary describes a single execution step (DAG level).

type Task 

type Task struct {
	// contains filtered or unexported fields
}

Task is a unit of work in an orchestration plan.

func NewTaskFunc 

func NewTaskFunc(
	name string,
	fn TaskFn,
) *Task

NewTaskFunc creates a functional task with custom logic.

func NewTaskFuncWithResults 

func NewTaskFuncWithResults(
	name string,
	fn TaskFnWithResults,
) *Task

NewTaskFuncWithResults creates a functional task that receives completed results from prior tasks.

func (*Task) Dependencies 

func (t *Task) Dependencies() []*Task

Dependencies returns the task's dependencies.

func (*Task) DependsOn 

func (t *Task) DependsOn(
	deps ...*Task,
) *Task

DependsOn sets this task's dependencies. Returns the task for chaining.

func (*Task) ErrorStrategy 

func (t *Task) ErrorStrategy() *ErrorStrategy

ErrorStrategy returns the per-task error strategy, or nil to use the plan default.

func (*Task) Fn 

func (t *Task) Fn() TaskFn

Fn returns the task function, or nil if not set.

func (*Task) Guard 

func (t *Task) Guard() GuardFn

Guard returns the guard function, or nil if none is set.

func (*Task) GuardReason 

func (t *Task) GuardReason() string

GuardReason returns the current guard reason.

func (*Task) IsFunc 

func (t *Task) IsFunc() bool

IsFunc returns true if this is a functional task.

func (*Task) Name 

func (t *Task) Name() string

Name returns the task name.

func (*Task) OnError 

func (t *Task) OnError(
	strategy ErrorStrategy,
)

OnError sets a per-task error strategy override.

func (*Task) OnlyIfChanged 

func (t *Task) OnlyIfChanged()

OnlyIfChanged marks this task to only run if at least one dependency reported Changed=true.

func (*Task) RequiresChange 

func (t *Task) RequiresChange() bool

RequiresChange returns true if OnlyIfChanged was set.

func (*Task) SetGuardReason 

func (t *Task) SetGuardReason(
	reason string,
)

SetGuardReason updates the skip reason shown when the guard returns false. Use inside a guard function to provide a dynamic reason based on runtime conditions.

func (*Task) SetName 

func (t *Task) SetName(
	name string,
)

SetName changes the task name.

func (*Task) When 

func (t *Task) When(
	fn GuardFn,
)

When sets a custom guard function that determines whether this task should execute.

func (*Task) WhenWithReason 

func (t *Task) WhenWithReason(
	fn GuardFn,
	reason string,
)

WhenWithReason sets a guard with a custom skip reason shown when the guard returns false.

type TaskFn 

type TaskFn func(
	ctx context.Context,
	client *osapiclient.Client,
) (*Result, error)

TaskFn is the signature for functional tasks. The client parameter provides access to the OSAPI SDK for making API calls.

type TaskFnWithResults 

type TaskFnWithResults func(
	ctx context.Context,
	client *osapiclient.Client,
	results Results,
) (*Result, error)

TaskFnWithResults is like TaskFn but receives completed task results for inter-task data access.

type TaskResult 

type TaskResult struct {
	JobID       string
	Name        string
	Status      Status
	Changed     bool
	Duration    time.Duration
	JobDuration time.Duration
	Error       error
	Data        map[string]any
	HostResults []HostResult
}

TaskResult records the full execution details of a task.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.