Documentation
¶
Overview ¶
Package wait is the framework terminal-state wait engine behind the reviewed contract.WaitSpec capability. It owns polling cadence, status extraction, and status→outcome mapping; it knows nothing about Cobra, MCP, or any product backend. How one poll executes is supplied by the leaf's WaitPoll hook (corecmd), so "poll = an existing read command" stays a leaf decision rather than a framework assumption.
Index ¶
Constants ¶
const DefaultPollInterval = 2 * time.Second
DefaultPollInterval is the cadence between polls when LoopSpec.Interval is zero. The first poll runs immediately so an already-terminal resource does not pay a sleep tax.
const MaxPollInterval = 30 * time.Second
MaxPollInterval caps the exponential backoff growth between polls so a long wait cannot degenerate into effectively-blind polling.
Variables ¶
var ErrEventStreamEnded = errors.New("wait: event stream ended before a terminal status")
ErrEventStreamEnded reports a stream that terminated before a terminal status. Auto mode uses it to fall back to polling; strict event mode surfaces it as a wait failure.
Functions ¶
func ExtractStatus ¶
ExtractStatus resolves a dotted status query against a poll document. Each segment walks one map level; array indexes are not supported because wait targets a single resource. Numeric segments are stringified, so a document decoded with json.Number keys still resolves.
func IsUnknownStatus ¶
IsUnknownStatus reports whether err is the closed fail-on-unknown error.
Types ¶
type ErrUnknownStatus ¶
ErrUnknownStatus reports a status value that is neither declared terminal nor declared pending. Unknown fails closed: mapping it to pending could hide a real state change until timeout, mapping it to success is worse.
func (*ErrUnknownStatus) Error ¶
func (e *ErrUnknownStatus) Error() string
type EventLoopSpec ¶
type EventLoopSpec struct {
StatusQuery string
MatchField string
Terminal map[string]contract.ResultOutcome
Pending []string
Timeout time.Duration
}
EventLoopSpec is the event-phase projection of contract.WaitSpec.
type EventStream ¶
EventStream is the leaf-owned push subscription consumed by the event phase (the WaitEvents hook in corecmd). Recv delivers the next decoded event document; it returns an error or io.EOF-style termination when the stream ends — the engine treats non-terminal termination as a stream failure the caller (auto mode) may fall back from.
type LoopSpec ¶
type LoopSpec struct {
StatusQuery string
Terminal map[string]contract.ResultOutcome
Pending []string
Timeout time.Duration
Interval time.Duration
}
LoopSpec is the runtime-resolved projection of contract.WaitSpec plus the caller-provided timeout.
type Outcome ¶
type Outcome struct {
Status string
Outcome contract.ResultOutcome
Attempts int
TimedOut bool
}
Outcome is the closed result of a wait loop. TimedOut reports deadline exhaustion (Outcome is then pending — an accepted-but-not-terminal state is not a process failure per the exit-code contract); Status is the last observed status value.
func Run ¶
Run polls poller until a declared terminal status, deadline exhaustion, or a poller error. The first poll is immediate; subsequent polls back off exponentially (×1.5) from Interval, capped at MaxPollInterval. Deadline exhaustion anywhere — before a poll, during a poll (a context-aware poller returns ctx.Err()), or during the wait between polls — always closes as timed-out pending with the last observed status, never as a poll failure.
func RunEvent ¶
func RunEvent(ctx context.Context, spec EventLoopSpec, resource string, stream EventStream) (Outcome, error)
RunEvent consumes stream until a correlated event reaches a declared terminal status, the deadline exhausts, or the stream ends. Events whose MatchField value does not equal resource are ignored (other resources on the same channel); a correlated event with an unknown status fails closed exactly like a poll would.
Source Files