engine

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DoctorIssue added in v0.5.0 

type DoctorIssue struct {
	Level       string // "error" or "warning"
	Check       string // short name of the check
	Description string // human-readable description
	Fix         string // description of the fix action
	WorkspaceID string // workspace ID if applicable
}

DoctorIssue describes a single problem found by Doctor.

type DoctorResult added in v0.5.0 

type DoctorResult struct {
	Issues    []DoctorIssue
	RuntimeOK bool
	ComposeOK bool
}

DoctorResult holds the outcome of a Doctor check.

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine orchestrates devcontainer lifecycle operations.

func New 

func New(d driver.Driver, composeHelper *compose.Helper, store *workspace.Store, logger *slog.Logger) *Engine

New creates an Engine with the given dependencies.

func (*Engine) ClearSnapshot added in v0.5.0 

func (e *Engine) ClearSnapshot(ctx context.Context, ws *workspace.Workspace)

ClearSnapshot removes the snapshot image and clears the metadata. Exported so the cmd layer can call it before rebuild.

func (*Engine) Doctor added in v0.5.0 

func (e *Engine) Doctor(ctx context.Context, fix bool) (*DoctorResult, error)

Doctor runs health checks on the crib installation and workspaces. If fix is true, it attempts to automatically resolve found issues.

func (*Engine) Down added in v0.3.0 

func (e *Engine) Down(ctx context.Context, ws *workspace.Workspace) error

Down stops and removes the container for the given workspace, but keeps workspace state in the store so that a subsequent "up" can recreate it. Hook markers are cleared so the next "up" runs all lifecycle hooks.

func (*Engine) Logs added in v0.5.0 

func (e *Engine) Logs(ctx context.Context, ws *workspace.Workspace, opts LogsOptions) error

Logs streams container logs for the given workspace. For compose workspaces, shows logs from all services.

func (*Engine) PreviewRemove added in v0.7.0 

func (e *Engine) PreviewRemove(ctx context.Context, ws *workspace.Workspace) *RemovePreview

PreviewRemove returns what Remove() would delete without actually removing anything.

func (*Engine) PruneImages added in v0.7.0 

func (e *Engine) PruneImages(ctx context.Context, opts PruneOptions) (*PruneResult, error)

PruneImages removes stale and orphan crib-managed images.

func (*Engine) Remove added in v0.3.0 

func (e *Engine) Remove(ctx context.Context, ws *workspace.Workspace) error

Remove stops and removes the container, then deletes all workspace state.

func (*Engine) RequireRunningContainer added in v0.8.0 

func (e *Engine) RequireRunningContainer(ctx context.Context, ws *workspace.Workspace) (*driver.ContainerDetails, error)

RequireRunningContainer finds the container for the workspace and returns it if it is running. Returns ErrNoContainer if no container exists, or ErrContainerStopped if the container exists but is not running.

func (*Engine) Restart added in v0.2.0 

func (e *Engine) Restart(ctx context.Context, ws *workspace.Workspace) (*RestartResult, error)

Restart restarts the container for the given workspace. It implements a "warm recreate" strategy:

  • If the devcontainer config hasn't changed, it does a simple container restart and runs only the resume-flow lifecycle hooks (postStartCommand, postAttachCommand).
  • If only "safe" properties changed (volumes, mounts, ports, env, runArgs), it recreates the container without rebuilding the image and runs the resume flow.
  • If image-affecting properties changed (image, Dockerfile, features, build args), it returns an error suggesting `crib rebuild`.

func (*Engine) SetBuildCacheMounts added in v0.5.0 

func (e *Engine) SetBuildCacheMounts(mounts []string)

SetBuildCacheMounts configures BuildKit cache mount targets for feature install RUN instructions (e.g. "/var/cache/apt", "/root/.npm").

func (*Engine) SetOutput 

func (e *Engine) SetOutput(stdout, stderr io.Writer)

SetOutput overrides the default stdout and stderr writers.

func (*Engine) SetPlugins added in v0.4.0 

func (e *Engine) SetPlugins(m *plugin.Manager)

SetPlugins attaches a plugin manager to the engine.

func (*Engine) SetProgress 

func (e *Engine) SetProgress(fn func(ProgressEvent))

