Skip to content

bundler: fix stale HTML-import manifest etag across rebuilds - #29233

Merged
Jarred-Sumner merged 3 commits into
mainfrom
dylan/html-manifest-etag
Apr 13, 2026
Merged

Jarred-Sumner merged 3 commits into
mainfrom
dylan/html-manifest-etag

Conversation

@dylan-conway

@dylan-conway dylan-conway commented Apr 12, 2026 •

Copy link
Copy Markdown
Member

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 #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.

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).
@robobun

robobun commented Apr 12, 2026 •

Copy link
Copy Markdown
Collaborator
Updated 6:28 PM PT - Apr 12th, 2026

✅ @dylan-conway, your commit ac4a689f91de7fc48cbfe3e05771a793d55f6dee passed in Build #45386! 🎉


🧪   To try this PR locally:

bunx bun-pr 29233

That installs a local version of the PR into your bun-29233 executable, so you can run:

bun-29233 --bun

@github-actions

Copy link
Copy Markdown
Contributor

Found 1 issue this PR may fix:

  1. Bun.build does not update hash/etag for HTML entrypoint when dependencies/assets change #23009 - Reports the exact bug fixed here: HTML entrypoint hash/etag doesn't update when JS/CSS dependencies change, causing browsers to serve stale cached HTML with outdated asset references (blank pages until hard refresh)

If this is helpful, copy the block below into the PR description to auto-close this issue on merge.

Fixes #23009

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Apr 12, 2026 •

Copy link
Copy Markdown
Contributor

Walkthrough

Modified 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

Cohort / File(s) Summary
ETag Calculation
src/bundler/HTMLImportManifest.zig
ETag generation now prefers ch.template.placeholder.hash when present, falling back to ch.isolated_hash.
Hash Traversal / Linker
src/bundler/LinkerContext.zig
appendIsolatedHashesForImportedChunks now traverses output-piece references for .asset, .chunk, and .scb kinds (recursively invoking for chunks and mapping SCB to entry-point chunk index); ignores .none and .html_import.
Tests
test/bundler/html-import-manifest.test.ts
Updated snapshots to reflect new ETag values, added utilities for temp fixtures, and added a concurrent test that rebuilds after modifying a referenced chunk to assert path stability and ETag changes.
🚥 Pre-merge checks | ✅ 2
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and specifically identifies the main fix: correcting a stale HTML-import manifest etag issue across rebuilds.
Description check ✅ Passed The PR description comprehensively explains what the PR does, provides clear technical rationale, and includes verification details with a new test case.

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


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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 | 🟠 Major

Don't exclude .html_import from transitive chunk hashing.

src/bundler/Chunk.zig:320-475 formats .html_import pieces by splicing HTMLImportManifest.formatEscapedJSON(...) into the chunk body. Skipping that kind here means an importer chunk can still keep the same template.placeholder.hash even 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

📥 Commits

Reviewing files that changed from the base of the PR and between 7c75a87 and fe4ad01.

📒 Files selected for processing (3)
  • src/bundler/HTMLImportManifest.zig
  • src/bundler/LinkerContext.zig
  • test/bundler/html-import-manifest.test.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between fe4ad01 and ac4a689.

📒 Files selected for processing (1)
  • test/bundler/html-import-manifest.test.ts

Comment on lines +367 to +371
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);`,
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ 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 40

Repository: 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.ts

Repository: 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.ts

Repository: 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 100

Repository: 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.ts

Repository: 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.

Suggested change
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.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);
},
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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:

  1. Test runner calls tempDirWithFiles("html-etag", { ... }) → returns e.g. /tmp/bun-test-html-etag-abc123 as a plain string.
  2. Two buildAndReadManifest() calls run, writing files into /tmp/bun-test-html-etag-abc123/out/.
  3. Test assertions pass. The test() callback returns/resolves.
  4. Because dir is a plain string, no [Symbol.asyncDispose] is called. The directory remains on disk indefinitely.

@Jarred-Sumner
Jarred-Sumner merged commit d35774f into main Apr 13, 2026
65 checks passed
@Jarred-Sumner
Jarred-Sumner deleted the dylan/html-manifest-etag branch April 13, 2026 04:54
structwafel pushed a commit to structwafel/bun that referenced this pull request Apr 25, 2026
…#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>
xhjkl pushed a commit to xhjkl/bun that referenced this pull request May 14, 2026
…#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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bun.build does not update hash/etag for HTML entrypoint when dependencies/assets change

3 participants