@bakery-framework/core 1.0.0

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

@@ -0,0 +1,301 @@
+import { errorDetail } from '../../logger/serve-log'
+import type { MapOf, MixedPromise } from '../../types'
+import { is } from '../../utils/common'
+import { fs } from '../../utils/fs'
+import { response } from '../../utils/http'
+import { Handler } from './$base'
+import { DynamicHandler } from './$dynamic'
+
+const DEFAULT_ERROR: Handler.Error.Data = {
+  errorCode: 500,
+  errorText: 'Internal Server Error',
+  errorBody: 'An unexpected error occurred.',
+}
+
+/**
+ * A fresh copy of the process-wide default error data.
+ *
+ * The copy is the point, not the convenience. `extractErrorData` assigns the
+ * getter's result to a local and then *mutates* it, which is safe only while
+ * every `this` it runs under hands back a new object — a plain
+ * `= DEFAULT_ERROR` would let any caller write the process-wide default's
+ * fields. Both `ErrorHandler` and `DynamicErrorHandler` need the getter and
+ * they sit in different class hierarchies, so neither can inherit it from the
+ * other; they call this instead of each keeping a copy of the copy.
+ */
+function defaultErrorData(): Handler.Error.Data {
+  return Object.assign({}, DEFAULT_ERROR)
+}
+
+/**
+ * The three lines every page handler opens with: the error-data default, the
+ * route lookup, and the 404 for a path that resolves to nothing.
+ *
+ * `HTMLHandler`, `TSXHandler` and the Vue plugin's handler render three
+ * different file formats and their bodies genuinely differ — but all three
+ * reach them this way. `errors` is `undefined` for an ordinary page, and
+ * `DEFAULT_ERROR` exists only on the error subclasses, so the fallback stays
+ * `undefined` for the ordinary handlers. `DynamicErrorHandler.resolveRoute`
+ * uses the second argument to prefer `error-<code>` over `error`;
+ * `DynamicHandler.resolveRoute` ignores it.
+ *
+ * Hands back the 404 `Response` itself rather than a `null` the caller has to
+ * remember to turn into one.
+ */
+export async function beginPageRoute(
+  handler: typeof DynamicHandler | typeof DynamicErrorHandler,
+  path: string,
+  errors?: Handler.Error.Data,
+): Promise<
+  | { errorData: Handler.Error.Data | undefined; info: Handler.Route.Info }
+  | Response
+> {
+  const errorData = errors || (handler as any).DEFAULT_ERROR
+  const info = await handler.resolveRoute(path, errorData)
+  if (!info) return response.error('Not Found')
+  return { errorData, info }
+}
+
+/**
+ * Stamp the DEV-only `__file` marker onto a page's params.
+ *
+ * One spelling of one rule: the marker goes on the params object **before**
+ * whatever error data gets merged in, and it names the route-relative path.
+ * `HTMLHandler` used to set it after the merge and `TSXHandler` before, which
+ * comes out the same today only because `publicErrorData` never emits a
+ * `__file` key — two orderings for one rule is what makes it look like the
+ * order might matter. It does not; this is the order, and `params` is the
+ * object because TSX also feeds that same object to `injectIfHtml`.
+ */
+export function markDevFile(params: MapOf<any>, routePath: string): void {
+  if (import.meta.env.DEV) params.__file = routePath
+}
+
+export class HandlerError extends Error {
+  data: Handler.Error.Data
+  request?: Request = undefined
+
+  static getDefaultData() {
+    return DEFAULT_ERROR
+  }
+
+  constructor(
+    message?: string,
+    req?: Request,
+    data?: Partial<Handler.Error.Data>,
+  ) {
+    const finalData = {
+      ...HandlerError.getDefaultData(),
+      ...data,
+    }
+
+    super(message || finalData.errorText || 'Handler Error')
+    this.data = finalData as Handler.Error.Data
+    this.request = req
+  }
+}
+
+export class ErrorHandler extends Handler {
+  /** A fresh copy every read — see `defaultErrorData`. */
+  static get DEFAULT_ERROR() {
+    return defaultErrorData()
+  }
+
+  static isError(error: any): boolean {
+    if (error instanceof Response) return error.status >= 400
+    if (error instanceof HandlerError) return true
+    if (is.object(error)) {
+      if ('errorCode' in error && is.number(error.errorCode)) {
+        return error.errorCode >= 400
+      }
+    }
+
+    return false
+  }
+
+  static canHandle(
+    path: string,
+    req: Request,
+    errors?: Handler.Error.Data,
+  ): MixedPromise<boolean>
+  static canHandle() {
+    return true
+  }
+
+  static handle(
+    path: string,
+    req: Request,
+    errors?: Handler.Error.Data,
+  ): Handler.Response
+  static handle() {}
+
+  /**
+   * The part of `error` that may cross the wire.
+   *
+   * `extractErrorData` puts `error.stack` into `errorBody` deliberately — that
+   * is what reaches the server log, and losing it would be a regression. But
+   * the same field was being handed straight to the client: a `SQLiteError`
+   * from a failed query answered a 500 with the failing statement, the table
+   * and column names, and absolute paths into the source tree.
+   *
+   * So the redaction belongs at the boundary, not at extraction. 5xx is the
+   * only band `extractErrorData` ever fills from a thrown `Error`, and
+   * therefore the only one whose body can be a stack; a 4xx body is authored
+   * by whoever constructed the `HandlerError` or the `Response` and is theirs
+   * to disclose.
+   */
+  static publicBody(error: Handler.Error.Data): string {
+    if (import.meta.env.DEV) return error.errorBody
+    return error.errorCode >= 500 ? DEFAULT_ERROR.errorBody : error.errorBody
+  }
+
+  /**
+   * Whether `error` is one of Bun's compile-time diagnostics.
+   *
+   * `BuildMessage` (a syntax error) and `ResolveMessage` (an import that
+   * resolves to nothing) are what the transpiler and the module resolver throw,
+   * and neither is `instanceof Error`. They used to reach the `is.object`
+   * branch below, which reads only `errorCode`/`errorText`/`errorBody` — none
+   * of which a diagnostic has — and so returned the untouched default. A typo
+   * in a route file, the single most common server-side failure there is,
+   * answered `An unexpected error occurred.` in development as well as in
+   * production.
+   *
+   * Recognised by shape rather than by constructor: the classes are not
+   * exported, and both report zero own enumerable keys, so a string `message`
+   * on a non-`Error` object is the only tell. The error-data keys are checked
+   * first by the caller, so a record that carries those still takes its own
+   * branch.
+   */
+  static isDiagnostic(error: any): boolean {
+    if (!is.object(error)) return false
+    if (error instanceof Error || error instanceof Response) return false
+    return is.string(error.message) && error.message.length > 0
+  }
+
+  static extractErrorData(error: any): Handler.Error.Data {
+    if (error instanceof HandlerError) return error.data
+
+    if (error instanceof Error) {
+      return {
+        ...this.DEFAULT_ERROR,
+        errorText: error.message,
+        // `errorDetail` is `error.stack` whenever there is one — so the common
+        // case is untouched — and falls back to the aggregated sub-diagnostics
+        // for the stackless `AggregateError` that `import()`ing a broken `.tsx`
+        // throws, where `String(error)` was a summary count and nothing else.
+        errorBody: errorDetail(error) || String(error),
+      }
+    }
+
+    if (error instanceof Response) {
+      return {
+        ...this.DEFAULT_ERROR,
+        errorCode: error.status,
+        errorText: error.statusText,
+        errorBody: `${error.status}: "${error.statusText}"`,
+      }
+    }
+
+    if (is.object(error)) {
+      const errorObj = error as Partial<Handler.Error.Data>
+      const authored =
+        errorObj.errorCode !== undefined ||
+        errorObj.errorText !== undefined ||
+        errorObj.errorBody !== undefined
+
+      // Authored error data wins, `message` or no `message` — the branch order
+      // and its semantics are unchanged for everything that ever reached it.
+      if (!authored && this.isDiagnostic(error)) {
+        return {
+          ...this.DEFAULT_ERROR,
+          errorText: error.message,
+          errorBody: errorDetail(error),
+        }
+      }
+
+      const errorData = this.DEFAULT_ERROR
+
+      errorData.errorCode = errorObj.errorCode ?? errorData.errorCode
+      errorData.errorText = errorObj.errorText ?? errorData.errorText
+      errorData.errorBody = errorObj.errorBody ?? errorData.errorBody
+      return errorData
+    }
+
+    if (is.string(error)) {
+      return { ...this.DEFAULT_ERROR, errorText: error }
+    }
+
+    return this.DEFAULT_ERROR
+  }
+}
+
+export class DynamicErrorHandler extends DynamicHandler {
+  /**
+   * The same fresh copy `ErrorHandler.DEFAULT_ERROR` hands back — see
+   * `defaultErrorData`. Declared again rather than inherited because this
+   * class descends from `DynamicHandler`, not from `ErrorHandler`.
+   */
+  static get DEFAULT_ERROR() {
+    return defaultErrorData()
+  }
+
+  static canHandle(
+    path: string,
+    req: Request,
+    errors?: Handler.Error.Data,
+  ): MixedPromise<boolean>
+  static async canHandle(path: string, _: any, errors?: Handler.Error.Data) {
+    return Boolean(await this.resolveRoute(path, errors))
+  }
+
+  static handle(
+    path: string,
+    req: Request,
+    errors?: Handler.Error.Data,
+  ): Handler.Response
+
+  static handle(path: string, req: Request, errors?: Handler.Error.Data) {
+    return (super.handle as any)(path, req, errors)
+  }
+
+  static async resolveRoute(path: string, errors?: Handler.Error.Data) {
+    errors ||= this.DEFAULT_ERROR
+
+    const parsed = fs.parse(path)
+    const pathArray = parsed.dir.split('/').filter(Boolean)
+
+    for (let i = pathArray.length; i >= 0; i--) {
+      const prefix = i ? `/${pathArray.slice(0, i).join('/')}` : ''
+
+      const defsPage = `${prefix}/error`
+      const codePage = `${prefix}/error-${errors.errorCode}`
+      const routeInfo =
+        (await super.resolveRoute(codePage)) ||
+        (await super.resolveRoute(defsPage))
+      if (routeInfo) return routeInfo
+    }
+
+    return null
+  }
+}
+
+/**
+ * Error data with `errorBody` reduced to what a client may see.
+ *
+ * `ErrorHandler.publicBody` is the rule; this is it applied to a whole record,
+ * for the handlers that hand error data to a *template* rather than rendering
+ * a string themselves. `HTMLErrorHandler` and `TSXErrorHandler` merge the
+ * record into their page params, and those params reach the document twice —
+ * through `{{...}}` substitution and through the `window.__PAGE_PARAMS__`
+ * script `DOMTools.params` injects into every page. The second path is why
+ * redacting in the template was never enough: an `error.html` that never
+ * mentions `errorBody` still published the stack, absolute source paths and
+ * all, to any anonymous request in production.
+ *
+ * `errorText` is deliberately untouched — `DefaultErrorHandler` shows it in
+ * its heading in every mode, and one rule in one place beats two that drift.
+ */
+export function publicErrorData(error: Handler.Error.Data): Handler.Error.Data {
+  return { ...error, errorBody: ErrorHandler.publicBody(error) }
+}

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

