@bakery-framework/core 2.2.2 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",

package/src/core/config.ts

@@ -12,6 +12,10 @@ import { fs } from '../utils/fs'
 import { checkCacheVersion } from './cache-version'
 import { hostStore } from './context'
 
+// Re-exported for the CLI's boot checks, which reach config through this
+// subpath; the module itself imports nothing, so it can sit under the router.
+export { checkHostMounts } from './host-mounts'
+
 export const NOOP = () => {}
 
 const defaultConfig: Required<AppConfig> = {
@@ -63,6 +67,7 @@ const defaultConfig: Required<AppConfig> = {
   sessions: {},
   root: 'src',
   hosts: {},
+  hostMounts: [],
   websocket: {
     message: NOOP,
     open: NOOP,

package/src/core/host-mounts.ts

@@ -0,0 +1,174 @@
+/**
+ * Host mounts: a host that serves one path subtree of the app at its root.
+ *
+ * `hostMounts: [{ host: 'kit.*', path: '/kit' }]` makes `kit.example.com/forms`
+ * the page `/kit/forms` is on every other host. The subtree stays part of the
+ * app: its pages load the app's modules, stylesheets and API from the root,
+ * the way they do on any host, so only page requests move into it. Which
+ * requests those are is `routeOf` in `router.ts`.
+ *
+ * Patterns rather than `hosts` keys, because a mount's hostname is often not
+ * known at boot: an app whose domain is a setting can still name "the `kit`
+ * label of whatever domain this is". A mount is also not a tenant. It changes
+ * which page a path names and nothing else, so sessions, caches and the
+ * `hosts` entries do not see it.
+ */
+
+export type HostMount = {
+  /**
+   * The hostnames the mount serves: a name (`kit.example.com`), a pattern in
+   * which `*` stands for one or more whole labels (`kit.*`,
+   * `*.docs.example.com`), or a function of the hostname, which it receives
+   * lowercased and without the port.
+   */
+  host: string | ((hostname: string) => boolean)
+  /** The subtree served at the host's root, such as `/kit`. */
+  path: string
+}
+
+export type CompiledHostMount = {
+  /** The subtree: a leading slash and no trailing one. */
+  readonly path: string
+  /** Whether a lowercased hostname without its port is served by the mount. */
+  matches(hostname: string): boolean
+}
+
+/** One label of a hostname pattern, `*` aside. */
+const LABEL = /^[a-z0-9_-]+$/
+
+/** `*` as a pattern label: one or more whole labels. */
+const ANY_LABELS = '[^.]+(?:\\.[^.]+)*'
+
+/**
+ * A hostname pattern as a regular expression. Throws naming `where` when
+ * `host` is not a name, or puts `*` inside a label: `k*t.example.com` would
+ * have to choose between matching part of a label and matching labels, and
+ * either reading surprises someone.
+ */
+export function hostPattern(host: string, where = 'host'): RegExp {
+  const labels = host.toLowerCase().split('.')
+  if (labels.some(label => label === '')) {
+    throw new Error(
+      `${where} '${host}' is not a hostname: a name has no empty label`,
+    )
+  }
+  const parts = labels.map(label => {
+    if (label === '*') return ANY_LABELS
+    if (!LABEL.test(label)) {
+      throw new Error(
+        `${where} '${host}' has the label '${label}': a label is letters, digits, '-' and '_', and '*' stands for whole labels only`,
+      )
+    }
+    return label
+  })
+  return new RegExp(`^${parts.join('\\.')}$`)
+}
+
+/**
+ * What every host serves from the app's root, a mounted one included: the
+ * framework's and the plugins' routes, the API, and the site-wide metadata
+ * RFC 8615 reserves. The router keeps requests under these out of a mount,
+ * and no mount may name a path under one.
+ */
+export const ROOT_ONLY = ['/_', '/api/', '/.well-known/'] as const
+
+function mountPath(value: unknown, where: string): string {
+  if (typeof value !== 'string' || !value.startsWith('/')) {
+    throw new Error(
+      `${where} must be a path starting with '/': got ${JSON.stringify(value)}`,
+    )
+  }
+  const path = value.replace(/\/+$/, '')
+  if (path === '') {
+    throw new Error(
+      `${where} '${value}' is the whole app, which every host already serves`,
+    )
+  }
+  const segments = path.slice(1).split('/')
+  if (segments.some(s => s === '' || s === '.' || s === '..')) {
+    throw new Error(
+      `${where} '${value}' has an empty, '.' or '..' segment: a mount names one directory`,
+    )
+  }
+  if (/[?#*\\]/.test(path)) {
+    throw new Error(
+      `${where} '${value}' is a path, so it holds no '?', '#', '*' or '\\'`,
+    )
+  }
+  const reserved = ROOT_ONLY.find(prefix => `${path}/`.startsWith(prefix))
+  if (reserved) {
+    throw new Error(
+      `${where} '${value}' is under ${reserved}, which every host serves as it is`,
+    )
+  }
+  return path
+}
+
+function compile(mount: HostMount, where: string): CompiledHostMount {
+  if (!mount || typeof mount !== 'object') {
+    throw new Error(`${where} must be { host, path }`)
+  }
+  const path = mountPath(mount.path, `${where}.path`)
+  const { host } = mount
+  if (typeof host === 'function') return { path, matches: host }
+  if (typeof host !== 'string') {
+    throw new Error(
+      `${where}.host must be a hostname, a pattern such as 'kit.*', or a function of the hostname`,
+    )
+  }
+  const pattern = hostPattern(host, `${where}.host`)
+  return { path, matches: hostname => pattern.test(hostname) }
+}
+
+/**
+ * Compiled once per array: the processed config is frozen for the life of
+ * the process, and a test that swaps it in brings a new array, so identity is
+ * the whole validity check.
+ */
+const compiled = new WeakMap<
+  readonly HostMount[],
+  readonly CompiledHostMount[]
+>()
+
+/** `hostMounts` compiled, throwing at the first entry that cannot mean anything. */
+export function compileHostMounts(
+  mounts: readonly HostMount[],
+): readonly CompiledHostMount[] {
+  const cached = compiled.get(mounts)
+  if (cached) return cached
+  if (!Array.isArray(mounts)) {
+    throw new Error('hostMounts must be an array of { host, path }')
+  }
+  const result = mounts.map((mount, i) => compile(mount, `hostMounts[${i}]`))
+  compiled.set(mounts, result)
+  return result
+}
+
+/**
+ * Compile the app's `hostMounts` before anything binds, so an entry that
+ * cannot mean anything stops the boot and names itself, rather than throwing
+ * on the first request that reaches it.
+ */
+export function checkHostMounts(config: {
+  hostMounts: readonly HostMount[]
+}): void {
+  compileHostMounts(config.hostMounts)
+}
+
+/** The first mount serving `hostname`, or null. */
+export function findHostMount(
+  mounts: readonly CompiledHostMount[],
+  hostname: string,
+): CompiledHostMount | null {
+  if (!mounts.length) return null
+  const host = hostname.toLowerCase()
+  for (const mount of mounts) {
+    if (mount.matches(host)) return mount
+  }
+  return null
+}
+
+/** `path` on a mounted host, as the app names it: `/` is the mount itself. */
+export function mountedPath(path: string, mount: string): string {
+  return path === '/' ? mount : `${mount}${path}`
+}

package/src/global.d.ts

@@ -168,6 +168,17 @@ declare global {
     sessions?: import('./session').SessionOptions
 
     hosts?: Record<string, HostEntry>
+
+    /**
+     * Hosts that serve one path subtree of the app at their root:
+     * `{ host: 'kit.*', path: '/kit' }` makes `kit.example.com/forms` the
+     * page `/kit/forms`. Only page requests move into the subtree (a
+     * navigation, or a method other than GET and HEAD); the modules,
+     * stylesheets, files and API those pages load come from the app's root,
+     * as on any host. The first entry whose `host` matches wins. See
+     * `core/host-mounts.ts` and `routeOf` in `router.ts`.
+     */
+    hostMounts?: import('./core/host-mounts').HostMount[]
   }
 
   type ServerPlugin = _plugins.ServerPlugin

package/src/router.ts

@@ -1,9 +1,16 @@
-import { Bakery, hostStore } from './core/bakery'
+import { Bakery, getHostname, hostStore } from './core/bakery'
 import { matchBlockedCached } from './core/context'
+import {
+  compileHostMounts,
+  findHostMount,
+  mountedPath,
+  ROOT_ONLY,
+} from './core/host-mounts'
 import { PluginHooks } from './core/plugins'
 import { DefaultErrorHandler } from './handlers/assets/static'
 import type { Handler } from './handlers/core/$base'
 import { ErrorHandler } from './handlers/core/$error'
+import { resolveMount } from './handlers/core/$mounts'
 import { WebSocketHandler } from './handlers/core/$websocket'
 import { errorMsg, getElapsed, log, serveLog } from './logger'
 import { Session } from './session'
@@ -82,14 +89,104 @@ function servesFiles(handler: any): boolean {
   return handler?.servesFiles !== false
 }
 
+/**
+ * How routing reads one request: the path it resolves, the host mount it
+ * moved into, and whether this URL's answer depends on the kind of request,
+ * which is what `processResponse` sends a `Vary` for.
+ */
+type Routing = { path: string; mount: string | null; varies: boolean }
+
+export type RequestRoute = Readonly<Pick<Routing, 'path' | 'mount'>>
+
+/** Weak, as `parsedUrl`'s memo is: an entry lives as long as its request. */
+const routings = new WeakMap<Request, Routing>()
+
+/**
+ * Whether `path` could be a page of a mounted subtree: nothing in `ROOT_ONLY`,
+ * no file named, and no plugin's route mount or proxy entry claiming it.
+ *
+ * "No file named" is a last segment with no extension. A page links its
+ * stylesheets, images and downloads by their root paths, and a navigation to
+ * one of them (a PDF opened in a tab) has to reach the file.
+ */
+function pagePathOnMount(
+  path: string,
+  config: Readonly<ProcessedAppConfig>,
+): boolean {
+  if (ROOT_ONLY.some(prefix => path.startsWith(prefix))) return false
+  if (path.slice(path.lastIndexOf('/') + 1).includes('.')) return false
+  if (resolveMount(path)) return false
+  for (const prefix in config.proxy) {
+    if (path.startsWith(prefix)) return false
+  }
+  return true
+}
+
+/**
+ * Whether `req` asks for a page rather than for something a page loads.
+ *
+ * A navigation (a tab or a frame loading the URL) is one, and so is any
+ * method but GET and HEAD: a form post, or a server action, which a Vue page
+ * posts to its own URL. A module import, a stylesheet, an image and a `fetch`
+ * are not, and that is the line that has to hold: an import of a TypeScript
+ * module is written `/kit/useDemo`, with no extension to tell it from a page,
+ * and moved into the subtree it would reach a catch-all page instead.
+ *
+ * A browser says which it is in `Sec-Fetch-Mode`. A client that sends no
+ * Fetch Metadata is navigating when it asks for HTML.
+ */
+function isPageRequest(req: Request): boolean {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return true
+  if (req.headers.has('upgrade')) return false
+  const mode = req.headers.get('sec-fetch-mode')
+  if (mode) return mode === 'navigate'
+  return (req.headers.get('accept') ?? '').includes('text/html')
+}
+
+function routing(req: Request): Routing {
+  const cached = routings.get(req)
+  if (cached) return cached
+
+  // Shared with worker.ts, which has already asked for the same parse; a
+  // direct caller (test, embedder) gets it parsed here instead.
+  const path = parsedUrl(req).pathname
+  let result: Routing = { path, mount: null, varies: false }
+
+  // A partial config (a test's, an embedder's) may carry no `hostMounts`.
+  const config = Bakery.config
+  const mounts = config.hostMounts?.length
+    ? compileHostMounts(config.hostMounts)
+    : null
+  const mount = mounts && findHostMount(mounts, getHostname(req, config))
+  if (mount && pagePathOnMount(path, config)) {
+    result = isPageRequest(req)
+      ? { path: mountedPath(path, mount.path), mount: mount.path, varies: true }
+      : { path, mount: null, varies: true }
+  }
+
+  routings.set(req, result)
+  return result
+}
+
+/**
+ * The path routing resolves for `req`, and the host mount it moved into.
+ *
+ * On a host that no entry of `hostMounts` serves, that is the request's own
+ * path and no mount. On a mounted host, a page request (`isPageRequest`) for
+ * a path that can be a page (`pagePathOnMount`) resolves under the mount:
+ * `/forms` is `/kit/forms`, and `/` is `/kit`. Every other request keeps its
+ * path, so the modules, stylesheets and API a subtree's pages load still come
+ * from the app's root. Memoized per request.
+ */
+export function routeOf(req: Request): RequestRoute {
+  return routing(req)
+}
+
 export function handleRequest(
   req: Request,
 ): Handler.Response | MixedPromise<symbol>
 export async function handleRequest(req: Request) {
-  // Shared with worker.ts, which has already asked for the same parse; a
-  // direct caller (test, embedder) gets it parsed here instead.
-  const url = parsedUrl(req)
-  const path = url.pathname
+  const path = routing(req).path
 
   // One read of the config getter, not three: `Bakery.serveRoot` walks
   // `hostStore.getStore()?.config ?? getConfig()` on every access, and the
@@ -312,6 +409,21 @@ export async function handleRequestError(
   return DefaultErrorHandler.handle(path, req, error)
 }
 
+/** Add `tokens` to `res`'s `Vary`, keeping what it names and naming each once. */
+function addVary(res: Response, tokens: readonly string[]): void {
+  const existing = res.headers.get('Vary')
+  const named = new Set(
+    (existing ?? '')
+      .split(',')
+      .map(token => token.trim().toLowerCase())
+      .filter(Boolean),
+  )
+  if (named.has('*')) return
+  const missing = tokens.filter(token => !named.has(token.toLowerCase()))
+  if (!missing.length) return
+  res.headers.set('Vary', [existing, ...missing].filter(Boolean).join(', '))
+}
+
 export async function processResponse(
   data: Handler.Response | MixedPromise<symbol>,
   req: Request,
@@ -373,6 +485,11 @@ export async function processResponse(
   const cors = Bakery.config.cors
   if (cors) applyCors(cors, req, resp)
 
+  // On a mounted host one URL can answer a navigation from the subtree and a
+  // module import from the root (see `routeOf`), so a cache keyed on the URL
+  // alone could hand either one to the other.
+  if (routing(req).varies) addVary(resp, ['Sec-Fetch-Mode', 'Accept'])
+
   const final = ETag.sendResponse(req, resp)
   if (!(final instanceof Response)) {
     log({

package/src/session-signing.ts

@@ -0,0 +1,90 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { Bakery } from './core/bakery'
+
+/**
+ * Session cookies are signed: `sId=<id>.<mac>`, an HMAC-SHA256 of the id.
+ *
+ * The id alone is the bearer token, and it is unguessable, so the signature
+ * adds nothing to whether a stolen cookie works. What it buys is a refusal
+ * that costs nothing: with `sessions.store`, every request carrying a
+ * well-formed id used to cost a lookup by primary key before the rate limiter
+ * could refuse it (`Session.attach` runs first, since `keyBy` may read the
+ * session), so a flood of made-up ids from one address queued on the pool
+ * behind real traffic. A made-up id now fails here, in microseconds, and no
+ * store is asked. The built-in store gains the same, for its SQLite tier.
+ *
+ * The stored id is unchanged: only the cookie carries the MAC, so no store
+ * row or column moves.
+ */
+
+/** Bytes of the MAC a cookie carries: 128 bits, ample for a MAC. */
+const MAC_BYTES = 16
+
+/** The key made for this process from `bakery/session.key`, once read. */
+let keptKey: Buffer | null = null
+
+/**
+ * The key that signs: `sessions.secret` when set, else the one kept in the
+ * data directory, made on first use. Every worker on the machine reads the
+ * same file, and the first to make it wins (`wx`), so they agree. Servers
+ * sharing one store need the same `sessions.secret`.
+ */
+function signingKey(secret: string | undefined): Buffer | string {
+  if (secret) return secret
+  keptKey ??= keyFromFile(`${Bakery.dataDir}/session.key`)
+  return keptKey
+}
+
+function keyFromFile(path: string): Buffer {
+  const read = () => Buffer.from(readFileSync(path, 'utf8').trim(), 'base64url')
+  try {
+    return read()
+  } catch (error: any) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+
+  // Absent: make it. A worker that loses the race to create it reads the
+  // winner's instead, so every worker signs with the same key.
+  mkdirSync(Bakery.dataDir, { recursive: true })
+  const key = randomBytes(32)
+  try {
+    writeFileSync(path, key.toString('base64url'), { flag: 'wx', mode: 0o600 })
+    return key
+  } catch (error: any) {
+    if (error?.code === 'EEXIST') return read()
+    throw new Error(
+      `Session cookies are signed with a key kept in ${path}, which could not be written (${error?.message ?? error}). Set sessions.secret in server.config.ts instead.`,
+    )
+  }
+}
+
+function mac(key: Buffer | string, id: string): Buffer {
+  return createHmac('sha256', key).update(id).digest().subarray(0, MAC_BYTES)
+}
+
+/** The cookie value for a session id: the id, a dot, and its MAC. */
+export function signSessionId(id: string, secret?: string): string {
+  return `${id}.${mac(signingKey(secret), id).toString('base64url')}`
+}
+
+/**
+ * The session id a cookie value names, or `''` when its MAC does not match
+ * (or it has none, as a cookie issued before signing has none): such a
+ * cookie names no session, and nothing is looked up for it. Compared in
+ * constant time, so the comparison says nothing about how close a guess came.
+ */
+export function verifiedSessionId(value: string, secret?: string): string {
+  const dot = value.lastIndexOf('.')
+  if (dot <= 0) return ''
+  const id = value.slice(0, dot)
+  const given = Buffer.from(value.slice(dot + 1), 'base64url')
+  const expected = mac(signingKey(secret), id)
+  if (given.length !== expected.length) return ''
+  return timingSafeEqual(given, expected) ? id : ''
+}
+
+/** Test seam: forget the kept key, so the next use reads the file again. */
+export function __forgetSessionKey(): void {
+  keptKey = null
+}

package/src/session.ts

@@ -3,6 +3,7 @@ import { Bakery, hostKey } from './core/bakery'
 import { peekConfig, resolveHostname } from './core/config'
 import { hostStore } from './core/context'
 import { errorMsg, serveLog } from './logger/serve-log'
+import { signSessionId, verifiedSessionId } from './session-signing'
 import type { MapOf } from './types'
 import { deferredValue, hasDeferredValue } from './utils'
 import { DEFAULT_SESSION_PERSIST, DEFAULT_SESSION_TTL } from './utils/constants'
@@ -175,6 +176,13 @@ export interface SessionOptions {
    * `Session.endForAccount` can end every session of one account.
    */
   account?: string
+  /**
+   * Signs the session cookie, so a made-up id is refused before any store is
+   * asked (`session-signing.ts`). Omitted, a key is made once and kept in
+   * `bakery/session.key`. Servers that share one store need the same secret.
+   * Changing it ends every session: their cookies no longer verify.
+   */
+  secret?: string
 }
 
 /**
@@ -359,7 +367,8 @@ export class Session<
       req.url?.startsWith('https:') || forwardedHttps || import.meta.env.PROD,
     )
     const secureFlag = isHttps ? '; Secure' : ''
-    return `sId=${session.id}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAgeSeconds}${secureFlag}`
+    const value = signSessionId(session.id, sessionOptions()?.secret)
+    return `sId=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAgeSeconds}${secureFlag}`
   }
 
   public static delete(reqOrId: string | Request): boolean {
@@ -413,7 +422,10 @@ export class Session<
 
     if (!request.headers.has('cookie')) return ''
     const cookieHeader = request.headers.get('cookie') || ''
-    return cookieHeader.match(/(?:^|;\s*)sId=([^;]+)/)?.[1] || ''
+    const value = cookieHeader.match(/(?:^|;\s*)sId=([^;]+)/)?.[1]
+    // Signed: an id whose MAC does not match names no session, so neither
+    // store is asked about it. See `session-signing.ts`.
+    return value ? verifiedSessionId(value, sessionOptions()?.secret) : ''
   }
 
   public static from<T extends MapOf<any> = MapOf<any>>(

package/src/utils/fs.ts

@@ -3,7 +3,11 @@ import {
   existsSync as nodeExistsSync,
   statSync as nodeStatSync,
 } from 'node:fs'
-import { mkdir as fsMkdir, rm as fsRm } from 'node:fs/promises'
+import {
+  mkdir as fsMkdir,
+  readdir as fsReaddir,
+  rm as fsRm,
+} from 'node:fs/promises'
 import {
   dirname as nodeDirname,
   relative as nodeRelative,
@@ -288,9 +292,11 @@ export namespace FileSystem {
    * one question about one file cost two stats and an allocation.
    *
    * It shows up wherever a caller asks both questions, which is the common
-   * shape - `validCache` below, `nm.ts`'s `exists(nmFile) ? nmFile.lastModified`,
-   * and both mtime comparisons in `image.ts`. Measured on this machine, four
-   * interleaved rounds against a CPU-bound control flat at 27-31 ms:
+   * shape - `nm.ts`'s `exists(nmFile) ? nmFile.lastModified`, both mtime
+   * comparisons in `image.ts`, and the cache check `validCache` was before
+   * the source's version went into the cache file's name (see
+   * `versionedName`). Measured on this machine, four interleaved rounds
+   * against a CPU-bound control flat at 27-31 ms:
    *
    *     validCache, file present    33.0 us -> 17.3 us    1.9x
    *     validCache, file absent     34.9 us -> 17.4 us    2.0x
@@ -563,19 +569,106 @@ export namespace FileSystem {
   }
 
   /**
-   * Two reads of one `BunFile`, which is one stat: `exists` no longer
-   * re-wraps the instance, so the second read comes off the cached stat.
+   * The name a build of `cacheName` from a source of `sourceMtime` is kept
+   * under: the mtime goes into the name ahead of the extension, which still
+   * decides the MIME type and the compression (`abc.js` built from a source of
+   * 1791456519209 is `abc@1791456519209.js`). With no mtime to check, the
+   * plain name.
+   *
+   * So a cached file answers for one version of its source, and existence is
+   * the whole test. The test before compared the source's mtime with the
+   * cache file's mtime, which is its *write* time: a build that read the
+   * source, then saw it edited before it wrote, left a file newer than the
+   * edit, which then counted as current for it and served the previous
+   * version until the next edit. Measured with a build held open across an
+   * edit: the request for the edit and every request after it got the build
+   * of the source before it. That is how an SFC in a dev server kept its old
+   * styles beside a new template and script after three quick edits.
+   */
+  function versionedName(cacheName: string, sourceMtime: number | null): string {
+    if (!sourceMtime) return cacheName
+    const ext = parse(cacheName).ext
+    return `${cacheName.slice(0, cacheName.length - ext.length)}@${sourceMtime}${ext}`
+  }
+
+  /**
+   * Delete the builds of `cacheName` from sources older than `sourceMtime`, raw
+   * and compressed, once a newer one is written: every edit would otherwise
+   * leave its predecessor's three files behind for as long as the cache lives.
+   *
+   * Older only, so a build that finishes late never deletes a newer one beside
+   * it. Best effort, and off the request's path: a file another request is
+   * still sending cannot be deleted on Windows, and the next build's sweep
+   * finds it again. Listing the directory is the cost, 1.5 ms for 3000 entries
+   * on this machine, paid once per build.
+   */
+  async function dropOlderBuilds(
+    cacheDir: string,
+    cacheName: string,
+    sourceMtime: number,
+  ): Promise<void> {
+    const ext = parse(cacheName).ext
+    const stem = cacheName.slice(0, cacheName.length - ext.length)
+    const [, names] = await Try.catch(() => fsReaddir(cacheDir))
+    if (!names) return
+
+    const prefix = `${stem}@`
+    for (const name of names) {
+      if (!name.startsWith(prefix)) continue
+      const rest = name.slice(prefix.length)
+      const version = rest.match(/^(\d+)/)?.[1]
+      if (!version || Number(version) >= sourceMtime) continue
+      // The rest of the name after the version must be this entry's own
+      // extension, compressed or not: `abc@1.root.js` is another entry.
+      const suffix = rest.slice(version.length)
+      if (!buildSuffixes(ext).includes(suffix)) continue
+      // Not awaited one by one, and a failure is only a file left for the
+      // next sweep: see above.
+      void fsRm(resolve(cacheDir, name), { force: true }).catch(() => undefined)
+    }
+  }
+
+  /** `.js`, `.js.zst`, `.js.gz`: the names one build writes, for `ext`. */
+  function buildSuffixes(ext: string): string[] {
+    return [ext, ...COMPRESSION_MAP.map(c => `${ext}${c.ext}`)]
+  }
+
+  /**
+   * How long a superseded build is kept before its sweep. A build of an
+   * older source can finish after a newer one has written, and its caller
+   * opens the file it was handed a moment later: a sweep run straight away
+   * deleted it first, and that request answered ENOENT (2 runs in 8 of the
+   * test that holds a build open across an edit). Ten seconds is far longer
+   * than a request takes to open its file.
    */
-  function validCache(file: Bun.BunFile, sourceMtime: number | null): boolean {
-    return exists(file) && (!sourceMtime || sourceMtime <= file.lastModified)
+  let sweepDelayMs = 10_000
+
+  /** Test seam: how long a sweep waits. See `sweepDelayMs`. */
+  export function __setSweepDelay(ms: number): void {
+    sweepDelayMs = ms
+  }
+
+  /** Sweep the versions before `sourceMtime` once the delay has passed. */
+  function scheduleSweep(
+    cacheDir: string,
+    cacheName: string,
+    sourceMtime: number,
+  ): void {
+    const timer = setTimeout(
+      () => void dropOlderBuilds(cacheDir, cacheName, sourceMtime),
+      sweepDelayMs,
+    )
+    // A pending sweep is housekeeping: it must not hold a process open.
+    timer.unref?.()
   }
 
   type FileContent = string | Uint8Array<ArrayBuffer> | ArrayBuffer
 
   /**
-   * Builds currently running, keyed on the resolved raw path.
+   * Builds currently running, keyed on the resolved raw path, which names the
+   * source's version (`versionedName`).
    *
-   * `validCache` is a pure filesystem test with no record of work in progress,
+   * The cache test is a pure filesystem test with no record of work in progress,
    * so N concurrent first-hits on a cold cache each saw "not cached", each ran
    * `compiler()`, and each wrote the same three paths. Measured: 8 concurrent
    * callers produced 8 compiler invocations. Every `.ts`/`.tsx`/`.vue` asset
@@ -589,12 +682,12 @@ export namespace FileSystem {
    * bounded by construction (convention 6): an entry exists only while its own
    * build is running, never past it.
    *
-   * The key is the path alone, not the path plus `sourceMtime`. A caller that
-   * joins mid-build can therefore receive a build started for a marginally
-   * older mtime: a window only as wide as one compile, which the next request
-   * re-validates and rebuilds. Including the mtime would close that window by
-   * letting two builds of the same file race each other onto the same three
-   * output paths, which is the worse trade.
+   * The key carries the version because the path does. A caller for a newer
+   * source used to join a build of an older one, and this note said the next
+   * request would re-validate and rebuild: it did not, since that build's file
+   * was written after the edit and so counted as current (`versionedName`).
+   * Builds of two versions write two sets of paths now, so they never race
+   * onto the same three.
    */
   const inFlightBuilds = new Map<string, Promise<Bun.BunFile | null>>()
 
@@ -605,7 +698,7 @@ export namespace FileSystem {
     compiler: () => MixedPromise<FileContent | null>,
     compress = true,
   ): Promise<Bun.BunFile | null> {
-    const rawPath = resolve(cacheDir, cacheName)
+    const rawPath = resolve(cacheDir, versionedName(cacheName, sourceMtime))
 
     const pending = inFlightBuilds.get(rawPath)
     if (pending) return pending
@@ -637,11 +730,17 @@ export namespace FileSystem {
     const compressible = compress && isCompressible(ext)
 
     const rawFile = Bun.file(rawPath)
+    // Once written, superseded versions go, after a delay: see
+    // `dropOlderBuilds` and `sweepDelayMs`.
+    const built = <T>(file: T): T => {
+      if (sourceMtime) scheduleSweep(cacheDir, cacheName, sourceMtime)
+      return file
+    }
 
     if (compressible) {
       for (const { ext: compExt } of COMPRESSION_MAP) {
         const compFile = Bun.file(`${rawPath}${compExt}`)
-        if (validCache(compFile, sourceMtime)) return compFile
+        if (exists(compFile)) return compFile
       }
 
       const content = await compiler()
@@ -670,19 +769,19 @@ export namespace FileSystem {
         }),
       ])
 
-      return Bun.file(rawPath + COMPRESSION_MAP[0].ext)
+      return built(Bun.file(rawPath + COMPRESSION_MAP[0].ext))
     }
 
     // The mirror of the compressed branch's check above. Without it a
     // non-compressible entry (a .woff2 from the gstatic proxy, say) was
     // rebuilt (for fonts, re-fetched upstream) on every single request.
-    if (validCache(rawFile, sourceMtime)) return rawFile
+    if (exists(rawFile)) return rawFile
 
     const content = await compiler()
     if (content == null) return null
     await mkdir(cacheDir)
     await rawFile.write(content)
-    return rawFile
+    return built(rawFile)
   }
 
   /**