Skip to content

Static assets, in standalone workerd - #8475

Open
ry wants to merge 1 commit into
mainfrom
ry/assets
Open

ry wants to merge 1 commit into
mainfrom
ry/assets

Conversation

@ry

@ry ry commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Adds an assets service to workerd: a directory served the way Cloudflare serves a Worker's static assets. Its router sends each request to the user Worker or to a file, following run_worker_first, html_handling, not_found_handling, base_path, _headers, _redirects and .assetsignore as production does. Its AssetWorker entrypoint backs a Worker's ASSETS binding. Every event other than an HTTP request (JS RPC, scheduled, tail) goes to the user Worker.

It is native Rust in the server crate. The routing, the rule parsers and the response headers are side-effect-free code ported from workers-sdk's workers-shared; the service itself only stats files, streams them and hands requests to the user Worker. Files are looked up as requests arrive, so nothing scans the directory at startup and edits are served immediately. With --experimental, assets in wrangler.json maps onto it.

Performance

An earlier revision of this PR implemented the same port in JS: a bundled Worker that read files through a disk service. Both revisions measured with wrk against a 4 vCPU VM, requests/sec.

In front of a Worker:

Path Previous revision (JS) This PR (native) Speedup
/style.css 3558 8200 2.3x
/about 3440 8472 2.5x
/about.html 4314 11056 2.6x
/api/users 3040 10596 3.5x

Assets only, no Worker:

Path Previous revision (JS) This PR (native) Speedup
/style.css 3994 8631 2.2x
/about 3913 8657 2.2x
/about.html 5090 10924 2.1x
/api/users (404) 4043 11447 2.8x

For reference, a Worker that returns a constant response, with nothing in front of it, does about 12k on this VM. The JS revision paid one extra Worker hop per request and about 60µs per file lookup. Native p99 on file paths is ~9ms vs ~90ms, and with run_worker_first: true it reaches that 12k (JS: 6.4k). Code size: native is +2492 non-test lines vs +1704 for JS.

Miniflare

No lockstep upgrade: unmodified Miniflare doesn't use this service, and its assets and core tests pass against this build. Miniflare pins an exact workerd version, so it adopts the service when it bumps that pin. The Miniflare side is cloudflare/workers-sdk#16932: it replaces Miniflare's own copies of the router, asset and assets-KV Workers, plus its RPC proxy, with this one service: +166 −663 lines, 105 of the added lines being generated config types.

@ry
ry requested review from a team as code owners November 15, 2026 17:30

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 8c619c4e.

This review, of 4ed123fc

🛑 Significant concerns — 1 BLOCKING: an empty, comment-only or all-invalid _redirects file makes every asset request throw a TypeError. There are also 2 WARNINGs: fields silently dropped when main is omitted, and the README's list of supported Wrangler fields is out of date.

