config

type BindOptions ¶

type BindOptions struct {
	Propagation    string
	CreateHostPath bool
}

type BuildSource ¶

type BuildSource struct {
	Dockerfile string
	Context    string
	Args       map[string]string
	Target     string
	CacheFrom  []string
	Options    map[string]string
}

func (*BuildSource) Kind() SourceKind

type Command ¶

type Command struct {
	Shell string
	Exec  []string
}

Command is a single executable invocation in either shell or exec form. Exactly one of Shell / Exec is populated.

func (c Command) IsEmpty() bool

type ComposeSource ¶

type ComposeSource struct {
	Files       []string
	Service     string
	RunServices []string
}

func (*ComposeSource) Kind() SourceKind

type ConfigInvalidError ¶

type ConfigInvalidError struct {
	Path    string
	Message string
}

ConfigInvalidError indicates that a parsed config violates a structural rule that prevents producing a ResolvedConfig (e.g. neither image, build, nor dockerComposeFile is set).

func (e *ConfigInvalidError) Error() string

type ConfigParseError ¶

type ConfigParseError struct {
	Path string
	Err  error
}

ConfigParseError indicates that a devcontainer.json file could not be parsed (JSONC syntax invalid, schema mismatch, etc.).

func (e *ConfigParseError) Error() string

func (e *ConfigParseError) Unwrap() error

type FeatureMetadata ¶

type FeatureMetadata struct {
	ID               string
	Version          string
	Name             string
	Description      string
	DocumentationURL string
	LicenseURL       string

	Options map[string]FeatureOption

	// Mergeable surface (devpod parity). Empty / nil means "unset".
	RemoteUser          string
	ContainerUser       string
	UserEnvProbe        UserEnvProbe
	WaitFor             LifecyclePhase
	ShutdownAction      ShutdownAction
	UpdateRemoteUserUID *bool

	ContainerEnv    map[string]string
	RemoteEnv       map[string]string
	Mounts          []Mount
	Init            *bool
	Privileged      *bool
	OverrideCommand *bool
	CapAdd          []string
	SecurityOpt     []string
	Entrypoint      string

	HostRequirements *HostRequirements

	InstallsAfter []string
	DependsOn     map[string]map[string]any

	OnCreateCommand      LifecycleCommand
	UpdateContentCommand LifecycleCommand
	PostCreateCommand    LifecycleCommand
	PostStartCommand     LifecycleCommand
	PostAttachCommand    LifecycleCommand

	Customizations map[string]json.RawMessage
}

FeatureMetadata is one layer of the devcontainer.metadata chain. It represents either the parsed devcontainer-feature.json contributed by a feature, OR a single entry in the image's devcontainer.metadata label (which may be a base image's prior layer, a feature's contribution, or the resolved-config "final" entry written by a previous build).

Every field is optional; the merge stage (MergeMetadata) treats empty strings, nil pointers, and zero-length slices/maps as "this layer did not contribute a value".

ID/Version/Name/Description/DocumentationURL/LicenseURL/Options/ InstallsAfter/DependsOn are feature-only — they have no merge semantics and are ignored when the layer originates from a label entry.

type FeatureOption ¶

type FeatureOption struct {
	Type        string // "string" | "boolean"
	Default     any
	Enum        []any
	Proposals   []any
	Description string
}

FeatureOption is one option declared by a feature, used to apply defaults and validate user-supplied values.

type FeatureSourceKind ¶

type FeatureSourceKind string

const (
	FeatureSourceOCI   FeatureSourceKind = "oci"
	FeatureSourceHTTPS FeatureSourceKind = "https"
	FeatureSourceLocal FeatureSourceKind = "local"
)

type GPURequirement ¶

type GPURequirement struct {
	Optional bool
}

type HostRequirements ¶

type HostRequirements struct {
	CPUs    int
	Memory  string
	Storage string
	GPU     *GPURequirement
}

HostRequirements is parsed and surfaced; v1 does not enforce.

type ImageSource ¶

type ImageSource struct {
	Image string
}

func (*ImageSource) Kind() SourceKind

type LifecycleCommand ¶

type LifecycleCommand struct {
	Single   *Command
	Parallel map[string]Command
}

LifecycleCommand is one phase's command, in either single or parallel-named form. At most one of Single / Parallel is populated; both empty means the phase is unconfigured and must be skipped.

func DecodeLifecycleCommand(data json.RawMessage) (LifecycleCommand, error)

func (l LifecycleCommand) IsEmpty() bool

type LifecycleCommands ¶

