@bakery-framework/core 1.0.0

package/src/plugins/routes.ts

@@ -0,0 +1,110 @@
+/**
+ * Declarative endpoint tables for plugins.
+ *
+ * The dashboard already used a `Record<path, handler>` map; analytics used a
+ * hand-rolled `if (path === … && method === …)` chain. This generalises the
+ * dashboard's shape — the one that was already working — so a third plugin does
+ * not arrive with a fourth style of dispatch.
+ *
+ * Scope is deliberately narrow: exact-match paths only, no params or wildcards.
+ * Anything needing those belongs in the core router (`DynamicHandler`), not in
+ * a parallel implementation here.
+ */
+
+import { checkCsrf, checkSameOrigin } from '../utils/http/csrf'
+import { response } from '../utils/http/response'
+import type { ValidResponses } from './types'
+
+/**
+ * Handlers may return anything the router knows how to serialize — the
+ * dashboard's return `JsonResponseData` and `BunFile` as well as `Response`.
+ * `ValidResponses` (= `Handler.Response`) is the framework's name for that set.
+ */
+export type PluginRoute = (req: Request, url: URL) => ValidResponses
+
+/**
+ * Keys are either a bare path (`'/api/_x/stats'`, matching any method) or a
+ * method-qualified path (`'POST /api/_x/reset'`). A method-qualified entry wins
+ * over a bare one for the same path.
+ *
+ * The two forms are guarded differently — see `guardFor` below. A bare key is
+ * same-origin-only; a method-qualified one gets the ordinary CSRF check.
+ */
+export type PluginRouteTable = Record<string, PluginRoute>
+
+/**
+ * What a dispatch built from `T` actually resolves to: the union of that
+ * table's own handler return types, awaited, with the `undefined`/`void` cases
+ * replaced by `null` — exactly what `dispatch` does at runtime with `?? null`.
+ *
+ * Keyed on the table type rather than flattened to `ValidResponses` because
+ * `ValidResponses` contains `object`, which absorbs `Response`, `Bun.BunFile`
+ * and `JsonResponseData` back into one useless member. Declaring a table with
+ * `satisfies PluginRouteTable` (rather than annotating it) keeps the literal
+ * type, and with it the precision.
+ */
+export type PluginRouteResult<T extends PluginRouteTable> =
+  | Exclude<Awaited<ReturnType<T[keyof T]>>, undefined | void>
+  // The 403 `dispatch` answers with when the request fails the guard below.
+  // Spelled out rather than smuggled through: a dispatch can return something
+  // no endpoint in the table declares, and the caller should have to see that.
+  | Response
+  | null
+
+/**
+ * How hard `dispatch` guards a match, by how much the table declared.
+ *
+ * A **method-qualified** key (`'POST /api/_x/reset'`) is an author who thought
+ * about methods, so it gets the ordinary `checkCsrf`: safe methods through,
+ * unsafe ones same-origin. `'GET /api/_x/public'` is therefore also the way to
+ * declare an endpoint that *is* meant to answer cross-origin.
+ *
+ * A **bare** key matches every method, which means the author did not say —
+ * and that is exactly how the dashboard's mutating endpoints ended up
+ * answering a `GET`. `checkCsrf` is no help there: it waves GET through by
+ * definition, so a cross-site `<img src="/api/_dashboard/execute-action">`
+ * arrives with the session attached and runs. A bare key therefore gets the
+ * stricter `checkSameOrigin`, on every method: the request must not come from
+ * another site whatever verb it used.
+ *
+ * The result is that a plugin cannot forget CSRF by omission. Forgetting to
+ * name the method now costs cross-origin reachability rather than the guard.
+ */
+function guardFor(qualified: boolean) {
+  return qualified ? checkCsrf : checkSameOrigin
+}
+
+export function routeTable<T extends PluginRouteTable>(routes: T) {
+  /**
+   * Declared as an overload — the same shape `handleRequest` uses in
+   * `router.ts`. The signature carries the precise per-table union; the
+   * implementation only ever sees the `PluginRoute` *constraint*, so on its own
+   * it could infer no better than the wide `ValidResponses`.
+   */
+  function dispatch(req: Request, url?: URL): Promise<PluginRouteResult<T>>
+  async function dispatch(req: Request, url: URL = new URL(req.url)) {
+    const path = url.pathname
+    const qualified = `${req.method} ${path}`
+
+    // hasOwn, not plain indexing: a bare `routes[path]` lookup would reach
+    // inherited Object.prototype members for a suitably named path.
+    const isQualified = Object.hasOwn(routes, qualified)
+    const handler = isQualified
+      ? routes[qualified]
+      : Object.hasOwn(routes, path)
+        ? routes[path]
+        : undefined
+
+    if (!handler) return null
+
+    // Runs after the match and before the handler, so an unmatched path still
+    // resolves to `null` and falls through to the rest of the router rather
+    // than being claimed by a 403.
+    const denied = guardFor(isQualified)(req, url)
+    if (denied) return response.error('Forbidden', 403)
+
+    return (await handler(req, url)) ?? null
+  }
+
+  return dispatch
+}