SetProgress sets a callback for user-facing progress events.

func (*Engine) SetRuntime added in v0.4.0 

func (e *Engine) SetRuntime(name string)

SetRuntime stores the runtime name (e.g. "docker", "podman") for plugin requests.

func (*Engine) SetVerbose added in v0.3.0 

func (e *Engine) SetVerbose(v bool)

SetVerbose enables verbose output (e.g. compose stdout).

func (*Engine) Status 

func (e *Engine) Status(ctx context.Context, ws *workspace.Workspace) (*StatusResult, error)

func (*Engine) Stop 

func (e *Engine) Stop(ctx context.Context, ws *workspace.Workspace) error

Stop stops the container for the given workspace without removing it. Hook markers are preserved so that a subsequent "up" runs only resume-flow hooks (postStartCommand, postAttachCommand).

func (*Engine) Up 

func (e *Engine) Up(ctx context.Context, ws *workspace.Workspace, opts UpOptions) (*UpResult, error)

Up brings a devcontainer up for the given workspace.

type EnvBuilder added in v0.6.0 

type EnvBuilder struct {
	// contains filtered or unexported fields
}

EnvBuilder accumulates environment variables from multiple sources, each with defined precedence. Layers are merged bottom-up: higher layers override lower layers for the same key.

func NewEnvBuilder added in v0.6.0 

func NewEnvBuilder(configRemoteEnv map[string]string) *EnvBuilder

NewEnvBuilder creates a builder seeded with the devcontainer.json remoteEnv. The caller must not mutate configRemoteEnv after this call; use SetConfigEnv to replace the layer with a fresh copy when it changes (e.g. after resolveRemoteEnv resolves ${containerEnv:VAR} references).

func (*EnvBuilder) AddPluginEnv added in v0.6.0 

func (b *EnvBuilder) AddPluginEnv(env map[string]string)

AddPluginEnv merges plugin Env vars into the plugin layer.

func (*EnvBuilder) AddPluginPathPrepend added in v0.6.0 

func (b *EnvBuilder) AddPluginPathPrepend(dirs []string)

AddPluginPathPrepend appends plugin PathPrepend dirs.

func (*EnvBuilder) AddPluginResponse added in v0.6.0 

func (b *EnvBuilder) AddPluginResponse(resp *plugin.PreContainerRunResponse)

AddPluginResponse merges a plugin response's Env and PathPrepend into the builder. Safe to call with nil.

func (*EnvBuilder) Build added in v0.6.0 

func (b *EnvBuilder) Build() map[string]string

Build merges all layers and returns the final env map. Precedence (lowest to highest):

  1. probed env (filtered via filterProbedEnv skip list)
  2. container base PATH (append missing dirs)
  3. plugin Env (overrides probed)
  4. devcontainer.json remoteEnv (overrides everything for non-PATH keys)
  5. plugin PathPrepend (prepended to PATH)

func (*EnvBuilder) RestoreFrom added in v0.6.0 

func (b *EnvBuilder) RestoreFrom(storedEnv map[string]string)

RestoreFrom loads a previously saved env as the probed layer. Used by restart paths that skip setupContainer. The stored env is the output of a previous Build() (all layers merged, already filtered), so re-filtering in Build() is a no-op for skip-list vars but harmless.

func (*EnvBuilder) SetConfigEnv added in v0.6.0 

func (b *EnvBuilder) SetConfigEnv(env map[string]string)

SetConfigEnv updates the configEnv layer. Called after resolveRemoteEnv resolves ${containerEnv:VAR} references.

func (*EnvBuilder) SetContainerPATH added in v0.6.0 

func (b *EnvBuilder) SetContainerPATH(path string)

SetContainerPATH records the container's base PATH for preservation.

func (*EnvBuilder) SetProbed added in v0.6.0 

func (b *EnvBuilder) SetProbed(env map[string]string)

SetProbed sets the probed environment (from userEnvProbe). Replaces any previously set probed env. The builder takes ownership of env; the caller must not mutate it afterward.

type ErrComposeNotAvailable added in v0.8.0 

type ErrComposeNotAvailable struct{}

ErrComposeNotAvailable is returned when an operation requires docker compose or podman compose but neither is installed.

func (*ErrComposeNotAvailable) Error added in v0.8.0 

