status

package
v1.20.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2026 License: MPL-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package status defines the structured progress events emitted by long-running commands.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Enter 

func Enter(r Reporter, phase Phase, step string)

func Fail 

func Fail(r Reporter, phase Phase, err error)

func Leave 

func Leave(r Reporter, phase Phase, step string)

func OperationID added in v1.20.0 

func OperationID(ctx context.Context) string

OperationID returns the current operation ID, if any.

func ParentOperationID added in v1.20.0 

func ParentOperationID(ctx context.Context) string

ParentOperationID returns the current operation ID, if any.

func Run added in v1.20.0 

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 RunStep added in v1.20.0 

func RunStep(ctx context.Context, phase Phase, step string, fn func(context.Context) error) error

RunStep reports a named child step when a caller supplied a reporter.

func Skip added in v1.20.0 

func Skip(r Reporter, phase Phase, step string)

Skip reports a phase that was intentionally not executed.

func ValidState added in v1.20.0 

func ValidState(s State) bool

ValidState reports whether s is part of the current status protocol.

func WithReporter added in v1.20.0 

func WithReporter(ctx context.Context, reporter Reporter) context.Context

WithReporter attaches a progress reporter to a workspace operation context.

Types

type EnvelopeReporter added in v1.20.0 

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 added in v1.20.0 

func (r *EnvelopeReporter) Report(e Event)

type ErrorInfo added in v1.20.0 

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.

func ErrorFrom added in v1.20.0 

func ErrorFrom(err error) *ErrorInfo

ErrorFrom converts an implementation error into the stable status error shape without exposing its wrapped Go error chain in the protocol.

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 added in v1.20.0 

type HumanReporter struct {
	PlainReporter
}

HumanReporter is the interactive human presentation.

type MemoryReporter added in v1.20.0 

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 added in v1.20.0 

func NewMemoryReporter() *MemoryReporter

NewMemoryReporter returns an empty concurrent event collector.

func (*MemoryReporter) Events added in v1.20.0 

func (r *MemoryReporter) Events() []Event

Events returns a snapshot that callers may safely modify.

func (*MemoryReporter) Report added in v1.20.0 

func (r *MemoryReporter) Report(e Event)

type Operation added in v1.20.0 

type Operation struct {
	Pipeline Pipeline
	Phase    Phase
	Step     string
}

Operation identifies a scoped status operation.

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"
	PhasePreparingDevContainer Phase = "preparing_devcontainer"
	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"
	PhaseImportingWorkspace    Phase = "importing_workspace"
	PhaseReady                 Phase = "ready"
	PhaseFailed                Phase = "failed"
)

Workspace up phases. 

const (
	PhaseInstallingProvider Phase = "installing_provider"
	PhaseResolvingOptions   Phase = "resolving_options"
	PhaseRunningInit        Phase = "running_init"
)

Provider phases.

type Pipeline 

type Pipeline string

Pipeline identifies which command's progress an Event describes. 

const (
	PipelineWorkspaceUp Pipeline = "workspace_up"
	PipelineProvider    Pipeline = "provider"
)

type PlainReporter added in v1.20.0 

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 added in v1.20.0 

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 

func ForPipeline(r Reporter, pipeline Pipeline) Reporter

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 added in v1.20.0 

func NewEnvelopeReporter(write func(Event) error) Reporter

NewEnvelopeReporter creates a thread-safe structured-event reporter.

func NewHumanReporter added in v1.20.0 

func NewHumanReporter(out io.Writer, prefix string, labels map[Phase]string) Reporter

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 added in v1.20.0 

func NewPlainReporter(out io.Writer, prefix string, labels map[Phase]string) Reporter

NewPlainReporter creates a human-readable status reporter. labels may be nil; in that case the phase name is used as-is.

func NewReporter added in v1.20.0 

func NewReporter(opts ReporterOptions) (Reporter, error)

NewReporter selects a status presentation.

func Nop 

func Nop() Reporter

func Tee 

func Tee(reporters ...Reporter) Reporter

Tee forwards every event to each reporter.

type ReporterOptions added in v1.20.0 

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.

type State added in v1.20.0 

type State string

State describes the lifecycle transition represented by an Event. 

const (
	StateStarted   State = "started"
	StateSucceeded State = "succeeded"
	StateFailed    State = "failed"
	StateSkipped   State = "skipped"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.