@@ -0,0 +1,71 @@
+import { Bakery } from '../../core/bakery'
+import { errorMsg, handlerLog } from '../../logger/serve-log'
+import { injectIfHtml, response } from '../../utils/http'
+import { Handler } from './$base'
+
+/**
+ * Per-request slot for the response produced during `canHandle`, so `handle`
+ * can return it without re-running the chain. This was previously a static
+ * field, which meant two concurrent requests could swap responses — including
+ * each other's `Set-Cookie` headers — at any `await` boundary.
+ */
+const pending = new WeakMap<Request, Response>()
+
+export class MiddlewareHandler extends Handler {
+  /** Answers from app code, not from disk. See `Handler.servesFiles`. */
+  static servesFiles = false
+
+  /**
+   * `canHandle` here means "was this request denied", which is a fact about
+   * the request and not about the path. Without this the route cache would
+   * serve the page handler that the first *allowed* request resolved to,
+   * and every later request to that path would skip middleware entirely.
+   */
+  static override alwaysResolve = true
+
+  static async canHandle(path: string, req: Request) {
+    const result = await this.handle(path, req)
+    if (result) pending.set(req, result)
+    return Boolean(result)
+  }
+
+  static async handle(_path: string, req: Request) {
+    const cached = pending.get(req)
+    if (cached) {
+      pending.delete(req)
+      return cached
+    }
+
+    // One config read for both `onRequest` and the middleware chain — same
+    // request, same host store, so the snapshot cannot go stale mid-call.
+    const config = Bakery.config
+    const intercepted = await config.onRequest(req!)
+    if (intercepted) {
+      // `|| undefined` used to sit here, and `injectIfHtml` returns null for
+      // anything that is not HTML — so a plain-text 403 from `onRequest`
+      // vanished and the request carried on. Inject when it is HTML, keep the
+      // original otherwise, exactly as the middleware chain below does.
+      return (await injectIfHtml(intercepted)) || intercepted
+    }
+
+    let data: any
+
+    for (const middleware of config.middleware) {
+      try {
+        const result = await middleware(req, Bakery.server!)
+        if (result instanceof Response) {
+          data = result
+          break
+        }
+      } catch (error) {
+        // Fail closed: a middleware that throws is often an auth check, and
+        // treating it as "no response" would let the request through.
+        handlerLog.MIDDLEWARE_ERR({ error: errorMsg(error) })
+        return response.error('Internal Server Error', 500)
+      }
+    }
+
+    const injectedRes = await injectIfHtml(data)
+    return injectedRes || data
+  }
+}

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