Findings: 1 blocking · 2 warnings · 1 info · 2 suggestions (5 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8475.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## BLOCKING (1)

### [Code Quality] An empty, comment-only or all-invalid `_redirects` file leaves the raw text in `configuration.redirects`, so `staticRedirectsMatcher` throws on every request
- **File:** src/workerd/server/assets/assets.js:1345

## WARNING (2)

### [Code Quality] With `assets` and no `main`, Worker-only fields (`vars`, `durable_objects`, `queues`, `workflows`, `triggers.crons`, …) are silently dropped or point at a Worker that doesn't exist
- **File:** src/workerd/server/cli/wrangler.rs:392

### [Documentation] README says any field not listed is an error, but `assets` (with `--experimental`) is now supported and `main` is optional when `assets` is set
- **File:** README.md:115

## INFO (1)

### [Code Quality] `serve()` resolves on the child's `exit` event, which can fire before stderr has been drained, so the stderr assertions may flake
- **File:** src/workerd/server/tests/assets/assets-wrangler-test.mjs:65

## SUGGESTION (2)

### [Security] Dotfiles such as `.git/` and `.env` are served from the assets directory by default; consider adding them to the default ignore list as Wrangler does
- **File:** src/workerd/server/cli/wrangler.rs:610

### [Code Quality] `exists()` assumes the disk service always sends an ETag, but the disk service only sets it when the file's modification time can be read
- **File:** src/workerd/server/assets/assets.js:1310

📋 Code Quality: 🛑 1 blocking · 1 warning · 1 info · 1 suggestion

An empty or invalid _redirects crashes every request. Fields are silently dropped without main. Two smaller robustness notes.

Recommendation: 🔴 Serious Concerns

  • [BLOCKING] An empty, comment-only or all-invalid _redirects file leaves the raw text in configuration.redirects, so staticRedirectsMatcher throws on every request (src/workerd/server/assets/assets.js:1345)
  • [WARNING] With assets and no main, Worker-only fields (vars, durable_objects, queues, workflows, triggers.crons, …) are silently dropped or point at a Worker that doesn't exist (src/workerd/server/cli/wrangler.rs:392)
  • [INFO] serve() resolves on the child's exit event, which can fire before stderr has been drained, so the stderr assertions may flake (src/workerd/server/tests/assets/assets-wrangler-test.mjs:65)
  • [SUGGESTION] exists() assumes the disk service always sends an ETag, but the disk service only sets it when the file's modification time can be read (src/workerd/server/assets/assets.js:1310)
View full review

1. Empty or invalid _redirects crashes every request (BLOCKING). load() passes ...config into normalizeConfiguration, so redirects and headers hold the raw file text from wrangler.rs (assets.js:1345). constructRedirects returns {} when redirects.rules.length === 0 (assets.js:1114). That happens for an empty file, a comment-only file, or one where every rule is invalid. The raw string therefore survives configuration?.redirects ?? {...} (assets.js:190). staticRedirectsMatcher then reads .staticRules off a string and indexes undefined (assets.js:259-260). An empty _redirects is a common scaffold. _headers leaks the same way: it doesn't crash, but the per-configuration compile cache never hits for it. Fix: clear redirects and headers before spreading in the parsed versions. Add a regression test that loads _redirects text of "" and of "# comment\n".

2. Fields silently dropped without main (WARNING). When main is absent, workers == 0 and set_bindings, set_workflows_engine and set_durable_objects never run (wrangler.rs:384-428). vars, durable_objects and similar fields are accepted and ignored. queues, workflows and triggers.crons still generate services that target a Worker that doesn't exist. This contradicts the module's rule that an unsupported field is an error. Reject these fields with a clear message when main is missing.

3. Missing ETag throws (SUGGESTION). exists() calls res.headers.get('ETag').slice(...) unconditionally (assets.js:1310). The disk service only sets ETag when metadata.modified() succeeds.

4. Possible test flake (INFO). serve() in assets-wrangler-test.mjs resolves on the child's exit event. That event can fire before stderr has been drained, so the assertions on refused.stderr can see empty output. Resolve on close instead.


🔒 Security: 💬 1 suggestion

No exploitable issues. One hardening note: dotfiles are served by default.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] Dotfiles such as .git/ and .env are served from the assets directory by default; consider adding them to the default ignore list as Wrangler does (src/workerd/server/cli/wrangler.rs:610)
View full review

Path handling holds up. Paths are percent-decoded, . and .. segments are rejected, and segments are re-encoded before the disk request.

The FILES disk service allows dotfiles. The default ignore list only covers .assetsignore, _redirects and _headers. If the assets directory contains .git/, .env or node_modules, they are served, whereas Wrangler leaves such files out of uploads by default. The impact is low because this is a local server over a directory the user chose.


📝 Documentation: ⚠️ 1 warning

The README's list of supported Wrangler fields is out of date.

Recommendation: 📝 Minor Comments

  • [WARNING] README says any field not listed is an error, but assets (with --experimental) is now supported and main is optional when assets is set (README.md:115)
View full review

README.md:111-116 lists the supported Wrangler fields and says that any other field is an error. With this change, assets is accepted under --experimental and main is optional when assets is set. Neither appears in that list.


✅ All other checks passed

📖 AGENTS.md: ✅ LGTM

No AGENTS.md issues in the changed files.


⚡ Performance: ✅ LGTM

No performance issues found. The per-request lookup memoization and the cost figures in the description are reasonable for a first version.


Reviewed commit: 4ed123fc

Comment thread src/workerd/server/assets/assets.js Resolved
Comment thread src/workerd/server/cli/wrangler.rs Resolved
Comment thread src/workerd/server/cli/wrangler.rs Resolved
Comment thread src/workerd/server/assets/assets.js Resolved

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 95c503d1.

This review, of 8c619c4e

