Repository navigation
bundler: fix stale HTML-import manifest etag across rebuilds - #29233
Conversation
The HTML chunk's manifest etag was its isolated_hash, which by design excludes the slots where child-chunk paths are substituted. So when only a referenced JS/CSS chunk changed, the HTML body changed (it embeds `/chunk-<hash>.js`) but its etag did not, and Bun.serve would 304 to a body that referenced chunks the new build no longer served. appendIsolatedHashesForImportedChunks now also recurses on .chunk/.scb output pieces (HTML chunks reference their JS/CSS via pieces only, not via cross_chunk_imports), and the manifest emits each chunk's template.placeholder.hash — the transitive hash — instead of isolated_hash. JS/CSS chunk filenames are unchanged (their piece-chunk references are already covered by cross_chunk_imports and skipped via the visit map).
|
Updated 6:28 PM PT - Apr 12th, 2026
✅ @dylan-conway, your commit ac4a689f91de7fc48cbfe3e05771a793d55f6dee passed in 🧪 To try this PR locally: bunx bun-pr 29233That installs a local version of the PR into your bun-29233 --bun |
|
Found 1 issue this PR may fix:
🤖 Generated with Claude Code |
WalkthroughModified ETag hash calculation in HTML import manifests to prefer placeholder hashes when present, and expanded hash traversal to include chunk and SCB piece references. Updated test snapshots and added a test validating ETag changes when referenced chunks are modified. Changes
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/bundler/LinkerContext.zig (1)
1513-1537:⚠️ Potential issue | 🟠 MajorDon't exclude
.html_importfrom transitive chunk hashing.
src/bundler/Chunk.zig:320-475formats.html_importpieces by splicingHTMLImportManifest.formatEscapedJSON(...)into the chunk body. Skipping that kind here means an importer chunk can still keep the sametemplate.placeholder.hasheven though its emitted JS bytes changed because the embedded manifest changed. That leaves stale hashed JS output / ETags one level up, which is the same cache-invalidation bug pattern this PR is fixing for HTML entries.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bundler/LinkerContext.zig` around lines 1513 - 1537, The switch over piece.query.kind currently skips .html_import, causing embedded HTML manifest changes to be ignored in transitive chunk hashing; add a .html_import branch that calls c.appendIsolatedHashesForImportedChunks with the same arguments used for the .scb branch (i.e., pass hash, chunks, c.graph.files.items(.entry_point_chunk_index)[piece.query.index], chunk_visit_map) so HTMLImportManifest.formatEscapedJSON changes are accounted for in the chunk hash.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@src/bundler/LinkerContext.zig`:
- Around line 1513-1537: The switch over piece.query.kind currently skips
.html_import, causing embedded HTML manifest changes to be ignored in transitive
chunk hashing; add a .html_import branch that calls
c.appendIsolatedHashesForImportedChunks with the same arguments used for the
.scb branch (i.e., pass hash, chunks,
c.graph.files.items(.entry_point_chunk_index)[piece.query.index],
chunk_visit_map) so HTMLImportManifest.formatEscapedJSON changes are accounted
for in the chunk hash.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9af58688-5ac9-4df4-8de0-147e9673bfbf
📒 Files selected for processing (3)
src/bundler/HTMLImportManifest.zigsrc/bundler/LinkerContext.zigtest/bundler/html-import-manifest.test.ts
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@test/bundler/html-import-manifest.test.ts`:
- Around line 367-371: Replace the use of tempDirWithFiles with tempDir to get a
DisposableString and write the fixture files explicitly using writeFileSync so
the test harness can clean up via using; locate the test that currently calls
tempDirWithFiles("html-etag", {...}) and change it to call tempDir("html-etag")
(or similar), then after obtaining the DisposableString call writeFileSync to
create "server.ts", "index.html", and "app.ts" with the same contents, ensuring
the DisposableString is disposed via the using block; update any variable names
around tempDirWithFiles to reflect tempDir/DisposableString so the test cleanup
runs correctly.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: ada401b4-6645-4b0f-9b1d-b7e8fc19bc45
📒 Files selected for processing (1)
test/bundler/html-import-manifest.test.ts
| const dir = tempDirWithFiles("html-etag", { | ||
| "server.ts": `import m from "./index.html"; console.log(JSON.stringify(m));`, | ||
| "index.html": `<!doctype html><script type="module" src="./app.ts"></script>`, | ||
| "app.ts": `console.log(1);`, | ||
| }); |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and read the context around the mentioned lines
head -n 380 test/bundler/html-import-manifest.test.ts | tail -n 40Repository: oven-sh/bun
Length of output: 1603
🏁 Script executed:
# Check imports at the top of the file
head -n 30 test/bundler/html-import-manifest.test.tsRepository: oven-sh/bun
Length of output: 841
🏁 Script executed:
# Search for all uses of tempDirWithFiles in this test file
rg "tempDirWithFiles" test/bundler/html-import-manifest.test.tsRepository: oven-sh/bun
Length of output: 146
🏁 Script executed:
# Check if there's explicit cleanup (like fs.rmSync) for the dir variable
rg -A 50 "tempDirWithFiles.*html-etag" test/bundler/html-import-manifest.test.ts | head -n 100Repository: oven-sh/bun
Length of output: 2103
🏁 Script executed:
# Check the full context of this test to see if dir is cleaned up explicitly
sed -n '360,400p' test/bundler/html-import-manifest.test.tsRepository: oven-sh/bun
Length of output: 1747
Use tempDir with explicit file writes to match test harness guidelines and enable proper cleanup.
The test currently uses tempDirWithFiles, which returns a plain string and does not enable automatic cleanup. Per the test harness guidelines and learnings, switch to tempDir (which returns a DisposableString) and write fixture files explicitly with writeFileSync. This ensures proper resource cleanup via the using statement.
Refactor
-import { tempDirWithFiles } from "harness";
+import { tempDir } from "harness";
import { readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
@@
- const dir = tempDirWithFiles("html-etag", {
- "server.ts": `import m from "./index.html"; console.log(JSON.stringify(m));`,
- "index.html": `<!doctype html><script type="module" src="./app.ts"></script>`,
- "app.ts": `console.log(1);`,
- });
+ using dir = tempDir("html-etag");
+ writeFileSync(join(dir, "server.ts"), `import m from "./index.html"; console.log(JSON.stringify(m));`);
+ writeFileSync(join(dir, "index.html"), `<!doctype html><script type="module" src="./app.ts"></script>`);
+ writeFileSync(join(dir, "app.ts"), `console.log(1);`);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const dir = tempDirWithFiles("html-etag", { | |
| "server.ts": `import m from "./index.html"; console.log(JSON.stringify(m));`, | |
| "index.html": `<!doctype html><script type="module" src="./app.ts"></script>`, | |
| "app.ts": `console.log(1);`, | |
| }); | |
| using dir = tempDir("html-etag"); | |
| writeFileSync(join(dir, "server.ts"), `import m from "./index.html"; console.log(JSON.stringify(m));`); | |
| writeFileSync(join(dir, "index.html"), `<!doctype html><script type="module" src="./app.ts"></script>`); | |
| writeFileSync(join(dir, "app.ts"), `console.log(1);`); |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@test/bundler/html-import-manifest.test.ts` around lines 367 - 371, Replace
the use of tempDirWithFiles with tempDir to get a DisposableString and write the
fixture files explicitly using writeFileSync so the test harness can clean up
via using; locate the test that currently calls tempDirWithFiles("html-etag",
{...}) and change it to call tempDir("html-etag") (or similar), then after
obtaining the DisposableString call writeFileSync to create "server.ts",
"index.html", and "app.ts" with the same contents, ensuring the DisposableString
is disposed via the using block; update any variable names around
tempDirWithFiles to reflect tempDir/DisposableString so the test cleanup runs
correctly.
There was a problem hiding this comment.
This PR touches the bundler's hash computation in the linker and HTML manifest generation — non-trivial production-critical paths that warrant a human look despite the targeted and well-explained fix.
Extended reasoning...
Overview\nThis PR modifies and to fix a caching bug where the HTML chunk's manifest etag didn't change when only referenced JS/CSS chunks changed. The fix has two parts: (1) now recurses on / output pieces in addition to pieces, and (2) the manifest emits (transitive hash) instead of for etag values. Snapshot updates in the test file reflect the new etag values.\n\n### Security risks\nNo security risks identified. The change affects hash/etag computation for HTTP caching, not auth or data access.\n\n### Level of scrutiny\nHigh. The modified code lives in the bundler's linker and directly affects chunk hashing logic that determines cache invalidation behavior. Incorrect changes here could cause either over-invalidation (performance regression) or under-invalidation (serving stale content). While the fix is logically sound and well-commented, this warrants a human reviewer who is familiar with the chunk hashing system to verify the visit-map interaction for non-HTML chunk types.\n\n### Other factors\nThe only bug found is a nit: the new test uses (returns a plain string, no cleanup) instead of the pattern prescribed for standalone blocks. This is a minor leak with no functional impact on CI. The existing snapshots passing after the etag changes provides good evidence the JS/CSS chunk filenames are unaffected.
| @@ -357,6 +360,41 @@ console.log("About manifest:", aboutHtml); | |||
| }, | |||
| }); | |||
|
|
|||
There was a problem hiding this comment.
🟡 The new test uses tempDirWithFiles which returns a plain string with no disposal mechanism, so the temp directory is never cleaned up after the test. Per project convention and CLAUDE.md, tests should use using dir = tempDir(...) which wraps the path in a DisposableString implementing Symbol.dispose/Symbol.asyncDispose for automatic cleanup.
Extended reasoning...
What the bug is: The test html-import/etag-changes-with-referenced-chunks at line 362 of test/bundler/html-import-manifest.test.ts uses tempDirWithFiles from harness to create a temporary directory. This function returns a plain string with no disposal mechanism attached. Without a Symbol.dispose or Symbol.asyncDispose method, the using / await using declarator cannot be applied, and consequently Bun's explicit-resource-management cleanup never fires.
The code path: tempDir (harness.ts:277) returns a DisposableString that wraps the path and implements both Symbol.dispose (calling fs.rmSync) and Symbol.asyncDispose (calling fs.promises.rm). tempDirWithFiles (harness.ts:259) internally calls a different helper and returns the path as a raw string. Because string has no Symbol.dispose, using const dir = tempDirWithFiles(...) — rather than await using dir = tempDir(...) — means the directory is never removed.
Why existing code does not prevent it: TypeScript accepts const dir = tempDirWithFiles(...) without error because the variable is simply typed as string; there is no type-level enforcement that a temp dir must use the using pattern. The test finishes successfully, the assertion passes, but the cleanup side-effect silently never happens.
Impact: Each test run leaks a directory under /tmp (or the OS temp location). In most CI environments /tmp is wiped between jobs, so this is rarely noticed in practice. On developer machines or long-lived CI agents that share /tmp, repeated test runs accumulate stale directories. The test is otherwise functionally correct.
Addressing the refutation: The refutation notes that tempDirWithFiles appears in CLAUDE.md's "Common Imports" section and is used ~957 times across 179 files. This is accurate — tempDirWithFiles is a legitimate utility. However, the usage pattern here is a new standalone test() block (not an itBundled callback that supplies its own directory management), which is exactly the context where tempDir + using is the prescribed pattern per CLAUDE.md line 127. The widespread use of tempDirWithFiles elsewhere is in contexts where cleanup is either handled differently or intentionally deferred; this test has no other cleanup path.
How to fix: Replace the tempDirWithFiles call with tempDir and use await using:
// Before
const dir = tempDirWithFiles("html-etag", { ... });
// After
await using dir = tempDir("html-etag", { ... });tempDir accepts an optional second argument for initial file contents in newer versions, or the files can be written manually after creation. Either way, the DisposableString returned will trigger fs.promises.rm(dir, { recursive: true }) when the test exits.
Step-by-step proof of the leak:
- Test runner calls
tempDirWithFiles("html-etag", { ... })→ returns e.g./tmp/bun-test-html-etag-abc123as a plainstring. - Two
buildAndReadManifest()calls run, writing files into/tmp/bun-test-html-etag-abc123/out/. - Test assertions pass. The
test()callback returns/resolves. - Because
diris a plainstring, no[Symbol.asyncDispose]is called. The directory remains on disk indefinitely.
…#29233) ## What does this PR do? The HTML chunk's manifest `etag` was its `isolated_hash`, which by design hashes the output pieces *between* unique-key placeholders — i.e. it excludes the slots where child-chunk paths are substituted. So when only a referenced JS/CSS chunk changed, the served HTML body changed (it embeds `/chunk-<hash>.js`) but its etag did not. `Bun.serve` would then 304 to a cached body that referenced chunks the new build no longer served, leaving the page blank until a hard refresh. Fix: - `appendIsolatedHashesForImportedChunks` now also recurses on `.chunk`/`.scb` output pieces. HTML chunks reference their JS/CSS via pieces only (their `cross_chunk_imports` is empty), so without this their transitive hash never folded in children. For JS chunks the visit map makes the new recursion a no-op since those pieces are already reached via `cross_chunk_imports`. - `HTMLImportManifest` emits each chunk's `template.placeholder.hash` (the transitive hash) instead of `isolated_hash`. JS/CSS chunk filenames are unchanged (verified by the existing snapshots — only `etag` values moved). Fixes oven-sh#23009 ## How did you verify your code works? New test `html-import/etag-changes-with-referenced-chunks` builds the same HTML import twice with different JS content and asserts the HTML `etag` differs while the HTML `path` stays the same. Fails on `main`, passes here. --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
…#29233) ## What does this PR do? The HTML chunk's manifest `etag` was its `isolated_hash`, which by design hashes the output pieces *between* unique-key placeholders — i.e. it excludes the slots where child-chunk paths are substituted. So when only a referenced JS/CSS chunk changed, the served HTML body changed (it embeds `/chunk-<hash>.js`) but its etag did not. `Bun.serve` would then 304 to a cached body that referenced chunks the new build no longer served, leaving the page blank until a hard refresh. Fix: - `appendIsolatedHashesForImportedChunks` now also recurses on `.chunk`/`.scb` output pieces. HTML chunks reference their JS/CSS via pieces only (their `cross_chunk_imports` is empty), so without this their transitive hash never folded in children. For JS chunks the visit map makes the new recursion a no-op since those pieces are already reached via `cross_chunk_imports`. - `HTMLImportManifest` emits each chunk's `template.placeholder.hash` (the transitive hash) instead of `isolated_hash`. JS/CSS chunk filenames are unchanged (verified by the existing snapshots — only `etag` values moved). Fixes oven-sh#23009 ## How did you verify your code works? New test `html-import/etag-changes-with-referenced-chunks` builds the same HTML import twice with different JS content and asserts the HTML `etag` differs while the HTML `path` stays the same. Fails on `main`, passes here. --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
What does this PR do?
The HTML chunk's manifest
etagwas itsisolated_hash, which by design hashes the output pieces between unique-key placeholders — i.e. it excludes the slots where child-chunk paths are substituted. So when only a referenced JS/CSS chunk changed, the served HTML body changed (it embeds/chunk-<hash>.js) but its etag did not.Bun.servewould then 304 to a cached body that referenced chunks the new build no longer served, leaving the page blank until a hard refresh.Fix:
appendIsolatedHashesForImportedChunksnow also recurses on.chunk/.scboutput pieces. HTML chunks reference their JS/CSS via pieces only (theircross_chunk_importsis empty), so without this their transitive hash never folded in children. For JS chunks the visit map makes the new recursion a no-op since those pieces are already reached viacross_chunk_imports.HTMLImportManifestemits each chunk'stemplate.placeholder.hash(the transitive hash) instead ofisolated_hash.JS/CSS chunk filenames are unchanged (verified by the existing snapshots — only
etagvalues moved).Fixes #23009
How did you verify your code works?
New test
html-import/etag-changes-with-referenced-chunksbuilds the same HTML import twice with different JS content and asserts the HTMLetagdiffers while the HTMLpathstays the same. Fails onmain, passes here.