@@ -0,0 +1,84 @@
+import { fs } from '../../utils'
+
+/**
+ * Route mounts: map a URL prefix onto a directory outside the app's serve root.
+ *
+ * Handlers resolve files under `Bakery.serveRoot`, so a plugin wanting to serve
+ * its own pages or client assets had no choice but to hand-roll it — reading
+ * files itself, bundling on the fly, and reimplementing the caching and
+ * containment the handler pipeline already does. `DashboardHandler` is the
+ * worked example of that cost.
+ *
+ * A mount lets a plugin say "paths under `/_dashboard` come from *my*
+ * directory", after which the normal handlers (TSX, TS, HTML, static, the
+ * compiler, the route cache) treat those files exactly like app files.
+ *
+ * Containment still applies: `getRoute` receives the mount directory as both
+ * the search dir *and* the root, so traversal cannot escape it.
+ */
+export interface RouteMount {
+  /** URL prefix, leading slash, no trailing slash — e.g. `/_dashboard`. */
+  prefix: string
+  /** Absolute directory the prefix resolves against. */
+  dir: fs.AbsolutePath
+}
+
+/** Registered longest-prefix-first, so nested mounts resolve predictably. */
+const mounts: RouteMount[] = []
+
+function normalizePrefix(prefix: string): string {
+  const withSlash = prefix.startsWith('/') ? prefix : `/${prefix}`
+  return withSlash.length > 1 && withSlash.endsWith('/')
+    ? withSlash.slice(0, -1)
+    : withSlash
+}
+
+/**
+ * Serve `prefix/*` from `dir`. Call from a plugin's `setup()`.
+ *
+ * Re-registering the same prefix replaces it, so a reloading dev worker does
+ * not accumulate duplicates.
+ */
+export function mountRoutes(prefix: string, dir: string): RouteMount {
+  const mount: RouteMount = {
+    prefix: normalizePrefix(prefix),
+    dir: fs.resolve(dir) as fs.AbsolutePath,
+  }
+
+  const existing = mounts.findIndex(m => m.prefix === mount.prefix)
+  if (existing !== -1) mounts.splice(existing, 1)
+
+  mounts.push(mount)
+  mounts.sort((a, b) => b.prefix.length - a.prefix.length)
+  return mount
+}
+
+/**
+ * The mount owning `path`, plus the path relative to it, or null.
+ *
+ * A prefix matches only on a segment boundary: `/_dash` must not capture
+ * `/_dashboard`.
+ */
+export function resolveMount(
+  path: string,
+): { mount: RouteMount; rest: string } | null {
+  const normalized = path.startsWith('/') ? path : `/${path}`
+
+  for (const mount of mounts) {
+    if (normalized === mount.prefix) return { mount, rest: '' }
+    if (normalized.startsWith(`${mount.prefix}/`)) {
+      return { mount, rest: normalized.slice(mount.prefix.length + 1) }
+    }
+  }
+  return null
+}
+
+/** Every registered mount, longest prefix first. */
+export function getMounts(): readonly RouteMount[] {
+  return mounts
+}
+
+/** Drop all mounts. Intended for tests. */
+export function clearMounts(): void {
+  mounts.length = 0
+}

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

