ADR 0281 — Static files are served by one responder

Amends ADR 0023 and ADR 0013. Serves I6, I8.

Context

ADR 0023 kept two file paths: staticRoute, dual-runtime and basic, reading the whole file into memory with no Range, no validators and no Cache-Control; and serveFile, which had all three but only on Bun. The split existed to keep Bun.file out of the route that also runs on Node.

A consuming project served its previews and videos through staticRoute and measured the cost: a 303 697-byte image came back with no ETag, Last-Modified, Accept-Ranges or Cache-Control, and Range: bytes=0-99 on a 2 458 038-byte .webm returned the whole file. A browser re-downloaded every preview on every visit, a <video> in Safari and in a Telegram Mini App on iOS needs 206 to play, and each request held up to 7 MiB in memory. The mechanics that fix all of it already shipped in the same file, one function away.

Decision

staticRoute keeps its containment checks — lexical, then realpath — and answers the contained file with serveFile. staticRoute(prefix, dir, { cacheControl }) passes the header through; its default sends none, as serveFile’s does.

serveFile runs on both runtimes. Size, mtime and the file check come from node:fs stat, so a directory is 404 on both. The body is the only runtime-specific part, one function: on Bun the lazy Bun.file().slice(), which the server sends without copying through JavaScript; on Node a createReadStream over the same inclusive span, wrapped as a web ReadableStream. Range parsing, validators and the 304/206/416 decisions are one implementation for both.

Alternatives

  • staticRoute({ ranges: true }), ADR 0023’s rejected option: still rejected. An option that turns correct HTTP on leaves the default wrong, and the default is what a consuming project ships.
  • A separate Node serveFile: rejected. Two responders drift in the conditional rules, which are the subtle half; the runtimes differ only in how bytes leave.
  • node:fs streams on Bun too: rejected. Bun sends a file slice without the read loop, and media is the load this path exists for.

Consequences

Every file a staticRoute serves carries a weak ETag, Last-Modified and Accept-Ranges: bytes, answers a single range with 206 and a matching validator with 304, and streams instead of buffering. A client that cached nothing before now revalidates; a consuming project sets cacheControl to cache. The route still answers GET only: a HEAD probe of a static file needs a method: 'ALL' raw route over serveFile, as ADR 0053 describes. Proven in packages/core/tests/static-route.test.ts, serve-file.test.ts, security.test.ts, and on Node by packages/core/scripts/node-smoke.mjs.