events

package
v0.1.3 Latest Latest
Warning

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

Go to latest
Published: May 13, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

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

View Source
const (
	TypeBuildStart     = "build.start"
	TypeBuildLog       = "build.log"
	TypeBuildLayer     = "build.layer"
	TypeBuildCompleted = "build.completed"
)
View Source
const (
	TypeConfigResolved = "config.resolved"
	TypeConfigWarning  = "config.warning"
)
View Source
const (
	TypeContainerCreating = "container.creating"
	TypeContainerCreated  = "container.created"
	TypeContainerStarted  = "container.started"
	TypeContainerStopped  = "container.stopped"
	TypeContainerRemoved  = "container.removed"
)
View Source
const (
	TypeExecStart     = "exec.start"
	TypeExecCompleted = "exec.completed"
)
View Source
const (
	TypeFeatureResolveStart = "feature.resolve_start"
	TypeFeatureResolved     = "feature.resolved"
	TypeFeatureSkipped      = "feature.skipped"
)
View Source
const (
	TypeLifecycleStart     = "lifecycle.start"
	TypeLifecycleOutput    = "lifecycle.output"
	TypeLifecycleSkipped   = "lifecycle.skipped"
	TypeLifecycleCompleted = "lifecycle.completed"
)
View Source
const TypeWarn = "engine.warn"

Variables

This section is empty.

Functions

func Send

func Send(ch chan<- Event, ev Event) bool

Send writes ev to ch if non-nil and not full. Never blocks. Returns true iff the event was accepted.

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.

func (Base) Seq

func (b Base) Seq() uint64

func (Base) Time

func (b Base) Time() time.Time

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

type ConfigWarningEvent struct {
	Base
	Code    string
	Message string
}

ConfigWarningEvent fires once per entry in cfg.Warnings (unknown field, deprecated key, substitution miss, etc.).

func (ConfigWarningEvent) EventType

func (ConfigWarningEvent) EventType() string

type ContainerCreatedEvent

type ContainerCreatedEvent struct {
	Base
	ContainerID string
	Name        string
}

ContainerCreatedEvent fires after CreateContainer succeeds.

func (ContainerCreatedEvent) EventType

func (ContainerCreatedEvent) EventType() string

type ContainerCreatingEvent

type ContainerCreatingEvent struct {
	Base
	Name string
}

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

type ContainerRemovedEvent struct {
	Base
	ContainerID string
}

ContainerRemovedEvent fires after RemoveContainer succeeds.

func (ContainerRemovedEvent) EventType

func (ContainerRemovedEvent) EventType() string

type ContainerStartedEvent

type ContainerStartedEvent struct {
	Base
	ContainerID string
	StartedAt   time.Time
}

ContainerStartedEvent fires after StartContainer succeeds.

func (ContainerStartedEvent) EventType

func (ContainerStartedEvent) EventType() string

type ContainerStoppedEvent

type ContainerStoppedEvent struct {
	Base
	ContainerID string
	ExitCode    int
}

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

func NewEmitter(now func() time.Time) *Emitter

NewEmitter returns an Emitter with the given clock (nil = time.Now).

func (*Emitter) Stamp

func (e *Emitter) Stamp() Base

Stamp returns a Base with a fresh Seq and current Time.

type Event

type Event interface {
	EventType() string
	Seq() uint64
	Time() time.Time
}

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

type ExecCompletedEvent struct {
	Base
	ContainerID string
	ExitCode    int
	DurationMs  int64
}

ExecCompletedEvent fires when an Engine.Exec returns. Opt-in via ExecOptions.EmitEvents.

func (ExecCompletedEvent) EventType

func (ExecCompletedEvent) EventType() string

type ExecStartEvent

type ExecStartEvent struct {
	Base
	ContainerID string
	Cmd         []string
}

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

type FeatureResolveStartEvent struct {
	Base
	Ref string
}

FeatureResolveStartEvent fires immediately before a feature is fetched (OCI pull, HTTPS download, or local read).

func (FeatureResolveStartEvent) EventType

func (FeatureResolveStartEvent) EventType() string

type FeatureResolvedEvent

type FeatureResolvedEvent struct {
	Base
	Ref       string
	Digest    string
	FromCache bool
}

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

type FeatureSkippedEvent struct {
	Base
	Ref    string
	Reason string
}

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

type LifecycleCompletedEvent struct {
	Base
	Phase      string
	ExitCode   int
	DurationMs int64
}

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

type LifecycleSkippedEvent struct {
	Base
	Phase  string
	Reason string
}

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

type LifecycleStartEvent struct {
	Base
	Phase   string
	Command string
}

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

type WarnEvent

type WarnEvent struct {
	Base
	Code    string
	Message string
}

WarnEvent is the catch-all surface for engine-level diagnostics that don't fit a more specific event. Code is a short stable tag (e.g. "compose_ports_ignored"); Message is human-readable detail.

func (WarnEvent) EventType

func (WarnEvent) EventType() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL