feat(static): add Last-Modified and ETag conditional caching

[pi0x]

Summary

Adds file-age and conditional-caching headers to serveStatic(). Every served file now carries Last-Modified and a weak ETag, and a conditional request that still matches is answered with an empty 304 Not Modified before the body is ever read.

• Last-Modified from the file's mtime, floored to second granularity to match HTTP-date precision.
• ETag — a weak validator (W/"<size>-<mtime>"). Weak because on-the-fly compression is not byte-stable and this middleware serves no byte ranges (the one advantage a strong tag would buy). The negotiated Content-Encoding is folded in, so a brotli and a gzip response under one URL get distinct validators — which a shared cache keying on Vary: Accept-Encoding relies on.
• If-None-Match / If-Modified-Since → 304. If-None-Match takes precedence (RFC 9110 §13.2.2): present-and-unmatched is final, and If-Modified-Since is never consulted. The 304 carries ETag/Last-Modified/Vary but drops the representation headers.
• The file handle is still opened (preserving the existing symlink-safety invariant), but the read stream and any compression are skipped for a 304.

Options

Two new options, both default true:

• lastModified — emit Last-Modified and honor If-Modified-Since.
• etag — emit ETag and honor If-None-Match.

renderHTML routes carry neither, since that body is the caller's to validate — consistent with how they are already excluded from compression.

Implementation notes

• ServableFile now carries mtimeMs, pulled from the fstat openServable already performs — no extra syscall.
• Validators are computed from the representation actually served (variant vs identity vs on-the-fly), so a client's echoed ETag always matches what it received.

Tests

14 new cases: weak-ETag shape, 304 round-trips for both validators, If-None-Match precedence over a fresh If-Modified-Since, per-encoding ETag distinctness (identity tag rejected on a gzip request), the etag: false / lastModified: false opt-outs, renderHTML exclusion, and conditional HEAD. All 125 static tests pass; lint and format clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Static file responses now include ETag and Last-Modified validators by default.
  • Supports conditional requests using If-None-Match and If-Modified-Since, returning 304 Not Modified when appropriate.
  • Added options to enable or disable either validator.
  • Validator handling supports compressed representations and HEAD requests.

• Documentation

  • Expanded middleware guidance for static file caching and conditional requests.

[coderabbitai]

Warning

Review limit reached

@pi0x, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 37 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 04d15d8d-e002-46a0-9616-b3e808de30a1

📥 Commits

Reviewing files that changed from the base of the PR and between ed28708 and 121c400.

📒 Files selected for processing (3)

• docs/1.guide/4.middleware.md
• src/static.ts
• test/static.test.ts

📝 Walkthrough

Walkthrough

Changes

Static cache validators

Layer / File(s)	Summary
Validator generation and conditional response flow src/static.ts	Adds configurable weak ETag and Last-Modified headers, encoded-representation support, conditional request precedence, and 304 Not Modified responses.
Documentation and behavioral coverage docs/1.guide/4.middleware.md, test/static.test.ts	Documents validator options and verifies conditional requests, encodings, disabled validators, renderHTML, and HEAD behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• h3js/srvx#233: Directly overlaps with static-file validators and conditional 304 handling.
• h3js/srvx#252: Covers encoded static representations and Vary behavior used by validator handling.

Suggested reviewers: pi0

Poem

A rabbit found validators bright,
ETags glowing softly at night.
“If unchanged,” they say,
“Send three-oh-four today!”
And files nap without a byte.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: static file conditional caching with Last-Modified and ETag support.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/static-caching-headers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/srvx@269

commit: 121c400

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@docs/1.guide/4.middleware.md`:
- Line 112: Update the opening statement in the middleware documentation to
qualify that served files, excluding renderHTML routes, carry ETag and
Last-Modified headers. Keep the existing renderHTML clarification and all
validator behavior details unchanged.

In `@src/static.ts`:
- Around line 453-475: Update conditional request handling around
matchesIfNoneMatch: read the raw If-None-Match header regardless of etagValue,
let its presence suppress If-Modified-Since, and only evaluate the date
validator for GET/HEAD methods. For a matching If-None-Match, return 304 for
GET/HEAD and 412 for other configured methods; add coverage for ETag-disabled
requests with both headers and non-GET/HEAD behavior.
- Around line 446-449: Update the Last-Modified handling near lastModifiedMs to
clamp future file mtimes to the response origination time before converting them
to UTC. Preserve second-level precision and existing header behavior, and add a
regression test with a future-dated fixture verifying the emitted Last-Modified
is not in the future.

🪄 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: 48364c4b-00cc-4312-ab3f-8e602eb54894

📥 Commits

Reviewing files that changed from the base of the PR and between 6b3b291 and ed28708.

📒 Files selected for processing (3)

• docs/1.guide/4.middleware.md
• src/static.ts
• test/static.test.ts