Documentation
¶
Overview ¶
Package progress writes contract:cli.deploy-progress v1: the NDJSON stream that `nself deploy --json --stream` and `nself deploy promote <src> <tgt> --json --stream` print.
Purpose: let an agent follow a long deploy without parsing human text. Inputs: step events from the deploy code, a promote.Observer feed and the final outcome. Outputs: one compact v1 envelope per line on an io.Writer. Progress lines carry an Event as data, the last line carries a Result as data. Constraints: every line is built with internal/output and then compacted, never hand-built; the Writer is nil-safe so a run without --stream pays nothing; no secret or hostname is added by this package.
Index ¶
- Constants
- Variables
- func PhaseForStatus(status string) string
- func ResultForPromote(status string) string
- func WithWriter(ctx context.Context, w *Writer) context.Context
- type Event
- type PromoteObserver
- type Result
- type Step
- type Writer
- func (w *Writer) At(env, server string) *Writer
- func (w *Writer) Err() error
- func (w *Writer) Event(step, phase, detail string)
- func (w *Writer) Finish(result string, steps []Step) error
- func (w *Writer) Outcome() (result string, steps []Step, ok bool)
- func (w *Writer) SetOutcome(result string, steps []Step)
- func (w *Writer) Status(step, status, detail string)
- func (w *Writer) Steps() []Step
Constants ¶
const ( TypeProgress = "progress" TypeResult = "result" )
Data types of the two kinds of line (data.type).
const ( PhaseStart = "start" PhaseDone = "done" PhaseFailed = "failed" PhaseSkipped = "skipped" PhaseRollback = "rollback" )
Phases of a progress event (data.phase).
const ( ResultOK = "ok" ResultFailed = "failed" ResultRolledBack = "rolled_back" ResultRollbackFailed = "rollback_failed" )
Outcomes of a run (data.result of the last line).
Variables ¶
var Phases = []string{PhaseStart, PhaseDone, PhaseFailed, PhaseSkipped, PhaseRollback}
Phases lists every accepted data.phase, in contract order.
var Results = []string{ResultOK, ResultFailed, ResultRolledBack, ResultRollbackFailed}
Results lists every accepted data.result, in contract order.
Functions ¶
func PhaseForStatus ¶
PhaseForStatus maps a deploy step status to the event phase that reports it: failed and unhealthy report failed, pending (a dry-run plan) and skipped report skipped, everything else reports done.
func ResultForPromote ¶
ResultForPromote maps a promote engine status ("ok", "failed", "rolled_back", "rollback_failed") to a data.result value; anything else is failed.
Types ¶
type Event ¶
type Event struct {
// Type is always TypeProgress.
Type string `json:"type"`
// Seq counts events from 1 and strictly increases within one run.
Seq int `json:"seq"`
// Step names the unit of work, for example "Build images" or "apply".
Step string `json:"step"`
// Phase is one of Phases.
Phase string `json:"phase"`
// Env is the environment the step acts on, or null.
Env *string `json:"env"`
// Server is the server the step acts on, or null when not per server.
Server *string `json:"server"`
// ElapsedMS is the time since the stream started, in milliseconds.
ElapsedMS int64 `json:"elapsed_ms"`
// Detail is a short redacted note (a reason or an error summary), or null.
Detail *string `json:"detail"`
}
Event is the data of one progress line. Field order is the key order on the wire (type first, as in the stream framing of contract:cli.json-stream v1). Every key is always present; Env, Server and Detail are null when unknown.
type PromoteObserver ¶
type PromoteObserver struct {
// contains filtered or unexported fields
}
PromoteObserver feeds the promote engine's synchronous lifecycle calls into a Writer. Its method set satisfies controlplane/promote.Observer. The events are labelled with the target environment and no server.
func NewPromoteObserver ¶
func NewPromoteObserver(w *Writer, env string) *PromoteObserver
NewPromoteObserver returns an observer writing to w, labelling events with env (the promotion target). A nil w gives an observer that does nothing.
func (*PromoteObserver) Done ¶
func (o *PromoteObserver) Done(step string, _ time.Duration)
Done reports that step finished. The engine's step time is not repeated: elapsed_ms already orders the events.
func (*PromoteObserver) Failed ¶
func (o *PromoteObserver) Failed(step string, err error)
Failed reports that step failed with err.
func (*PromoteObserver) Rollback ¶
func (o *PromoteObserver) Rollback(step string, err error)
Rollback reports the compensating action of step: undone when err is nil, else the undo failed.
func (*PromoteObserver) Skipped ¶
func (o *PromoteObserver) Skipped(step, reason string)
Skipped reports that step did not run, with the reason.
func (*PromoteObserver) Start ¶
func (o *PromoteObserver) Start(step string)
Start reports that step began.
type Result ¶
type Result struct {
// Type is always TypeResult.
Type string `json:"type"`
// Result is one of Results.
Result string `json:"result"`
// Steps lists each step with its last known status, in first-seen order.
Steps []Step `json:"steps"`
}
Result is the data of the last line. Steps is never null.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer writes progress lines for one run. At returns views that share the sequence, the clock and the destination but label events with another environment or server.
func FromContext ¶
FromContext returns the Writer ctx carries, or nil when the run is not streaming (a nil ctx is allowed).
func NewWriter ¶
NewWriter returns a Writer that writes to w. command is the registry command path put in every envelope ("deploy" or "deploy promote"). The elapsed clock starts now.
func NewWriterClock ¶
NewWriterClock is NewWriter with an injected clock, for tests.
func (*Writer) At ¶
At returns a view of w whose events carry env and server ("" is null). It returns nil for a nil w.
func (*Writer) Event ¶
Event writes one progress line for step in phase and records the step's status. detail ("" is null) is redacted and shortened first.
func (*Writer) Finish ¶
Finish writes the last line once: data.type "result" with the outcome and steps (nil means the recorded step list). Later calls and events are ignored. It returns the first write error of the stream.
func (*Writer) SetOutcome ¶
SetOutcome records the result and step list the stream should end with, for a caller that knows them better than the recorded events do (the promote engine's own result). The last call wins; Finish uses it when asked for no result.
Source Files