@@ -0,0 +1,153 @@
+import { LRUCache } from '../../cache/lru'
+import type { Handler } from './$base'
+
+/**
+ * Registry ids for `routeCache` keys. A module counter gives the same
+ * per-process uniqueness a UUID did (the cache never outlives the process)
+ * with a key prefix of a few characters instead of thirty-six.
+ */
+let nextMapId = 0
+
+export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
+  any,
+  number
+> {
+  public static routeCache = new LRUCache<string, typeof Handler>(
+    import.meta.env.THREAD_WORKER ? 500 : 5000,
+  )
+
+  private cachedList: T[] | null = null
+  private cachedGates: T[] | null = null
+  private cachedOrder: Map<any, number> | null = null
+  private id = nextMapId++
+
+  constructor(entries?: readonly (readonly [any, number])[] | null) {
+    super()
+    if (!entries) return
+
+    for (const [handlerClass, priority] of entries) {
+      this.set(handlerClass, priority)
+    }
+  }
+
+  set(handlerClass: any, priority: number = 10): this {
+    super.set(handlerClass, priority)
+    this.cachedList = null
+    this.cachedGates = null
+    this.cachedOrder = null
+    return this
+  }
+
+  add(handlerClass: any, priority?: number): this {
+    return this.set(handlerClass, priority)
+  }
+
+  list(): T[] {
+    if (this.cachedList) {
+      return this.cachedList
+    }
+    this.cachedList = Array.from(this.entries())
+      .sort((a, b) => b[1] - a[1])
+      .map(entry => entry[0])
+
+    return this.cachedList
+  }
+
+  /** Handlers that opt out of the cache bypass, in priority order. */
+  private gatekeepers(): T[] {
+    this.cachedGates ??= this.list().filter(h => (h as any).alwaysResolve)
+    return this.cachedGates
+  }
+
+  /** Position of each handler in the priority-sorted list. */
+  private order(): Map<any, number> {
+    this.cachedOrder ??= new Map(this.list().map((h, i) => [h, i]))
+    return this.cachedOrder
+  }
+
+  /**
+   * `canHandle` without the microtask hop when the answer is synchronous.
+   *
+   * Most canHandles are plain predicates, and `await`ing their boolean cost a
+   * microtask hop (~426ns) per probe, 2–4 probes per request. Returns a
+   * boolean for a sync answer and the promise itself for an async one, so
+   * callers only `await` a value that is actually a promise:
+   *
+   *     const r = HandlerMap.probe(...)
+   *     if (r === true || (r !== false && (await r))) ...
+   */
+  private static probe(
+    handler: any,
+    path: string,
+    req: Request | undefined,
+    rest: any[],
+  ): boolean | Promise<any> {
+    const r = handler.canHandle(path, req, ...rest)
+    return r && typeof (r as any).then === 'function' ? r : Boolean(r)
+  }
+
+  /**
+   * The first extra argument is the request in every registry's call shape
+   * (fetch: `(path, req)`, websocket: `(path, req)`, error:
+   * `(path, req, error)`), so it is named rather than fished out of a variadic
+   * list with an `instanceof` scan per request. `...rest` carries the error
+   * registry's error through to `canHandle`/`handle` untouched.
+   */
+  // The `probed` bookkeeping exists because middleware has side effects and
+  // must not run twice. That constraint is what the branching encodes.
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: cache-path + side-effect-sensitive probe loop
+  async resolve(path: string, req?: Request, ...rest: any[]) {
+    const host = req?.__hostname || ''
+    const pathId = `${this.id}:${host}:${path}`
+    const cached: any = HandlerMap.routeCache.get(pathId)
+
+    // Only tracked once there is a cache hit to skip past. Middleware has
+    // side effects (sessions, rate-limit counters), so a handler probed on the
+    // cache path must not be probed a second time by the loop below.
+    let probed: Set<any> | null = null
+
+    if (cached) {
+      probed = new Set()
+      // A cache hit skips every handler above the cached one. Ask the
+      // gatekeepers that outrank it first — the same handlers, in the same
+      // order, a cold resolve would have reached before the cached one.
+      const rank = this.order().get(cached) ?? Number.POSITIVE_INFINITY
+      for (const gate of this.gatekeepers()) {
+        if ((this.order().get(gate) ?? 0) >= rank) break
+        probed.add(gate)
+        const r = HandlerMap.probe(gate, path, req, rest)
+        if (r === true || (r !== false && (await r))) return gate
+      }
+
+      probed.add(cached)
+      const r = HandlerMap.probe(cached, path, req, rest)
+      if (r === true || (r !== false && (await r))) return cached
+      HandlerMap.routeCache.delete(pathId)
+    }
+
+    for (const handler of this.list() as any) {
+      if (probed?.has(handler)) continue
+      const r = HandlerMap.probe(handler, path, req, rest)
+      if (r === true || (r !== false && (await r))) {
+        // A gatekeeper's `true` describes this request, not this path. Caching
+        // it would both evict the path's real handler and park a per-request
+        // decision in a cache that has no TTL.
+        if (!handler.alwaysResolve) HandlerMap.routeCache.set(pathId, handler)
+        return handler as T
+      }
+    }
+
+    return null
+  }
+
+  initRoutes() {
+    return Promise.all(this.list().map(handler => handler.initRoutes()))
+  }
+
+  handle(path: string, req?: Request, ...rest: any[]): Handler.Response
+  async handle(path: string, req?: Request, ...rest: any[]) {
+    const handler: any = await this.resolve(path, req, ...rest)
+
+    return handler ? handler.handle(path, req, ...rest) : null
+  }
+}