@bakery-framework/core 1.0.0

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

@@ -0,0 +1,205 @@
+import Bakery from '../../core'
+import { fs } from '../../utils'
+import { type Handler, RouteData } from './$base'
+
+const GETFILE = (dir: fs.AbsolutePath) => ({
+  absolute: true,
+  cwd: dir,
+  dot: true,
+  onlyFiles: true,
+})
+
+export type RouteScanOptions = {
+  staticOnly?: boolean
+  dynamicOnly?: boolean
+}
+
+// `[!.]` keeps catch-alls (`[...name]`) out of the single-param globs: they
+// are matched separately, and last — a catch-all is the weakest route form,
+// consulted only after specific files, single-param siblings and child-index
+// descent have all missed.
+const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
+
+// The single-param route forms, in the order they are tried: `[name].ext`
+// first, then the escaped-literal `*.ext`. Built here rather than twice inside
+// `routeGlobs` — the `dynamicOnly` branch and the combined branch returned
+// character-identical pairs, and the two must stay in step or a route form
+// resolves under one caller and not the other. A function, not a hoisted
+// constant: `ext` varies per handler, and `staticOnly` returns before it needs
+// them at all.
+const dynamicGlobs = (ext: string) => [
+  new Bun.Glob(`[[][!.]*${ext || '.*'}`),
+  new Bun.Glob(`\\*${ext || '.*'}`),
+]
+
+const routeGlobs = (
+  first: string,
+  ext: string,
+  exts: string[],
+  options: RouteScanOptions = {},
+) => {
+  if (options.dynamicOnly) {
+    return dynamicGlobs(ext)
+  }
+
+  const hasExt = Boolean(fs.parse(first).ext)
+  const valid =
+    !hasExt || exts.length === 0 || exts.some(e => first.endsWith(`.${e}`))
+  const stem = fs.parse(first).name
+
+  const staticGlobs: Bun.Glob[] = []
+  if (valid) {
+    staticGlobs.push(new Bun.Glob(hasExt ? first : first + ext))
+  }
+  if (hasExt && ext && !valid) {
+    staticGlobs.push(new Bun.Glob(stem + ext))
+  }
+
+  if (options.staticOnly) {
+    return staticGlobs
+  }
+
+  return [...staticGlobs, ...dynamicGlobs(ext)]
+}
+
+/**
+ * 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
+ * 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.
+ */
+async function getCatchAllRoute(
+  ext: string,
+  dir: fs.AbsolutePath,
+  root: fs.AbsolutePath,
+  restSegments: string[],
+): Promise<Handler.Route.Info | null> {
+  const found = await catchAllGlob(ext)
+    .scan(GETFILE(dir))
+    .next()
+    .catch(() => null)
+  if (!found || found.done || !found.value) return null
+
+  if (restSegments.length) {
+    const target = fs.resolve(dir, restSegments.join('/'))
+    // Stat only inside `dir`. A rest containing `..` resolves outside it, and
+    // statting there would make this yield a boolean existence probe for any
+    // path on the filesystem — the 404-vs-render difference is observable.
+    // URL parsing normalises `..` and `%2e%2e` away, so no HTTP request
+    // reaches here with one; this closes the door for any caller that skips
+    // that normalisation. An escape skips the yield rather than refusing, so
+    // the catch-all answers exactly as it did before the yield rule existed.
+    // `dir` comes from `fs.resolve`, so the separator-suffixed prefix test is
+    // exact — plain `startsWith(dir)` would also accept a sibling directory
+    // whose name merely begins with it.
+    if (
+      (target === dir || target.startsWith(`${dir}/`)) &&
+      fs.isFileSync(target)
+    ) {
+      return null
+    }
+  }
+
+  const file = fs.resolve(found.value)
+  if (fs.isForbidden(file, root)) return null
+  return new RouteData.Info(file, fs.relative(root, file))
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: request-to-route dispatcher
+export async function getRoute(
+  pathOrArr: string | string[],
+  exts: string[] = [],
+  dir?: fs.AbsolutePath,
+  root?: fs.AbsolutePath,
+  options: RouteScanOptions = {},
+): Promise<Handler.Route.Info | null> {
+  // Both used to default to `Bakery.serveRoot` independently — two reads of
+  // the config getter (an AsyncLocalStorage getStore each) when a caller
+  // omits both. One read now covers whichever is missing; the values are
+  // unchanged.
+  if (dir === undefined || root === undefined) {
+    const serveRoot = Bakery.serveRoot
+    dir ??= serveRoot
+    root ??= serveRoot
+  }
+
+  if (fs.isForbidden(dir, root)) return null
+
+  let pathArr = Array.isArray(pathOrArr)
+    ? [...pathOrArr]
+    : pathOrArr.split('/').filter(Boolean)
+  exts = exts.filter(Boolean).map(e => e.replace(/^\./, ''))
+
+  if (pathArr.length === 0) {
+    pathArr = ['index']
+  }
+
+  const count = pathArr.length
+  const first = pathArr.shift() ?? ''
+  const ext = exts.length ? `.{${exts.join(',')}}` : ''
+  const scanOptions = GETFILE(dir)
+  const globs = routeGlobs(first, ext, exts, options)
+
+  if (count === 1) {
+    let file: string | null = null
+
+    for (const glob of globs) {
+      const globFile = await glob
+        .scan(scanOptions)
+        .next()
+        .catch(() => null)
+      if (!globFile || globFile.done || !globFile.value) continue
+
+      file = fs.resolve(globFile.value)
+      if (fs.isForbidden(file, root)) {
+        file = null
+        continue
+      }
+      break
+    }
+
+    if (file) return new RouteData.Info(file, fs.relative(root, file))
+
+    // No containment check before either recursion: the callee's first
+    // statement is `isForbidden(dir, root)` with these exact arguments, and its
+    // `null` reaches the same `return null` this function ends on. Checking
+    // here as well made every level of a nested route pay two identical
+    // directory tree-walks — and `isForbidden` walks from the file to the root
+    // doing an existsSync at each level, so that is the most expensive thing
+    // this function does. `src/tests/forbidden.test.ts` pins both branches.
+    if (first !== 'index') {
+      const targetDir = fs.resolve(dir, first)
+      const route = await getRoute('', exts, targetDir, root, options)
+      if (route) return route
+    }
+
+    // `first === 'index'` covers the bare-directory request (`/docs` arrives
+    // here as an injected 'index' segment): the catch-all pattern requires at
+    // least one rest segment, so it cannot match that request — returning the
+    // Info anyway would claim the route with null params.
+    if (!options.staticOnly && first !== 'index') {
+      return await getCatchAllRoute(ext, dir, root, [first])
+    }
+  }
+
+  if (count > 1) {
+    const targetDir = fs.resolve(dir, first)
+    const route = await getRoute(pathArr, exts, targetDir, root, options)
+    if (route) return route
+
+    // The walk above descends one real segment at a time and dead-ends when
+    // the next directory does not exist — which for a catch-all request
+    // (`/docs/a/b/c` against `docs/[...slug].tsx`) is the common case. Each
+    // level unwinds through here, so the deepest existing directory gets the
+    // first chance to claim the rest.
+    if (!options.staticOnly) {
+      return await getCatchAllRoute(ext, dir, root, [first, ...pathArr])
+    }
+    return null
+  }
+  return null
+}

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

@@ -0,0 +1,100 @@
+import { Bakery } from '../../core/bakery'
+import { Try } from '../../utils/common'
+import { fs } from '../../utils/fs'
+import { resolveMount } from './$mounts'
+
+/**
+ * Literal file resolution — the static counterpart to `getRoute`.
+ *
+ * `getRoute` answers "which file backs this *route*", with extensionless URLs,
+ * 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
+ * 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
+ * the first time someone mounts a directory containing an upload.
+ *
+ * **Three of those four go through this; NMHandler does not, on purpose.** Its
+ * entry point is resolved by `Bun.build`, not by the filesystem, so
+ * `/_nm/pkg/sub` legitimately means `pkg/sub/index.js` — a path this function
+ * answers `null` for, because it is a directory. It therefore repeats the
+ * containment test and calls `fs.isForbidden` itself; the reasoning, and the
+ * test that pins the divergence, are in `handlers/assets/nm.ts`. It is the one
+ * documented exception, and it stayed a *silent* one long enough for `/_nm/*`
+ * to be the only file-serving surface that ignored `.forbidden`.
+ */
+export interface StaticTarget {
+  /** Absolute path to the file on disk. */
+  file: fs.AbsolutePath
+  /** The root it was resolved against; containment is relative to this. */
+  root: fs.AbsolutePath
+  /** True when a route mount supplied the root rather than app config. */
+  mounted: boolean
+}
+
+/**
+ * Resolve `path` to a servable file, or null.
+ *
+ * A registered mount wins over `roots`: the prefix is stripped and the mount
+ * directory becomes both the search root and the containment boundary, so a
+ * mounted plugin cannot be traversed out of.
+ *
+ * Roots are tried in order, and a root that fails containment is skipped
+ * rather than aborting — mirroring ImageHandler, which legitimately looks in
+ * both the serve root and the public root.
+ */
+export async function getStatic(
+  path: string,
+  roots: string | string[] = Bakery.serveRoot,
+): Promise<StaticTarget | null> {
+  const mounted = resolveMount(path)
+
+  const candidates: { root: string; relative: string }[] = mounted
+    ? [{ root: mounted.mount.dir, relative: mounted.rest }]
+    : (Array.isArray(roots) ? roots : [roots]).map(root => ({
+        root,
+        relative: path.replace(/^\/+/, ''),
+      }))
+
+  for (const candidate of candidates) {
+    const root = fs.resolve(candidate.root)
+    const file = fs.resolve(root, candidate.relative)
+
+    // Two checks, not one: the prefix test catches a resolved path that
+    // escaped the root, and isForbidden additionally honours `.forbidden`
+    // markers. It does *not* apply the blocked globs — `Bakery.config.blocked`
+    // is matched against the request path in `router.ts` and again in
+    // `handlers/assets/static.ts`, never against a resolved file path — so a
+    // caller reaching for `getStatic` as a one-stop authorisation check is
+    // getting containment and `.forbidden` only.
+    //
+    // Containment stays first — nothing stats a path that escaped the root.
+    // After that the order is by cost: `isForbidden` walks every directory
+    // between the file and the root, so running it before the existence check
+    // paid for a whole tree-walk on every candidate that simply is not there —
+    // which is most of them, since a miss here is how each root in the list,
+    // and every extensionless probe, gets ruled out. All checks are pure and
+    // all `continue`, so the candidate chosen is unchanged.
+    //
+    // One stat answers both questions. This used to be `fs.exists` (a stat)
+    // then `fs.isDir` (which is `fs.exists` plus a second stat of its own) —
+    // up to three stats per candidate at ~28us each on Bun/Windows. A failed
+    // stat means "nothing servable here" and falls through to the next
+    // candidate, exactly as the exists check did.
+    if (file !== root && !file.startsWith(`${root}/`)) continue
+    const stat = await Try(() => Bun.file(file).stat())
+    if (!stat || stat.isDirectory()) continue
+    if (fs.isForbidden(file, root)) continue
+
+    return {
+      file: file as fs.AbsolutePath,
+      root: root as fs.AbsolutePath,
+      mounted: Boolean(mounted),
+    }
+  }
+
+  return null
+}

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

@@ -0,0 +1,52 @@
+import { Bakery, hostStore } from '../../core/bakery'
+import type { MixedPromise } from '../../types'
+import { Handler } from './$base'
+
+export class WebSocketHandler extends Handler {
+  static WS_UPGRADE = Symbol('WS_UPGRADE')
+
+  static canHandle(path: string, req: Request): MixedPromise<boolean>
+  static canHandle() {
+    return true
+  }
+
+  static handle(path: string, req: Request) {
+    let data = this.upgrade(req, path) || ({} as any)
+    data = {
+      this: this,
+      type: 'websocket',
+      orig: this.name,
+      path,
+      hostname: req.__hostname || '',
+      config: hostStore.getStore()?.config ?? Bakery.config,
+      data,
+    }
+
+    const upgraded = Bakery.server?.upgrade(req, { data })
+    return upgraded ? (WebSocketHandler.WS_UPGRADE as any) : null
+  }
+
+  static upgrade(req: Request, path: string): MixedPromise<UpgradeData>
+  static upgrade() {}
+
+  static open(ws: ServerWebSocket<any>, data: any): MixedPromise<void>
+  static open() {}
+
+  static message(
+    ws: ServerWebSocket<any>,
+    msg: any,
+    data: any,
+  ): MixedPromise<void>
+  static message() {}
+
+  static close(
+    ws: ServerWebSocket<any>,
+    code: number,
+    reason: string,
+    data: any,
+  ): MixedPromise<void>
+  static close() {}
+
+  static drain(ws: ServerWebSocket<any>, data: any): MixedPromise<void>
+  static drain() {}
+}

package/src/handlers/index.ts

@@ -0,0 +1,21 @@
+export * from './assets/google-font'
+export * from './assets/image'
+export * from './assets/nm'
+export * from './assets/public'
+export * from './assets/static'
+export * from './assets/ts'
+export * from './assets/tsx'
+export * from './assets/virtual-asset'
+export * from './core/$base'
+export * from './core/$dynamic'
+export * from './core/$error'
+export * from './core/$middleware'
+export * from './core/$mounts'
+export * from './core/$registry'
+export * from './core/$routing'
+export * from './core/$static'
+export * from './core/$websocket'
+export * from './routes/api'
+export * from './routes/html'
+export * from './routes/livereload'
+export * from './routes/proxy'

package/src/handlers/routes/api.ts

@@ -0,0 +1,95 @@
+import { Bakery } from '../../core/bakery'
+import { handlerLog } from '../../logger/serve-log'
+import { FileSystem } from '../../utils/fs'
+import { checkCsrf, response } from '../../utils/http'
+import type { Handler } from '../core/$base'
+import { bustInDev, DynamicHandler } from '../core/$dynamic'
+import { ErrorHandler } from '../core/$error'
+
+export class ApiHandler extends DynamicHandler {
+  /** Executes a module and returns its value; never file bytes. See `Handler.servesFiles`. */
+  static servesFiles = false
+
+  static canHandle(path: string) {
+    return path.startsWith('/api/')
+  }
+
+  static get config() {
+    return {
+      ext: ['ts', 'js'],
+      dir: Bakery.apiRoot,
+    }
+  }
+
+  static resolveRoute(path: string) {
+    path = path.slice(4) // remove api prefix
+    return super.resolveRoute(path)
+  }
+
+  static async handle(path: string, req: Request) {
+    // State-changing methods must be same-origin. SameSite=Lax alone does not
+    // cover this: a cross-site form POST is a CORS-simple request.
+    const url: URL = (req as any).__parsedUrl || new URL(req.url)
+    const csrf = checkCsrf(req, url)
+    if (csrf) return response.json.error(403, csrf) as unknown as Response
+
+    const info = await this.resolveRoute(path)
+    if (!info) return response.error('No API handler found')
+
+    const cleanPath = path.slice(4)
+    const params = info.getParams(cleanPath) || {}
+    const body = await this.params(req, params)
+
+    const filePath = FileSystem.resolve(this.config.dir, info.path)
+    const result = await this.executeModule(filePath, req, body)
+
+    if (result !== null && result !== undefined) return result
+
+    // Two different faults used to share one bare 404, and neither channel
+    // named the file — so "No response from handler" sent the developer
+    // hunting for a route that was sitting on disk the whole time.
+    //
+    // `null` and `undefined` are what tell them apart, and the split is exact
+    // rather than incidental: `DynamicHandler.executeModule` *throws* when the
+    // import fails (that is the 500 path), returns a literal `null` for
+    // "module loaded, no `default`", and otherwise returns whatever the
+    // handler produced — `undefined` when it produced nothing.
+    if (result === null) {
+      // A 500, not a 404: the route resolved, the file exists, and the server
+      // could not answer with it. That is a server fault, and the message says
+      // what to add. PROD still redacts it — `publicBody` replaces any 5xx
+      // body — so naming the file here discloses nothing to a client.
+      handlerLog.API_NO_DEFAULT({ file: filePath })
+      return response.error(
+        `API route has no export default: ${info.path}`,
+        500,
+      )
+    }
+
+    handlerLog.API_NO_RESPONSE({ file: filePath })
+    return response.error('No response from handler')
+  }
+
+  static async executeModule(
+    file: FileSystem.AbsolutePath,
+    req: Request,
+    body: any,
+  ): Promise<any> {
+    // See `bustInDev` for why the suffix exists and why `!TEST` is part of the
+    // gate. `TSXHandler` applies the same rule through the same helper.
+    return super.executeModule(bustInDev(file), req, body)
+  }
+}
+
+export class ApiErrorHandler extends ErrorHandler {
+  static canHandle(path: string) {
+    return path.startsWith('/api/')
+  }
+
+  static handle(_p: string, _r: Request, error: Handler.Error.Data) {
+    // `publicBody`, not `errorBody`: in production the latter is the stack of
+    // whatever threw. The full trace still reaches the log — `handleRequestError`
+    // passes the unredacted data to `config.onError` before this runs.
+    return response.json.error(error.errorCode, ErrorHandler.publicBody(error))
+  }
+}

package/src/handlers/routes/html.ts

@@ -0,0 +1,95 @@
+import { Bakery, hostKey } from '../../core/bakery'
+import type { MapOf } from '../../types'
+import { assembleHtml, fs, toHash } from '../../utils'
+import { injectIfHtml, response } from '../../utils/http'
+import type { Handler } from '../core/$base'
+import { DynamicHandler } from '../core/$dynamic'
+import {
+  beginPageRoute,
+  DynamicErrorHandler,
+  markDevFile,
+  publicErrorData,
+} from '../core/$error'
+
+export class HTMLHandler extends DynamicHandler {
+  static get config() {
+    return {
+      ext: ['html'],
+      dir: Bakery.serveRoot,
+    }
+  }
+
+  static canHandle(path: string, req: Request) {
+    return path.endsWith('.html') || super.canHandle(path, req)
+  }
+
+  static handle = sharedHandler
+}
+
+export class HTMLErrorHandler extends DynamicErrorHandler {
+  static get config() {
+    return {
+      ext: ['html'],
+      dir: Bakery.serveRoot,
+      include: ['**/error.html', '**/error-*.html'],
+    }
+  }
+
+  static handle = sharedHandler
+}
+
+function getCacheDir() {
+  return fs.resolve(Bakery.cacheDir, 'html')
+}
+
+async function sharedHandler(
+  this: typeof DynamicHandler | typeof DynamicErrorHandler,
+  path: string,
+  req: Request,
+  errors?: Handler.Error.Data,
+) {
+  const begun = await beginPageRoute(this, path, errors)
+  if (begun instanceof Response) return begun
+  const { errorData, info } = begun
+
+  const file = info.file
+
+  if (!info.isDynamic && !errorData) {
+    const cacheHash = toHash(hostKey(info.path))
+    const cacheName = `${cacheHash}.html`
+
+    const cached = await fs.getOrCreateCachedFile(
+      getCacheDir(),
+      cacheName,
+      file.lastModified,
+      async () => {
+        const content = await file.text()
+        return assembleHtml(content)
+      },
+    )
+
+    if (cached) return cached
+  }
+
+  const params = await this.params(req, info.getParams(path) || {})
+  markDevFile(params, info.path)
+  const content = await info.file.text()
+  // `publicErrorData`, not `errorData`: these params reach the document
+  // through `{{...}}` *and* through the `__PAGE_PARAMS__` script injected
+  // into every page, so the raw stack was published in PROD even by a
+  // template that never mentioned it. Guarded because `errorData` is
+  // `undefined` for an ordinary page — `DEFAULT_ERROR` only exists on the
+  // error handler — and the spread below tolerates that where the helper,
+  // deliberately strict about the shape it redacts, does not.
+  // Annotated because `beginPageRoute` hands back real `Handler.Error.Data`
+  // where this used to read an untyped `(this as any).DEFAULT_ERROR`: the
+  // merged record now has a numeric `errorCode` in it, and `injectIfHtml`
+  // substitutes stringly. Same object as before, same values.
+  const data: MapOf<any> = {
+    ...params,
+    ...(errorData && publicErrorData(errorData)),
+  }
+
+  const html = await injectIfHtml(content, data)
+  return html || response.error('Not Found')
+}

package/src/handlers/routes/livereload.ts

@@ -0,0 +1,54 @@
+import { connectedLoggers, log, serveLog } from '../../logger'
+import { WebSocketHandler } from '../core/$websocket'
+
+export class LiveReloadHandler extends WebSocketHandler {
+  static connectedLoggers = connectedLoggers
+
+  static init() {}
+
+  static canHandle(path: string) {
+    if (!import.meta.env.DEV || !import.meta.env.DEV_WORKER) return false
+    return path === '/_livereload'
+  }
+
+  static upgrade() {}
+
+  static open(ws: ServerWebSocket) {
+    if (!import.meta.env.DEV) return
+    ws.subscribe('livereload')
+  }
+
+  static message(ws: ServerWebSocket, message: any) {
+    if (!import.meta.env.DEV) return
+    try {
+      const parsed = JSON.parse(String(message))
+      const { type: msgType, level, payload } = parsed
+      switch (msgType) {
+        case 'subscribe_logger':
+          LiveReloadHandler.connectedLoggers.add(ws)
+          break
+
+        case 'force_reload':
+          serveLog.MANUAL_RELOAD()
+          ws.publish('livereload', 'force_reload')
+
+          break
+        case 'client_log': {
+          const ipAddr = ws.remoteAddress
+          const clientLogMsg = JSON.stringify({ ...parsed, by: ipAddr })
+          LiveReloadHandler.connectedLoggers.forEach(
+            loggerWs => void loggerWs.send(clientLogMsg),
+          )
+          log({ by: ipAddr, msg: payload, level })
+          break
+        }
+      }
+    } catch (err: any) {
+      serveLog.WEBSOCKET_ERR({ ip: ws.remoteAddress, error: String(err) })
+    }
+  }
+
+  static close(ws: ServerWebSocket) {
+    LiveReloadHandler.connectedLoggers.delete(ws)
+  }
+}