@bakery-framework/core 2.5.0-alpha.0 → 2.5.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.5.0-alpha.0",
+  "version": "2.5.0-alpha.2",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",
@@ -65,6 +65,6 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.4"
   }
 }

package/src/client/utils.ts

@@ -331,9 +331,13 @@ if (typeof document !== 'undefined') {
     // A `source: 'document'` rule with href_matches '/*' and eager eagerness
     // ignored the exclusions above and fully loaded (and ran the JS of) every
     // same-origin link, including things like /logout or a destructive GET.
+    //
+    // Prefetch waits for intent too. With no eagerness a list rule fetches at
+    // once, so a sidebar of 32 links asked for all 32 pages at every load (1.5 s
+    // and 6 MB on one app); moderate asked for none at load and one on a hover.
     const urlList = Array.from(urls)
     specScript.textContent = JSON.stringify({
-      prefetch: [{ source: 'list', urls: urlList }],
+      prefetch: [{ source: 'list', urls: urlList, eagerness: 'moderate' }],
       prerender: [{ source: 'list', urls: urlList, eagerness: 'moderate' }],
     })
 

package/src/compiler/compiler.ts

@@ -1,12 +1,7 @@
 import { Strings } from '../cache/string'
 import { Bakery } from '../core/bakery'
 import { PluginHooks } from '../core/plugins'
-import {
-  compLog,
-  errorMsg,
-  errorWithPosition,
-  handlerLog,
-} from '../logger/serve-log'
+import { compLog, errorWithPosition, handlerLog } from '../logger/serve-log'
 import type { MapOf } from '../types'
 import { is, Try, toHash } from '../utils/common'
 import { FileSystem as fs } from '../utils/fs'
@@ -37,7 +32,8 @@ async function buildDefines(): Promise<MapOf<string>> {
     const file = await Bun.file(`${process.cwd()}/package.json`).json()
     if (file?.version) bakeryVersion = file.version
   } catch {
-    // No package.json in cwd, or it is unreadable. The version is cosmetic (    // it lands in a banner and a build define), so the default above stands.
+    // No package.json in cwd, or it is unreadable. The version is cosmetic
+    // (it lands in a banner and a build define), so the default above stands.
   }
 
   return {
@@ -128,10 +124,14 @@ function preprocessImports(source: string, filePath: fs.AbsolutePath): string {
  * Compile `source`, naming `path` so a failure can say where it happened.
  *
  * The two branches are not symmetric on purpose. Without a path there is no
- * file to name and no caller that can render a 500 (the Vue plugin compiles
- * fragments of an SFC it has already parsed), so a failure logs and hands the
- * source back. With a path the failure is a served request, and the answer is
- * `null`: `TSHandler` turns that into the 500 it has always had a branch for.
+ * file to resolve imports against and no caller that can render a 500 (the
+ * Vue plugin compiles fragments of an SFC it has already parsed), so a failure
+ * logs and hands the source back. `origin.file` names the file such a
+ * fragment came from, for that log line only: without it the line read
+ * "Failed to compile inline source: Transform failed", and a component that
+ * would not parse in the browser had to be found by hand. With a path the
+ * failure is a served request, and the answer is `null`: `TSHandler` turns
+ * that into the 500 it has always had a branch for.
  *
  * It used to be neither. The transpiler was wrapped only on the pathless
  * branch, so a syntax error in a `.ts` asset threw straight past `compile()`,
@@ -140,22 +140,31 @@ function preprocessImports(source: string, filePath: fs.AbsolutePath): string {
  * `Unhandled Server Error: <message>` with no file and no line while the client
  * got `An unexpected error occurred.` A total blackout for a one-character typo.
  */
-export function compileText(source: string): Promise<string>
+export function compileText(
+  source: string,
+  origin?: { file: string },
+): Promise<string>
 export function compileText(
   source: string,
   path: fs.AbsolutePath,
 ): Promise<string | null>
-export async function compileText(source: string, path?: fs.AbsolutePath) {
-  if (!path) {
-    try {
-      const content = await (await getTranspiler()).transform(source)
-      return content
-    } catch (err) {
-      compLog.COMPILE_SOURCE_FAIL({ error: errorMsg(err) })
-      return source
-    }
+export async function compileText(
+  source: string,
+  where?: fs.AbsolutePath | { file: string },
+) {
+  if (typeof where !== 'string') {
+    const [failed, content] = await Try.catch(
+      (await getTranspiler()).transform(source),
+    )
+    if (!failed) return content!
+
+    const error = errorWithPosition(failed)
+    if (where) compLog.COMPILE_FAIL({ file: where.file, error })
+    else compLog.COMPILE_SOURCE_FAIL({ error })
+    return source
   }
 
+  const path = where
   source = preprocessImports(source, path)
 
   const [failed, transformed] = await Try.catch(
@@ -163,8 +172,9 @@ export async function compileText(source: string, path?: fs.AbsolutePath) {
   )
 
   if (failed) {
-    // `errorWithPosition`, not `errorMsg`: the thrown `BuildMessage` has no
-    // stack, so `errorMsg` degrades to the bare message and the line number (    // the only thing that makes this actionable) is dropped. The file comes
+    // `errorWithPosition`, not `errorMsg`: what `transform()` rejects with
+    // has no stack, so `errorMsg` degrades to a bare message and drops the
+    // line number, the only thing that makes this actionable. The file comes
     // from `{file}`; the diagnostic's own `position.file` is `input.ts`,
     // because `transform()` was handed a string.
     compLog.COMPILE_FAIL({ file: path, error: errorWithPosition(failed) })

package/src/compiler/dev-service.ts

@@ -542,7 +542,8 @@ const MODULE_ROUTE_EXT = /\.(tsx|jsx)$/
  * change and restarts already.
  *
  * `rename` is the creation signal. Measured on Windows: an in-place write
- * (`Bun.write`, `fs.writeFile`) emits only `change` and keeps the fast path ( * 14-15ms edit-to-served), while creating a file emits `rename` then
+ * (`Bun.write`, `fs.writeFile`) emits only `change` and keeps the fast path
+ * (14-15ms edit-to-served), while creating a file emits `rename` then
  * `change`. Writers that replace rather than overwrite report `rename` for an
  * *edit* too and pay one restart (~440ms): shell redirection (`> file`) does
  * this, and an editor that saves atomically will as well. That is the safe

package/src/core/define-route.ts

@@ -5,7 +5,8 @@ import { type Validator, validate } from '../utils/http/validate'
 /**
  * `defineRoute`, in its own module rather than in `core/index.ts`.
  *
- * `core/index.ts` is a barrel (it pulls in the logger, plugins, jsx and utils),  * so anything importing it from *inside* core closes a cycle and dies with
+ * `core/index.ts` is a barrel (it pulls in the logger, plugins, jsx and utils),
+ * so anything importing it from *inside* core closes a cycle and dies with
  * `ReferenceError: Cannot access 'Logger' before initialization`. That is
  * recorded in CLAUDE.md as costing 67 tests once; it cost this file's own tests
  * a second time, which is what moved it here. Consumers still reach it through

package/src/core/jsx.ts

@@ -33,7 +33,7 @@ export const Fragment = ({ children }: { children?: any }) =>
  * like a string everywhere (`.trim()`, concatenation, `String()`), so callers
  * are unaffected.
  */
-export class SafeHtml extends String {}
+class SafeHtml extends String {}
 
 /** Mark a string as trusted HTML, exempting it from escaping. */
 export function raw(value: unknown): string {

package/src/handlers/assets/google-font.ts

@@ -123,6 +123,39 @@ function canonicalQuery(search: string): string | null {
   return `?${pairs.sort().join('&')}`
 }
 
+/**
+ * A `&text=` subset's address, as the CSS endpoint writes it:
+ * `l/font?kit=neILzCirqoswsqX9_oC0MuFXPPo&skey=7ed805a363b4659c&v=v32`.
+ *
+ * It has no extension and names its font in the query alone, so it cannot pass
+ * `GF_GSTATIC_PATH`, and every such request answered 404. The three parameters
+ * are the only ones allowed through, in a canonical order, and a kit is free
+ * text in the way a family name is: `GF_MAX_ENTRIES` is what bounds them.
+ */
+const GF_SUBSET_PATH = 'l/font'
+const GF_SUBSET_PARAMS = new Set(['kit', 'skey', 'v'])
+const GF_SUBSET_VALUE = /^[a-zA-Z0-9_-]+$/
+
+/** The subset's query in canonical order, or `null` if it is not one. */
+function subsetQuery(search: string): string | null {
+  const raw = search.startsWith('?') ? search.slice(1) : search
+  if (!raw || raw.length > GF_MAX_GSTATIC_PATH) return null
+
+  const pairs = raw.split('&')
+  const names = new Set<string>()
+  for (const pair of pairs) {
+    const [name, value, extra] = pair.split('=')
+    if (!GF_SUBSET_PARAMS.has(name) || names.has(name)) return null
+    if (extra !== undefined || !value || !GF_SUBSET_VALUE.test(value)) {
+      return null
+    }
+    names.add(name)
+  }
+  if (!names.has('kit')) return null
+
+  return `?${pairs.sort().join('&')}`
+}
+
 export class GoogleFontHandler extends Handler {
   static get cacheDir() {
     return fs.resolve(Bakery.cacheDir, 'gf_cache')
@@ -134,7 +167,7 @@ export class GoogleFontHandler extends Handler {
 
   static async handle(path: string, req: Request) {
     if (path.startsWith('/_gf/gstatic/')) {
-      return this.handleGstatic(path)
+      return this.handleGstatic(path, new URL(req.url).search)
     }
 
     const rawPath = path.slice('/_gf'.length)
@@ -185,28 +218,35 @@ export class GoogleFontHandler extends Handler {
     return cached
   }
 
-  private static async handleGstatic(path: string) {
+  private static async handleGstatic(path: string, search: string) {
     const gstaticPath = path.slice('/_gf/gstatic/'.length)
+    const isSubset = gstaticPath === GF_SUBSET_PATH
+    const query = isSubset ? subsetQuery(search) : ''
 
     // Refused before `this.cacheDir` is read, so a rejection costs neither a
     // config lookup nor a path resolution.
     if (
+      query === null ||
       gstaticPath.length > GF_MAX_GSTATIC_PATH ||
-      !GF_GSTATIC_PATH.test(gstaticPath)
+      (!isSubset && !GF_GSTATIC_PATH.test(gstaticPath))
     ) {
       return response.error('Unknown Google Fonts asset', 404)
     }
 
     const cacheDir = fs.resolve(this.cacheDir, 'gstatic')
-    const cacheExt = `${fs.parse(gstaticPath).ext || '.bin'}`
-    const cacheName = `${toHash(gstaticPath)}${cacheExt}`
+    // The CSS endpoint asks as Chrome, so a subset is always a woff2. It has no
+    // extension of its own to read that from.
+    const cacheExt = isSubset
+      ? '.woff2'
+      : `${fs.parse(gstaticPath).ext || '.bin'}`
+    const cacheName = `${toHash(`${gstaticPath}${query}`)}${cacheExt}`
 
     const cached = await fs.getOrCreateCachedFile(
       cacheDir,
       cacheName,
       null,
       async () => {
-        const gfUrl = `https://fonts.gstatic.com/${gstaticPath}`
+        const gfUrl = `https://fonts.gstatic.com/${gstaticPath}${query}`
         const res = await fetch(gfUrl)
 
         if (!res.ok) return null

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

@@ -253,7 +253,8 @@ export class Handler {
   static servesFiles = true
 
   /**
-   * The URL prefix this handler owns as a complete user-facing surface (   * `'/_dashboard'`, `'/_db'`), or `null` for the ordinary case of a handler
+   * The URL prefix this handler owns as a complete user-facing surface
+   * (`'/_dashboard'`, `'/_db'`), or `null` for the ordinary case of a handler
    * that answers by extension or content rather than by prefix.
    *
    * This exists so one surface can ask whether another is mounted without

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

@@ -88,7 +88,8 @@ const routeGlobs = (
  * The catch-all fallback for one directory level: `dir/[...name].ext`,
  * containment-checked like every other candidate. Skipped for `staticOnly`
  * (the caller wants a literal file), and it *yields to any real file*: when
- * the request's remaining segments name an existing file under `dir` ( * whatever its extension) the catch-all declines, so a lower-priority
+ * the request's remaining segments name an existing file under `dir`
+ * (whatever its extension) the catch-all declines, so a lower-priority
  * handler (TSHandler, StaticHandler) can serve the file itself. A directory
  * is not a file and does not trigger the yield. `findDynamicRoute` applies
  * the same rule on the cached path; the two must agree.

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

@@ -10,7 +10,8 @@ import { resolveMount } from './$mounts'
  * dynamic `[id]` segments and glob scanning. This answers the simpler question
  * "which file is at this path, and am I allowed to serve it".
  *
- * It exists because four handlers were each spelling that out themselves ( * StaticHandler, PublicHandler, ImageHandler and NMHandler) in four slightly
+ * It exists because four handlers were each spelling that out themselves
+ * (StaticHandler, PublicHandler, ImageHandler and NMHandler) in four slightly
  * different ways, and only some of them checked everything. Once route mounts
  * arrived the drift got worse: a mount-aware StaticHandler sitting next to a
  * mount-blind PublicHandler is the kind of inconsistency that turns into a bug

package/src/logger/serve-log.ts

@@ -257,12 +257,20 @@ export function errorDetail(err: any): string {
  * `position.file` is `input.ts` whenever `transform()` was handed a source
  * string rather than a path (which is every compile this codebase does), so
  * printing it beside the real path would contradict it.
+ *
+ * `transform()` rejects with an `AggregateError` whose own message is only
+ * "Transform failed", with no position, and whose `errors` are the
+ * diagnostics, so the first of those is the one read. The rest usually follow
+ * from it: a `;` inside an object literal is reported as `Expected "}" but
+ * found ";"`, then as `Unexpected }` at the brace after it.
  */
 export function errorWithPosition(err: any): string {
-  const position = (err as Diagnostic)?.position
+  const first: Diagnostic =
+    Array.isArray(err?.errors) && err.errors.length ? err.errors[0] : err
+  const position = first?.position
   if (!position || position.line == null) return errorMsg(err)
 
-  const message = (err as Diagnostic).message || errorMsg(err)
+  const message = first.message || errorMsg(first)
   return `${message} (line ${position.line}, column ${position.column ?? 0})`
 }
 

package/src/router.ts

@@ -289,7 +289,8 @@ export const serveWebSocket: Bun.WebSocketHandler<any> = {
       try {
         const h = prepareWSData(ws)
         if (h) return await h.handler.message(ws, message, h.data)
-        config.websocket.message(ws, message)
+        // Optional since bun-types 1.4.4, like the other three below.
+        await config.websocket.message?.(ws, message)
       } catch (err: any) {
         serveLog.UNHANDLED_ERR({
           error: `WebSocket message error: ${errorMsg(err)}`,

package/src/utils/fs.ts

@@ -784,7 +784,10 @@ export namespace FileSystem {
     if (content == null) return null
     await mkdir(cacheDir)
     await rawFile.write(content)
-    return built(rawFile)
+    // A new handle: `rawFile` read its size before the file existed, so serving
+    // it answered 200 with `content-length: 0` and no body. Measured on a cold
+    // font, which Chrome then reports as failed; the next request read the file.
+    return built(Bun.file(rawPath))
   }
 
   /**

package/src/utils/http/csrf.ts

@@ -7,6 +7,7 @@
  * arrive with the victim's session attached.
  */
 
+import { Bakery } from '../../core/bakery'
 import { Try } from '../isomorphic/try'
 
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
@@ -14,20 +15,47 @@ const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
 /** `Sec-Fetch-Site` values that mean the request did not come from another site. */
 const SAME_SITE_VALUES = new Set(['same-origin', 'same-site', 'none'])
 
+/**
+ * The origin a browser sees for this request.
+ *
+ * A proxy that ends TLS leaves the request looking like `http://app.example`
+ * while the browser reports `https://app.example`. Under `trustProxy` the
+ * proxy's forwarded scheme and host are believed, as `getHostname` and the
+ * session's `Secure` flag believe them. Without it the request's own URL
+ * decides, since any client could send those headers.
+ */
+export function requestOrigin(req: Request, url: URL): string {
+  if (!Bakery.config.trustProxy) return url.origin
+
+  const forwarded = (name: string) =>
+    req.headers.get(name)?.split(',')[0].trim()
+  const scheme = forwarded('x-forwarded-proto') || url.protocol.slice(0, -1)
+  const host = forwarded('x-forwarded-host') || url.host
+
+  return Try(() => new URL(`${scheme}://${host}`).origin) ?? url.origin
+}
+
 /**
  * Returns a reason string when the request looks cross-site, or `null` when it
  * is safe to process. Requests with neither `Origin` nor `Sec-Fetch-Site` (curl,
  * server-to-server, older clients) are allowed: browsers always send at least
  * one of them on a cross-origin request.
+ *
+ * A same-origin `Sec-Fetch-Site` settles it before `Origin` is read. A browser
+ * sets that header and page script cannot, and it is right behind a proxy that
+ * ends TLS, where `Origin` names a scheme this server never saw: measured, every
+ * browser write there answered 403, with `trustProxy` on or off. A client that
+ * forges the header could forge `Origin` as well, so nothing is lost.
  */
 export function checkSameOrigin(req: Request, url: URL): string | null {
   const fetchSite = req.headers.get('sec-fetch-site')
   if (fetchSite && !SAME_SITE_VALUES.has(fetchSite)) {
     return `cross-site request rejected (Sec-Fetch-Site: ${fetchSite})`
   }
+  if (fetchSite === 'same-origin' || fetchSite === 'none') return null
 
   const origin = req.headers.get('origin')
-  if (origin && origin !== 'null' && origin !== url.origin) {
+  if (origin && origin !== 'null' && origin !== requestOrigin(req, url)) {
     return `cross-origin request rejected (Origin: ${origin})`
   }
 
@@ -63,7 +91,8 @@ function safeEcho(value: string): string {
  *
  * WebSockets are exempt from the same-origin policy. Any page the developer
  * visits can open `ws://localhost:3000/_livereload`, and until this existed
- * one `{"type":"subscribe_logger"}` bought a live feed of the server log ( * failing SQL, table and column names, absolute source paths) plus the
+ * one `{"type":"subscribe_logger"}` bought a live feed of the server log
+ * (failing SQL, table and column names, absolute source paths) plus the
  * ability to reload every open browser. The only thing that separates the
  * app's own page from an attacker's is `Origin`, which the browser sets on
  * every handshake and page script cannot override.

package/src/utils/http/etag.ts

@@ -102,7 +102,8 @@ export namespace ETag {
   /**
    * One stat, and the values are kept rather than discarded: a `BunFile`
    * caches its stat on first property access (~66us fresh, ~40ns after), so
-   * routing the probe through `fs.exists` (which stats a throwaway instance)    * made every served variant pay a second, identical stat in `fromFile`.
+   * routing the probe through `fs.exists` (which stats a throwaway instance)
+   * made every served variant pay a second, identical stat in `fromFile`.
    * Same existence predicate as `fs.exists`; note a missing file reports
    * size 0 and a far-future sentinel `lastModified`, never 0.
    */

package/src/utils/http/html.ts

@@ -5,7 +5,9 @@ import { DOMTools, headBodyCache } from './dom'
 import { ETag } from './etag'
 
 /**
- * Mark `res` as already carrying the head/body injects, so `injectIfHtml` ( * and therefore `processResponse`, which every response funnels through)  * hands it back untouched.
+ * Mark `res` as already carrying the head/body injects, so `injectIfHtml`
+ * (and therefore `processResponse`, which every response funnels through)
+ * hands it back untouched.
  *
  * Exported for the one caller that means "never", not "already":
  * `DefaultErrorHandler` brands its production error page so the import map is

package/src/utils/http/sse.ts

@@ -13,6 +13,8 @@
  * write after the client has gone throws where nobody is catching.
  */
 
+import { Bakery } from '../../core/bakery'
+
 /** One event. Every field is optional except the payload. */
 export interface SSEMessage {
   /** Serialized with `JSON.stringify` unless it is already a string. */
@@ -105,6 +107,11 @@ export function sse(
   const encoder = new TextEncoder()
   const { keepAlive = 15_000, retry } = options
 
+  // A quiet stream is not a finished one, and `Bun.serve` closes a connection
+  // that stays quiet past its idle timeout. Lifted for this request only: the
+  // stream ends when the client leaves or `close()` runs.
+  Bakery.server?.timeout(req, 0)
+
   let controller: ReadableStreamDefaultController<Uint8Array> | null = null
   let closed = false
   let cleanup: (() => void) | void
@@ -123,16 +130,22 @@ export function sse(
     }
   }
 
-  function finish() {
-    if (closed) return
-    closed = true
-    if (keepAliveTimer) clearInterval(keepAliveTimer)
+  function runCleanup() {
+    const pending = cleanup
+    cleanup = undefined
     try {
-      cleanup?.()
+      pending?.()
     } catch {
       // A producer's cleanup that throws must not prevent the stream closing;
       // the connection is already going away either way.
     }
+  }
+
+  function finish() {
+    if (closed) return
+    closed = true
+    if (keepAliveTimer) clearInterval(keepAliveTimer)
+    runCleanup()
     try {
       controller?.close()
     } catch {
@@ -176,6 +189,9 @@ export function sse(
 
       try {
         cleanup = await producer(stream)
+        // The client can leave during that await. `finish` has then run, found
+        // no cleanup and will not run again, so this one would never be called.
+        if (closed) runCleanup()
       } catch {
         // A producer that throws ends the stream rather than leaving the client
         // hanging on a connection nobody will write to again.

package/src/utils/http/validate.ts

@@ -1,9 +1,10 @@
 /**
  * Request-body validation for route modules.
  *
- * `defineRoute<{ title: string }>` declares a body shape and enforces nothing ( * the scaffolder's own template says so twice: *"declares the contract) it
- * does not validate it. The body is still client input."* Every route was left
- * to hand-check or not, and most did not.
+ * `defineRoute<{ title: string }>` declares a body shape and enforces nothing,
+ * as the scaffolder's own template puts it: *"It states the contract; it does
+ * not enforce it."* Every route was left to hand-check or not, and most did
+ * not.
  *
  * **No schema library is bundled, and none is depended on.** `@bakery-framework/
  * core` has zero runtime dependencies and that is worth keeping, so validation

package/src/utils/isomorphic/stringify.ts

@@ -2,7 +2,8 @@
  * Circular-safe JSON helpers.
  *
  * Three copies of this logic existed: the client `$fmt` formatter, the
- * livereload log serializer, and ad-hoc replacers on the server. They drifted ( * the `$fmt` one shipped with a one-parameter replacer that made every object
+ * livereload log serializer, and ad-hoc replacers on the server. They drifted
+ * (the `$fmt` one shipped with a one-parameter replacer that made every object
  * render as `""`), so the kernel lives here once and callers layer their own
  * extras on top.
  */