Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down
12 changes: 12 additions & 0 deletions build.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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()

Expand Down Expand Up @@ -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,
Expand Down
13 changes: 13 additions & 0 deletions cmd/devcontainer/up.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ func newUpCmd(rf *rootFlags) *cobra.Command {
recreate bool
runInitializeCommand bool
runSecretsCommand bool
frozenLockfile bool
noLockfile bool
)

cmd := &cobra.Command{
Expand All @@ -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()
Expand All @@ -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
}
60 changes: 60 additions & 0 deletions design/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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@<integrity>` 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.

Expand Down
26 changes: 16 additions & 10 deletions devcontainer.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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"),
Expand Down
Loading
Loading