Documentation
¶
Overview ¶
Package status defines the structured progress events emitted by long-running commands.
Index ¶
- func Enter(r Reporter, phase Phase, step string)
- func Fail(r Reporter, phase Phase, err error)
- func Leave(r Reporter, phase Phase, step string)
- func OperationID(ctx context.Context) string
- func ParentOperationID(ctx context.Context) string
- func Run(ctx context.Context, reporter Reporter, operation Operation, ...) error
- func Skip(r Reporter, phase Phase, step string)
- func ValidState(s State) bool
- type EnvelopeReporter
- type ErrorInfo
- type Event
- type HumanReporter
- type MemoryReporter
- type Operation
- type Phase
- type Pipeline
- type PlainReporter
- type Reporter
- func ForPipeline(r Reporter, pipeline Pipeline) Reporter
- func NewEnvelopeReporter(write func(Event) error) Reporter
- func NewHumanReporter(out io.Writer, prefix string, labels map[Phase]string) Reporter
- func NewLogReporter() Reporter
- func NewPlainReporter(out io.Writer, prefix string, labels map[Phase]string) Reporter
- func NewReporter(opts ReporterOptions) (Reporter, error)
- func Nop() Reporter
- func Tee(reporters ...Reporter) Reporter
- type ReporterOptions
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func OperationID ¶
OperationID returns the current operation ID, if any.
func ParentOperationID ¶
ParentOperationID returns the current operation ID, if any.
func Run ¶
func Run( ctx context.Context, reporter Reporter, operation Operation, fn func(context.Context) error, ) error
Run reports an operation lifecycle and returns the callback error.
func ValidState ¶
ValidState reports whether s is part of the current status protocol.
Types ¶
type EnvelopeReporter ¶
type EnvelopeReporter struct {
// contains filtered or unexported fields
}
EnvelopeReporter forwards events to an encoder supplied by the output layer. Keeping encoding injectable avoids coupling status to any envelope package while centralizing synchronization and reporter selection.
func (*EnvelopeReporter) Report ¶
func (r *EnvelopeReporter) Report(e Event)
type ErrorInfo ¶
type ErrorInfo struct {
Code string `json:"code,omitempty"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
Context map[string]string `json:"context,omitempty"`
}
ErrorInfo is the serializable, user-facing portion of an operation failure.
type Event ¶
type Event struct {
Pipeline Pipeline `json:"pipeline,omitempty"`
OperationID string `json:"operationId,omitempty"`
ParentOperationID string `json:"parentOperationId,omitempty"`
Phase Phase `json:"phase"`
Step string `json:"step,omitempty"`
State State `json:"state,omitempty"`
Duration time.Duration `json:"-"`
Error *ErrorInfo `json:"error,omitempty"`
}
Event is one phase transition.
type HumanReporter ¶
type HumanReporter struct {
PlainReporter
}
HumanReporter is the interactive human presentation.
type MemoryReporter ¶
type MemoryReporter struct {
// contains filtered or unexported fields
}
MemoryReporter collects status events for tests and embedding applications. It is safe for concurrent Report calls.
func NewMemoryReporter ¶
func NewMemoryReporter() *MemoryReporter
NewMemoryReporter returns an empty concurrent event collector.
func (*MemoryReporter) Events ¶
func (r *MemoryReporter) Events() []Event
Events returns a snapshot that callers may safely modify.
func (*MemoryReporter) Report ¶
func (r *MemoryReporter) Report(e Event)
type Phase ¶
type Phase string
Phase identifies a step in a pipeline. PhaseReady and PhaseFailed are shared terminal phases.
const ( PhaseCloningRepository Phase = "cloning_repository" PhaseResolvingConfig Phase = "resolving_config" PhaseInitializeCommand Phase = "initialize_command" PhaseBuildingImage Phase = "building_image" PhaseStartingContainer Phase = "starting_container" PhaseInjectingAgent Phase = "injecting_agent" PhaseRunningLifecycleHook Phase = "running_lifecycle_hook" PhaseWaitingFor Phase = "waiting_for" PhaseRunningCommand Phase = "running_command" PhaseConfiguringWorkspace Phase = "configuring_workspace" PhaseConfiguringSSH Phase = "configuring_ssh" PhaseStartingSSHTunnel Phase = "starting_ssh_tunnel" PhaseLaunchingIDE Phase = "launching_ide" PhaseStoppingWorkspace Phase = "stopping_workspace" PhaseDeletingWorkspace Phase = "deleting_workspace" PhaseRebuildingWorkspace Phase = "rebuilding_workspace" PhaseResettingWorkspace Phase = "resetting_workspace" PhaseReady Phase = "ready" PhaseFailed Phase = "failed" )
Workspace up phases.
type Pipeline ¶
type Pipeline string
Pipeline identifies which command's progress an Event describes.
type PlainReporter ¶
type PlainReporter struct {
// contains filtered or unexported fields
}
PlainReporter renders deterministic ASCII status lines. It never writes terminal control sequences, making it safe for redirected output and CI.
func (PlainReporter) Report ¶
func (r PlainReporter) Report(e Event)
type Reporter ¶
type Reporter interface {
Report(Event)
}
Reporter receives status events as they occur. Implementations must be safe to call from goroutines.
func ForPipeline ¶
ForPipeline stamps every event a reporter receives with pipeline, so the Enter/Leave/Fail helpers stay pipeline-agnostic and each producer declares its pipeline once where it builds its reporter.
func NewEnvelopeReporter ¶
NewEnvelopeReporter creates a thread-safe structured-event reporter.
func NewHumanReporter ¶
NewHumanReporter creates an ASCII-safe human reporter.
func NewLogReporter ¶
func NewLogReporter() Reporter
NewLogReporter returns a Reporter that logs each event at debug level.
func NewPlainReporter ¶
NewPlainReporter creates a human-readable status reporter. labels may be nil; in that case the phase name is used as-is.
func NewReporter ¶
func NewReporter(opts ReporterOptions) (Reporter, error)
NewReporter selects a status presentation.
type ReporterOptions ¶
type ReporterOptions struct {
Format string
Out io.Writer
Prefix string
Labels map[Phase]string
Envelope func(Event) error
Interactive bool
Verbose bool
// SuppressFailureDetails leaves failure details to the command boundary.
SuppressFailureDetails bool
}
ReporterOptions configures status presentation.
Source Files