⚠️ Minor issues — The earlier _redirects crash is fixed in the Rust port, so nothing blocks this pull request. There are 4 WARNINGs: HEAD responses send Content-Length: 0, Worker-only fields are silently dropped when main is omitted, src/workerd/server/BUILD.bazel switched to crate labels that may not resolve, and the README's list of supported Wrangler fields is out of date.

Findings: 4 warnings · 3 info · 1 suggestion (5 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8475.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (4)

### [Code Quality] HEAD requests for an asset are answered with `Content-Length: 0` instead of the file's size
- **File:** src/workerd/server/server/services/assets/mod.rs:293

### [Code Quality] With `assets` and no `main`, Worker-only fields (`vars`, `durable_objects`, `queues`, `workflows`, `triggers.crons`) are still silently dropped or target a Worker that doesn't exist
- **File:** src/workerd/server/cli/wrangler.rs:392

### [Code Quality] Crate deps rewritten to `@crates_vendor//name`, while every other label uses the hub's `@crates_vendor//:name` aliases. This could not be checked against the generated repository in this run.
- **File:** src/workerd/server/BUILD.bazel:97

### [Documentation] README says any field not listed is an error, but `assets` (with `--experimental`) is now supported and `main` is optional when `assets` is set
- **File:** README.md:115

## INFO (3)

### [Code Quality] `_redirects` and `_headers` rules whose regex fails to compile are dropped without a warning
- **File:** src/workerd/server/server/services/assets/router/rules.rs:43

### [Code Quality] `serve()` resolves on the child's `exit` event, which can fire before stderr is drained, so the stderr assertions may flake
- **File:** src/workerd/server/tests/assets/assets-wrangler-test.mjs:65

### [Performance] Blocking `std::fs::metadata` runs on the async request path, possibly several times per request
- **File:** src/workerd/server/server/services/assets/mod.rs:85

## SUGGESTION (1)

### [Security] Dotfiles such as `.git/` and `.env` are served from the assets directory by default
- **File:** src/workerd/server/server/services/assets/router/ignore.rs:17

📋 Code Quality: ⚠️ 3 warnings · 2 info

The _redirects crash is fixed in the Rust port. Open: HEAD responses send Content-Length: 0, Worker-only fields are still dropped without main, the crate labels in BUILD.bazel are questionable, uncompilable rules are dropped silently, and the test harness can flake.

Recommendation: 📝 Minor Comments

  • [WARNING] HEAD requests for an asset are answered with Content-Length: 0 instead of the file's size (src/workerd/server/server/services/assets/mod.rs:293)
  • [WARNING] With assets and no main, Worker-only fields (vars, durable_objects, queues, workflows, triggers.crons) are still silently dropped or target a Worker that doesn't exist (src/workerd/server/cli/wrangler.rs:392)
  • [WARNING] Crate deps rewritten to @crates_vendor//name, while every other label uses the hub's @crates_vendor//:name aliases. This could not be checked against the generated repository in this run. (src/workerd/server/BUILD.bazel:97)
  • [INFO] _redirects and _headers rules whose regex fails to compile are dropped without a warning (src/workerd/server/server/services/assets/router/rules.rs:43)
  • [INFO] serve() resolves on the child's exit event, which can fire before stderr is drained, so the stderr assertions may flake (src/workerd/server/tests/assets/assets-wrangler-test.mjs:65)
View full review

🔄 Since last review: the BLOCKING _redirects crash and the missing-ETag suggestion are resolved, the main-less WARNING and the test-harness INFO are preserved, and there are 3 new findings.

The router now lives in Rust (server/services/assets/), not in /workerd/assets.js. The description still describes the JS module and a disk-service HEAD per lookup, but lookups now call std::fs::metadata in-process. Please update the description.

Findings

  • HEAD reports Content-Length: 0 (mod.rs:293). Config::serve sets body = false for HEAD as well as for 304, and request() sends the length only when body is true. A HEAD for an asset therefore reports a length of 0 rather than the file's size. Fix: send metadata.len() for every status except 304, and copy the body only when served.body is true.
  • Worker-only fields ignored without main (wrangler.rs:392). This is unchanged since the last review. With assets and no main, set_bindings, set_workflows_engine and set_durable_objects never run, so vars and durable_objects are accepted and then ignored. queues, workflows and triggers.crons still generate services that target a Worker that doesn't exist. Reject these fields with a clear error when main is missing.
  • Crate labels (BUILD.bazel:97-108). These deps were rewritten from @crates_vendor//:name to @crates_vendor//name. Every other label in the repository, including the new regex dep in server/server/BUILD.bazel, uses the //:name aliases of the crate.from_cargo hub (build/deps/rust.MODULE.bazel:128-139). @crates_vendor//capnp means @crates_vendor//capnp:capnp, a package the hub may not define. This could not be checked against the generated repository in this run.
  • Uncompilable rules dropped silently (rules.rs:43). RulesMatcher::new uses filter_map, so a rule whose regex fails to compile is dropped without a warning. Examples are a repeated :name, or two * in a _redirects rule, since parse_redirects doesn't call no_multiple_wildcards.
  • Test harness (assets-wrangler-test.mjs:65). exited resolves on exit, which can fire before stderr is drained, so the stderr assertions can flake. Resolve on close instead.

🔒 Security: 💬 1 suggestion

Path handling holds up. One low-impact suggestion remains: dotfiles are served by default.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] Dotfiles such as .git/ and .env are served from the assets directory by default (src/workerd/server/server/services/assets/router/ignore.rs:17)
View full review

