Documentation
¶
Overview ¶
Package lifecycle plans the post-build / post-start commands a devcontainer expects to run, in the order required by the spec, with the marker-file scheme that the upstream devcontainer CLI uses.
The package is pure: it does not exec anything itself. Instead, Plan returns a slice of Phase records, and a host-specific package (e.g. pkg/host/docker) decides how to execute each phase against the container at runtime — running it imperatively for docker, projecting it into Pod fields for kubernetes.
Compatibility is intentional. Marker file names, marker contents, command-form semantics (string→shell, array→exec, object→parallel), and run-once vs run-on-start vs run-on-attach mirror upstream's src/spec-common/injectHeadless.ts.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SystemVarFolder ¶
SystemVarFolder is the system-wide devcontainer state folder used for marker files that need root (e.g. patching /etc/environment). Defaults to "/var/devcontainer" per upstream.
func UserDataFolder ¶
UserDataFolder returns the per-user devcontainer state folder inside the container. The default is "${homeDir}/.devcontainer", overridable by passing a non-empty containerDataFolder, mirroring upstream's containerDataFolder option.
Types ¶
type Hook ¶
type Hook string
Hook names mirror the spec's command field names so log output and marker filenames stay legible / compatible.
type Origin ¶
type Origin struct {
// Source is "devcontainer.json" for top-level commands, or the
// feature's source ref (e.g. "ghcr.io/devcontainers/features/node:1")
// for feature-supplied commands.
Source string
}
Origin records where a command came from, so executors can label log output the way upstream does ("Running postCreateCommand from devcontainer.json..." vs "...from Feature 'ghcr.io/.../node:1'...").
type Phase ¶
Phase is one logical run of a single command (or set of parallel named commands) for a particular hook.
func Plan ¶
func Plan(dc *spec.DevContainer, resolved []features.Resolved) []Phase
Plan returns the ordered phases that should run for the given spec and resolved features, with the standard execution order:
onCreate (features…) → onCreate (spec) updateContent (features…) → updateContent (spec) postCreate (features…) → postCreate (spec) postStart (features…) → postStart (spec) postAttach (features…) → postAttach (spec)
Within each hook, each feature's command runs in install order, then the spec's own command, matching upstream's metadata order (features before devcontainer.json). Phases whose command is empty are omitted, so callers can simply iterate the returned slice.
func (Phase) MarkerPath ¶
MarkerPath returns the path inside the container that the executor should use to record successful completion. WhenAttach phases have no marker; the empty string is returned in that case.
userDataFolder is the user's devcontainer data folder; pass UserDataFolder(homeDir, "") to use the default.
type When ¶
type When int
When describes how often a Phase runs across container lifetimes.
const ( // WhenOnce runs at most once per container creation. Marker file's // content is the container's createdAt; if the marker is missing or // stale, the phase runs and the marker is updated. WhenOnce When = iota // WhenStart runs once per container start, including initial // creation. Marker content is startedAt. WhenStart // WhenAttach runs every time a client attaches. No marker — // upstream re-runs unconditionally on every attach. WhenAttach )
Source Files