Documentation
¶
Overview ¶
relationships:
references: [metadata, lifecycle]
Package metadata reads and writes the devcontainer.metadata image label and merges its ordered entries using the upstream devcontainers CLI rules.
relationships:
references: [merge]
relationships:
references: [metadata]
Index ¶
- Constants
- func DockerfileLabel(entries []Entry) (string, error)
- func Encode(entries []Entry) (string, error)
- func Plan(entries []Entry) []lifecycle.Phase
- type CollectOptions
- type Entry
- func Collect(base []Entry, resolved []features.Resolved, dc *spec.DevContainer) []Entry
- func CollectWithOptions(base []Entry, resolved []features.Resolved, dc *spec.DevContainer, ...) []Entry
- func FromConfig(dc *spec.DevContainer) Entry
- func Parse(value string) ([]Entry, error)
- func Read(labels map[string]string, logf func(string, ...any)) []Entry
- func Substitute(entries []Entry, replace func(string) string) ([]Entry, error)
- func Update(entries []Entry, dc *spec.DevContainer) []Entry
- type Merged
Constants ¶
const Label = "devcontainer.metadata"
Label is the interoperable image and container label name.
Variables ¶
This section is empty.
Functions ¶
func DockerfileLabel ¶
DockerfileLabel escapes a label value for a double-quoted Dockerfile LABEL. Empty metadata adds no instruction, preserving the base image labels.
Types ¶
type CollectOptions ¶
type CollectOptions struct {
// SkipFeatureCustomizations omits only newly referenced feature customizations.
SkipFeatureCustomizations bool
// OmitConfigRemoteEnv omits only the current config's remoteEnv contribution.
OmitConfigRemoteEnv bool
}
CollectOptions controls newly persisted contributions, preserving inherited entries.
type Entry ¶
type Entry struct {
ID string `json:"id,omitempty"`
Init *bool `json:"init,omitempty"`
Privileged *bool `json:"privileged,omitempty"`
CapAdd []string `json:"capAdd,omitempty"`
SecurityOpt []string `json:"securityOpt,omitempty"`
Entrypoint string `json:"entrypoint,omitempty"`
Mounts []any `json:"mounts,omitempty"`
Customizations map[string]any `json:"customizations,omitempty"`
OnCreate spec.Command `json:"onCreateCommand,omitzero"`
UpdateContent spec.Command `json:"updateContentCommand,omitzero"`
PostCreate spec.Command `json:"postCreateCommand,omitzero"`
PostStart spec.Command `json:"postStartCommand,omitzero"`
PostAttach spec.Command `json:"postAttachCommand,omitzero"`
WaitFor string `json:"waitFor,omitempty"`
RemoteUser string `json:"remoteUser,omitempty"`
ContainerUser string `json:"containerUser,omitempty"`
UserEnvProbe string `json:"userEnvProbe,omitempty"`
RemoteEnv map[string]any `json:"remoteEnv,omitempty"`
ContainerEnv map[string]any `json:"containerEnv,omitempty"`
OverrideCommand *bool `json:"overrideCommand,omitempty"`
PortsAttributes map[string]any `json:"portsAttributes,omitempty"`
OtherPortsAttributes map[string]any `json:"otherPortsAttributes,omitempty"`
ForwardPorts []any `json:"forwardPorts,omitempty"`
ShutdownAction string `json:"shutdownAction,omitempty"`
UpdateRemoteUserUID *bool `json:"updateRemoteUserUID,omitempty"`
HostRequirements map[string]any `json:"hostRequirements,omitempty"`
}
Entry is one base-image, feature, or devcontainer.json contribution. Feature IDs identify the original user feature reference, not its short ID.
func Collect ¶
Collect appends feature entries in install order, then the config entry. Feature containerEnv is image ENV, rather than label metadata, in upstream.
func CollectWithOptions ¶
func CollectWithOptions(base []Entry, resolved []features.Resolved, dc *spec.DevContainer, opts CollectOptions) []Entry
CollectWithOptions filters only the new feature and config contributions.
func FromConfig ¶
func FromConfig(dc *spec.DevContainer) Entry
FromConfig picks only the properties upstream persists in image metadata.
func Parse ¶
Parse accepts the array and legacy single-object forms. Invalid labels return an error; callers can log it and continue without metadata, as upstream does.
func Read ¶
Read reads labels and falls back to no metadata on invalid input. The optional logger receives the parse error, matching upstream's nonfatal label handling.
func Substitute ¶
Substitute applies a string substitution to every metadata value, including object mount fields and all lifecycle command forms. Keys stay unchanged.
type Merged ¶
type Merged struct {
*spec.DevContainer
Customizations map[string][]any
Entrypoints []string
OnCreateCommands []spec.Command
UpdateContentCommands []spec.Command
PostCreateCommands []spec.Command
PostStartCommands []spec.Command
PostAttachCommands []spec.Command
}
Merged keeps the ordinary config shape for Go callers and exposes upstream's collected lifecycle/customization fields in JSON.
func Merge ¶
func Merge(config *spec.DevContainer, entries []Entry) Merged
Merge combines an already-collected list; it does not append config again. The config supplies fields that are not part of image metadata (e.g. image, build, workspace and runArgs). Neither config nor entries is modified.
func (Merged) MarshalJSON ¶
MarshalJSON uses the merged configuration names from the upstream CLI.
Source Files