Path handling holds up:

  • Segments go through is_entry_name, and . and .. are rejected.
  • base_path rejects backslashes, control characters and percent-encoding.
  • Placeholder substitution can't inject CR or LF.
  • Redirect targets collapse slashes, so a protocol-relative redirect can't be produced.
  • The regex crate matches in linear time, so a hostile _redirects or _headers file can't cause catastrophic backtracking.

One low-impact suggestion remains: the default ignore list covers only .assetsignore, _redirects and _headers. Files such as .git/ and .env in the assets directory are served.


⚡ Performance: 💬 1 info

Asset lookups use a blocking std::fs::metadata on the event loop.

Recommendation: 💬 Optional Nits

  • [INFO] Blocking std::fs::metadata runs on the async request path, possibly several times per request (src/workerd/server/server/services/assets/mod.rs:85)
View full review

Assets::stat calls std::fs::metadata synchronously, up to several times per request when html_handling probes candidates. This is cheap on a local disk. On a slow or network-mounted directory it stalls the event loop for every request. File bodies are streamed with copy_file, and config parsing happens once at startup.


📝 Documentation: ⚠️ 1 warning

The README's list of supported Wrangler fields still omits assets.

Recommendation: 📝 Minor Comments

  • [WARNING] README says any field not listed is an error, but assets (with --experimental) is now supported and main is optional when assets is set (README.md:115)
View full review

README.md:111-116 lists the supported Wrangler fields and says that any other field is an error. With this change, assets is accepted with --experimental, and main can be omitted when assets is set. Neither appears in that list. This was raised in the last review and is unchanged.


✅ All other checks passed

📖 AGENTS.md: ✅ LGTM

No AGENTS.md issues in the changed files.


Reviewed commit: 8c619c4e

Comment thread src/workerd/server/BUILD.bazel Resolved

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Superseded by the review of 13a2a01f.

This review, of 95c503d1

💬 Approved with comments — All earlier WARNINGs in the code are fixed. Two WARNINGs remain: an .assetsignore pattern that fails to compile is dropped silently, so the file it should hide is served, and the README's list of supported Wrangler fields still says assets is an error.

Findings: 2 warnings · 1 suggestion (1 is an inline comment on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8475.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Code Quality] An `.assetsignore` pattern whose regex fails to compile is dropped silently, so the file it was meant to hide is served
- **File:** src/workerd/server/server/services/assets/router/ignore.rs:37

### [Documentation] README says any unlisted Wrangler field is an error, but `assets` is now supported with `--experimental` and `main` is optional when `assets` is set (README.md:116)
- **File:** README.md:116

## SUGGESTION (1)

### [Security] Dotfiles such as `.git/` and `.env` in the assets directory are served by default
- **File:** src/workerd/server/server/services/assets/router/ignore.rs:17

🔒 Security: 💬 1 suggestion

No vulnerabilities found. One optional hardening note remains open: dotfiles are served by default.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] Dotfiles such as .git/ and .env in the assets directory are served by default (src/workerd/server/server/services/assets/router/ignore.rs:17)
View full review

Path handling holds up. Segments go through is_entry_name, which rejects . and ... Rules compile with the linear-time regex crate.

