runner

package
v1.0.0-beta.7 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: ISC Imports: 27 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NormalizeParamsForState 

func NormalizeParamsForState(source, params, sourceBecome, become map[string]any) map[string]any

func ParamHash 

func ParamHash(params map[string]any) string

ParamHash computes a SHA256 hash of the params map as a hex string.

func StateParamHash 

func StateParamHash(source, params, sourceBecome, become map[string]any) string

func StateParamSummary 

func StateParamSummary(source, params, sourceBecome, become map[string]any) any

func SummarizeParams 

func SummarizeParams(params map[string]any) any

SummarizeParams produces a redacted, JSON-friendly summary of parameters for state diff output.

Types

type BoundTask 

type BoundTask struct {
	Name   string
	When   string
	Params map[string]any
	Become map[string]any
}

BoundTask holds the template-rendered task fields before secret resolution.

type BoundTaskResult 

type BoundTaskResult struct {
	Name         string
	Params       map[string]any
	Become       map[string]any
	SourceParams map[string]any // pre-secret-resolution copy for state
	SourceBecome map[string]any // pre-secret-resolution copy for state
	ExecOpts     target.ExecutionOptions
}

BoundTaskResult is the output of the consolidated bind pipeline: a fully resolved task ready to execute, plus pre-resolution copies for state hashing.

type ComparisonStatus 

type ComparisonStatus string
const (
	ComparisonStatusNew        ComparisonStatus = "NEW"
	ComparisonStatusChanged    ComparisonStatus = "CHANGED"
	ComparisonStatusUnchanged  ComparisonStatus = "UNCHANGED"
	ComparisonStatusRemoved    ComparisonStatus = "REMOVED"
	ComparisonStatusStatusOnly ComparisonStatus = "STATUS-ONLY"
)

type Config 

type Config struct {
	DryRun        bool
	Tags          []string
	SkipTags      []string
	Concurrency   int
	ProjectDir    string
	ProjectName   string
	ProjectEnv    string
	ProjectVars   map[string]any
	InventoryVars map[string]any
	Vars          map[string]any // from --var CLI flags
	TargetVars    map[string]any
	TargetName    string
	// StagePlatform overrides live target discovery only while assembling a bundle.
	StagePlatform                 *target.Platform
	Phase                         string // "plan", "fetch", "stage", "apply" (empty = all)
	SkipFetch                     bool
	Renderer                      output.Renderer
	Secrets                       *secrets.Resolver
	SecretsConfig                 config.SecretsConfig
	StatePath                     string
	ModuleRegistry                target.ModuleRegistry
	BundleOutputDir               string
	BundlePlugins                 []plugins.LoadedPlugin
	AllowPlaintextSecretsInBundle bool
	Lockfile                      *action.Lockfile
	Version                       string
	Commit                        string
	BuildDate                     string
}

Config holds the options that control runner behavior.

type DAG 

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

DAG is a directed acyclic graph of tasks for dependency-ordered execution.

func BuildDAG 

func BuildDAG(tasks []*PlanTask) (*DAG, error)

BuildDAG constructs a DAG from the given tasks. DependsOn values are resolved by canonical dependency refs prepared during planning. Returns an error if a dependency references an unknown task ref or if there is a cycle.

func (*DAG) DependencyIDs 

func (d *DAG) DependencyIDs(task *PlanTask) ([]string, error)

DependencyIDs resolves a task's dependency refs to stable task IDs.

func (*DAG) TopologicalOrder 

func (d *DAG) TopologicalOrder() []*PlanTask

TopologicalOrder returns tasks in dependency-first execution order.

type ExecutionPlan 

type ExecutionPlan struct {
	PlaybookName string
	Tasks        []*PlanTask
	// contains filtered or unexported fields
}

ExecutionPlan is the result of the Plan phase: a flat, ordered list of tasks with all variables resolved.

func (*ExecutionPlan) DAG 

func (p *ExecutionPlan) DAG() (*DAG, error)

DAG returns the plan's validated dependency graph, rebuilding it only for hand-constructed test plans or older callers that did not come from Plan().

type GateRefusal 

type GateRefusal struct {
	RuntimeKind target.RuntimeKind
	Violations  []GateViolation
}

GateRefusal is the typed error returned when the apply-start support gate refuses a run. The gate runs after Info() resolves the runtime kind and facts are gathered, before task 1: every task that will actually run is validated against the support matrix, and the whole run is refused with every violation listed. It is when-aware (when-false tasks are excluded) and ignore_errors-exempt (those tasks keep fail-and-continue at execution time). Per-task apply-time errors remain only for environment prerequisites the matrix cannot know.

func (*GateRefusal) Error 

func (g *GateRefusal) Error() string

Error renders the refusal: a summary line naming the runtime, then one line per violation.

func (*GateRefusal) Event 

func (g *GateRefusal) Event(targetName string) output.SupportGateEvent

Event builds the run-log event for this refusal.

type GateViolation 

type GateViolation struct {
	TaskName string
	Module   string
	Err      error
}

GateViolation is one task-level support-matrix violation collected by the apply-start gate.

type PlanTask 

type PlanTask struct {
	ID           string // unique ID, e.g. "task-0", "task-1"
	Name         string
	Ref          string
	ActionPath   string // human-readable parent path, e.g. "Apply machine baseline/Configure computer name"
	Module       string
	Params       map[string]any
	Become       map[string]any
	Scope        *template.Scope
	DependsOn    []string
	When         string
	Tags         []string
	IgnoreErrors bool
}

PlanTask is a single task entry in the execution plan.

func PreviewTask 

func PreviewTask(task *PlanTask, targetVars map[string]any) (*PlanTask, error)

PreviewTask renders a single PlanTask against the given target vars using BindPartial, preserving unknown references. Used for plan previews and staged-bundle analysis.

type PlannedTaskState 

type PlannedTaskState struct {
	TaskKey      string
	TaskName     string
	Module       string
	DependsOn    []string
	TaskHash     string
	ParamHash    string
	ParamSummary any
}

func BuildPlannedTaskState 

func BuildPlannedTaskState(ctx context.Context, plan *ExecutionPlan, rt *template.RuntimeContext, resolver *secrets.Resolver) ([]PlannedTaskState, error)

type Runner 

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

Runner orchestrates the Plan→Fetch→Stage→Apply pipeline.

func New 

func New(t target.Target, resolver action.Chain, cfg Config) *Runner

New creates a new Runner with the given target, resolver chain, and config.

func (*Runner) Apply 

func (r *Runner) Apply(ctx context.Context, plan *ExecutionPlan) (err error)

func (*Runner) Fetch 

func (r *Runner) Fetch(ctx context.Context, playbook *action.Playbook) error

func (*Runner) Plan 

func (r *Runner) Plan(ctx context.Context, playbook *action.Playbook) (*ExecutionPlan, error)

func (*Runner) PlannedTaskState 

func (r *Runner) PlannedTaskState(ctx context.Context, plan *ExecutionPlan) ([]PlannedTaskState, error)

PlannedTaskState renders the current plan with execution-time target context so state comparisons use the same task names and params that apply records.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context, playbook *action.Playbook) (err error)

Run executes the playbook through the configured phases. If Config.Phase is empty, all phases run in order: plan, fetch, stage, apply. Otherwise only the specified phase runs (plan is always required first).

func (*Runner) Stage 

func (r *Runner) Stage(ctx context.Context, plan *ExecutionPlan) (err error)

type SecretValueAnalysis 

type SecretValueAnalysis struct {
	RefNames          []string
	HasLiteralSecrets bool
}

func AnalyzeSecretValues 

func AnalyzeSecretValues(value any) SecretValueAnalysis

type State 

type State struct {
	Version     int                     `json:"version,omitempty"`
	LastApplied time.Time               `json:"last_applied"`
	Tasks       map[string]TaskSnapshot `json:"tasks,omitempty"`
}

State holds persisted runner state written to disk after each apply.

func LoadState 

func LoadState(path string) (*State, error)

LoadState reads a state file from path. If the file does not exist, an empty State is returned (not an error).

func (*State) RecordTask 

func (s *State) RecordTask(snapshot TaskSnapshot)

RecordTask stores a v2 snapshot in the state, keyed by stable task key.

func (*State) Save 

func (s *State) Save(path string) error

Save writes the state to path as JSON. The file is written atomically by writing to a temp file and renaming it.

type TaskComparison 

type TaskComparison struct {
	Status          ComparisonStatus
	TaskKey         string
	TaskName        string
	Module          string
	RecordedStatus  target.Status
	RecordedSummary any
	PlannedSummary  any
}

func ComparePlannedTasks 

func ComparePlannedTasks(planned []PlannedTaskState, state *State) []TaskComparison

type TaskSnapshot 

type TaskSnapshot struct {
	TaskKey      string        `json:"task_key"`
	TaskName     string        `json:"task_name"`
	Module       string        `json:"module,omitempty"`
	DependsOn    []string      `json:"depends_on,omitempty"`
	TaskHash     string        `json:"task_hash,omitempty"`
	ParamHash    string        `json:"param_hash,omitempty"`
	ParamSummary any           `json:"param_summary,omitempty"`
	Status       target.Status `json:"status"`
	Message      string        `json:"message,omitempty"`
	Timestamp    time.Time     `json:"timestamp"`
}

TaskSnapshot is the v2 persisted state model used for comparison and audit.

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.