type LifecycleCommands struct {
	Initialize    []LifecycleCommand
	OnCreate      []LifecycleCommand
	UpdateContent []LifecycleCommand
	PostCreate    []LifecycleCommand
	PostStart     []LifecycleCommand
	PostAttach    []LifecycleCommand
}

LifecycleCommands holds the resolved command(s) for each phase. Each phase is a list because the metadata-merge pipeline (base image label → each feature → user devcontainer.json) can contribute hooks that all run in sequence per-phase, per spec.

Initialize is host-side and only ever populated from the user's devcontainer.json today, but is shaped as a slice for symmetry.

type LifecyclePhase ¶

type LifecyclePhase string

LifecyclePhase names the spec lifecycle phases plus initialize.

const (
	LifecycleInitialize    LifecyclePhase = "initialize"
	LifecycleOnCreate      LifecyclePhase = "onCreate"
	LifecycleUpdateContent LifecyclePhase = "updateContent"
	LifecyclePostCreate    LifecyclePhase = "postCreate"
	LifecyclePostStart     LifecyclePhase = "postStart"
	LifecyclePostAttach    LifecyclePhase = "postAttach"
)

type Mount ¶

type Mount struct {
	Type     MountType
	Source   string
	Target   string
	ReadOnly bool

	BindOptions   *BindOptions
	VolumeOptions *VolumeOptions
	TmpfsOptions  *TmpfsOptions
}

Mount is the normalized object form of a mount entry. Spec CSV strings are parsed into this shape during merge.

type MountType ¶

type MountType string

MountType is the docker mount type.

const (
	MountBind   MountType = "bind"
	MountVolume MountType = "volume"
	MountTmpfs  MountType = "tmpfs"
)

type PortAttributes ¶

type PortAttributes struct {
	Label            string
	Protocol         string
	OnAutoForward    string
	ElevateIfNeeded  bool
	RequireLocalPort bool
}

type PortSpec ¶

type PortSpec struct {
	Container int
	Host      int
	Label     string
}

PortSpec describes a forwarded port. Host == 0 means "any free host port".

type ResolveInput ¶

type ResolveInput struct {
	// LocalWorkspaceFolder is the absolute host path containing the project.
	LocalWorkspaceFolder string

	// ConfigPath is the absolute path of the source devcontainer.json.
	// Used as Warning.Source and to resolve relative paths in build/compose.
	ConfigPath string

	// DevcontainerID is the stable workspace id. Callers may use the default
	// scheme via DevcontainerID(local, config) or supply their own.
	DevcontainerID string

	// LocalEnv is the host environment for ${localEnv:*} resolution. Callers
	// typically pass the result of os.Environ() turned into a map.
	LocalEnv map[string]string
}

ResolveInput is the contextual data needed to produce a ResolvedConfig from a parsed devcontainer.json document.

type ResolvedConfig ¶

type ResolvedConfig struct {
	DevcontainerID string

	Source Source

	Name                     string
	LocalWorkspaceFolder     string
	ContainerWorkspaceFolder string
	WorkspaceMount           *Mount

	ContainerUser       string
	RemoteUser          string
	UpdateRemoteUserUID *bool
	UserEnvProbe        UserEnvProbe

	ContainerEnv map[string]string
	RemoteEnv    map[string]string

	Mounts          []Mount
	RunArgs         []string
	Init            *bool
	Privileged      *bool
	CapAdd          []string
	SecurityOpt     []string
	OverrideCommand *bool
	ShutdownAction  ShutdownAction

	Features []ResolvedFeature

	Lifecycle LifecycleCommands
	WaitFor   LifecyclePhase

	// SecretsCommand is a host-side hook that runs before container start
	// (analogous to initializeCommand) and whose stdout is parsed as
	// key=value lines and merged into the container's environment. Unlike
	// the lifecycle phases, it is not contributed by feature/base-image
	// metadata layers — only the user's devcontainer.json sources it —
	// so it is a single LifecycleCommand rather than a slice. Empty
	// when devcontainer.json has no `secretsCommand`.
	SecretsCommand LifecycleCommand

	ForwardPorts         []PortSpec
	PortsAttributes      map[string]PortAttributes
	OtherPortsAttributes *PortAttributes

	HostRequirements *HostRequirements

	Customizations map[string]json.RawMessage

	Warnings []Warning
}

ResolvedConfig is the merged and host-substituted devcontainer configuration produced by Resolve. Treat as read-only after Resolve returns; mutate only via DefensiveCopy.

String fields may still contain unresolved ${containerEnv:*} placeholders; see HasPendingSubstitutions.