The default ignore list covers only .assetsignore, _redirects and _headers. Files such as .git/ or .env in the assets directory are served unless the user lists them in .assetsignore. This matches production behaviour, so it is optional hardening.


📋 Code Quality: ⚠️ 1 warning

Earlier findings are fixed. One remains: an .assetsignore pattern whose regex fails to compile is dropped without a warning, so the file is served.

Recommendation: 📝 Minor Comments

  • [WARNING] An .assetsignore pattern whose regex fails to compile is dropped silently, so the file it was meant to hide is served (src/workerd/server/server/services/assets/router/ignore.rs:37)
View full review

🔄 Since last review: 6 findings resolved, 2 preserved, 1 new.

These earlier findings are fixed at this commit:

  • A HEAD now sends the file's length, and only a 304 sends 0 (services/assets/mod.rs:293-303). The e2e test checks this.
  • With assets and no main, Worker-only fields are now an error, with tests.
  • _headers and dynamic _redirects rules that fail to compile are skipped with a warning (router/parse.rs).
  • serve() in the wrangler e2e test waits for close.
  • src/workerd/server/BUILD.bazel is no longer changed.

The synchronous std::fs::metadata on the request path is intended, matching the disk service, as the author explained.

New finding

  • .assetsignore fails open (router/ignore.rs:37). Matcher::new drops any pattern whose regex fails to compile, via Regex::new(&re).ok()?, and reports nothing. glob_regex copies a [...] class body almost verbatim, so a reversed range such as secret-[z-a].txt produces an invalid regex. The file the user meant to exclude is then served. _headers and _redirects now warn in this case; .assetsignore should do the same.

📝 Documentation: ⚠️ 1 warning

The README's list of supported Wrangler fields still says any other field, including assets, is an error.

Recommendation: 📝 Minor Comments

  • [WARNING] README says any unlisted Wrangler field is an error, but assets is now supported with --experimental and main is optional when assets is set (README.md:116) (README.md:116)
View full review

README.md:111-117 lists the Wrangler fields workerd serve accepts and says "any other field is an error". With this pull request, assets is accepted with --experimental, and main can be omitted when assets is set. The README is not changed, so it now states something false about shipped behaviour. Add assets to the --experimental list, and say that main is optional with assets and that Worker-only fields then become an error.


✅ All other checks passed

📖 AGENTS.md: ✅ LGTM

No AGENTS.md issues in the changed files.


⚡ Performance: ✅ LGTM

File bodies are streamed with copy_file, and HEAD responses copy no body. As the author explained, the synchronous stat calls are intended.


Reviewed commit: 95c503d1

} else {
format!("^(?:.*/)?{re}$")
};
Some((negate, dir_only, Regex::new(&re).ok()?))

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ WARNING · Code Quality

An .assetsignore pattern whose regex fails to compile is dropped silently, so the file it was meant to hide is served

Regex::new(&re).ok()? drops any pattern whose generated regex is invalid. glob_regex passes a [...] body through almost verbatim, so a reversed range like [z-a] fails to compile. A dropped ignore rule fails open: the user believes the file is excluded, and the assets service serves it. _headers and _redirects now warn on rules that fail to compile. Pass the same warn callback into Matcher::new and report the pattern, and add an invalid-pattern case to ignore-test.rs.

@codecov-commenter

codecov-commenter commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 33.26517% with 979 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.34%. Comparing base (a04c441) to head (13a2a01).

Files with missing lines Patch % Lines
...kerd/server/server/services/assets/router/parse.rs 0.00% 389 Missing ⚠️
src/workerd/server/cli/wrangler.rs 0.00% 140 Missing ⚠️
...erd/server/server/services/assets/router/intent.rs 59.72% 89 Missing ⚠️
...kerd/server/server/services/assets/router/serve.rs 0.00% 85 Missing ⚠️
...kerd/server/server/services/assets/router/rules.rs 42.59% 62 Missing ⚠️
.../server/server/services/assets/router/base_path.rs 15.87% 53 Missing ⚠️
src/workerd/server/server/services/assets/mod.rs 75.59% 31 Missing ⚠️
...c/workerd/server/factory/worker-factory-listen.c++ 0.00% 27 Missing ⚠️
...erd/server/server/services/assets/router/ignore.rs 70.12% 23 Missing ⚠️
...erver/server/services/assets/router/mitigations.rs 30.30% 23 Missing ⚠️
... and 4 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8475      +/-   ##
==========================================
- Coverage   66.54%   66.34%   -0.20%     
==========================================
  Files         783      793      +10     
  Lines      201145   202567    +1422     
  Branches    31476    31478       +2     
