runtime: select BuildKit explicitly + fix tar symlink encoding

[bilby91]

Summary

• runtime/docker/build.go was calling ImageBuild without setting ImageBuildOptions.Version, so dockerd routed every build through its classic builder. Classic synthesizes one intermediate container per Dockerfile step; each container API call is authz-checked. Behind an authz plugin this turns a sub-second build into a multi-minute one (~140× slowdown observed on a 7-step Dockerfile against a 7.7GB base — production uid_reconcile builds were taking ~200s where BuildKit takes ~1.5s on the same host).
• Setting Version: build.BuilderBuildKit is sufficient — the moby /build endpoint accepts a tar request body in BuildKit mode, so no session / filesync wiring is required (verified empirically against a real dockerd before writing the patch). This avoids pulling in github.com/moby/buildkit as a direct dep.
• Per-step progress events are dropped under BuildKit (aux records are protobuf-encoded and decoding requires the buildkit module). BuildStart / BuildCompleted still fire and errors still propagate; per-vertex progress is deferred to a future PR if needed.
• Fix a long-standing bug in tarDirectory: symlinks were emitted as TypeSymlink with an empty Linkname, which some tar readers reject as malformed. Common in compose contexts containing node_modules/.bin/* or similar bin-symlinks. Now os.Readlink(path) is passed to tar.FileInfoHeader.
• Drop the # syntax=docker/dockerfile:1.4 directive from feature/dockerfile.go: classic ignored it, but BuildKit treats it as a hard frontend-pull requirement that needs a session for credential forwarding (we don't open one) and hangs behind broken registry mirrors. Emitted Dockerfile uses no 1.4-only syntax. The identical fix in useruid.go is on branch fix/uid-reconcile-syntax-directive.

BuildKit is now a hard requirement. Docker Engine has shipped with BuildKit enabled by default since 23.0 (Feb 2023); this is in line with the lib's modern-spec stance.

Test plan

• Unit tests pass (go test ./...)
• New integration test TestBuildContext_SurvivesSymlinks builds a workspace whose context contains an unreferenced symlink — regression guard for the tar encoding bug
• Existing integration tests pass (go test -tags integration ./test/integration/, ~52s)
• Frontend-directive regression guard added to feature/dockerfile_test.go
• Verified against local dockerd: Version=BuilderBuildKit + tar request body builds successfully without a session

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Build contexts preserve symlinks so unreferenced symlinked files won’t break builds.
  • Docker builds now enforce BuildKit for consistent build behavior.
  • Generated Dockerfiles no longer include the syntax directive comment.

• Tests

  • Added integration test validating symlink preservation in build contexts.
  • Added unit tests covering Dockerfile base-image extraction and build-arg substitution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7c618ab3-c757-4cbf-946e-9626722a901d

📥 Commits

Reviewing files that changed from the base of the PR and between 7f942c8 and 9d3dcc1.

📒 Files selected for processing (1)

• runtime/docker/build_test.go

🚧 Files skipped from review as they are similar to previous changes (1)

• runtime/docker/build_test.go

---

📝 Walkthrough

Walkthrough

Removes the generated Dockerfile # syntax= directive, enforces BuildKit for image builds, pre-pulls resolved base images, preserves symlinks in build-context tar archives, and adds unit and integration tests for parsing, substitution, and symlink survival.

Changes

Docker BuildKit and symlink handling

Layer / File(s)	Summary
Dockerfile syntax directive removal feature/dockerfile.go, feature/dockerfile_test.go	generateDockerfile no longer emits a # syntax= frontend directive; tests updated to assert no # syntax= lines appear.
BuildKit enforcement, pre-pull, and helpers runtime/docker/build.go	Import BuildKit build types, set client.ImageBuildOptions.Version = build.BuilderBuildKit, add prePullBaseImages, extractBaseImages, and substitution helpers, and expand streamBuildOutput docs.
Build context symlink preservation runtime/docker/build.go	tarDirectory preserves symlinks as tar.TypeSymlink using os.Readlink for linkname and skips reading symlink target contents when archiving.
Integration test for symlink handling test/integration/build_context_symlink_test.go	New integration test (build-tagged integration) creates a temp workspace with a real file and a relative symlink, runs eng.Up, and asserts the built image produced the expected marker.
Unit tests for Dockerfile parsing and substitution runtime/docker/build_test.go	New unit tests for extractBaseImages and substituteArgs covering multiple Dockerfile scenarios and variable forms.

Sequence Diagram(s)

sequenceDiagram
  participant PrePull as prePullBaseImages
  participant Tar as tarDirectory
  participant DockerClient as ImageBuild
  participant Stream as streamBuildOutput

  PrePull->>DockerClient: pull resolved base images (best-effort)
  Tar->>DockerClient: stream build context tar (symlinks preserved)
  DockerClient->>Stream: emit build JSON-line records (BuildKit/classic)
  Stream->>Client: forward parsed output lines

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• crunchloop/devcontainer#48: Also removes a # syntax= Dockerfile frontend directive from generated Dockerfiles and adds tests to prevent reintroduction.

"🐰
I skip the Dockerfile cue tonight,
BuildKit hums and builds just right,
Symlinks tucked into the tar so neat,
Tests confirm our build's heartbeat,
Hops of joy for builds complete!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the two main changes: BuildKit selection and tar symlink encoding fixes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/buildkit-builder

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@runtime/docker/build_test.go`:
- Around line 8-14: The TestExtractBaseImages test struct has inconsistent field
alignment causing gofmt to fail; open the struct in TestExtractBaseImages and
reformat the fields (name, dockerfile, buildArgs, want) to have consistent
spacing/indentation, then run gofmt -w runtime/docker/build_test.go (or run your
editor's gofmt) to apply the canonical formatting so CI passes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51eb8f8e-cb43-4c1d-b036-07011f5104e1

📥 Commits

Reviewing files that changed from the base of the PR and between 7873300 and 7f942c8.

📒 Files selected for processing (2)

• runtime/docker/build.go
• runtime/docker/build_test.go