Documentation
¶
Overview ¶
Package events defines the typed, versioned protocol the CI runner speaks to the server: the lifecycle of a multi-stack Terraform execution (init → phase → per-stack updates → finalize) plus the apply-time gate exchange. One module, one version — the runner baked into a CI image and the deployed server share these types, so they can never disagree about event shapes.
Index ¶
Constants ¶
const Version = 1
Version is the protocol version. Bump on any breaking change to the payloads below; runner and server are expected to share the same module version.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Category ¶ added in v0.6.0
Category is a classification label matched by a stack. Alias of the canonical domain type (carries Name/Icon and, additively, emitted Attributes).
type Claim ¶ added in v0.15.0
type Claim struct {
Environment string `json:"environment"`
StackPath string `json:"stack_path"`
OwnerPR int `json:"owner_pr"`
ExpiresAt time.Time `json:"expires_at"`
}
Claim is one apply-lock claim row, mirroring store.Claim over the wire for the /api/claims/list endpoint.
type Counts ¶ added in v0.11.0
Counts is a stack's per-kind operation tally. Alias of the canonical domain type so the runner and server share one definition with the render pipeline.
type Finalize ¶
type Finalize struct {
ID string `json:"id"`
ReportMarkdown string `json:"report_markdown"`
Projects map[string]string `json:"projects,omitempty"` // stack path → grouping/target key
StackReports map[string]string `json:"stack_reports,omitempty"` // stack path → rendered plan section
Gates []GateTarget `json:"gates,omitempty"` // (class,target) pairs needing approval
Moving []string `json:"moving,omitempty"` // stack paths adopting resources via a cross-state move
Failed bool `json:"failed,omitempty"`
Categories map[string][]Category `json:"categories,omitempty"` // stack path → matched categories
Counts map[string]Counts `json:"counts,omitempty"` // stack path → op counts
}
Finalize records the terminal plan state: the rendered report, per-stack target backfill, the gates that must be approved, and the moving/failed flags.
type GateCheck ¶
GateCheck is the apply-time gate pre-check (fail-closed): is every required gate for this (PR, environment) approved?
type GateRevoke ¶
GateRevoke asks the server to revoke the grants it requested for this (PR, environment) — best-effort post-apply cleanup.
type GateTarget ¶
GateTarget names one thing that must be approved: a classification class (e.g. "iam") against a target (e.g. a cloud project/account). Generalises the single implicit IAM/project gate into (class, target) pairs so multiple approval classes are accommodated from the start.
type Graph ¶
type Graph struct {
Stacks []StackState `json:"stacks"`
Edges []Edge `json:"edges"`
}
Graph is the changed subgraph for one execution.
type Init ¶
type Init struct {
ID string `json:"id"`
Repo string `json:"repo"`
SHA string `json:"sha"`
PR int `json:"pr"`
Environment string `json:"environment"`
LogURL string `json:"log_url"` // CI log deep-link, shown on failures
Context string `json:"context,omitempty"` // commit-status context this run drives
Stacks []StackState `json:"stacks"`
Edges []Edge `json:"edges"`
}
Init registers an execution and its changed subgraph.
type LogChunk ¶ added in v0.6.0
type LogChunk struct {
ID string `json:"id"`
Stack string `json:"stack"`
Data string `json:"data"`
}
LogChunk is a slice of one stack's combined output, streamed during execution.
type Phase ¶
type Phase string
Phase is the execution-wide lifecycle phase, narrated before and across the per-stack work.
const ( PhaseWarming Phase = "warming" // warming the provider plugin cache PhaseLinting Phase = "linting" // static lint (e.g. tflint) over modules PhaseInitializing Phase = "initializing" // sequential terraform init PhasePlanning Phase = "planning" // parallel plan PhaseApplying Phase = "applying" // sequential apply PhaseTesting Phase = "testing" // post-apply contract tests PhaseVerifying Phase = "verifying" // post-apply verification )
type PhaseEvent ¶
type PhaseEvent struct {
ID string `json:"id"`
Repo string `json:"repo,omitempty"`
SHA string `json:"sha,omitempty"`
PR int `json:"pr,omitempty"`
Environment string `json:"environment,omitempty"`
LogURL string `json:"log_url,omitempty"`
Context string `json:"context,omitempty"`
Phase Phase `json:"phase"`
}
PhaseEvent narrates a lifecycle phase transition (may arrive before Init).
type StackState ¶
type StackState struct {
Path string `json:"path"`
Project string `json:"project,omitempty"` // grouping/target key (e.g. cloud project/account)
Status Status `json:"status,omitempty"`
Detail string `json:"detail,omitempty"` // optional failure detail (last error lines)
Categories []Category `json:"categories,omitempty"` // matched classification categories
Counts *Counts `json:"counts,omitempty"` // per-kind op tally (nil until finalize)
}
StackState is one node in the execution graph.
type Status ¶
type Status string
Status is the lifecycle of a single stack within an execution.
const ( StatusPending Status = "pending" // intends to run StatusInitializing Status = "initializing" // terraform init running for this stack StatusInitialized Status = "initialized" // init done, awaiting plan StatusRunning Status = "running" // running now StatusPlanned Status = "planned" // plan done, no gate required StatusGated Status = "gated" // blocked on an approval gate StatusSafe Status = "safe" // approved / applied with changes / clean StatusNochange Status = "nochange" // applied, terraform reported 0 changes StatusMoving Status = "moving" // adopting resources via a cross-state move (non-gating) StatusFailed Status = "failed" // this stack errored StatusAborted Status = "aborted" // run failed elsewhere; this stack never reached a terminal tick )
func AllStatuses ¶ added in v0.17.0
func AllStatuses() []Status
AllStatuses lists every known stack status. Retained as public API: the test suite validates all members via this, and docs/consumers enumerate statuses from it.
func ParseStatus ¶ added in v0.17.0
ParseStatus validates a raw wire string into a Status, returning a coded (WIRE-001) error for an unknown non-empty value.
func (*Status) UnmarshalJSON ¶ added in v0.17.0
UnmarshalJSON decodes a JSON string and validates it, so an unknown status in an untrusted payload fails fast at the wire boundary rather than entering the system silently. (The store does not decode status via JSON — it scans the column directly — so persisted values are never re-validated here.)
Source Files