==========================================
+ Hits       133845   134391     +546     
- Misses      48861    49736     +875     
- Partials    18439    18440       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Adds an `assets` service to workerd: a directory served as Cloudflare
serves a Worker's static assets. Its router sends each request to the
user Worker or to a file, as run_worker_first and the files ask, and
its AssetWorker entrypoint backs a Worker's ASSETS binding. Events
other than HTTP requests go to the user Worker.

The service is native Rust in the server crate. The routing, the
_headers, _redirects, .assetsignore and run_worker_first parsers and
the head of an asset's response are pure code, ported from workers-sdk's
workers-shared; the host only stats files, streams them and forwards to
the user Worker. Files are looked up as requests arrive, so nothing
walks the directory at startup and a change to it is seen at once. An
asset's ETag is its size and modification time.

html_handling, not_found_handling, base_path, compatibility date and
flags behave as in production, as does the filter on _next/image
responses. A bad config is an error at startup; invalid _headers and
_redirects rules are warnings.

With --experimental, assets in wrangler.json becomes one service,
<name>-assets, with or without main.

A wd-test checks that the router passes JS RPC, scheduled and tail
events to the user Worker and that the AssetWorker entrypoint does not.

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💬 Approved with comments — Two WARNINGs remain from the last review: an .assetsignore pattern that fails to compile is skipped without a warning, so the file it should hide is served, and the README still lists assets among the fields that are an error. Nothing new was found in the code changed since then.

Findings: 2 warnings

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8475.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (2)

### [Code Quality] An `.assetsignore` pattern whose regex fails to compile is dropped silently, so the file it was meant to hide is served
- **File:** src/workerd/server/server/services/assets/router/ignore.rs:37

### [Documentation] README.md:111-117 says any Wrangler field not listed is an error, but `assets` is now supported with `--experimental`, and `main` is optional when `assets` is set

📋 Code Quality: ⚠️ 1 warning

One earlier warning is still open: .assetsignore fails open when a pattern's regex does not compile.

Recommendation: 📝 Minor Comments

  • [WARNING] An .assetsignore pattern whose regex fails to compile is dropped silently, so the file it was meant to hide is served (src/workerd/server/server/services/assets/router/ignore.rs:37)
View full review

.assetsignore fails open (router/ignore.rs:37). Matcher::new ends each pattern with Regex::new(&re).ok()? inside filter_map, so a pattern whose regex fails to compile is skipped and nothing is reported. glob_regex copies a [...] class body almost unchanged, so a reversed range such as secret-[z-a].txt produces an invalid regex. The file the user meant to exclude is then served.

_headers and _redirects rules that fail to compile already produce a warning through Config::parse's warn callback. .assetsignore is the only one of the three rule files that skips them silently, and it is the one that controls which files are served.

The code changed since the last review (wrangler.rs: the assets-only path, the Worker-only field errors, the --experimental check; the events test) has no new issues.


📝 Documentation: ⚠️ 1 warning

The README's list of supported Wrangler fields still says assets is an error.

Recommendation: 📝 Minor Comments

  • [WARNING] README.md:111-117 says any Wrangler field not listed is an error, but assets is now supported with --experimental, and main is optional when assets is set
View full review

README.md:111-117 lists the Wrangler fields that workerd serve accepts and ends with "any other field is an error". With this pull request, assets is accepted with --experimental, and main can be left out when assets is set. The README is not changed, so it now says something false about the shipped behaviour. Add assets to the --experimental list, and say that main is optional with assets and that Worker-only fields are then an error.


✅ All other checks passed

🔒 Security: ✅ LGTM

Path segments go through is_entry_name, which rejects . and .., and rules compile with the linear-time regex crate. The .assetsignore fail-open issue is covered in the Code Quality section. One earlier optional note is still open: dotfiles are served by default. You explained that this matches production, so it is not repeated here.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md issues in the changed files.


⚡ Performance: ✅ LGTM

File bodies are streamed, and HEAD responses copy no body. As you explained, the synchronous stat calls on the request path are intended.


Reviewed commit: 13a2a01f

@danlapid

