flow.go

package legatus

// Flow is an ordered, host-agnostic sequence of steps — a playbook. A Runner

// executes a Flow against each selected host, fanning out per host.

type Flow struct {

	Name  string

	Steps []Step

}

// FlowSource is anything that lowers to a runnable Flow: a static Flow (the

// identity case) or a declarative spec that resolves to one (see

// legatus/flowspec). Runner.Run accepts a FlowSource, so callers pass either kind

// interchangeably. Resolve is host-independent — it yields the same Flow for

// every host, so the Runner resolves once before fanning out.

type FlowSource interface {

	Resolve() (Flow, error)

}

// Resolve makes Flow its own FlowSource: a materialized Flow is already resolved,

// so it returns itself unchanged with a nil error.

func (f Flow) Resolve() (Flow, error) { return f, nil }

// Step is one unit of work. Check probes whether a change is needed (need=false

// reports Skipped and, in dry-run, ends the step). Apply performs the change and

// reports what it did.

type Step interface {

	Name() string

	Check(fc *FlowCtx) (need bool, err error)

	Apply(fc *FlowCtx) (Outcome, error)

}

// Outcome is what a step reports about what it did. The engine wraps this in a

// StepResult with timing and a derived Status.

type Outcome struct {

	Changed bool

	Message string

	Data    any

}

// AlwaysApply embeds into steps with no meaningful check; Check always reports a

// change is needed.

type AlwaysApply struct{}

// Check always reports need=true.

func (AlwaysApply) Check(*FlowCtx) (bool, error) { return true, nil }

type stepFunc struct {

	AlwaysApply

	name string

	fn   func(*FlowCtx) (Outcome, error)

}

func (s stepFunc) Name() string                       { return s.name }

func (s stepFunc) Apply(fc *FlowCtx) (Outcome, error) { return s.fn(fc) }

// StepFunc adapts a function into a Step that always applies.

func StepFunc(name string, fn func(*FlowCtx) (Outcome, error)) Step {

	return stepFunc{name: name, fn: fn}

}