@bakery-framework/core 2.2.1 → 2.3.0

package/package.json

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

package/src/cache/index.ts

@@ -1,5 +1,21 @@
 import { Bakery } from '../core/bakery'
+import { HandlerMap } from '../handlers/core/$registry'
+
+/**
+ * The dev watcher's route reset, run on every change to a route file: each
+ * handler's own caches, and `HandlerMap.routeCache` with them.
+ *
+ * The route cache is what a created file needs cleared. It remembers which
+ * handler won a path, and a hit re-asks only that handler, so a winner that
+ * still says yes keeps the path after a file that outranks it appears.
+ * `StaticHandler` says yes to every path. Measured in a dev app: with a root
+ * catch-all deleted and `/` requested (404, as livereload does on the delete),
+ * `/` still answered 404 three seconds after `index.vue` was written, until
+ * the dev worker restarted. And `/about` kept serving `about.html` after an
+ * `about.vue` (VueHandler, 58, above HTMLHandler, 55) was written beside it.
+ */
 export function initRoutes() {
+  HandlerMap.routeCache.clear()
   for (const [, handlers] of Object.entries(Bakery.handlers)) {
     for (const HandlerClass of handlers.list()) {
       HandlerClass.initRoutes()

package/src/compiler/dev-service.ts

@@ -456,9 +456,8 @@ const watchIgnores = Glob.strings(
 // restart was Bun's module registry caching the imported page module, and
 // TSXHandler now busts that per request in dev exactly as ApiHandler always
 // has. Pages take the cheap path via `tsScriptGlob` above. The one thing the
-// restart still bought (flushing *components* a page imports) is a
-// documented limitation (docs/getting-started/first-app.md): touch
-// server.config.ts or restart when editing a shared Layout.tsx.
+// restart still bought, flushing the *components* a page imports,
+// `isLoadedModule` now does for exactly the files that need it.
 const prioFilesGlob = Glob.strings('server.config.ts')
 
 /**
@@ -563,6 +562,45 @@ export function isCreatedRouteModule(
   return MODULE_ROUTE_EXT.test(filePath)
 }
 
+/**
+ * Whether `filePath` is a module this process imported through a plain
+ * specifier, so Bun's registry keeps serving the copy it already has and an
+ * edit cannot reach the running server without a restart.
+ *
+ * Routes are imported cache-busted (`bustInDev`'s `?v=<mtime>`), and the
+ * registry keys those with their query, so an edited route is not one: the
+ * next request imports it under a new key. Everything a route imports is
+ * keyed bare, and that is what used to go stale: a component a page imports
+ * (a shared `Layout.tsx`), and a helper an API route imports from outside the
+ * api directory, such as a top-level `server/` folder of permission checks.
+ * Measured in a dev app: an edit to `server/auth.ts` did not apply until a
+ * file under `src/api` was touched.
+ *
+ * `require.cache` is where Bun lists them, ES modules included (1.4.2: a
+ * static import keyed by path, `a.ts?v=1` keyed with its query). A Bun that
+ * stopped listing them would turn this back into the old behavior rather than
+ * break anything, and `dev-service.test.ts` asks the real registry, so it
+ * would say so.
+ */
+export function isLoadedModule(
+  filePath: string,
+  loaded: Iterable<string> = Object.keys(require.cache),
+  cwd: string = fs.cwd,
+): boolean {
+  const target = modulePathKey(resolve(cwd, filePath))
+  for (const key of loaded) {
+    if (!key.includes('?') && modulePathKey(key) === target) return true
+  }
+  return false
+}
+
+/** One spelling of a path for comparison: forward slashes, and case-folded
+ * on Windows, where `Auth.ts` and `auth.ts` are one file. */
+function modulePathKey(path: string): string {
+  const slashed = path.replaceAll('\\', '/')
+  return process.platform === 'win32' ? slashed.toLowerCase() : slashed
+}
+
 async function processFileEvent(
   filePath: string,
   server: any,
@@ -588,6 +626,12 @@ async function processFileEvent(
       return process.exit(42)
     }
 
+    // A module the server holds a plain copy of: see `isLoadedModule`.
+    if (isLoadedModule(filePath)) {
+      serveLog.BACKEND_CHANGE({ file: filePath })
+      return process.exit(42)
+    }
+
     if (tsScriptGlob.match(filePath)) {
       initRoutes()
       return notifySockets(server, filePath)

package/src/handlers/core/$dynamic.ts

@@ -35,9 +35,10 @@ const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
  * a bare `PROD` gate flipped mid-suite and broke the reload tests in files
  * loaded after it, while passing in isolation.
  *
- * Only the route module itself is busted: components it imports (a shared
- * `Layout.tsx`, helpers) stay in Bun's registry until a restart. Documented in
- * `docs/getting-started/first-app.md`.
+ * Only the route module itself is busted: components and helpers it imports
+ * (a shared `Layout.tsx`) stay in Bun's registry, and the dev watcher restarts
+ * the worker when one of them changes (`isLoadedModule` in
+ * compiler/dev-service.ts).
  *
  * One implementation on purpose. `ApiHandler` and `TSXHandler`/`TSXErrorHandler`
  * both need it, and they carried a byte-identical copy each (including this

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)
   }
 
   /**