engine

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Mar 10, 2026 License: MIT Imports: 27 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) 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(string))

SetProgress sets a callback for user-facing progress messages.

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) 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 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 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.