func ResolveBytes(src []byte, input ResolveInput) (*ResolvedConfig, error)

func (c *ResolvedConfig) Finalize()

type ResolvedFeature ¶

type ResolvedFeature struct {
	Ref              string
	ResolvedRef      string
	Dir              string
	Metadata         FeatureMetadata
	Options          map[string]any
	SourceKind       FeatureSourceKind
	AlreadyInstalled bool
}

ResolvedFeature is a feature reference plus user-supplied options. It is progressively populated through the pipeline:

• After config.Resolve: Ref, Options (raw user input), SourceKind are populated. ResolvedRef, Dir, Metadata are empty; AlreadyInstalled is false.
• After feature.Order on the partial set: position in the slice reflects overrideFeatureInstallOrder if the user supplied it.
• After Engine.Up reads the base image's devcontainer.metadata label: AlreadyInstalled may flip true; in that case fetch is skipped and Dir/Metadata stay empty.
• After feature.Store.Fetch: Dir, ResolvedRef, Metadata populated.
• After feature.Order on the full set: position reflects the dependsOn / installsAfter DAG.

type ShutdownAction ¶

type ShutdownAction string

ShutdownAction selects how the container is treated when the workspace is closed.

const (
	ShutdownNone          ShutdownAction = "none"
	ShutdownStop          ShutdownAction = "stop"
	ShutdownStopContainer ShutdownAction = "stopContainer"
	ShutdownStopCompose   ShutdownAction = "stopCompose"
)

type Source ¶

type Source interface {
	Kind() SourceKind
	// contains filtered or unexported methods
}

Source identifies where the container comes from. Implementations are sealed: ImageSource, BuildSource, ComposeSource.

type SourceKind ¶

type SourceKind string

const (
	SourceImage   SourceKind = "image"
	SourceBuild   SourceKind = "build"
	SourceCompose SourceKind = "compose"
)

type SubstitutionContext ¶

type SubstitutionContext struct {
	LocalWorkspaceFolder     string
	ContainerWorkspaceFolder string
	DevcontainerID           string
	LocalEnv                 map[string]string
	ContainerEnv             map[string]string
}

SubstitutionContext holds the values used to resolve placeholders in devcontainer.json strings. Fields left empty cause the corresponding variable to be preserved as a literal placeholder.

ContainerEnv is populated only after a container has been created and inspected; nil signals "host pass" and leaves ${containerEnv:*} references literal so the runtime layer can resolve them later.

type TmpfsOptions ¶

type TmpfsOptions struct {
	SizeBytes int64
	Mode      uint32
}

type UserEnvProbe ¶

type UserEnvProbe string

UserEnvProbe selects the shell strategy for capturing the user's interactive environment when computing remoteEnv.

const (
	UserEnvProbeNone             UserEnvProbe = "none"
	UserEnvProbeLoginShell       UserEnvProbe = "loginShell"
	UserEnvProbeInteractiveShell UserEnvProbe = "interactiveShell"
	UserEnvProbeLoginInteractive UserEnvProbe = "loginInteractiveShell"
)

type VolumeDriverConfig ¶

type VolumeDriverConfig struct {
	Name    string
	Options map[string]string
}

type VolumeOptions ¶

type VolumeOptions struct {
	NoCopy       bool
	Labels       map[string]string
	DriverConfig *VolumeDriverConfig
}

type Warning ¶

type Warning struct {
	Code    WarningCode
	Message string
	Path    string
	Source  string
}

Warning is a non-fatal diagnostic accumulated during parse, merge, or substitution. Path is a JSON pointer; Source identifies the contributing document (file path, image label reference, or feature id).

func ResolveString(s string, ctx SubstitutionContext) (string, []Warning)

type WarningCode ¶

type WarningCode string

WarningCode classifies a non-fatal diagnostic.

const (
	WarnUnknownField            WarningCode = "unknown_field"
	WarnDeprecatedKey           WarningCode = "deprecated_key"
	WarnUnsupportedFeatureField WarningCode = "unsupported_feature_field"
	WarnUnresolvedLocalEnv      WarningCode = "unresolved_local_env"
	WarnUnresolvedContainerEnv  WarningCode = "unresolved_container_env"
	WarnUnknownVariable         WarningCode = "unknown_variable"
	WarnDeepFeatureChain        WarningCode = "deep_feature_chain"
	WarnUnknownFeatureOption    WarningCode = "unknown_feature_option"
	WarnComposePortsIgnored     WarningCode = "compose_ports_ignored"
	WarnUIDReconcileSkipped     WarningCode = "uid_reconcile_skipped"
)