func (e *ErrComposeNotAvailable) Error() string

type ErrContainerStopped added in v0.8.0 

type ErrContainerStopped struct {
	WorkspaceID string
	ContainerID string
}

ErrContainerStopped is returned when a workspace operation requires a running container but the container exists in a stopped state.

func (*ErrContainerStopped) Error added in v0.8.0 

func (e *ErrContainerStopped) Error() string

type ErrNoContainer added in v0.8.0 

type ErrNoContainer struct {
	WorkspaceID string
}

ErrNoContainer is returned when a workspace operation requires a container but none exists.

func (*ErrNoContainer) Error added in v0.8.0 

func (e *ErrNoContainer) Error() string

type LogsOptions added in v0.5.0 

type LogsOptions struct {
	Follow bool   // stream logs as they are produced
	Tail   string // number of lines from the end ("all" or a number)
}

LogsOptions controls the behavior of the Logs operation.

type ProgressEvent added in v0.8.0 

type ProgressEvent struct {
	Phase   ProgressPhase
	Message string
}

ProgressEvent carries a structured progress update from the engine.

type ProgressPhase added in v0.8.0 

type ProgressPhase string

ProgressPhase identifies a stage of the devcontainer lifecycle. 

const (
	PhaseInit    ProgressPhase = "init"
	PhaseBuild   ProgressPhase = "build"
	PhaseCreate  ProgressPhase = "create"
	PhasePlugins ProgressPhase = "plugins"
	PhaseHooks   ProgressPhase = "hooks"
	PhaseRestart ProgressPhase = "restart"
)

type PruneError added in v0.7.0 

type PruneError struct {
	Reference string
	Err       error
}

PruneError records a failed image removal.

type PruneOptions added in v0.7.0 

type PruneOptions struct {
	WorkspaceID string // empty = all workspaces
	DryRun      bool
}

PruneOptions controls which images PruneImages removes.

type PruneResult added in v0.7.0 

type PruneResult struct {
	Removed []PrunedImage
	Errors  []PruneError
}

PruneResult holds the outcome of a prune operation.

type PrunedImage added in v0.7.0 

type PrunedImage struct {
	Reference   string
	ID          string
	Size        int64
	WorkspaceID string
	Orphan      bool
}

PrunedImage describes an image that was (or would be) removed.

type RemovePreview added in v0.7.0 

type RemovePreview struct {
	ContainerID string   // empty if no container found
	Images      []string // image references that will be removed
}

RemovePreview describes what Remove() will delete.

type RestartResult added in v0.2.0 

type RestartResult struct {
	// ContainerID is the container ID.
	ContainerID string

	// WorkspaceFolder is the path inside the container where the project is mounted.
	WorkspaceFolder string

	// RemoteUser is the user to run commands as inside the container.
	RemoteUser string

	// Recreated indicates whether the container was recreated (config changed)
	// rather than simply restarted.
	Recreated bool

	// Ports lists the published port bindings.
	Ports []driver.PortBinding
}

RestartResult holds the outcome of a Restart operation.

type StatusResult added in v0.3.0 

type StatusResult struct {
	// Container is the primary container details (nil if not found).
	Container *driver.ContainerDetails

	// Services holds the status of compose services (nil for non-compose workspaces).
	Services []compose.ServiceStatus
}

Status returns the current container details for a workspace, or nil if not found. StatusResult holds the outcome of a Status query.

type UpOptions 

type UpOptions struct {
	// Recreate forces container recreation even if one already exists.
	Recreate bool
}

UpOptions controls the behavior of the Up operation.

type UpResult 

type UpResult struct {
	// ContainerID is the container ID.
	ContainerID string

	// ImageName is the name of the built image (for compose feature images).
	ImageName string

	// WorkspaceFolder is the path inside the container where the project is mounted.
	WorkspaceFolder string

	// RemoteUser is the user to run commands as inside the container.
	RemoteUser string

	// Ports lists the published port bindings.
	Ports []driver.PortBinding

	// HasFeatureEntrypoints is true when the image has feature-declared
	// entrypoints baked in. Persisted to result.json for restart paths.
	HasFeatureEntrypoints bool
}

UpResult holds the outcome of a successful Up operation.

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.