plan

Documentation

Overview

Package plan parses and validates testfleet acceptance plans (plan.yaml) and computes a stable plan_hash.

The plan_hash is the cornerstone of reproducible batch acceptance: it is a sha256 over the *normalized* entries (name + dir + resolved selector, in authored order), NOT over the raw file bytes. This makes it insensitive to YAML whitespace, comments, and intra-entry field order, but sensitive to the logical content (which dirs, which selectors, in which order). Re-running the same plan under a new staging version therefore yields the same plan_hash, while editing the plan changes it.

Index

• Variables
• type Entry
  • func (e Entry) Selector() string
• type Plan
  • func Load(path, defaultTag string) (*Plan, error)
  • func Synthesize(dirs []string, selectorMachine, selectorTag, defaultTag string) (*Plan, error)
  • func (p *Plan) Hash() string
  • func (p *Plan) ResolveDir(e Entry) string
  • func (p *Plan) Source() string

Variables

var ErrEmptyPlan = errors.New("empty plan")

ErrEmptyPlan marks a plan with zero entries. The cmd layer maps this to output.ErrEmptyPlan.

var ErrInvalidPlan = errors.New("invalid plan")

ErrInvalidPlan marks a structurally invalid plan (bad version, missing name/dir, duplicate name, both selectors set, malformed YAML). The cmd layer maps this to output.ErrInvalidPlan.

Types

type Entry

type Entry struct {
	Name    string `yaml:"name" json:"name"`
	Dir     string `yaml:"dir" json:"dir"`
	Machine string `yaml:"machine,omitempty" json:"machine,omitempty"`
	Tag     string `yaml:"tag,omitempty" json:"tag,omitempty"`
}

Entry is one planned test dispatch: a named test dir plus a machine selector (machine XOR tag). After Load/Synthesize validation, exactly one of Machine or Tag is non-empty (entries lacking both are filled with the default tag).

func (Entry) Selector

func (e Entry) Selector() string

Selector returns the canonical selector descriptor used both for hashing and for the batch item record: "machine:<name>" or "tag:<tag>".

type Plan

type Plan struct {
	Version int     `yaml:"version" json:"version"`
	Entries []Entry `yaml:"entries" json:"entries"`
	// contains filtered or unexported fields
}

Plan is a parsed, validated acceptance plan.

func Load

func Load(path, defaultTag string) (*Plan, error)

Load reads and validates a plan.yaml. defaultTag fills entries that specify neither machine nor tag. Returns ErrInvalidPlan / ErrEmptyPlan (wrapped, with detail) on validation failure, or a read/parse error otherwise.

func Synthesize

func Synthesize(dirs []string, selectorMachine, selectorTag, defaultTag string) (*Plan, error)

Synthesize builds an inline plan from positional dirs. A machine XOR tag selector overrides the per-entry default; entries with neither fall back to defaultTag. Entry names derive from dir basenames (disambiguated on clash).

func (*Plan) Hash

func (p *Plan) Hash() string

Hash returns the sha256 hex of the canonical JSON of the normalized entries, in authored order.

func (*Plan) ResolveDir

func (p *Plan) ResolveDir(e Entry) string

ResolveDir resolves an entry's dir for dispatch. Relative dirs join against the plan file's directory; absolute dirs pass through unchanged. Inline plans (no baseDir) return the dir as-authored.

func (*Plan) Source

func (p *Plan) Source() string

Source returns the provenance descriptor for the batch record: "plan:<path>" for file-backed plans, "inline" for synthesized plans.