package/src/plugins/types.ts

@@ -0,0 +1,19 @@
+import type { Handler } from '../handlers/core/$base'
+import type { MixedPromise } from '../types'
+
+export type ValidResponses = Handler.Response
+
+export interface ServerPlugin {
+  name: string
+  setup?(config: ProcessedAppConfig): MixedPromise<void>
+  onStart?(server: Bun.Server<any>): MixedPromise<void>
+  onRequest?(req: Request): ValidResponses
+  onRoute?(req: Request): MixedPromise<void>
+  onError?(error: Handler.Error.Data, req?: Request): ValidResponses
+  onShutdown?(): MixedPromise<void>
+  onCompile?(content: string, path: string): MixedPromise<string>
+}
+
+export function definePlugin<T extends ServerPlugin>(plugin: T): T {
+  return plugin
+}

package/src/router.ts

@@ -0,0 +1,351 @@
+import { Bakery, hostStore } from './core/bakery'
+import { matchBlockedCached } from './core/context'
+import { PluginHooks } from './core/plugins'
+import { DefaultErrorHandler } from './handlers/assets/static'
+import type { Handler } from './handlers/core/$base'
+import { ErrorHandler } from './handlers/core/$error'
+import { WebSocketHandler } from './handlers/core/$websocket'
+import { errorMsg, getElapsed, log, serveLog } from './logger'
+import { Session } from './session'
+import type { MixedPromise } from './types'
+import { JsonResponseData } from './utils'
+import { is, Try } from './utils/common'
+import { fs } from './utils/fs'
+import {
+  checkWebSocketOrigin,
+  ETag,
+  injectIfHtml,
+  response,
+  withStatus,
+} from './utils/http'
+
+/**
+ * Resolve a WebSocket upgrade, refusing cross-origin handshakes first.
+ *
+ * The origin check lives here rather than in each `canHandle` on purpose:
+ * every socket a plugin or an app registers inherits it, instead of every
+ * author having to remember. `/_analytics_ws` was the only handler that got it
+ * right on its own, and it did so by authenticating — `/_livereload` had
+ * nothing, and `WebSocketHandler.canHandle` returns `true` by default, so the
+ * base class was handing out sockets to anyone who asked.
+ *
+ * Returning `false` (rather than a 403) keeps the published signature — the
+ * caller below turns a refusal into `400 WebSocket Upgrade Failed`, which is
+ * also what an unclaimed path gets. The reason reaches the log; the client is
+ * told nothing it did not already know.
+ */
+export async function upgradeWebsocket(
+  req: Request,
+  path: string,
+): Promise<boolean | undefined> {
+  const url: URL = (req as any).__parsedUrl || new URL(req.url)
+  const denied = checkWebSocketOrigin(req, url)
+  if (denied) {
+    serveLog.WEBSOCKET_ERR({
+      ip: Bakery.server?.requestIP(req)?.address || 'Unknown',
+      error: denied,
+    })
+    return false
+  }
+
+  try {
+    const upgrade = await Bakery.handlers.websocket.handle(path, req)
+    return Boolean(upgrade)
+  } catch (err: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `Error checking WebSocketHandler: ${errorMsg(err)}`,
+    })
+  }
+  return false
+}
+
+/**
+ * Whether the deny-list applies to whatever this handler is about to answer
+ * with. `Bakery.config.blocked` exists to stop files on disk being served, so
+ * handlers that read the request path as a route *name* opt out by declaring
+ * `servesFiles = false` — `ApiHandler`, `ProxyHandler`, `MiddlewareHandler`.
+ *
+ * Deny by default, and the direction matters. Naming only the obvious file
+ * servers — Static, Public, NM — would have left `/schema.ts` and
+ * `/server.config.ts` reachable through `TSHandler`, which compiles a source
+ * file and serves the result. Anything that does not opt out, including a
+ * plugin's handler, keeps the check.
+ *
+ * The flag lives on `Handler` (see its doc comment) rather than in a list
+ * here so that `DynamicHandler.resolveRoute` can gate the *resolved-file*
+ * check on the same answer. Two lists would have drifted, and the resolved
+ * check is what closes the extension-substitution hole this one cannot see.
+ */
+function servesFiles(handler: any): boolean {
+  return handler?.servesFiles !== false
+}
+
+export function handleRequest(
+  req: Request,
+): Handler.Response | MixedPromise<symbol>
+export async function handleRequest(req: Request) {
+  // worker.ts parses and attaches this before calling in; the fallback keeps
+  // direct callers (tests, embedders) working.
+  const url: URL = (req as any).__parsedUrl || new URL(req.url)
+  ;(req as any).__parsedUrl = url
+  const path = url.pathname
+
+  // One read of the config getter, not three: `Bakery.serveRoot` walks
+  // `hostStore.getStore()?.config ?? getConfig()` on every access, and the
+  // blocked-glob check below used to pay the same walk again. And no
+  // `fs.resolve` around the target — `isForbidden` normalises both arguments
+  // itself, so that was a second full path resolution of the same string on
+  // every request.
+  const config = Bakery.config
+  const serveRoot = config.root
+  if (fs.isForbidden(serveRoot + path, serveRoot)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+
+  if (req.headers.get('Upgrade') === 'websocket') {
+    const wsHandled = await upgradeWebsocket(req, path)
+    return wsHandled
+      ? WebSocketHandler.WS_UPGRADE
+      : response.error('WebSocket Upgrade Failed', 400)
+  }
+
+  await PluginHooks.onRoute(req)
+
+  const pluginResponse = await PluginHooks.onRequest(req)
+  if (pluginResponse) return pluginResponse
+
+  // Resolved rather than dispatched, because the blocked globs are a question
+  // about *which* handler is about to answer. Testing them against the raw
+  // path up front made `/api/manifest.json` a 403 before routing had a say,
+  // and no config could opt out of it. `resolve` is what `HandlerMap.handle`
+  // calls anyway, so this costs nothing extra.
+  const handler = await Bakery.handlers.fetch.resolve(path, req)
+  if (!handler) return new Response('Not Found', { status: 404 })
+
+  // `matchBlockedCached` memoises the verdict on the request store, so the
+  // re-check `StaticHandler.handle` keeps for its direct callers costs a map
+  // hit instead of a second pair of glob matches.
+  if (servesFiles(handler) && matchBlockedCached(config.blocked, path)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+
+  return handler.handle(path, req)
+}
+
+const isWSHandler = (handler: any) =>
+  handler &&
+  (handler.prototype instanceof WebSocketHandler ||
+    handler === WebSocketHandler)
+
+function prepareWSData(ws: any) {
+  ws.data ||= {}
+  const mainData = ws.data
+  if (isWSHandler(mainData.this)) {
+    mainData.data ||= {}
+    return { handler: mainData.this, data: mainData.data }
+  }
+  return null
+}
+
+/**
+ * The resolved config is handed to `fn` rather than re-read inside it:
+ * `Bakery.config` inside the callback would land on exactly the store entry
+ * installed here, so reading it again paid a second
+ * `AsyncLocalStorage.getStore` per WebSocket event for the same object.
+ */
+function runInHostContext<T>(
+  ws: any,
+  fn: (config: Readonly<ProcessedAppConfig>) => Promise<T> | T,
+): Promise<T> | T {
+  const mainData = ws?.data || {}
+  const config = mainData.config || Bakery.config
+  const hostname = mainData.hostname || ''
+  return hostStore.run({ config, hostname }, () => fn(config))
+}
+
+export const serveWebSocket: Bun.WebSocketHandler<any> = {
+  async message(ws: any, message) {
+    return runInHostContext(ws, async config => {
+      try {
+        const h = prepareWSData(ws)
+        if (h) return await h.handler.message(ws, message, h.data)
+        config.websocket.message(ws, message)
+      } catch (err: any) {
+        serveLog.UNHANDLED_ERR({
+          error: `WebSocket message error: ${errorMsg(err)}`,
+        })
+      }
+    })
+  },
+  async open(ws: any) {
+    return runInHostContext(ws, async config => {
+      try {
+        const h = prepareWSData(ws)
+        if (h) return await h.handler.open(ws, h.data)
+        await config.websocket.open?.(ws)
+      } catch (err: any) {
+        serveLog.UNHANDLED_ERR({
+          error: `WebSocket open error: ${errorMsg(err)}`,
+        })
+      }
+    })
+  },
+  async close(ws: any, code: number, reason: string) {
+    return runInHostContext(ws, async config => {
+      try {
+        const h = prepareWSData(ws)
+        if (h) return await h.handler.close(ws, code, reason, h.data)
+        await config.websocket.close?.(ws, code, reason)
+      } catch (err: any) {
+        serveLog.UNHANDLED_ERR({
+          error: `WebSocket close error: ${errorMsg(err)}`,
+        })
+      }
+    })
+  },
+  async drain(ws: any) {
+    return runInHostContext(ws, async config => {
+      try {
+        const h = prepareWSData(ws)
+        if (h) return await h.handler.drain(ws, h.data)
+        await config.websocket.drain?.(ws)
+      } catch (err: any) {
+        serveLog.UNHANDLED_ERR({
+          error: `WebSocket drain error: ${errorMsg(err)}`,
+        })
+      }
+    })
+  },
+}
+
+/**
+ * Make an error page answer with the error's status.
+ *
+ * The HTML and TSX error handlers end in `injectIfHtml`, which builds its
+ * Response without one — so an app with `src/error-404.html` served its 404
+ * page as `200 OK` and every crawler, cache and monitor believed it. Applied
+ * here rather than inside `injectIfHtml` on purpose: the only status signal
+ * available down there is `params`, which for a GET is the query string, and
+ * `?errorCode=500` is not something a client gets to decide.
+ *
+ * A `JsonResponseData` (the `/api/` arm) carries its own `.status` that
+ * `processResponse` reads, and a BunFile has no status at all — both pass
+ * through untouched.
+ */
+function applyErrorStatus(
+  res: Awaited<Handler.Response>,
+  code: number,
+): Awaited<Handler.Response> {
+  if (!(res instanceof Response)) return res
+  if (!Number.isInteger(code) || code < 400 || code > 599) return res
+  return withStatus(res, code)
+}
+
+export function handleRequestError(
+  path: string,
+  req?: Request,
+  error?: any,
+): Handler.Response
+export async function handleRequestError(
+  path: string,
+  req?: Request,
+  error?: any,
+) {
+  req ||= new Request('http://localhost/__internal__')
+  error = ErrorHandler.extractErrorData(error)
+
+  const pluginRes = await PluginHooks.onError(error, req)
+  if (pluginRes) return pluginRes
+
+  const bakeryError = Object.assign({}, error, {
+    errorBody: `${error.errorBody} at ${path}`,
+  })
+
+  // Wrapped for the same reason the registry call below it is: this is app
+  // code. An `onError` that throws used to escape `Try.return`'s fallback in
+  // the caller — a fallback that itself rejects is not a fallback — so the one
+  // hook whose job is to handle failure took the app's error page down with
+  // it and the client got Bun's raw 500 instead.
+  const [onErrorFailed, configError] = await Try.catch(() =>
+    Bakery.config.onError(bakeryError),
+  )
+
+  if (onErrorFailed) {
+    serveLog.UNHANDLED_ERR({
+      error: `Error in config.onError: ${errorMsg(onErrorFailed)}`,
+    })
+  }
+
+  if (configError instanceof Response) {
+    const injectedRes = await injectIfHtml(configError)
+    return injectedRes || configError
+  }
+
+  try {
+    const errRes = await Bakery.handlers.error.handle(path, req, error)
+    if (errRes) return applyErrorStatus(errRes, error.errorCode)
+  } catch (err: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `Error in ErrorHandler: ${errorMsg(err)}`,
+    })
+  }
+
+  return DefaultErrorHandler.handle(path, req, error)
+}
+
+export async function processResponse(
+  data: Handler.Response | MixedPromise<symbol>,
+  req: Request,
+): Promise<Response | undefined> {
+  data = await data
+  let status = 200
+  let type = 'text/plain; charset=utf-8'
+  if (data === WebSocketHandler.WS_UPGRADE) return
+  if (data === null || data === undefined)
+    return new Response(null, { status: 204 })
+
+  const resp = await (async function getResponse() {
+    if (data instanceof Response) {
+      return (await injectIfHtml(data)) || data
+    }
+
+    if (data instanceof Blob) {
+      return ETag.sendFile(data as Bun.BunFile, req)
+    }
+
+    if (typeof data === 'string') {
+      const injected = await injectIfHtml(data)
+      return injected || response.text(data)
+    }
+
+    if (data instanceof JsonResponseData) {
+      data.time = getElapsed(req.startNs)
+      status = data.status
+      data = data.toJson()
+      type = 'application/json'
+    }
+
+    if (is.object(data)) {
+      data = JSON.stringify(data)
+      type = 'application/json'
+    }
+
+    return ETag.sendText(String(data), req, type, status)
+  })()
+
+  const sess = Session.getCookie(req)
+
+  // append, not set: a handler may already have issued its own Set-Cookie
+  // (e.g. an auth cookie from a login route) that must not be overwritten.
+  sess && resp.headers.append('Set-Cookie', sess)
+  const final = ETag.sendResponse(req, resp)
+  if (!(final instanceof Response)) {
+    log({
+      by: 'final-response',
+      level: 'error',
+      msg: 'ETag failed to generate a valid response',
+    })
+  }
+
+  return final
+}