@bakery-framework/core 1.0.0

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

@@ -0,0 +1,256 @@
+import { LRUCache } from '../../cache/lru'
+import type { MapOf, MixedPromise } from '../../types'
+import { fs } from '../../utils/fs'
+import { processBody } from '../../utils/http'
+
+const RX_PARAM = /[[\]{}()*+?.\\^$|]/g
+export const RX_DYNAMIC = /\[([\w$]+)\]/
+export const RX_CATCHALL = /\[\.\.\.([\w$]+)\]/
+
+export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
+  const cleanPath = path.replace(/\\/g, '/').replace(/^\/+/, '')
+  if (!cleanPath) return null
+  if (!RX_DYNAMIC.test(cleanPath) && !RX_CATCHALL.test(cleanPath)) return null
+
+  const params: string[] = []
+  const segments = cleanPath.split('/')
+  const last = segments.length - 1
+  let catchAll = false
+
+  const mappedPaths: string[] = []
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+
+    const catchAllMatch = segment.match(RX_CATCHALL)
+    if (catchAllMatch) {
+      // Only terminal: a segment after `[...x]` has no unambiguous meaning
+      // (which segments belong to the rest?), so the file stays inert — the
+      // same behavior it had before catch-alls existed.
+      if (i !== last) return null
+      params.push(catchAllMatch[1])
+      // `.+` rather than `.*`: the catch-all requires at least one segment,
+      // so `docs/[...slug]` does not shadow a `docs/index` sibling for
+      // `/docs` itself.
+      mappedPaths.push('(.+)')
+      catchAll = true
+      continue
+    }
+
+    const dynamicMatch = segment.match(RX_DYNAMIC)
+    if (dynamicMatch) {
+      params.push(dynamicMatch[1])
+      mappedPaths.push('([^/]+?)')
+      continue
+    }
+
+    mappedPaths.push(segment.replace(RX_PARAM, '\\$&'))
+  }
+
+  return {
+    pattern: new RegExp(`^/${mappedPaths.join('/')}(?:\\.([a-z]*))?$`),
+    params,
+    catchAll,
+  }
+}
+
+export namespace RouteData {
+  export interface Info {
+    readonly file: Bun.BunFile
+    readonly filePath: fs.AbsolutePath
+    readonly path: fs.RelativePath
+    readonly params: string[]
+    readonly valid: boolean
+    readonly isDynamic: boolean
+    readonly catchAll: boolean
+    readonly regex: RegExp | null
+    getParams(path: string): MapOf<string> | null
+  }
+
+  export type Meta = {
+    type: 'endpoint' | 'route' | 'proxy' | 'static' | 'websocket'
+    isRoot: boolean
+    fileName: string
+  }
+}
+
+export namespace Route {
+  export type Info = RouteData.Info
+  export type Meta = RouteData.Meta
+}
+
+// A class, not an object of statics, because it is also a **type** namespace:
+// `RouteData.Info` and `RouteData.Meta` are referenced in type position at four
+// sites above and below. A class declaration provides both a value and a
+// namespace for its nested classes; `const RouteData = { Info: class {} }`
+// provides only the value, and every one of those type references stops
+// resolving.
+// biome-ignore lint/complexity/noStaticOnlyClass: also a type namespace — see above
+export class RouteData {
+  static Info = class Info {
+    readonly params: string[]
+    readonly filePath: fs.AbsolutePath
+    readonly path: fs.RelativePath
+    readonly regex: RegExp | null
+    readonly catchAll: boolean
+
+    constructor(filePath: fs.AbsolutePath, path: fs.RelativePath) {
+      this.filePath = fs.resolve(filePath) as fs.AbsolutePath
+      this.path = path
+
+      const route = getDynamicRoute(path)
+      this.regex = route?.pattern || null
+      this.params = route?.params || []
+      this.catchAll = route?.catchAll || false
+    }
+
+    get file() {
+      return Bun.file(this.filePath)
+    }
+
+    get valid() {
+      return fs.exists(this.filePath)
+    }
+
+    get isDynamic() {
+      return this.regex !== null
+    }
+
+    getParams(path: string): MapOf<string> | null {
+      if (!this.regex) return null
+      const cleanPath = path.startsWith('/') ? path : `/${path}`
+      const match = cleanPath.match(this.regex)
+      if (!match) return null
+
+      const boundParams: MapOf<string> = {}
+      for (let i = 0; i < this.params.length; i++) {
+        boundParams[this.params[i]] = match[i + 1]
+      }
+      return boundParams as MapOf<string>
+    }
+  }
+}
+
+export namespace Handler {
+  export type Response = MixedPromise<
+    globalThis.Response | Bun.BunFile | undefined | object | string | void
+  >
+
+  export namespace Dynamic {
+    export type Config = {
+      ext: string[]
+      dir?: fs.AbsolutePath
+      include?: string[]
+    }
+
+    export type Route = {
+      pattern: RegExp
+      params: string[]
+      /** True when the final segment is a `[...name]` multi-segment matcher. */
+      catchAll?: boolean
+    }
+  }
+
+  export namespace Route {
+    export type Info = RouteData.Info
+    export type Meta = RouteData.Meta
+  }
+
+  export namespace Error {
+    export type Data = {
+      errorCode: number
+      errorText: string
+      errorBody: string
+    }
+  }
+}
+
+/**
+ * Keyed by class identity rather than stored as a `${name}_cache` dynamic
+ * property: the getter runs several times per request, and the template
+ * string + megamorphic property lookup showed up in profiles. A `Map` (not
+ * `WeakMap`) is fine — handler classes live for the process.
+ */
+const handlerCaches = new Map<any, HandlerCache<string, Route.Info>>()
+
+export class Handler {
+  /**
+   * Opt out of the route cache's bypass.
+   *
+   * `HandlerMap.resolve` remembers which handler served a path and goes
+   * straight to it next time, skipping every handler above it. That is safe
+   * when `canHandle` answers a *routing* question ("is there a .tsx file
+   * here?"), because the answer is a property of the path. It is unsafe when
+   * `canHandle` answers a question about *this* request:
+   * `MiddlewareHandler.canHandle` is `Boolean(response)`, i.e. "was this
+   * request denied", so an allowed request caches the page handler and every
+   * later request to that path is served without the gate ever running.
+   *
+   * A handler that sets this is consulted before any cache hit it outranks,
+   * and is never itself written into the cache.
+   */
+  static alwaysResolve = false
+
+  /**
+   * Whether this handler answers with the *bytes of a file*, and so must be
+   * judged by `config.blocked`.
+   *
+   * `false` for handlers that read the request path as a route *name*:
+   * `ApiHandler` resolves a module and executes it, `ProxyHandler` answers
+   * from an upstream, `MiddlewareHandler` from app code. None can leak a
+   * source file by being handed a path that looks like one, and applying the
+   * deny-list to them made `/api/manifest.json` a 403 no config could undo.
+   *
+   * Deny by default: anything that does not opt out — including a plugin's
+   * handler — keeps the check. This is the single source of truth for that
+   * question; `router.ts` gates its request-path check on it, and
+   * `DynamicHandler.resolveRoute` gates the resolved-file check on it.
+   */
+  static servesFiles = true
+
+  protected constructor() {}
+
+  static get cache(): HandlerCache<string, Route.Info> {
+    let cache = handlerCaches.get(this)
+    if (!cache) {
+      cache = new HandlerCache()
+      handlerCaches.set(this, cache)
+    }
+    return cache
+  }
+
+  static canHandle(path: string, req: Request): MixedPromise<boolean>
+  static canHandle(): boolean {
+    return false
+  }
+
+  static Route = RouteData
+  static initRoutes(): MixedPromise<void> {}
+
+  static async params(
+    req: Request,
+    overrides?: MapOf<any>,
+  ): Promise<MapOf<any>> {
+    const body = await processBody(req)
+    return Object.assign({}, body, overrides)
+  }
+
+  static handle(path: string, req: Request): Handler.Response
+  static handle() {
+    return undefined
+  }
+
+  static [Symbol.hasInstance](instance: any): boolean {
+    if (!instance) return false
+    return (
+      instance === this ||
+      (typeof instance === 'function' && instance.prototype instanceof this) ||
+      Object.prototype.isPrototypeOf.call(this.prototype, instance)
+    )
+  }
+}
+
+export class HandlerCache<K, V> extends LRUCache<K, V> {
+  constructor(cacheSize = import.meta.env.THREAD_WORKER ? 50 : 500) {
+    super(cacheSize)
+  }
+}

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

