From 45c0015c262fb870cef8107c4a3e7c31d581b7a8 Mon Sep 17 00:00:00 2001 From: bilby91 <2201079+bilby91@users.noreply.github.com> Date: Wed, 4 Nov 2026 14:57:50 +0000 Subject: [PATCH] feat(features): write and honor devcontainer-lock.json The spec's feature lockfile was neither produced nor read (#26). Up and Build now pin every OCI and HTTPS feature to its lockfile entry and write devcontainer-lock.json beside devcontainer.json when what resolved differs, as the reference CLI does by default since 0.87. - DiskStore already returns the two values the lockfile records as Fetched.ResolvedRef (OCI manifest digest, HTTPS body sha256), so no store change: OCI features are fetched as repo@, which the digest local-first cache serves offline; HTTPS downloads are checked against integrity (*feature.FeatureIntegrityError). - UpOptions.Lockfile / BuildOptions.Lockfile: LockfileDefault, LockfileFrozen (*feature.LockfileMismatchError when missing, before any fetch, or out of date; never writes), LockfileUpgrade, LockfileDisabled. devcontainer up gains --frozen-lockfile and --no-lockfile. - CLI over spec where they differ: keys verbatim, .devcontainer-lock.json beside a .devcontainer.json. Output is byte-identical to the CLI's generated fixtures; files are compared by content, not bytes. - Features baked into the base image keep their existing entry. Compose reattach does not consult the lockfile, and it is not hashed into the compose inputs (the first Up writes it, so hashing it would recreate every compose project once). - Up and Build fix the discovered config path before resolving. They previously assumed .devcontainer/ for local features and the compose working directory, which was wrong for a root .devcontainer.json; a relative ConfigPath with local features also failed. Closes #26. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 39 ++++ README.md | 2 +- build.go | 12 ++ cmd/devcontainer/up.go | 13 ++ design/features.md | 60 ++++++ devcontainer.go | 26 ++- feature/lockfile.go | 232 +++++++++++++++++++++++ feature/lockfile_test.go | 228 +++++++++++++++++++++++ lockfile.go | 97 ++++++++++ lockfile_test.go | 294 ++++++++++++++++++++++++++++++ test/integration/lockfile_test.go | 94 ++++++++++ up.go | 61 +++++-- up_compose_reattach.go | 2 +- up_compose_reattach_test.go | 4 +- 14 files changed, 1131 insertions(+), 33 deletions(-) create mode 100644 feature/lockfile.go create mode 100644 feature/lockfile_test.go create mode 100644 lockfile.go create mode 100644 lockfile_test.go create mode 100644 test/integration/lockfile_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index b0e5167..68adca8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **features** — `devcontainer-lock.json` support, following the spec's + feature lockfile and the reference CLI. (#26) + - By default, `Up` and `Build` pin each OCI and HTTPS feature to its + lockfile entry and write the lockfile beside `devcontainer.json` + whenever what resolved differs from it. If the file is missing, it + is created. + - OCI features are fetched by the locked manifest digest, so a locked + workspace builds from the feature cache with no registry call. HTTPS + downloads are checked against the locked sha256 + (`*feature.FeatureIntegrityError`). + - `UpOptions.Lockfile` / `BuildOptions.Lockfile` select the mode: + - `LockfileFrozen` returns `*feature.LockfileMismatchError` when the + lockfile is missing or out of date, and never writes. + - `LockfileUpgrade` re-resolves every tag and rewrites the lockfile. + - `LockfileDisabled` neither reads nor writes it. + - `devcontainer up` gains `--frozen-lockfile` and `--no-lockfile` + (mutually exclusive), named as in the reference CLI. + - The file is byte-compatible with the CLI's, and a `.devcontainer.json` + gets a `.devcontainer-lock.json`. Local features are not recorded. + - Features baked into the base image keep their existing entry. + - Compose reattach does not consult the lockfile. + - See design/features.md §8.2. + +### Changed + +- **features** — the first `Up`/`Build` after upgrading now creates a + `devcontainer-lock.json` in the workspace's `.devcontainer/` for any + config with OCI or HTTPS features. Embedders that don't want files + written into user repositories set `Lockfile: LockfileDisabled`. + +### Fixed + +- **engine** — `Up` and `Build` called without `ConfigPath` now use the + discovered `devcontainer.json`'s directory for local features and the + compose working directory. Previously they always assumed + `.devcontainer/`, which was wrong for a root `.devcontainer.json`. + ## [0.5.3] - 2026-10-28 ### Fixed diff --git a/README.md b/README.md index 1d7846a..d3f1c54 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ field/behavior the library covers. Legend: ✅ acted on · ⚠️ parsed but not | `features` (OCI / HTTPS / local) | ✅ | DAG ordering, options validation, content-addressed cache (local-first for digests and exact `X.Y.Z` versions; floating tags fall back to the last resolution when the registry is unreachable) | | `dependsOn` / `installsAfter` / `overrideFeatureInstallOrder` | ✅ | | | Pre-baked-image short-circuit | ✅ | `devcontainer.metadata` label read on Up | -| `devcontainer-lock.json` | ❌ | [#26](https://github.com/crunchloop/devcontainer/issues/26) | +| `devcontainer-lock.json` | ✅ | Written and pinned by default (`UpOptions.Lockfile` / `BuildOptions.Lockfile`: frozen, upgrade, disabled), CLI-compatible format. Records declared features only: features reachable only through `dependsOn` are not installed | **Lifecycle** diff --git a/build.go b/build.go index 947f735..9564328 100644 --- a/build.go +++ b/build.go @@ -51,6 +51,9 @@ type BuildOptions struct { // IfNotPresent — same as Up. PullPolicy PullPolicy + // Lockfile controls the feature lockfile, as UpOptions.Lockfile. + Lockfile LockfileMode + // Platform pins the target platform (e.g. "linux/amd64", // "linux/arm64") on every BuildImage call. Empty leaves it // unspecified. @@ -106,6 +109,14 @@ func (e *Engine) Build(ctx context.Context, opts BuildOptions) (*BuildResult, er return nil, fmt.Errorf("BuildOptions.LocalWorkspaceFolder is required") } + // Fix the config path Resolve would discover: the lockfile and + // local features are located beside it. + configPath, err := configPathFor(opts.LocalWorkspaceFolder, opts.ConfigPath) + if err != nil { + return nil, err + } + opts.ConfigPath = configPath + bus := newEventBus(e.emitter, opts.Events) defer bus.Close() @@ -134,6 +145,7 @@ func (e *Engine) Build(ctx context.Context, opts BuildOptions) (*BuildResult, er ConfigPath: opts.ConfigPath, LocalEnv: opts.LocalEnv, PullPolicy: opts.PullPolicy, + Lockfile: opts.Lockfile, bus: bus, override: &buildOverride{ FinalTag: opts.ImageName, diff --git a/cmd/devcontainer/up.go b/cmd/devcontainer/up.go index 701c3bd..0c981fd 100644 --- a/cmd/devcontainer/up.go +++ b/cmd/devcontainer/up.go @@ -11,6 +11,8 @@ func newUpCmd(rf *rootFlags) *cobra.Command { recreate bool runInitializeCommand bool runSecretsCommand bool + frozenLockfile bool + noLockfile bool ) cmd := &cobra.Command{ @@ -36,12 +38,20 @@ func newUpCmd(rf *rootFlags) *cobra.Command { defer closeEng() evCh, stop := startEventPrinter(level) + lockfile := devcontainer.LockfileDefault + switch { + case frozenLockfile: + lockfile = devcontainer.LockfileFrozen + case noLockfile: + lockfile = devcontainer.LockfileDisabled + } workspace, upErr := eng.Up(ctx, devcontainer.UpOptions{ LocalWorkspaceFolder: ws, ConfigPath: rf.configPath, Recreate: recreate, RunInitializeCommand: runInitializeCommand, RunSecretsCommand: runSecretsCommand, + Lockfile: lockfile, Events: evCh, }) stop() @@ -62,6 +72,9 @@ func newUpCmd(rf *rootFlags) *cobra.Command { cmd.Flags().BoolVar(&recreate, "recreate", false, "Alias for --remove-existing-container") cmd.Flags().BoolVar(&runInitializeCommand, "run-initialize-command", false, "Run devcontainer.json initializeCommand on the host before container creation") cmd.Flags().BoolVar(&runSecretsCommand, "run-secrets-command", false, "Run devcontainer.json secretsCommand on the host and inject its output as container env") + cmd.Flags().BoolVar(&frozenLockfile, "frozen-lockfile", false, "Fail if devcontainer-lock.json is missing or out of date; never write it") + cmd.Flags().BoolVar(&noLockfile, "no-lockfile", false, "Neither read nor write devcontainer-lock.json") + cmd.MarkFlagsMutuallyExclusive("frozen-lockfile", "no-lockfile") return cmd } diff --git a/design/features.md b/design/features.md index a249e9d..3085114 100644 --- a/design/features.md +++ b/design/features.md @@ -344,6 +344,66 @@ tag rewrites its record (write to a temporary file, then rename). HTTPS features are unchanged: their content hash is only known after the download. +### 8.2 Lockfile + +The spec's [`devcontainer-lock.json`](https://github.com/devcontainers/spec/blob/main/docs/specs/devcontainer-lockfile.md) +records, beside `devcontainer.json`, the exact artifact every OCI and +HTTPS feature resolved to. `UpOptions.Lockfile` / `BuildOptions.Lockfile` +select the mode. These follow the reference CLI as of 0.87, where the +lockfile is on by default: + +| Mode | Reads pins | Writes | Fails when | +| --- | --- | --- | --- | +| `LockfileDefault` | yes | when what resolved differs (created if missing) | a pinned HTTPS download has a different digest | +| `LockfileFrozen` | yes | never | the lockfile is missing (before any fetch), or what resolved differs from it | +| `LockfileUpgrade` | no | when what resolved differs | — | +| `LockfileDisabled` | no | never | — | + +`DiskStore` already returns the two values the lockfile records as +`Fetched.ResolvedRef`: the OCI manifest digest and the HTTPS body +sha256. So the lockfile needs no store change: + +- **OCI pin:** `layerFeatures` fetches `repo@` instead of the + tag. That is a digest reference, so §8.1 serves it from cache without + a registry call: a locked workspace builds offline. +- **HTTPS pin:** the URL is fetched as before and its digest is compared + with `integrity` (`*feature.FeatureIntegrityError` on mismatch). +- **Write:** after the fetch loop and before the build, as the CLI does. + The lockfile is regenerated from scratch, so stale entries drop. It is + compared by content, not bytes, and written only when entries changed. + +Decisions: + +1. **CLI over spec where they differ.** Keys are the feature reference + verbatim (the spec says lowercase; the CLI doesn't), and a + `.devcontainer.json` gets a `.devcontainer-lock.json`. The output + format is byte-identical to the CLI's (2-space indent, sorted keys, + trailing newline; checked against the CLI's own generated test + fixtures). The one divergence is key order for keys where bytewise + order and `localeCompare` disagree. Comparing by content keeps either + tool from rewriting the other's file over it. +2. **Features baked into the base image keep their existing entry.** + They are not fetched, so they produce no new entry. Dropping theirs + would churn the file on every pre-baked run and always fail frozen + mode. +3. **Compose reattach neither reads nor writes the lockfile, and the + lockfile is not part of the compose inputs hash.** Reattach resolves + nothing, matching the CLI, which does not re-resolve features when it + starts an existing container. Hashing the lockfile looks tidier, but + the first `Up` writes it, so the second `Up` would see a new hash and + recreate every compose project once. +4. **`Up` and `Build` fix the config path before resolving.** With + `ConfigPath` empty they used to drop the discovered path and assume + `.devcontainer/`. That put the lockfile, local features and the + compose working directory in the wrong place for a root + `.devcontainer.json`. + +Known gap: the engine installs only the features declared in +`devcontainer.json`. It does not pull in features reachable only through +another feature's `dependsOn`. The CLI does, and locks them too. The +lockfile here therefore lists declared features only. Transitive +install is separate work. + Concurrency: a small lockfile (`extracted/.lock`) per cache entry so parallel `Resolve` calls for the same ref don't race. diff --git a/devcontainer.go b/devcontainer.go index e1abd03..105bd50 100644 --- a/devcontainer.go +++ b/devcontainer.go @@ -56,16 +56,9 @@ func Resolve(ctx context.Context, opts ResolveOptions) (*ResolvedConfig, error) return nil, fmt.Errorf("LocalWorkspaceFolder must be absolute: %q", opts.LocalWorkspaceFolder) } - configPath := opts.ConfigPath - if configPath == "" { - p, err := lookupConfigPath(opts.LocalWorkspaceFolder) - if err != nil { - return nil, err - } - configPath = p - } - if !filepath.IsAbs(configPath) { - configPath = filepath.Join(opts.LocalWorkspaceFolder, configPath) + configPath, err := configPathFor(opts.LocalWorkspaceFolder, opts.ConfigPath) + if err != nil { + return nil, err } src, err := os.ReadFile(configPath) @@ -91,6 +84,19 @@ func Resolve(ctx context.Context, opts ResolveOptions) (*ResolvedConfig, error) }) } +// configPathFor returns the absolute path of the devcontainer.json that +// Resolve reads for workspaceFolder and configPath: configPath (joined +// onto workspaceFolder if relative), or the discovered one when empty. +func configPathFor(workspaceFolder, configPath string) (string, error) { + if configPath == "" { + return lookupConfigPath(workspaceFolder) + } + if !filepath.IsAbs(configPath) { + return filepath.Join(workspaceFolder, configPath), nil + } + return configPath, nil +} + func lookupConfigPath(workspaceFolder string) (string, error) { candidates := []string{ filepath.Join(workspaceFolder, ".devcontainer", "devcontainer.json"), diff --git a/feature/lockfile.go b/feature/lockfile.go new file mode 100644 index 0000000..aa5e307 --- /dev/null +++ b/feature/lockfile.go @@ -0,0 +1,232 @@ +package feature + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "reflect" + "sort" + "strings" + + "github.com/google/go-containerregistry/pkg/name" + + "github.com/crunchloop/devcontainer/config" +) + +// Lockfile is the spec's devcontainer-lock.json: for every OCI and +// HTTPS feature in devcontainer.json, the exact artifact it resolved to. +// Local features are not recorded (their directory is the source). +// +// Features is keyed by the feature reference exactly as written in +// devcontainer.json. The spec says keys are lowercased; the reference +// CLI writes and looks them up verbatim, and this follows the CLI so a +// lockfile is interchangeable between the two. +type Lockfile struct { + Features map[string]LockedFeature `json:"features"` +} + +// LockedFeature is one lockfile entry. +type LockedFeature struct { + // Version is the feature's full version from its + // devcontainer-feature.json. Informational: resolution never + // checks it. + Version string `json:"version"` + // Resolved is the pinned location: repo@digest for OCI, the URL + // for HTTPS. + Resolved string `json:"resolved"` + // Integrity is the artifact digest: the manifest digest for OCI, + // the sha256 of the tarball for HTTPS. + Integrity string `json:"integrity"` + // DependsOn lists the feature's dependsOn keys as declared. + DependsOn []string `json:"dependsOn,omitempty"` +} + +// LockfilePath returns the lockfile beside the devcontainer.json at +// configPath: .devcontainer-lock.json for a .devcontainer.json, +// devcontainer-lock.json otherwise (the reference CLI's naming). +func LockfilePath(configPath string) string { + base := "devcontainer-lock.json" + if strings.HasPrefix(filepath.Base(configPath), ".") { + base = "." + base + } + return filepath.Join(filepath.Dir(configPath), base) +} + +// ReadLockfile reads the lockfile at path. A missing or blank file is +// no lockfile: (nil, nil). A file that is not a lockfile is an error, +// never silently replaced. +func ReadLockfile(path string) (*Lockfile, error) { + b, err := os.ReadFile(path) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("read lockfile: %w", err) + } + if len(bytes.TrimSpace(b)) == 0 { + return nil, nil + } + var lf Lockfile + if err := json.Unmarshal(b, &lf); err != nil { + return nil, fmt.Errorf("parse lockfile %s: %w", path, err) + } + return &lf, nil +} + +// WriteLockfile writes lf to path in the reference CLI's format: two +// space indent, entries sorted by key, trailing newline. +func WriteLockfile(path string, lf *Lockfile) error { + features := lf.Features + if features == nil { + features = map[string]LockedFeature{} + } + // encoding/json sorts map keys bytewise; the CLI sorts with + // localeCompare. They agree on the lowercase registry references + // features use. Where they don't, neither tool rewrites the other's + // file, since both compare content rather than bytes. + b, err := json.MarshalIndent(Lockfile{Features: features}, "", " ") + if err != nil { + return err + } + if err := os.WriteFile(path, append(b, '\n'), 0o644); err != nil { + return fmt.Errorf("write lockfile: %w", err) + } + return nil +} + +// Equal reports whether l and o lock the same features to the same +// artifacts. Formatting and key order do not matter; a nil lockfile +// equals only another nil lockfile. +func (l *Lockfile) Equal(o *Lockfile) bool { + if l == nil || o == nil { + return l == o + } + return len(l.Changed(o)) == 0 +} + +// Changed returns the keys whose entries differ between l and o, +// sorted: added, removed or re-pinned features. A nil lockfile has no +// entries. +func (l *Lockfile) Changed(o *Lockfile) []string { + var changed []string + for k, v := range l.entries() { + if w, ok := o.Entry(k); !ok || !reflect.DeepEqual(v, w) { + changed = append(changed, k) + } + } + for k := range o.entries() { + if _, ok := l.Entry(k); !ok { + changed = append(changed, k) + } + } + sort.Strings(changed) + return changed +} + +// Entry returns the entry for the feature keyed ref. A nil lockfile +// has no entries. +func (l *Lockfile) Entry(ref string) (LockedFeature, bool) { + entry, ok := l.entries()[ref] + return entry, ok +} + +func (l *Lockfile) entries() map[string]LockedFeature { + if l == nil { + return nil + } + return l.Features +} + +// Lock returns the lockfile entry for a fetched feature. ok is false +// for features the lockfile does not record (local ones). +func Lock(f config.ResolvedFeature) (entry LockedFeature, ok bool) { + var resolved string + switch f.SourceKind { + case config.FeatureSourceOCI: + resolved = f.ResolvedRef + case config.FeatureSourceHTTPS: + resolved = f.Ref + default: + return LockedFeature{}, false + } + var dependsOn []string + for id := range f.Metadata.DependsOn { + dependsOn = append(dependsOn, id) + } + sort.Strings(dependsOn) + return LockedFeature{ + Version: f.Metadata.Version, + Resolved: resolved, + Integrity: integrity(f.SourceKind, f.ResolvedRef), + DependsOn: dependsOn, + }, true +} + +// PinnedRef is the reference to fetch for f when the lockfile holds +// entry for it: the OCI repository at the locked digest. Other kinds +// fetch their reference as written and are checked with +// CheckIntegrity. +func PinnedRef(f config.ResolvedFeature, entry LockedFeature) (string, error) { + if f.SourceKind != config.FeatureSourceOCI { + return f.Ref, nil + } + ref, err := name.ParseReference(f.Ref) + if err != nil { + return "", fmt.Errorf("parse OCI ref %q: %w", f.Ref, err) + } + return ref.Context().Name() + "@" + entry.Integrity, nil +} + +// CheckIntegrity returns a *FeatureIntegrityError when fetched is not +// the artifact entry locks f to. +func CheckIntegrity(f config.ResolvedFeature, fetched Fetched, entry LockedFeature) error { + if got := integrity(f.SourceKind, fetched.ResolvedRef); got != entry.Integrity { + return &FeatureIntegrityError{Ref: f.Ref, Want: entry.Integrity, Got: got} + } + return nil +} + +// integrity extracts the artifact digest from a Fetched.ResolvedRef: +// the digest of an OCI repo@digest, or the HTTPS content digest itself. +func integrity(kind config.FeatureSourceKind, resolvedRef string) string { + if kind == config.FeatureSourceOCI { + if i := strings.LastIndex(resolvedRef, "@"); i >= 0 { + return resolvedRef[i+1:] + } + } + return resolvedRef +} + +// FeatureIntegrityError is returned when a feature fetched under a +// lockfile pin is not the locked artifact. +type FeatureIntegrityError struct { + Ref string + Want string + Got string +} + +func (e *FeatureIntegrityError) Error() string { + return fmt.Sprintf("feature %s: digest %s does not match lockfile integrity %s", e.Ref, e.Got, e.Want) +} + +// LockfileMismatchError is returned in frozen mode when the lockfile is +// missing or does not match what the features resolve to. Nothing is +// written in that case. +type LockfileMismatchError struct { + Path string + // Missing is true when no lockfile exists at Path. + Missing bool + // Changed lists the feature keys that would be added, removed or + // re-pinned. + Changed []string +} + +func (e *LockfileMismatchError) Error() string { + if e.Missing { + return fmt.Sprintf("lockfile %s does not exist", e.Path) + } + return fmt.Sprintf("lockfile %s does not match: %s", e.Path, strings.Join(e.Changed, ", ")) +} diff --git a/feature/lockfile_test.go b/feature/lockfile_test.go new file mode 100644 index 0000000..1c5dc34 --- /dev/null +++ b/feature/lockfile_test.go @@ -0,0 +1,228 @@ +package feature + +import ( + "errors" + "os" + "path/filepath" + "reflect" + "strings" + "testing" + + "github.com/crunchloop/devcontainer/config" +) + +const ( + digestA = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + digestB = "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" +) + +func TestLockfilePath(t *testing.T) { + for configPath, want := range map[string]string{ + "/w/.devcontainer/devcontainer.json": "/w/.devcontainer/devcontainer-lock.json", + "/w/.devcontainer.json": "/w/.devcontainer-lock.json", + "/w/.devcontainer/python/devcontainer.json": "/w/.devcontainer/python/devcontainer-lock.json", + } { + if got := LockfilePath(configPath); got != want { + t.Errorf("LockfilePath(%q) = %q, want %q", configPath, got, want) + } + } +} + +func TestReadLockfile_MissingAndBlankAreNoLockfile(t *testing.T) { + dir := t.TempDir() + if lf, err := ReadLockfile(filepath.Join(dir, "missing.json")); lf != nil || err != nil { + t.Errorf("missing: got (%v, %v), want (nil, nil)", lf, err) + } + blank := filepath.Join(dir, "blank.json") + if err := os.WriteFile(blank, []byte(" \n"), 0o644); err != nil { + t.Fatal(err) + } + if lf, err := ReadLockfile(blank); lf != nil || err != nil { + t.Errorf("blank: got (%v, %v), want (nil, nil)", lf, err) + } +} + +func TestReadLockfile_MalformedIsAnError(t *testing.T) { + path := filepath.Join(t.TempDir(), "devcontainer-lock.json") + if err := os.WriteFile(path, []byte("{not json"), 0o644); err != nil { + t.Fatal(err) + } + if _, err := ReadLockfile(path); err == nil { + t.Fatal("expected a parse error") + } +} + +// TestWriteLockfile_CLIFormat pins the byte format to what the +// reference CLI writes (JSON.stringify(lockfile, null, 2) + '\n', keys +// sorted, dependsOn omitted when empty), so the two tools produce the +// same file. +func TestWriteLockfile_CLIFormat(t *testing.T) { + path := filepath.Join(t.TempDir(), "devcontainer-lock.json") + lf := &Lockfile{Features: map[string]LockedFeature{ + "ghcr.io/devcontainers/features/node:1": { + Version: "1.6.1", + Resolved: "ghcr.io/devcontainers/features/node@" + digestB, + Integrity: digestB, + }, + "ghcr.io/devcontainers/features/common-utils:2": { + Version: "2.5.2", + Resolved: "ghcr.io/devcontainers/features/common-utils@" + digestA, + Integrity: digestA, + DependsOn: []string{"ghcr.io/devcontainers/features/node"}, + }, + }} + if err := WriteLockfile(path, lf); err != nil { + t.Fatal(err) + } + got, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + want := `{ + "features": { + "ghcr.io/devcontainers/features/common-utils:2": { + "version": "2.5.2", + "resolved": "ghcr.io/devcontainers/features/common-utils@` + digestA + `", + "integrity": "` + digestA + `", + "dependsOn": [ + "ghcr.io/devcontainers/features/node" + ] + }, + "ghcr.io/devcontainers/features/node:1": { + "version": "1.6.1", + "resolved": "ghcr.io/devcontainers/features/node@` + digestB + `", + "integrity": "` + digestB + `" + } + } +} +` + if string(got) != want { + t.Errorf("written lockfile:\n%s\nwant:\n%s", got, want) + } + + read, err := ReadLockfile(path) + if err != nil { + t.Fatal(err) + } + if !read.Equal(lf) { + t.Errorf("round trip changed entries: %v", read.Changed(lf)) + } +} + +func TestWriteLockfile_EmptyWritesEmptyFeatures(t *testing.T) { + path := filepath.Join(t.TempDir(), "devcontainer-lock.json") + if err := WriteLockfile(path, &Lockfile{}); err != nil { + t.Fatal(err) + } + got, _ := os.ReadFile(path) + if want := "{\n \"features\": {}\n}\n"; string(got) != want { + t.Errorf("got %q, want %q", got, want) + } +} + +func TestLockfileChanged(t *testing.T) { + entry := func(d string) LockedFeature { return LockedFeature{Version: "1.0.0", Resolved: "r@" + d, Integrity: d} } + old := &Lockfile{Features: map[string]LockedFeature{ + "kept": entry(digestA), + "repined": entry(digestA), + "removed": entry(digestA), + }} + next := &Lockfile{Features: map[string]LockedFeature{ + "kept": entry(digestA), + "repined": entry(digestB), + "added": entry(digestA), + }} + if got, want := next.Changed(old), []string{"added", "removed", "repined"}; !reflect.DeepEqual(got, want) { + t.Errorf("Changed = %v, want %v", got, want) + } + if next.Equal(old) { + t.Error("Equal = true for differing lockfiles") + } + if got := next.Changed(nil); !reflect.DeepEqual(got, []string{"added", "kept", "repined"}) { + t.Errorf("Changed(nil) = %v", got) + } + if next.Equal(nil) || (*Lockfile)(nil).Equal(next) { + t.Error("a lockfile equals nil") + } + if !(*Lockfile)(nil).Equal(nil) { + t.Error("nil does not equal nil") + } + // An existing lockfile with no entries is not the same as none: it + // is written, not left absent. + if (&Lockfile{}).Equal(nil) { + t.Error("empty lockfile equals nil") + } +} + +func TestLock(t *testing.T) { + meta := config.FeatureMetadata{ + Version: "1.2.3", + DependsOn: map[string]map[string]any{"ghcr.io/x/b:1": {}, "ghcr.io/x/a:1": {}}, + } + oci := config.ResolvedFeature{ + Ref: "ghcr.io/x/f:1", SourceKind: config.FeatureSourceOCI, + ResolvedRef: "ghcr.io/x/f@" + digestA, Metadata: meta, + } + got, ok := Lock(oci) + want := LockedFeature{ + Version: "1.2.3", Resolved: "ghcr.io/x/f@" + digestA, Integrity: digestA, + DependsOn: []string{"ghcr.io/x/a:1", "ghcr.io/x/b:1"}, + } + if !ok || !reflect.DeepEqual(got, want) { + t.Errorf("OCI: got (%+v, %v), want %+v", got, ok, want) + } + + https := config.ResolvedFeature{ + Ref: "https://example.com/devcontainer-feature-f.tgz", SourceKind: config.FeatureSourceHTTPS, + ResolvedRef: digestB, Metadata: config.FeatureMetadata{Version: "0.1.0"}, + } + got, ok = Lock(https) + want = LockedFeature{Version: "0.1.0", Resolved: https.Ref, Integrity: digestB} + if !ok || !reflect.DeepEqual(got, want) { + t.Errorf("HTTPS: got (%+v, %v), want %+v", got, ok, want) + } + + local := config.ResolvedFeature{Ref: "./f", SourceKind: config.FeatureSourceLocal, ResolvedRef: "/w/f"} + if _, ok := Lock(local); ok { + t.Error("local feature locked") + } +} + +func TestPinnedRef(t *testing.T) { + entry := LockedFeature{Integrity: digestA} + for ref, want := range map[string]string{ + "ghcr.io/x/f:1": "ghcr.io/x/f@" + digestA, + "ghcr.io/x/f": "ghcr.io/x/f@" + digestA, + "ghcr.io/x/f@" + digestB: "ghcr.io/x/f@" + digestA, + } { + got, err := PinnedRef(config.ResolvedFeature{Ref: ref, SourceKind: config.FeatureSourceOCI}, entry) + if err != nil || got != want { + t.Errorf("PinnedRef(%q) = (%q, %v), want %q", ref, got, err, want) + } + } + url := "https://example.com/devcontainer-feature-f.tgz" + if got, _ := PinnedRef(config.ResolvedFeature{Ref: url, SourceKind: config.FeatureSourceHTTPS}, entry); got != url { + t.Errorf("HTTPS PinnedRef = %q, want the URL", got) + } +} + +func TestCheckIntegrity(t *testing.T) { + https := config.ResolvedFeature{Ref: "https://example.com/devcontainer-feature-f.tgz", SourceKind: config.FeatureSourceHTTPS} + entry := LockedFeature{Integrity: digestA} + if err := CheckIntegrity(https, Fetched{ResolvedRef: digestA}, entry); err != nil { + t.Errorf("matching digest: %v", err) + } + err := CheckIntegrity(https, Fetched{ResolvedRef: digestB}, entry) + var ie *FeatureIntegrityError + if !errors.As(err, &ie) || ie.Want != digestA || ie.Got != digestB { + t.Fatalf("got %v, want *FeatureIntegrityError", err) + } + if !strings.Contains(err.Error(), https.Ref) { + t.Errorf("error %q does not name the feature", err) + } + + oci := config.ResolvedFeature{Ref: "ghcr.io/x/f:1", SourceKind: config.FeatureSourceOCI} + if err := CheckIntegrity(oci, Fetched{ResolvedRef: "ghcr.io/x/f@" + digestA}, entry); err != nil { + t.Errorf("OCI matching digest: %v", err) + } +} diff --git a/lockfile.go b/lockfile.go new file mode 100644 index 0000000..bd9e3bf --- /dev/null +++ b/lockfile.go @@ -0,0 +1,97 @@ +package devcontainer + +import ( + "github.com/crunchloop/devcontainer/config" + "github.com/crunchloop/devcontainer/feature" +) + +// LockfileMode controls how Up and Build use the feature lockfile +// (devcontainer-lock.json beside devcontainer.json). See feature.Lockfile. +type LockfileMode string + +const ( + // LockfileDefault pins features to the lockfile's entries and + // rewrites the lockfile when what resolved differs from it, + // creating it if missing. Matches the reference CLI's default. + LockfileDefault LockfileMode = "" + + // LockfileFrozen pins features to the lockfile's entries and + // returns a *feature.LockfileMismatchError, before building, when + // the lockfile is missing or the features no longer resolve to + // exactly its entries (a feature added, removed or re-keyed). + // Never writes. For CI and reproducible builds. + LockfileFrozen LockfileMode = "frozen" + + // LockfileDisabled neither reads nor writes the lockfile. + LockfileDisabled LockfileMode = "disabled" + + // LockfileUpgrade ignores the lockfile's pins, resolves every + // feature reference afresh, and rewrites the lockfile with the + // result. + LockfileUpgrade LockfileMode = "upgrade" +) + +// featureLock is one Up or Build call's view of the feature lockfile. +type featureLock struct { + mode LockfileMode + path string + existing *feature.Lockfile +} + +// loadFeatureLock reads the lockfile for the devcontainer.json at +// configPath. A frozen lock fails here, before any fetch, when there +// is no lockfile. +func loadFeatureLock(mode LockfileMode, configPath string) (*featureLock, error) { + l := &featureLock{mode: mode, path: feature.LockfilePath(configPath)} + if mode == LockfileDisabled { + return l, nil + } + existing, err := feature.ReadLockfile(l.path) + if err != nil { + return nil, err + } + if existing == nil && mode == LockfileFrozen { + return nil, &feature.LockfileMismatchError{Path: l.path, Missing: true} + } + l.existing = existing + return l, nil +} + +// pin returns the entry f must resolve to, if any. +func (l *featureLock) pin(f config.ResolvedFeature) (feature.LockedFeature, bool) { + if l.mode == LockfileUpgrade || f.SourceKind == config.FeatureSourceLocal { + return feature.LockedFeature{}, false + } + return l.existing.Entry(f.Ref) +} + +// commit records what features resolved to: written in default and +// upgrade modes when it differs from the existing lockfile, compared +// in frozen mode. +// +// Features the base image already carries were not fetched, so there +// is nothing new to record for them: their existing entry is kept. +func (l *featureLock) commit(features []config.ResolvedFeature) error { + if l.mode == LockfileDisabled { + return nil + } + next := &feature.Lockfile{Features: map[string]feature.LockedFeature{}} + for _, f := range features { + if f.AlreadyInstalled { + if entry, ok := l.existing.Entry(f.Ref); ok { + next.Features[f.Ref] = entry + } + continue + } + if entry, ok := feature.Lock(f); ok { + next.Features[f.Ref] = entry + } + } + if next.Equal(l.existing) { + return nil + } + if l.mode == LockfileFrozen { + return &feature.LockfileMismatchError{Path: l.path, Changed: next.Changed(l.existing)} + } + return feature.WriteLockfile(l.path, next) +} diff --git a/lockfile_test.go b/lockfile_test.go new file mode 100644 index 0000000..b6f24b6 --- /dev/null +++ b/lockfile_test.go @@ -0,0 +1,294 @@ +package devcontainer + +import ( + "context" + "errors" + "os" + "path/filepath" + "reflect" + "slices" + "strings" + "testing" + + "github.com/crunchloop/devcontainer/config" + "github.com/crunchloop/devcontainer/feature" + "github.com/crunchloop/devcontainer/runtime" +) + +const ( + lockDigestOld = "sha256:1111111111111111111111111111111111111111111111111111111111111111" + lockDigestNew = "sha256:2222222222222222222222222222222222222222222222222222222222222222" +) + +// tagStore is a feature.Store whose OCI tags currently point at +// lockDigestNew. It serves any repo@digest reference as that digest +// and records every reference it is asked for. +type tagStore struct { + dir string + https map[string]string // URL → content digest + fetched []string +} + +func (s *tagStore) Fetch(_ context.Context, ref string, kind config.FeatureSourceKind) (feature.Fetched, error) { + s.fetched = append(s.fetched, ref) + meta := config.FeatureMetadata{ID: "f", Version: "1.0.0"} + switch kind { + case config.FeatureSourceHTTPS: + return feature.Fetched{Dir: s.dir, ResolvedRef: s.https[ref], Metadata: meta}, nil + case config.FeatureSourceLocal: + return feature.Fetched{Dir: s.dir, ResolvedRef: ref, Metadata: meta}, nil + } + if i := strings.LastIndex(ref, "@"); i >= 0 { + return feature.Fetched{Dir: s.dir, ResolvedRef: ref, Metadata: meta}, nil + } + repo := ref[:strings.LastIndex(ref, ":")] + return feature.Fetched{Dir: s.dir, ResolvedRef: repo + "@" + lockDigestNew, Metadata: meta}, nil +} + +type lockFixture struct { + t *testing.T + eng *Engine + rt *fakeRuntime + store *tagStore + ws string + lockPath string +} + +func newLockFixture(t *testing.T, features string) *lockFixture { + t.Helper() + ws := writeImageDevcontainer(t, `{"image":"alpine:3.20","features":`+features+`}`) + if err := os.MkdirAll(filepath.Join(ws, ".devcontainer", "local"), 0o755); err != nil { + t.Fatal(err) + } + rt := newFakeRuntime() + store := &tagStore{dir: t.TempDir(), https: map[string]string{}} + eng, err := New(EngineOptions{Runtime: rt, FeatureStore: store}) + if err != nil { + t.Fatal(err) + } + return &lockFixture{t: t, eng: eng, rt: rt, store: store, ws: ws, + lockPath: filepath.Join(ws, ".devcontainer", "devcontainer-lock.json")} +} + +// build runs Engine.Build. The fake runtime cannot build images, so a +// run that got past feature resolution ends in ErrNotImplemented; that +// error is swallowed and any other is returned. +func (f *lockFixture) build(mode LockfileMode) error { + f.t.Helper() + _, err := f.eng.Build(context.Background(), BuildOptions{LocalWorkspaceFolder: f.ws, Lockfile: mode}) + if errors.Is(err, runtime.ErrNotImplemented) { + return nil + } + return err +} + +func (f *lockFixture) writeLock(lf *feature.Lockfile) { + f.t.Helper() + if err := feature.WriteLockfile(f.lockPath, lf); err != nil { + f.t.Fatal(err) + } +} + +func (f *lockFixture) readLock() *feature.Lockfile { + f.t.Helper() + lf, err := feature.ReadLockfile(f.lockPath) + if err != nil { + f.t.Fatal(err) + } + return lf +} + +func ociEntry(repo, digest string) feature.LockedFeature { + return feature.LockedFeature{Version: "1.0.0", Resolved: repo + "@" + digest, Integrity: digest} +} + +func TestLockfile_DefaultWritesOCIAndHTTPSNotLocal(t *testing.T) { + const url = "https://example.com/devcontainer-feature-h.tgz" + f := newLockFixture(t, `{"ghcr.io/x/a:1":{},"`+url+`":{},"./local":{}}`) + f.store.https[url] = lockDigestOld + + if err := f.build(LockfileDefault); err != nil { + t.Fatal(err) + } + want := &feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestNew), + url: {Version: "1.0.0", Resolved: url, Integrity: lockDigestOld}, + }} + if got := f.readLock(); !got.Equal(want) { + t.Errorf("lockfile differs from want in %v: %+v", got.Changed(want), got) + } +} + +func TestLockfile_PinsToLockedDigestAndLeavesFileAlone(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{}}`) + // Hand-formatted: a rewrite would normalize it. + body := `{"features":{"ghcr.io/x/a:1":{"version":"1.0.0","resolved":"ghcr.io/x/a@` + lockDigestOld + `","integrity":"` + lockDigestOld + `"}}}` + if err := os.WriteFile(f.lockPath, []byte(body), 0o644); err != nil { + t.Fatal(err) + } + + if err := f.build(LockfileDefault); err != nil { + t.Fatal(err) + } + if want := []string{"ghcr.io/x/a@" + lockDigestOld}; !reflect.DeepEqual(f.store.fetched, want) { + t.Errorf("fetched %v, want %v", f.store.fetched, want) + } + if got, _ := os.ReadFile(f.lockPath); string(got) != body { + t.Errorf("unchanged lockfile was rewritten:\n%s", got) + } +} + +func TestLockfile_DefaultDropsStaleAndAddsNewEntries(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{},"ghcr.io/x/b:1":{}}`) + f.writeLock(&feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + "ghcr.io/x/gone:1": ociEntry("ghcr.io/x/gone", lockDigestOld), + }}) + + if err := f.build(LockfileDefault); err != nil { + t.Fatal(err) + } + want := &feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + "ghcr.io/x/b:1": ociEntry("ghcr.io/x/b", lockDigestNew), + }} + if got := f.readLock(); !got.Equal(want) { + t.Errorf("lockfile differs from want in %v", got.Changed(want)) + } +} + +func TestLockfile_UpgradeReresolvesAndRewrites(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{}}`) + f.writeLock(&feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + }}) + + if err := f.build(LockfileUpgrade); err != nil { + t.Fatal(err) + } + if want := []string{"ghcr.io/x/a:1"}; !reflect.DeepEqual(f.store.fetched, want) { + t.Errorf("fetched %v, want %v", f.store.fetched, want) + } + if got, _ := f.readLock().Entry("ghcr.io/x/a:1"); got.Integrity != lockDigestNew { + t.Errorf("integrity = %s, want %s", got.Integrity, lockDigestNew) + } +} + +func TestLockfile_FrozenMissingFailsBeforeFetching(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{}}`) + + err := f.build(LockfileFrozen) + var me *feature.LockfileMismatchError + if !errors.As(err, &me) || !me.Missing { + t.Fatalf("got %v, want missing *LockfileMismatchError", err) + } + if len(f.store.fetched) != 0 { + t.Errorf("fetched %v before failing", f.store.fetched) + } + if _, err := os.Stat(f.lockPath); !errors.Is(err, os.ErrNotExist) { + t.Errorf("frozen mode created the lockfile: %v", err) + } +} + +func TestLockfile_FrozenMismatchFailsWithoutWriting(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{},"ghcr.io/x/b:1":{}}`) + f.writeLock(&feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + }}) + before, _ := os.ReadFile(f.lockPath) + + err := f.build(LockfileFrozen) + var me *feature.LockfileMismatchError + if !errors.As(err, &me) || me.Missing || !reflect.DeepEqual(me.Changed, []string{"ghcr.io/x/b:1"}) { + t.Fatalf("got %v, want *LockfileMismatchError naming ghcr.io/x/b:1", err) + } + if after, _ := os.ReadFile(f.lockPath); string(after) != string(before) { + t.Error("frozen mode rewrote the lockfile") + } +} + +func TestLockfile_FrozenMatchBuilds(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{}}`) + f.writeLock(&feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + }}) + if err := f.build(LockfileFrozen); err != nil { + t.Fatal(err) + } +} + +func TestLockfile_DisabledNeitherReadsNorWrites(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{}}`) + if err := os.WriteFile(f.lockPath, []byte("{not json"), 0o644); err != nil { + t.Fatal(err) + } + if err := f.build(LockfileDisabled); err != nil { + t.Fatal(err) + } + if got, _ := os.ReadFile(f.lockPath); string(got) != "{not json" { + t.Errorf("disabled mode touched the lockfile: %s", got) + } +} + +func TestLockfile_HTTPSIntegrityMismatchFails(t *testing.T) { + const url = "https://example.com/devcontainer-feature-h.tgz" + f := newLockFixture(t, `{"`+url+`":{}}`) + f.store.https[url] = lockDigestNew + f.writeLock(&feature.Lockfile{Features: map[string]feature.LockedFeature{ + url: {Version: "1.0.0", Resolved: url, Integrity: lockDigestOld}, + }}) + + var ie *feature.FeatureIntegrityError + if err := f.build(LockfileDefault); !errors.As(err, &ie) { + t.Fatalf("got %v, want *FeatureIntegrityError", err) + } +} + +// TestLockfile_KeepsEntryForFeatureBakedIntoBaseImage: a feature the +// base image's metadata label satisfies is not fetched, so its entry +// carries over rather than being dropped (which frozen mode would +// then reject on every run). +func TestLockfile_KeepsEntryForFeatureBakedIntoBaseImage(t *testing.T) { + f := newLockFixture(t, `{"ghcr.io/x/a:1":{},"ghcr.io/x/b:1":{}}`) + f.rt.imagesByRef["alpine:3.20"] = &runtime.ImageDetails{Labels: map[string]string{ + feature.MetadataLabel: `[{"id":"a","version":"1.0.0"}]`, + }} + locked := &feature.Lockfile{Features: map[string]feature.LockedFeature{ + "ghcr.io/x/a:1": ociEntry("ghcr.io/x/a", lockDigestOld), + "ghcr.io/x/b:1": ociEntry("ghcr.io/x/b", lockDigestOld), + }} + f.writeLock(locked) + + if err := f.build(LockfileFrozen); err != nil { + t.Fatal(err) + } + if want := []string{"ghcr.io/x/b@" + lockDigestOld}; !reflect.DeepEqual(f.store.fetched, want) { + t.Errorf("fetched %v, want only b", f.store.fetched) + } +} + +// TestLockfile_DotDevcontainerJSON: with a discovered root +// .devcontainer.json, the lockfile is .devcontainer-lock.json beside it +// and local features resolve relative to the workspace root. +func TestLockfile_DotDevcontainerJSON(t *testing.T) { + ws := t.TempDir() + body := `{"image":"alpine:3.20","features":{"ghcr.io/x/a:1":{},"./local":{}}}` + if err := os.WriteFile(filepath.Join(ws, ".devcontainer.json"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + store := &tagStore{dir: t.TempDir()} + eng, err := New(EngineOptions{Runtime: newFakeRuntime(), FeatureStore: store}) + if err != nil { + t.Fatal(err) + } + if _, err := eng.Build(context.Background(), BuildOptions{LocalWorkspaceFolder: ws}); !errors.Is(err, runtime.ErrNotImplemented) { + t.Fatalf("Build: %v", err) + } + lf, err := feature.ReadLockfile(filepath.Join(ws, ".devcontainer-lock.json")) + if err != nil || lf == nil { + t.Fatalf("no .devcontainer-lock.json: (%v, %v)", lf, err) + } + if want := filepath.Join(ws, "local"); !slices.Contains(store.fetched, want) { + t.Errorf("fetched %v, want local feature at %s", store.fetched, want) + } +} diff --git a/test/integration/lockfile_test.go b/test/integration/lockfile_test.go new file mode 100644 index 0000000..d07ee44 --- /dev/null +++ b/test/integration/lockfile_test.go @@ -0,0 +1,94 @@ +//go:build integration + +package integration + +import ( + "context" + "path/filepath" + "regexp" + "strings" + "testing" + "time" + + "github.com/google/go-containerregistry/pkg/name" + "github.com/google/go-containerregistry/pkg/v1/remote" + + devcontainer "github.com/crunchloop/devcontainer" + "github.com/crunchloop/devcontainer/feature" +) + +// TestLockfile_PublicGHCR resolves a public feature through Build (on +// Debian: the feature's install.sh needs bash, which alpine lacks), +// checks the lockfile records the registry's manifest digest for its +// tag, then shows a frozen Build fetches by the locked digest rather +// than the tag. +func TestLockfile_PublicGHCR(t *testing.T) { + if testing.Short() { + t.Skip() + } + eng, rt := newEngineWith(t, devcontainer.EngineOptions{FeatureCacheDir: t.TempDir()}) + defer rt.Close() + + dir := t.TempDir() + mustWrite(t, filepath.Join(dir, ".devcontainer", "devcontainer.json"), `{ + "image": "debian:bookworm-slim", + "features": { "`+publicFeatureRef+`": {} } + }`) + lockPath := filepath.Join(dir, ".devcontainer", "devcontainer-lock.json") + + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) + defer cancel() + build := func(mode devcontainer.LockfileMode) error { + _, err := eng.Build(ctx, devcontainer.BuildOptions{LocalWorkspaceFolder: dir, Lockfile: mode}) + return err + } + + if err := build(devcontainer.LockfileDefault); err != nil { + t.Fatalf("Build: %v", err) + } + lf, err := feature.ReadLockfile(lockPath) + if err != nil || lf == nil { + t.Fatalf("ReadLockfile: (%v, %v)", lf, err) + } + entry, ok := lf.Entry(publicFeatureRef) + if !ok { + t.Fatalf("no entry for %s: %+v", publicFeatureRef, lf) + } + + tag, err := name.ParseReference(publicFeatureRef) + if err != nil { + t.Fatal(err) + } + head, err := remote.Head(tag, remote.WithContext(ctx)) + if err != nil { + t.Fatalf("HEAD %s: %v", publicFeatureRef, err) + } + repo := tag.Context().Name() + if entry.Integrity != head.Digest.String() { + t.Errorf("integrity = %s, want manifest digest %s", entry.Integrity, head.Digest) + } + if want := repo + "@" + head.Digest.String(); entry.Resolved != want { + t.Errorf("resolved = %s, want %s", entry.Resolved, want) + } + if !regexp.MustCompile(`^1\.\d+\.\d+$`).MatchString(entry.Version) { + t.Errorf("version = %q, want the feature's full 1.x.y version", entry.Version) + } + + if err := build(devcontainer.LockfileFrozen); err != nil { + t.Fatalf("frozen Build with matching lockfile: %v", err) + } + + // Lock the tag to a digest the registry does not have: a frozen + // Build must fail fetching it, not quietly resolve the tag. + const missing = "sha256:0000000000000000000000000000000000000000000000000000000000000000" + entry.Integrity = missing + entry.Resolved = repo + "@" + missing + lf.Features[publicFeatureRef] = entry + if err := feature.WriteLockfile(lockPath, lf); err != nil { + t.Fatal(err) + } + err = build(devcontainer.LockfileFrozen) + if err == nil || !strings.Contains(err.Error(), missing) { + t.Fatalf("frozen Build with unknown locked digest: got %v, want a fetch error for %s", err, missing) + } +} diff --git a/up.go b/up.go index 89649b7..2d1a588 100644 --- a/up.go +++ b/up.go @@ -53,6 +53,13 @@ type UpOptions struct { // PullPolicy controls image pulling. Default IfNotPresent. PullPolicy PullPolicy + // Lockfile controls the feature lockfile (devcontainer-lock.json + // beside devcontainer.json). Default LockfileDefault: pin features + // to it and write it when what resolved differs, as the reference + // CLI does. Not consulted when Up starts or reattaches an existing + // container, since nothing is resolved then. + Lockfile LockfileMode + // Events optionally receives structured engine events for the duration // of this Up call (config resolved, feature resolve, build/pull // progress, container lifecycle, spec lifecycle phases). Drop-on-full; @@ -176,6 +183,14 @@ func (e *Engine) Up(ctx context.Context, opts UpOptions) (*Workspace, error) { return nil, fmt.Errorf("UpOptions.LocalWorkspaceFolder is required") } + // Fix the config path Resolve would discover: the lockfile, local + // features and compose files are all located beside it. + configPath, err := configPathFor(opts.LocalWorkspaceFolder, opts.ConfigPath) + if err != nil { + return nil, err + } + opts.ConfigPath = configPath + opts.bus = newEventBus(e.emitter, opts.Events) defer opts.bus.Close() @@ -493,14 +508,10 @@ func composeProjectName(cfg *config.ResolvedConfig) string { // composeWorkingDir picks the directory `docker compose` should run // in. Compose interprets relative paths in the user's compose file // (build contexts, env_file paths, volumes) relative to this. Default: -// the directory containing the source devcontainer.json. Falls back -// to LocalWorkspaceFolder when ConfigPath isn't supplied (Resolve's -// auto-discovery path). -func composeWorkingDir(cfg *config.ResolvedConfig, opts UpOptions) string { - if opts.ConfigPath != "" { - return filepath.Dir(opts.ConfigPath) - } - return filepath.Join(cfg.LocalWorkspaceFolder, ".devcontainer") +// the directory containing the source devcontainer.json, which Up +// always sets. +func composeWorkingDir(opts UpOptions) string { + return filepath.Dir(opts.ConfigPath) } // createFreshCompose handles the *ComposeSource path of Up. It loads @@ -534,7 +545,7 @@ func (e *Engine) createFreshCompose(ctx context.Context, cfg *config.ResolvedCon return nil, fmt.Errorf("compose source: devcontainer.json must specify \"service\"") } - workingDir := composeWorkingDir(cfg, opts) + workingDir := composeWorkingDir(opts) projectName := composeProjectName(cfg) envList := mapToEnvList(opts.LocalEnv) @@ -1274,16 +1285,13 @@ func (e *Engine) layerFeatures(ctx context.Context, cfg *config.ResolvedConfig, return baseImage, baseMeta, nil } - configDir := "" - // LocalWorkspaceFolder is always populated by Resolve; ConfigPath - // (where local features are relative to) lives only on the - // ResolveOptions. We re-derive configDir from what the user - // supplied via UpOptions; if neither is supplied use - // LocalWorkspaceFolder/.devcontainer as a sensible fallback. - if opts.ConfigPath != "" { - configDir = filepath.Dir(opts.ConfigPath) - } else { - configDir = filepath.Join(cfg.LocalWorkspaceFolder, ".devcontainer") + // Local features are relative to devcontainer.json; Up and Build + // always set ConfigPath. + configDir := filepath.Dir(opts.ConfigPath) + + lock, err := loadFeatureLock(opts.Lockfile, opts.ConfigPath) + if err != nil { + return "", nil, err } // Emit a Skipped event for features the base-image label satisfied @@ -1302,11 +1310,22 @@ func (e *Engine) layerFeatures(ctx context.Context, cfg *config.ResolvedConfig, if f.SourceKind == config.FeatureSourceLocal { ref = feature.ResolveLocalRef(configDir, f.Ref) } + pin, pinned := lock.pin(*f) + if pinned { + if ref, err = feature.PinnedRef(*f, pin); err != nil { + return "", nil, err + } + } opts.bus.Emit(events.FeatureResolveStartEvent{Ref: f.Ref}) fetched, err := e.featureStore.Fetch(ctx, ref, f.SourceKind) if err != nil { return "", nil, fmt.Errorf("fetch feature %s: %w", f.Ref, err) } + if pinned { + if err := feature.CheckIntegrity(*f, fetched, pin); err != nil { + return "", nil, err + } + } f.Dir = fetched.Dir f.ResolvedRef = fetched.ResolvedRef f.Metadata = fetched.Metadata @@ -1323,6 +1342,10 @@ func (e *Engine) layerFeatures(ctx context.Context, cfg *config.ResolvedConfig, cfg.Warnings = append(cfg.Warnings, mwarns...) } + if err := lock.commit(cfg.Features); err != nil { + return "", nil, err + } + // Re-order with fully-populated metadata so installsAfter / dependsOn apply. ordered, oWarns, err := feature.Order(cfg.Features, nil) if err != nil { diff --git a/up_compose_reattach.go b/up_compose_reattach.go index 19eb7e0..6f8cc5e 100644 --- a/up_compose_reattach.go +++ b/up_compose_reattach.go @@ -121,7 +121,7 @@ func (e *Engine) composeInputsHash(cfg *config.ResolvedConfig, opts UpOptions, p if baseImageID == "" { return "", fmt.Errorf("compose inputs hash: base image ID unknown") } - configDir := composeWorkingDir(cfg, opts) + configDir := composeWorkingDir(opts) features := make([]composeHashedFeature, 0, len(cfg.Features)) for _, f := range cfg.Features { hf := composeHashedFeature{Ref: f.Ref, SourceKind: f.SourceKind, Options: f.Options} diff --git a/up_compose_reattach_test.go b/up_compose_reattach_test.go index b055a6e..21ebde5 100644 --- a/up_compose_reattach_test.go +++ b/up_compose_reattach_test.go @@ -48,7 +48,7 @@ func newHashFixture(t *testing.T, dir, devcontainerJSON, composeYAML string) *ha src := cfg.Source.(*config.ComposeSource) project, err := compose.Load(context.Background(), compose.LoadOptions{ Files: src.Files, - WorkingDir: composeWorkingDir(cfg, opts), + WorkingDir: composeWorkingDir(opts), ProjectName: composeProjectName(cfg), Env: mapToEnvList(opts.LocalEnv), }) @@ -289,7 +289,7 @@ func (f *hashFixture) reattach(t *testing.T) error { t.Fatal(err) } _, err = f.eng.reattachCompose(context.Background(), f.cfg, f.opts, f.project, src, primary, - composeProjectName(f.cfg), composeWorkingDir(f.cfg, f.opts)) + composeProjectName(f.cfg), composeWorkingDir(f.opts)) return err }