Documentation
¶
Overview ¶
Package feature fetches Dev Container Features referenced by a devcontainer.json and merges the properties they contribute into the parsed configuration, producing the effective configuration defined by the Dev Container specification's merge logic (see https://containers.dev/implementors/spec/#merge-logic).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Merge ¶
func Merge(ctx context.Context, f *Fetcher, fsRoot *os.Root, configDir string, root *hujson.Value) error
Merge fetches the Features referenced under "/features" of root, a devcontainer.json parsed from a file at configDir within fsRoot, and merges the properties they contribute into root in place, following the merge logic of the Dev Container specification. Features named by "dependsOn" are resolved recursively and contribute properties as well.
fsRoot and configDir together locate the referencing devcontainer.json (fsRoot is discovery.ConfigFile.Root and configDir is the directory of its Path): a local Feature reference is resolved relative to configDir and read through fsRoot, so it cannot escape fsRoot's boundary.
Every node Merge adds to the tree carries the byte offset of the referencing Feature key in the original file, so findings on merged-in properties point at the Feature reference. Any fetch or parse failure, or a dependency cycle, is returned as an error.
Types ¶
type Dependency ¶
type Dependency struct {
Ref string
Options optionValue
}
Dependency is one entry of a Feature's "dependsOn": the reference of a required Feature and the options it is requested with. The options make an otherwise identical dependency a distinct contributor for install ordering.
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher retrieves Feature metadata for the references found in devcontainer.json files. It caches every result in memory for the lifetime of the Fetcher, including failures, so a reference shared by several files is fetched at most once per run.
func NewFetcher ¶
func NewFetcher() *Fetcher
NewFetcher returns a Fetcher with a default HTTP client.
func (*Fetcher) Fetch ¶
func (f *Fetcher) Fetch(ctx context.Context, raw string, fsRoot *os.Root, configDir string) (*Metadata, error)
Fetch retrieves the metadata of the Feature referenced by raw. fsRoot and configDir together locate the devcontainer.json that references the Feature (fsRoot is discovery.ConfigFile.Root and configDir is the directory of its Path): fsRoot is the boundary every filesystem access is confined to, and configDir is the referencing file's directory within it. A local reference is resolved by joining configDir with it and reading the result through fsRoot, so the resolution cannot escape fsRoot's boundary. fsRoot and configDir are unused for an OCI or tarball reference.
type Metadata ¶
type Metadata struct {
// ID is the Feature's declared identifier.
ID string
// Version is the Feature's declared version.
Version string
// DependsOn lists the Features this Feature depends on, in declaration order. Dependencies are
// installed before the Feature and contribute properties of their own.
DependsOn []Dependency
// InstallsAfter lists Feature IDs this Feature prefers to be installed after. Unlike DependsOn
// it does not pull in new Features; it only influences installation order.
InstallsAfter []string
// Aliases are the Feature's identifiers, its ID followed by any legacy IDs. They match a renamed
// Feature named by another Feature's "installsAfter" or by "overrideFeatureInstallOrder".
Aliases []string
// Digest is the resolved manifest digest of an OCI Feature (e.g. "sha256:..."). It is empty for
// local and tarball Features. It distinguishes otherwise identical references for install order.
Digest string
// Root is the parsed devcontainer-feature.json. It is the source of truth for the properties
// the Feature contributes (e.g. Root.Find("/containerEnv")); values grafted from it are
// stripped of comments and re-anchored into the target document at merge time.
Root hujson.Value
}
Metadata is the declaration of one fetched Feature: the content of its devcontainer-feature.json.
type Ref ¶
type Ref struct {
// Raw is the reference exactly as written.
Raw string
// Kind identifies how the reference locates the Feature.
Kind RefKind
// OCI holds the parsed registry reference (registry, repository, and the tag or digest) for a
// KindOCI reference; it is the zero value for other kinds.
OCI registry.Reference
}
Ref is a parsed Feature reference, as used for the keys of the "features" object in a devcontainer.json.
type RefKind ¶
type RefKind int
RefKind identifies how a Feature reference locates the Feature.
const ( // KindOCI is a reference to a Feature distributed as an OCI artifact, e.g. // "ghcr.io/devcontainers/features/node:1". KindOCI RefKind = iota // KindTarball is a direct HTTPS URI to a Feature tarball. KindTarball // KindLocal is a relative path to a Feature directory next to the devcontainer.json. KindLocal )
Source Files