Documentation
¶
Index ¶
- type DoctorIssue
- type DoctorResult
- type Engine
- func (e *Engine) ClearSnapshot(ctx context.Context, ws *workspace.Workspace)
- func (e *Engine) Doctor(ctx context.Context, fix bool) (*DoctorResult, error)
- func (e *Engine) Down(ctx context.Context, ws *workspace.Workspace) error
- func (e *Engine) Logs(ctx context.Context, ws *workspace.Workspace, opts LogsOptions) error
- func (e *Engine) Remove(ctx context.Context, ws *workspace.Workspace) error
- func (e *Engine) Restart(ctx context.Context, ws *workspace.Workspace) (*RestartResult, error)
- func (e *Engine) SetBuildCacheMounts(mounts []string)
- func (e *Engine) SetOutput(stdout, stderr io.Writer)
- func (e *Engine) SetPlugins(m *plugin.Manager)
- func (e *Engine) SetProgress(fn func(string))
- func (e *Engine) SetRuntime(name string)
- func (e *Engine) SetVerbose(v bool)
- func (e *Engine) Status(ctx context.Context, ws *workspace.Workspace) (*StatusResult, error)
- func (e *Engine) Up(ctx context.Context, ws *workspace.Workspace, opts UpOptions) (*UpResult, error)
- type EnvBuilder
- func (b *EnvBuilder) AddPluginEnv(env map[string]string)
- func (b *EnvBuilder) AddPluginPathPrepend(dirs []string)
- func (b *EnvBuilder) AddPluginResponse(resp *plugin.PreContainerRunResponse)
- func (b *EnvBuilder) Build() map[string]string
- func (b *EnvBuilder) RestoreFrom(storedEnv map[string]string)
- func (b *EnvBuilder) SetConfigEnv(env map[string]string)
- func (b *EnvBuilder) SetContainerPATH(path string)
- func (b *EnvBuilder) SetProbed(env map[string]string)
- type LogsOptions
- type RestartResult
- type StatusResult
- type UpOptions
- type UpResult
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
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
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
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
Logs streams container logs for the given workspace. For compose workspaces, shows logs from all services.
func (*Engine) Remove ¶ added in v0.3.0
Remove stops and removes the container, then deletes all workspace state.
func (*Engine) Restart ¶ added in v0.2.0
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
SetBuildCacheMounts configures BuildKit cache mount targets for feature install RUN instructions (e.g. "/var/cache/apt", "/root/.npm").
func (*Engine) SetPlugins ¶ added in v0.4.0
SetPlugins attaches a plugin manager to the engine.
func (*Engine) SetProgress ¶
SetProgress sets a callback for user-facing progress messages.
func (*Engine) SetRuntime ¶ added in v0.4.0
SetRuntime stores the runtime name (e.g. "docker", "podman") for plugin requests.
func (*Engine) SetVerbose ¶ added in v0.3.0
SetVerbose enables verbose output (e.g. compose stdout).
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):
- probed env (filtered via filterProbedEnv skip list)
- container base PATH (append missing dirs)
- plugin Env (overrides probed)
- devcontainer.json remoteEnv (overrides everything for non-PATH keys)
- 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 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