Copy link
Copy Markdown
Collaborator

One thing needs fixing whatever else happens, and it comes first below. The rest is about
reusing this router from edgeworker, which will route Workers+Assets requests in
the runtime instead of through the router-worker. Happy for this to land first;
mine will rebase onto it.

1. Don't resolve compatibility flags by hand. Config::parse takes
compatibility_date and compatibility_flags as JSON strings and works out
assets_navigation_prefers_asset_serving itself:

has("assets_navigation_prefers_asset_serving")
    || (date >= "2025-04-01" && !has("assets_navigation_has_no_effect"))

This has to go. Turning a compatibility date plus explicit flags into flag
values is what compileCompatibilityFlags() does, from the definitions in
compatibility-date.capnp. A second copy is a different implementation:

  • It skips date validation and the experimental-flag checks, and it doesn't
    reject conflicting or unknown flags.
  • It defaults to a different date when none is given.
  • Its answers drift whenever compatibility-date.capnp changes.

The factory already compiles the user Worker's flags (compileFlags() in
worker-factory.c++), and AssetsService already names userWorker. So the
assets service should take the compiled
assetsSecFetchModeNavigateHeaderPrefersAssetServing from there and pass the
router a bool. For assets with no user Worker, compile the date and flags
through compileCompatibilityFlags() too, as typed capnp fields rather than
JSON text. Either way, the compatibility_date and compatibility_flags JSON
fields and the string comparison go away.

The same pattern is already on main, in cli/wrangler.rs's Workflows mapping
(compatibility_date >= "2026-05-14" for
workflows_replace_non_retryable_error_message). It should get the same fix,
here or in a follow-up.

2. Make router/ its own crate. It's a module of workerd-server today, so
depending on it from edgeworker would link the whole Rust server and the C++
worker factory. It only uses regex, url and serde, so it lifts out as is,
e.g. to src/rust/assets-router. As its own crate it can also be
#![forbid(unsafe_code)], which it can't be while it shares a crate with the
cxx bridge. services/assets/mod.rs and the JSON Config::parse would stay in
the server.

3. Keep exists as &impl Fn(&str) -> Option<String>. Edgeworker resolves
against the deployment's manifest, using content hashes as ETags, and still
sends asset requests to the asset worker, passing only the manifest entries the
request looked up. I checked that this works with your respond(). I built the
subset from the paths your code looks up, then ran an upstream-faithful
resolver against it. Its answer never changed from the full manifest's, across
~2.5M cases: every html_handling x not_found_handling, every subset of a set
of file layouts, GET/HEAD/other, percent-encoded and non-ASCII paths, a base
path, and 200 and 301 rules. So nothing needs to change here; please just keep
the lookup generic.

4. safe_redirect should compare only the ETag, as upstream does. Upstream
checks intent.asset.eTag === await exists(file) (asset-worker/src/handler.ts).
This version compares (path, etag). The two differ when two files have the
same ETag. With production's content hashes, that happens whenever
/about.html and /about/index.html have identical contents:

  • force-trailing-slash: production redirects /about.html to /about/; this
    serves /about.html.
  • drop-trailing-slash: production redirects /about/index.html to /about;
    this serves /about/index.html.

It was the only difference in results I found between this and a port that
follows upstream. Miniflare's dev content hash includes the file path, so
comparing the ETag alone wouldn't change anything for Miniflare as long as the
host's ETag includes the path. Which files count as the same then becomes the
host's call, and production keeps upstream behaviour.

5. Have route() report the /_image block instead of answering it.
Production checks some things after routing has picked the user Worker and
before it runs. Upstream's /_image block is one of those checks, but
route() answers it itself with Respond(blocked()), so nothing can go before
it. If Route::UserWorker carried block_image_href: bool next to
filter_image_response, the host would send the 403. Workerd's host would do
that straight away, and edgeworker could run its own checks first, in
upstream's order. The router doesn't need to know what those checks are.

6. Bring the upstream parity vectors along. I had golden vectors generated
by running the unmodified upstream functions (decodePath/encodePath, the
_redirects and _headers rules engine, replacer, and the static-routing
matcher). They all pass against this code unchanged, so they'd be a pure
addition and guard against drift from upstream later. Recording the upstream
commit that each file was ported from would help with that too. I can send
them as a follow-up once the crate is split out if that's easier.

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.

3 participants