Documentation
¶
Overview ¶
Package events defines the structured event surface emitted by Engine operations (Up / Down / Exec / RunLifecycle) and feature/build/runtime activity reached through them.
EXPERIMENTAL: This package is doc-tagged experimental until v1.0.0. Field names, event types, and emission cadence may change without a SemVer-major bump while the library is below v1. Callers should write dispatch code defensively (type switch with default branch) and not rely on Seq gaps being absent across versions.
Usage:
ch := make(chan events.Event, 64)
go func() {
for ev := range ch {
switch e := ev.(type) {
case events.ConfigResolvedEvent:
// ...
case events.LifecycleCompletedEvent:
// ...
}
}
}()
ws, err := eng.Up(ctx, devcontainer.UpOptions{Events: ch, ...})
All events carry a monotonic Seq (allocated per Engine) and a Time stamped at emission. The channel is non-blocking from the engine's perspective — events are dropped on a full channel rather than stalling work.
Channel ownership: the caller owns the channel; the engine only writes to it and never closes it. The caller MUST NOT close the channel before the operation (Up / Down / Exec) it was passed to returns — doing so races with the engine's send and will panic. The safe pattern is to close after the call returns, or simply leave the channel open and let it be garbage-collected.
Index ¶
- Constants
- func Send(ch chan<- Event, ev Event) bool
- type Base
- type BuildCompletedEvent
- type BuildLayerEvent
- type BuildLogEvent
- type BuildSource
- type BuildStartEvent
- type ConfigResolvedEvent
- type ConfigWarningEvent
- type ContainerCreatedEvent
- type ContainerCreatingEvent
- type ContainerRemovedEvent
- type ContainerStartedEvent
- type ContainerStoppedEvent
- type Emitter
- type Event
- type ExecCompletedEvent
- type ExecStartEvent
- type FeatureResolveStartEvent
- type FeatureResolvedEvent
- type FeatureSkippedEvent
- type LifecycleCompletedEvent
- type LifecycleOutputEvent
- type LifecycleSkippedEvent
- type LifecycleStartEvent
- type WarnEvent
Constants ¶
const ( TypeBuildStart = "build.start" TypeBuildLog = "build.log" TypeBuildLayer = "build.layer" TypeBuildCompleted = "build.completed" )
const ( TypeConfigResolved = "config.resolved" TypeConfigWarning = "config.warning" )
const ( TypeContainerCreating = "container.creating" TypeContainerCreated = "container.created" TypeContainerStarted = "container.started" TypeContainerStopped = "container.stopped" TypeContainerRemoved = "container.removed" )
const ( TypeExecStart = "exec.start" TypeExecCompleted = "exec.completed" )
const ( TypeFeatureResolveStart = "feature.resolve_start" TypeFeatureResolved = "feature.resolved" TypeFeatureSkipped = "feature.skipped" )
const ( TypeLifecycleStart = "lifecycle.start" TypeLifecycleOutput = "lifecycle.output" TypeLifecycleSkipped = "lifecycle.skipped" TypeLifecycleCompleted = "lifecycle.completed" )
const TypeWarn = "engine.warn"
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Base ¶
type Base struct {
// contains filtered or unexported fields
}
Base carries the fields common to every event. Embed it in each concrete event type.
type BuildCompletedEvent ¶
type BuildCompletedEvent struct {
Base
Source BuildSource
ImageID string
DurationMs int64
}
BuildCompletedEvent fires when the build/pull completes successfully.
func (BuildCompletedEvent) EventType ¶
func (BuildCompletedEvent) EventType() string
type BuildLayerEvent ¶
type BuildLayerEvent struct {
Base
Source BuildSource
LayerID string
Status string
}
BuildLayerEvent carries per-layer pull/build progress. Status values: "pulling", "extracting", "cached", "done".
func (BuildLayerEvent) EventType ¶
func (BuildLayerEvent) EventType() string
type BuildLogEvent ¶
type BuildLogEvent struct {
Base
Source BuildSource
Stream string
Line string
}
BuildLogEvent carries a raw line of build/pull output. Stream is "stdout" or "stderr"; the docker build stream does not always distinguish, in which case Stream is "stdout".
func (BuildLogEvent) EventType ¶
func (BuildLogEvent) EventType() string
type BuildSource ¶
type BuildSource string
BuildSource identifies where the build originated.
const ( BuildSourceImage BuildSource = "image" BuildSourceDockerfile BuildSource = "dockerfile" BuildSourceCompose BuildSource = "compose" BuildSourceFeatures BuildSource = "features" BuildSourceUIDReconcile BuildSource = "uid_reconcile" )
type BuildStartEvent ¶
type BuildStartEvent struct {
Base
Source BuildSource
Ref string // image ref being pulled, or build target tag
}
BuildStartEvent fires once at the top of a build/pull operation.
func (BuildStartEvent) EventType ¶
func (BuildStartEvent) EventType() string
type ConfigResolvedEvent ¶
type ConfigResolvedEvent struct {
Base
Config *config.ResolvedConfig
}
ConfigResolvedEvent fires once per Engine.Up after Resolve returns, before any image work. Config is the same pointer the caller would observe via Workspace.Config later — consumers must treat it as read-only.
func (ConfigResolvedEvent) EventType ¶
func (ConfigResolvedEvent) EventType() string
type ConfigWarningEvent ¶
ConfigWarningEvent fires once per entry in cfg.Warnings (unknown field, deprecated key, substitution miss, etc.).
func (ConfigWarningEvent) EventType ¶
func (ConfigWarningEvent) EventType() string
type ContainerCreatedEvent ¶
ContainerCreatedEvent fires after CreateContainer succeeds.
func (ContainerCreatedEvent) EventType ¶
func (ContainerCreatedEvent) EventType() string
type ContainerCreatingEvent ¶
ContainerCreatingEvent fires immediately before a CreateContainer call. Name is the resolved container name, or empty for compose-managed containers (compose generates the name itself).
func (ContainerCreatingEvent) EventType ¶
func (ContainerCreatingEvent) EventType() string
type ContainerRemovedEvent ¶
ContainerRemovedEvent fires after RemoveContainer succeeds.
func (ContainerRemovedEvent) EventType ¶
func (ContainerRemovedEvent) EventType() string
type ContainerStartedEvent ¶
ContainerStartedEvent fires after StartContainer succeeds.
func (ContainerStartedEvent) EventType ¶
func (ContainerStartedEvent) EventType() string
type ContainerStoppedEvent ¶
ContainerStoppedEvent fires after StopContainer returns. ExitCode is the container's exit code if known; -1 if not retrieved.
func (ContainerStoppedEvent) EventType ¶
func (ContainerStoppedEvent) EventType() string
type Emitter ¶
type Emitter struct {
// contains filtered or unexported fields
}
Emitter allocates monotonic sequence numbers and stamps Base. One Emitter per Engine; safe for concurrent use.
func NewEmitter ¶
NewEmitter returns an Emitter with the given clock (nil = time.Now).
type Event ¶
Event is the marker interface for every event type. All concrete events embed Base so they inherit Seq() and Time() for free; they implement EventType() with a string constant.
type ExecCompletedEvent ¶
ExecCompletedEvent fires when an Engine.Exec returns. Opt-in via ExecOptions.EmitEvents.
func (ExecCompletedEvent) EventType ¶
func (ExecCompletedEvent) EventType() string
type ExecStartEvent ¶
ExecStartEvent fires when an Engine.Exec begins. Opt-in via ExecOptions.EmitEvents: hot-loop readiness probes can run hundreds of execs per minute and would otherwise drown the events channel.
func (ExecStartEvent) EventType ¶
func (ExecStartEvent) EventType() string
type FeatureResolveStartEvent ¶
FeatureResolveStartEvent fires immediately before a feature is fetched (OCI pull, HTTPS download, or local read).
func (FeatureResolveStartEvent) EventType ¶
func (FeatureResolveStartEvent) EventType() string
type FeatureResolvedEvent ¶
FeatureResolvedEvent fires after a feature is fetched (or cache hit). Digest is the content-addressed identifier (sha256 for OCI/HTTPS, empty for local paths). FromCache is true when no network/disk read was needed beyond the cache lookup.
func (FeatureResolvedEvent) EventType ¶
func (FeatureResolvedEvent) EventType() string
type FeatureSkippedEvent ¶
FeatureSkippedEvent fires when a requested feature is already present in the base image's devcontainer.metadata label and is therefore not re-installed. Reason is a short tag, e.g. "already_installed".
func (FeatureSkippedEvent) EventType ¶
func (FeatureSkippedEvent) EventType() string
type LifecycleCompletedEvent ¶
LifecycleCompletedEvent fires when a phase finishes. ExitCode is the process exit; 0 on success.
func (LifecycleCompletedEvent) EventType ¶
func (LifecycleCompletedEvent) EventType() string
type LifecycleOutputEvent ¶
type LifecycleOutputEvent struct {
Base
Phase string
Stream string // "stdout" or "stderr"
Line string
}
LifecycleOutputEvent carries one line of a lifecycle command's stdout or stderr. Emitted as the command runs.
func (LifecycleOutputEvent) EventType ¶
func (LifecycleOutputEvent) EventType() string
type LifecycleSkippedEvent ¶
LifecycleSkippedEvent fires when a phase is skipped because its idempotency marker is already present. Reason is a short tag like "marker_present".
func (LifecycleSkippedEvent) EventType ¶
func (LifecycleSkippedEvent) EventType() string
type LifecycleStartEvent ¶
LifecycleStartEvent fires when a phase begins executing in the container. Phase is one of: "initialize", "onCreate", "updateContent", "postCreate", "postStart", "postAttach". Command is the resolved shell or argv string for display (may be the joined parallel form).
func (LifecycleStartEvent) EventType ¶
func (LifecycleStartEvent) EventType() string