@@ -0,0 +1,285 @@
+import Bakery from '../../core'
+import { hostKey } from '../../core/bakery'
+import { matchBlockedCached } from '../../core/context'
+import { errorMsg, handlerLog } from '../../logger/serve-log'
+import type { MixedPromise } from '../../types'
+import { fs, Try } from '../../utils'
+import {
+  Handler,
+  HandlerCache,
+  type Route,
+  RX_CATCHALL,
+  RX_DYNAMIC,
+} from './$base'
+import { resolveMount } from './$mounts'
+import { getRoute } from './$routing'
+
+const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
+
+/**
+ * `file`, carrying the `?v=<mtime>` suffix that gives DEV edit-and-refresh.
+ *
+ * The suffix makes Bun's module registry treat every edit as a new module,
+ * which is what lets an edited route (a `.ts` API handler, a `.tsx` page) take
+ * the cheap dev path — route-cache flush plus browser reload — instead of the
+ * full process restart it used to force. It also costs a stat and a string
+ * alloc per request and permanently retains each superseded module: acceptable
+ * in DEV, pure waste in PROD where route files cannot change. So PROD imports
+ * the bare specifier once and serves from the registry cache; the trade is that
+ * PROD needs a restart to pick up changed route files, which is already true
+ * operationally since PROD runs no watcher.
+ *
+ * `&& !TEST` is load-bearing: `init.ts` defaults `PROD` to true whenever
+ * `--dev` is absent, and `bun test` loads init via the CLI package's tests — so
+ * 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`.
+ *
+ * One implementation on purpose. `ApiHandler` and `TSXHandler`/`TSXErrorHandler`
+ * both need it, and they carried a byte-identical copy each — including this
+ * reasoning — which is two places for the `!TEST` clause to be dropped from.
+ */
+export function bustInDev(file: fs.AbsolutePath): fs.AbsolutePath {
+  if (import.meta.env.PROD && !import.meta.env.TEST) return file
+  return `${file}?v=${Bun.file(file).lastModified}` as fs.AbsolutePath
+}
+
+export class DynamicHandler extends Handler {
+  static get config(): Handler.Dynamic.Config {
+    return {
+      ext: [],
+      dir: Bakery.serveRoot,
+      include: ['**/*'],
+    }
+  }
+
+  static get dynamicCache(): HandlerCache<RegExp, Route.Info> {
+    // Same per-class Map pattern as `Handler.cache` — see the comment there.
+    let cache = dynamicCaches.get(this)
+    if (!cache) {
+      cache = new HandlerCache()
+      dynamicCaches.set(this, cache)
+    }
+    return cache
+  }
+
+  static initRoutes() {
+    this.cache.clear()
+    this.dynamicCache.clear()
+  }
+
+  static canHandle(path: string, req?: Request): MixedPromise<boolean>
+  static async canHandle(path: string) {
+    // A request path spelled like a route template ('/blog/[id]' or
+    // '/docs/[...slug]') addresses the template file, not a route.
+    if (RX_DYNAMIC.test(path) || RX_CATCHALL.test(path)) return false
+    if (this.cache.has(hostKey(path))) return true
+    // The dynamic half of the line above. A dynamic route is never written to
+    // `this.cache`, so without this every request to one ran `resolveRoute`
+    // twice — once here and once in `handle` — and each run is two globbing
+    // `getRoute` scans. `findDynamicRoute` is a regex test per cached route
+    // plus one stat for the match, and a hit here implies `resolveRoute` is
+    // about to be truthy too: it consults the same cache and returns that
+    // entry unless a static file outranks it, which is also truthy. The
+    // side effects skipped (cache population) are redone by `handle`.
+    if (this.findDynamicRoute(path)) return true
+    const info = await this.resolveRoute(path)
+    return Boolean(info)
+  }
+
+  static async executeModule(
+    file: fs.AbsolutePath,
+    req: Request,
+    body: any,
+  ): Promise<any> {
+    // A broken route module is a server fault, not a missing route: `null`
+    // means 404 to every caller, so after logging the file for context the
+    // failure is rethrown. `extractErrorData` turns the throw into a 500 whose
+    // `errorBody` carries the stack — shown in DEV, redacted by `publicBody`
+    // in PROD. Only the genuinely-missing cases below return null.
+    const [error, mod] = await Try.catch(import(file))
+    if (error) {
+      handlerLog.API_IMPORT_ERR({ file, error: errorMsg(error) })
+      throw error
+    }
+
+    if (mod?.default === undefined) return null
+    if (typeof mod.default !== 'function') return mod.default
+
+    // `ApiCallback` declares three parameters and this is its only call site,
+    // so the third was always `undefined`. Passed rather than removed from the
+    // type: `html()` in core/jsx.ts already hands `Bakery.server` to the render
+    // function it wraps, so dropping it would leave wrapped and unwrapped
+    // routes with different signatures for no gain.
+    return await mod.default(req, body, Bakery.server)
+  }
+
+  // Segment matching with catch-all and specificity precedence. The branches
+  // are the precedence rules; splitting them hides the ordering that is the
+  // whole point.
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: route-precedence dispatcher
+  static findDynamicRoute(path: string): Route.Info | null {
+    const root = Bakery.serveRoot
+    let deferred: Route.Info[] | null = null
+    for (const [_, info] of this.dynamicCache) {
+      // Cheapest filter first. `valid` is a stat and `isForbidden` walks every
+      // directory between the file and the root doing an existsSync at each
+      // level, and both ran for every cached route before anything asked
+      // whether the route even matched the path — so a miss cost one tree-walk
+      // per entry and a hit cost one per entry ahead of the match. The regex is
+      // pure and all four filters still `continue`, so a matching-but-rejected
+      // entry does not shadow a later one; `$dynamic.test.ts` pins that.
+      if (!info.getParams(path)) continue
+      // Every single-segment route outranks every catch-all, whatever order
+      // the cache filled in — so catch-alls are set aside, and their stat and
+      // tree-walk filters run only after the loop finds no specific match.
+      if (info.catchAll) {
+        ;(deferred ??= []).push(info)
+        continue
+      }
+      if (!info.valid) continue
+      // `filePath` is already `fs.resolve`d by the Info constructor; resolving
+      // it again here re-normalised an identical string.
+      if (!info.filePath!.startsWith(`${root}/`)) continue
+      if (fs.isForbidden(info.filePath!, root)) continue
+      return info
+    }
+    if (deferred) {
+      // A real file always beats a catch-all, whatever handler would serve
+      // it: when the requested path names an existing file, every catch-all
+      // declines so the file's own handler (possibly lower-priority — CSS
+      // falls all the way to StaticHandler) gets asked. One stat, paid only
+      // when a catch-all is about to answer. `getCatchAllRoute` applies the
+      // same rule on the discovery path; the two must agree — including the
+      // containment clamp: `root + path` is unresolved, so a `..` in the
+      // path would have `statSync` resolve it outside the root and turn this
+      // into an existence probe. See the comment there.
+      const target = fs.resolve(root, `.${path}`)
+      if (
+        (target === root || target.startsWith(`${root}/`)) &&
+        fs.isFileSync(target)
+      ) {
+        return null
+      }
+      // Longest route path first: `docs/guides/[...rest]` beats
+      // `docs/[...rest]` for the paths both match.
+      if (deferred.length > 1) {
+        deferred.sort((a, b) => b.path.length - a.path.length)
+      }
+      for (const info of deferred) {
+        if (!info.valid) continue
+        if (!info.filePath!.startsWith(`${root}/`)) continue
+        if (fs.isForbidden(info.filePath!, root)) continue
+        return info
+      }
+    }
+    return null
+  }
+
+  static getCachedRoute(path: string): Route.Info | null {
+    const key = hostKey(path)
+    return this.validateCachedRoute(key, this.cache.get(key)!)
+  }
+
+  static cacheStaticRoute(path: string, info: Route.Info): Route.Info {
+    const key = hostKey(path)
+    this.cache.set(key, info)
+
+    if (path.endsWith('/index')) {
+      this.cache.set(hostKey(path.slice(0, -6) || '/'), info)
+    }
+    return info
+  }
+
+  static validateCachedRoute(path: string, info: Route.Info | null) {
+    if (!info) return null
+    if (info.valid && !fs.isForbidden(info.filePath!, Bakery.serveRoot))
+      return info
+    this.cache.delete(path)
+    if (info.regex) this.dynamicCache.delete(info.regex)
+    return null
+  }
+
+  /**
+   * Resolve `path` to a file this handler may serve.
+   *
+   * The deny-list is matched against the *request path* in `router.ts`, but
+   * `routeGlobs` deliberately answers a request with a file of a different
+   * extension — `/schema.css` and `/schema` both resolve to `schema.ts` via
+   * stem+ext substitution. So the router's check was being asked about a
+   * string that named no file: it said "not blocked", and `TSHandler`
+   * compiled and served the very file the default list exists to protect.
+   * Verified against a live server before the fix: `/schema.ts` 403,
+   * `/schema.js` 200 with the file's contents.
+   *
+   * Re-running the check against what actually resolved is the fix. It is
+   * gated on `servesFiles` so route-only handlers keep their exemption, and
+   * it wraps every branch — cached, static, dynamic, catch-all — rather than
+   * each return point, so a future branch cannot forget it.
+   */
+  static resolveRoute(path: string): Promise<Route.Info | null>
+  static async resolveRoute(path: string) {
+    const info = await this.resolveRouteFile(path)
+    if (!info) return null
+
+    if (
+      this.servesFiles &&
+      matchBlockedCached(Bakery.config.blocked, `/${info.path}`)
+    ) {
+      return null
+    }
+
+    return info
+  }
+
+  protected static resolveRouteFile(path: string): Promise<Route.Info | null>
+  protected static async resolveRouteFile(path: string) {
+    const cached = this.getCachedRoute(path)
+    if (cached) return cached
+
+    // One read of the `config` getter: every access builds a fresh object and
+    // reads `Bakery.serveRoot` (an AsyncLocalStorage getStore), and this
+    // function used to read it three times.
+    const config = this.config
+
+    // A plugin may claim this prefix and serve it from its own directory; the
+    // rest of the pipeline (compiler, caches, containment) is unchanged.
+    const mounted = resolveMount(path)
+    const dir = mounted ? mounted.mount.dir : config.dir || Bakery.serveRoot
+    const routePath = mounted ? mounted.rest : path
+
+    const staticInfo = await getRoute(routePath, config.ext, dir, dir, {
+      staticOnly: true,
+    })
+    if (staticInfo) {
+      return this.cacheStaticRoute(path, staticInfo)
+    }
+
+    // `findDynamicRoute` already required `valid` and `!isForbidden` against
+    // `Bakery.serveRoot` before returning, so wrapping it in
+    // `validateCachedRoute` — which asserts exactly those two, against exactly
+    // that root — re-ran a stat and a directory tree-walk on a value that had
+    // just passed both, and its eviction branch was unreachable from here.
+    // `getCachedRoute` still needs the wrapper; entries read from `this.cache`
+    // have not been checked.
+    const dyn = this.findDynamicRoute(path)
+    if (dyn) {
+      return dyn
+    }
+
+    const info = await getRoute(routePath, config.ext, dir, dir, {
+      dynamicOnly: true,
+    })
+    if (!info) return null
+
+    if (info.isDynamic && info.regex) {
+      this.dynamicCache.set(info.regex, info)
+      return info
+    }
+
+    return this.cacheStaticRoute(path, info)
+  }
+}