@bakery-framework/core 1.0.0

package/src/startup.ts

@@ -0,0 +1,154 @@
+import { networkInterfaces } from 'node:os'
+import { Bakery } from './core/bakery'
+import { getConfigLoadError } from './core/config'
+import { resolvePort } from './core/port'
+import {
+  ApiErrorHandler,
+  ApiHandler,
+  DefaultErrorHandler,
+  GoogleFontHandler,
+  HTMLErrorHandler,
+  HTMLHandler,
+  ImageHandler,
+  LiveReloadHandler,
+  MiddlewareHandler,
+  NMHandler,
+  ProxyHandler,
+  PublicHandler,
+  StaticHandler,
+  TSHandler,
+  TSXErrorHandler,
+  TSXHandler,
+  VirtualAssetHandler,
+} from './handlers'
+import { log, serveLog } from './logger'
+import { match } from './utils/common'
+import { DEFAULT_RATE_LIMIT } from './utils/constants'
+
+let pluginSetup: Promise<void> | null = null
+
+/**
+ * `PluginHooks.setup()`, exactly once per process.
+ *
+ * Two call sites legitimately need plugins ready and neither can be dropped.
+ * The CLI entries (`cli/dev.ts`, `cli/prod.ts`) must run it before
+ * `initImportMap()`, because a plugin's `setup()` may add import-map entries.
+ * `setupServer()` must run it too, because a cluster worker is spawned straight
+ * into `cli/worker.ts` and never passes through either entry.
+ *
+ * Calling both meant every non-clustered worker set its plugins up twice.
+ * Handler and mount registration is idempotent so that went unnoticed, but the
+ * analytics plugin registers a shutdown hook and kicks off `loadAnalyticsData()`
+ * from `setup()` — so it got two of each. Memoising the promise (not a boolean)
+ * also makes a concurrent second caller await the first run rather than race it.
+ */
+export function setupPlugins(): Promise<void> {
+  pluginSetup ??= (async () => {
+    const { PluginHooks } = await import('./core/plugins')
+    await PluginHooks.setup()
+  })()
+
+  return pluginSetup
+}
+
+/**
+ * Test seam, in the family of `__setTestConfig` / `__setTestDb`. The memo above
+ * is process-wide by design, which is exactly what a test asserting "once"
+ * needs to be able to clear between cases.
+ */
+export function __resetPluginSetup(): void {
+  pluginSetup = null
+}
+
+export async function setupServer(): Promise<void> {
+  if (import.meta.env.DEV) {
+    await LiveReloadHandler.init()
+    Bakery.handlers.websocket.set(LiveReloadHandler)
+  }
+  Bakery.handlers.error.set(ApiErrorHandler, 30)
+  Bakery.handlers.error.set(TSXErrorHandler, 20)
+  Bakery.handlers.error.set(HTMLErrorHandler, 10)
+  Bakery.handlers.error.set(DefaultErrorHandler, 0)
+
+  Bakery.handlers.fetch.set(MiddlewareHandler, 100)
+  Bakery.handlers.fetch.set(ProxyHandler, 95)
+  Bakery.handlers.fetch.set(VirtualAssetHandler, 90)
+  Bakery.handlers.fetch.set(GoogleFontHandler, 87)
+  Bakery.handlers.fetch.set(ImageHandler, 85)
+  Bakery.handlers.fetch.set(PublicHandler, 84)
+  Bakery.handlers.fetch.set(NMHandler, 80)
+  Bakery.handlers.fetch.set(ApiHandler, 70)
+  Bakery.handlers.fetch.set(TSXHandler, 60)
+  Bakery.handlers.fetch.set(HTMLHandler, 55)
+  Bakery.handlers.fetch.set(TSHandler, 50)
+  Bakery.handlers.fetch.set(StaticHandler, 0)
+
+  await setupPlugins()
+
+  await Promise.all([
+    Bakery.handlers.fetch.initRoutes(),
+    Bakery.handlers.error.initRoutes(),
+    Bakery.handlers.websocket.initRoutes(),
+  ])
+}
+
+export async function runStartupBanner(): Promise<void> {
+  const host = Bakery.config.host
+
+  // Ground truth first. The banner's job is to print where the server is
+  // listening, and `Bakery.server.port` is what the OS actually gave us —
+  // which is the only correct answer under `PORT=0`, and the only *honest*
+  // one if the bound port and the requested one ever part company again.
+  // `resolvePort` covers the callers that print a banner without a server
+  // (a `--sync`-only run, an embedder), and it is the same function
+  // `worker.ts` binds with, so the two cannot drift apart.
+  const port = Bakery.server?.port || resolvePort(Bakery.config.port)
+
+  const isThreadWorker = import.meta.env.THREAD_WORKER
+  if (!isThreadWorker || import.meta.env.THREAD_ID === '0') {
+    if (isThreadWorker) {
+      serveLog.THREAD_STARTED({ id: import.meta.env.THREAD_ID })
+    } else {
+      serveLog.SERVER_STARTED()
+    }
+
+    const logAllNets = () => {
+      serveLog.SERVER_URL({ type: 'Local  ', host: 'localhost', port })
+      const nets = networkInterfaces()
+      for (const name of Object.keys(nets)) {
+        for (const net of nets[name] || []) {
+          if (net.internal) continue
+          if (net.family !== 'IPv4') continue
+          serveLog.SERVER_URL({ type: 'Network', host: net.address, port })
+        }
+      }
+    }
+
+    match(host, {
+      '0.0.0.0': logAllNets,
+      '::': logAllNets,
+      [match]: () => serveLog.SERVER_URL({ type: 'Local ', host, port }),
+    })
+
+    // Identity, not deep equality: `defaultConfig.rateLimit` *is* this
+    // constant, and any user-supplied value replaces the reference. The
+    // default limiter 429s load tests and shared-NAT offices with nothing
+    // anywhere saying it exists, so this line is its one announcement. An
+    // app-configured value prints nothing — their choice, their knowledge.
+    if (Bakery.config.rateLimit === DEFAULT_RATE_LIMIT) {
+      serveLog.RATE_LIMIT_DEFAULT(DEFAULT_RATE_LIMIT)
+    }
+
+    // A broken server.config.ts already logged its import error in DEV, but
+    // that scrolls away; the banner is what the developer actually reads.
+    if (getConfigLoadError()) {
+      serveLog.CONFIG_BROKEN_BANNER()
+    }
+
+    log({ by: 'serve', msg: '' })
+  }
+
+  const { PluginHooks } = await import('./core/plugins')
+  await PluginHooks.onStart(Bakery.server!)
+  await Bakery.config.onStart()
+}

package/src/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Framework helper types, importable rather than ambient.
+ *
+ * These were declared in `declare global`, which is fine inside one repo and a
+ * hazard the moment the packages are published: the names are generic enough
+ * that a consuming app is likely to define its own `MapOf`, and a global type
+ * alias cannot be merged or opted out of — the app just gets a redeclaration
+ * error with nowhere to put the fix.
+ *
+ * Moving them cost 24 files an `import type` line and cost consumers nothing:
+ * neither app in this repo referenced any of the five, which is the evidence
+ * that they were always internal plumbing rather than DX.
+ *
+ * `verbatimModuleSyntax` makes the compiler reject a value-position import of
+ * these, so nothing can accidentally introduce a runtime module edge — which
+ * matters because `client/utils.ts` is compiled into the browser bundle.
+ */
+export type MapOf<T> = { [key: string]: T }
+
+/** A value, or a function producing it. */
+export type Wrapped<T, Args extends any[] = []> = T | ((...args: Args) => T)
+
+/** Awaited or not — the shape almost every framework hook returns. */
+export type MixedPromise<T> = Promise<T> | T
+
+type ResolveMatchReturn<V, R> = R extends any
+  ? R extends (v: V) => infer U
+    ? U
+    : R
+  : never
+
+export type Match<D extends symbol> = {
+  default: D
+  [Symbol.toPrimitive](hint: string): symbol
+
+  <V, C extends readonly (readonly [any, any])[]>(
+    value: V,
+    cases: C,
+  ): [Extract<C[number][0], D>] extends [never]
+    ? ResolveMatchReturn<V, C[number][1]> | undefined
+    : ResolveMatchReturn<V, C[number][1]>
+
+  <V extends string, K>(
+    value: V,
+    cases: Record<string | symbol, K | ((v: V) => K)> & { length?: never },
+  ): K
+
+  <V extends string, K>(
+    value: V,
+    cases: Record<string, K | ((v: V) => K)> & { length?: never },
+  ): K | undefined
+} & D
+
+/**
+ * The `body` a route module's default export receives: declared params merge
+ * over a permissive base. `body.id` is `string` once you declare it, while
+ * `body.anythingElse` stays reachable as `any` — the parse rules in
+ * `utils/http/body.ts` mean the framework genuinely cannot know every key, so
+ * locking the object down would be a lie in the other direction.
+ *
+ * There is no filename-literal inference (`[id].ts` does not conjure
+ * `{ id: string }` on its own — that needs codegen); the contract is that the
+ * author declares the shape once, at the `defineRoute` / `html` call, instead
+ * of annotating the whole signature or settling for `any`.
+ */
+export type RouteBody<P = {}> = P & MapOf<any>
+
+/**
+ * What a route module may actually return — read off `processResponse`
+ * (`router.ts`) and `ApiHandler.handle`: a `Response`, a `BunFile` (streamed
+ * with an ETag), the JSON envelope, a plain data object or array (JSON-encoded
+ * as-is), a string (HTML-sniffed) or number, or nothing (204; a 404 under
+ * `/api/`).
+ *
+ * Deliberately not `object` (which `Handler.Response` uses): `object` absorbs
+ * `Response`, `BunFile` and `JsonResponse` into one member and the union stops
+ * saying anything — the same trap `routeTable()`'s dispatch avoids. `MapOf<any>`
+ * is the narrowest thing that covers "a plain data object"; a target index
+ * signature of `any` does still accept class instances, but that only matters
+ * for inference targets — this union is a constraint on what an author may
+ * return, and nothing consumes a route module's return type downstream, so the
+ * members stay legible instead of collapsing.
+ */
+export type RouteResponse = MixedPromise<
+  | Response
+  | Bun.BunFile
+  | JsonResponse<any>
+  | MapOf<any>
+  | readonly unknown[]
+  | string
+  | number
+  | null
+  | undefined
+  | void
+>
+
+/**
+ * A typed route module default export. `$dynamic.executeModule` calls it as
+ * `(req, body, Bakery.server)` — the third argument is optional here because
+ * `Bakery.server` is itself optional before `Bun.serve` runs, and almost no
+ * handler wants it.
+ *
+ * Named `RouteHandler`, not `ApiHandler`: `handlers/routes/api.ts` already
+ * exports an `ApiHandler` class (and `$base.ts` a `Handler`), and TSX pages use
+ * the same calling convention, so the name should not claim `/api/` either.
+ */
+export type RouteHandler<P = {}> = (
+  req: Request,
+  body: RouteBody<P>,
+  server?: Bun.Server<any>,
+) => RouteResponse

package/src/utils/common/case.ts

@@ -0,0 +1,11 @@
+/**
+ * `Case` moved to `utils/isomorphic/case` — the client bundle carried an
+ * identical copy. `toHash` stays here: it calls `Bun.hash`, so it is server-only
+ * and must not be pulled into the isomorphic layer.
+ */
+export * from '../isomorphic/case'
+
+export function toHash(str = '') {
+  str ||= Math.random().toString(16).slice(2)
+  return Bun.hash(str).toString(36)
+}

package/src/utils/common/index.ts

@@ -0,0 +1,5 @@
+export * from './case'
+export * from './json'
+export * from './match'
+export * from './misc'
+export * from './try'

package/src/utils/common/json.ts

@@ -0,0 +1,35 @@
+export class JsonResponseData<T = any> implements JsonResponse<T> {
+  time: number = 0
+
+  constructor(
+    public status: number,
+    public message: string,
+    public data?: T,
+  ) {}
+
+  toJson() {
+    return JSON.stringify({
+      time: this.time,
+      status: this.status,
+      message: this.message,
+      data: this.data,
+    })
+  }
+
+  toObject() {
+    return {
+      time: this.time,
+      status: this.status,
+      message: this.message,
+      data: this.data,
+    }
+  }
+}
+
+export function jsonResponse<T>(
+  status: number,
+  message: string,
+  data?: T,
+): JsonResponseData<T> {
+  return new JsonResponseData(status, message, data)
+}

package/src/utils/common/match.ts

@@ -0,0 +1,6 @@
+/**
+ * Moved to `utils/isomorphic/match` so the browser bundle and the server share
+ * one implementation — the prototype-chain fix (`Object.hasOwn` rather than
+ * `in`) previously had to be applied to both copies separately.
+ */
+export * from '../isomorphic/match'

package/src/utils/common/misc.ts

@@ -0,0 +1,53 @@
+/**
+ * `is`, `Math2` and `throws` moved to `utils/isomorphic/` — the client bundle
+ * carried its own copies of all three. They are re-exported here so existing
+ * `@server/utils` importers are unaffected.
+ *
+ * `deferredValue` / `hasDeferredValue` stay: they are server-only in practice
+ * and were never duplicated.
+ */
+import type { MapOf } from '../../types'
+
+export { is } from '../isomorphic/is'
+export { Math2 } from '../isomorphic/math'
+export { throws } from '../isomorphic/misc'
+
+const DEFERRED = Symbol('deferred')
+export function deferredValue<O extends object, T>(
+  object: O,
+  key: string,
+  value: (this: O, o: O) => T,
+) {
+  if (!(DEFERRED in object)) {
+    Object.defineProperty(object, DEFERRED, {
+      enumerable: false,
+      configurable: false,
+      writable: false,
+      value: {},
+    })
+  }
+
+  const map = (object as any)[DEFERRED] as MapOf<any>
+
+  Object.defineProperty(object, key, {
+    enumerable: true,
+    configurable: true,
+    get() {
+      if (key in map) return map[key]
+      map[key] = value.call(this, this)
+      return map[key]
+    },
+    set(val) {
+      map[key] = val
+    },
+  })
+}
+
+export function hasDeferredValue<
+  O extends object,
+  T extends keyof O | (string & {}),
+>(object: object, key: T): boolean {
+  if (!(DEFERRED in object)) return false
+  const map = object[DEFERRED] as MapOf<any>
+  return key in map
+}

package/src/utils/common/try.ts

@@ -0,0 +1,6 @@
+/**
+ * Moved to `utils/isomorphic/try` so the browser bundle and the server share one
+ * implementation. Re-exported here because `@server/utils` and a number of
+ * modules import `Try` from this path.
+ */
+export * from '../isomorphic/try'

package/src/utils/constants.ts

@@ -0,0 +1,153 @@
+export const DEFAULT_PORT = 3000
+export const DEFAULT_HOST = '0.0.0.0'
+
+export const DEFAULT_DB_BACKUPS = 10
+
+export const DEFAULT_SESSION_TTL = 1000 * 60 * 60 // 1 hour in ms
+export const DEFAULT_SESSION_PERSIST = DEFAULT_SESSION_TTL * 24 * 30 // 30 days in ms
+
+export const DEFAULT_RATE_LIMIT = { max: 100, refill: 10 }
+
+/**
+ * Files that must never be served off disk.
+ *
+ * These are matched against the file a *file-serving* handler is about to
+ * return, not against every request path — see `servesFiles` in `router.ts`.
+ * An API route or a proxied path is a name, not a file, and never had any
+ * business being tested against this list.
+ *
+ * **Every pattern here must stay lower-case.** `matchBlocked` below folds the
+ * request path to lower case before the second of its two match attempts, and
+ * an upper-case character in a default pattern would be silently unreachable
+ * on that attempt.
+ *
+ * Note what is *not* here: an extension-wide ban on JSON. It caught every
+ * JSON document an app might legitimately publish — a web app manifest, a
+ * `.well-known` document — and since `blocked` in config can only ever append,
+ * an app had no way to opt back out. What the list is actually protecting is
+ * the handful of JSON files that describe the project, so those are named.
+ */
+export const DEFAULT_BLOCKED_GLOBS = [
+  '**/.env',
+  '**/*.env',
+  '**/*.sql',
+  '**/*.db',
+  '**/package.json',
+  '**/package-lock.json',
+  '**/tsconfig.json',
+  '**/tsconfig.*.json',
+  '**/*.yaml',
+  '**/*.yml',
+  '**/*.lock',
+  // `bun.lock` is covered by `*.lock`; the binary lockfile is not.
+  '**/bun.lockb',
+  // `dir/**/*`, not `dir/**`. These patterns are joined into a single
+  // brace-expanded glob by `initConfig`, and inside a brace group Bun's
+  // trailing `**` collapses to a single segment: `{**/node_modules/**}` matches
+  // `/node_modules/a` and then stops, so `/node_modules/pkg/index.js` was not
+  // blocked by anything. Each pattern still matched on its own, which is why
+  // it survived — the defect only exists in the form the config actually uses.
+  // `.cache` is the framework's disposable working dir and `bakery/` holds the
+  // database and its backups — the visible one is the precious one, so that a
+  // dotfile sweep cannot reach the data. `bakery/` being un-dotted is why it
+  // needs naming here explicitly: `*.db` covers the database file itself, but
+  // not the `.ts` schema snapshots under `bakery/backups/`.
+  '**/.cache/**/*',
+  '**/bakery/**/*',
+  '**/_internal/**/*',
+  '**/.git/**/*',
+  '**/.vscode/**/*',
+  '**/node_modules/**/*',
+  '**/server.config.ts',
+  '**/schema.ts',
+  '**/.gitignore',
+  '**/*.exe',
+]
+
+/**
+ * A request path folded to the form the *filesystem* would resolve it to.
+ *
+ * Two normalisations, both of them things the OS does and the glob does not:
+ *
+ * - **Case.** NTFS and APFS are case-insensitive, so `/PACKAGE.JSON` opens the
+ *   same bytes as `/package.json` — but `Bun.Glob` is case-sensitive, so only
+ *   the second one was blocked. Every file this list protects was reachable by
+ *   holding down shift, and the static pipeline was verified to serve
+ *   `/STYLES/GLOBAL.CSS` and `/styles/global.css` as the same 170 bytes.
+ * - **Trailing dots and spaces.** Win32 strips both from each path component,
+ *   so `/package.json.` and `/package.json ` are the same file too.
+ *
+ * `.`, `..` and any all-dots component are left intact — trimming those would
+ * rewrite a relative segment into something else, and containment is
+ * `fs.isForbidden`'s job, not this function's.
+ */
+export function normalizeBlockedPath(path: string): string {
+  return path
+    .toLowerCase()
+    .split('/')
+    .map(segment => segment.replace(/[. ]+$/, '') || segment)
+    .join('/')
+}
+
+/**
+ * Each path component truncated at its first `:`.
+ *
+ * Win32 resolves `x.ts::$DATA` to the bytes of `x.ts` and
+ * `dir::$INDEX_ALLOCATION` to `dir` — NTFS alternate-data-stream syntax — and
+ * `new URL()` keeps the suffix in `pathname`, so a glob anchored on the real
+ * name missed while the filesystem opened the file anyway. The directory form
+ * matters independently: it defeats the `dir/**` patterns that the file form
+ * cannot reach.
+ *
+ * Only ever used as an *extra* match candidate (see `matchBlocked`), never as
+ * a replacement — colons are legal in POSIX filenames, and a real file named
+ * `a:b.db` must stay blocked by `*.db` rather than being tested as `a`.
+ */
+function stripStreamSuffix(path: string): string {
+  if (!path.includes(':')) return path
+  return path
+    .split('/')
+    .map(segment => {
+      const colon = segment.indexOf(':')
+      return colon === -1 ? segment : segment.slice(0, colon) || segment
+    })
+    .join('/')
+}
+
+/**
+ * Whether `path` is refused by the blocked globs.
+ *
+ * Matched twice: once as written, once normalised. Both are needed, and for
+ * different reasons. The normalised pass is what closes the case and
+ * trailing-dot variants above. The verbatim pass is what keeps an app's own
+ * `blocked: ['**\/Secrets.txt']` working — `initConfig` appends user patterns
+ * to this list untouched, so folding only the path would quietly stop matching
+ * the very patterns the app wrote.
+ *
+ * On a case-*sensitive* filesystem this over-blocks: a file genuinely named
+ * `/PACKAGE.JSON`, distinct from `/package.json`, is refused. That is the
+ * intended direction to be wrong in, and it is the reason this normalises the
+ * path rather than resolving the file. The router runs this check before it
+ * knows which file — often before there is a file at all — so "ask the
+ * filesystem for the real name" is not available at the point the answer is
+ * needed, and would cost a `realpath` per request where it was.
+ */
+export function matchBlocked(
+  blocked: { match(path: string): boolean } | undefined,
+  path: string,
+): boolean {
+  if (!blocked) return false
+  if (blocked.match(path)) return true
+
+  // Candidates are only ever *added*, never substituted, so no form of this
+  // can unblock something a plainer form already caught.
+  const normalized = normalizeBlockedPath(path)
+  if (normalized !== path && blocked.match(normalized)) return true
+
+  const stripped = stripStreamSuffix(path)
+  if (stripped === path) return false
+  if (blocked.match(stripped)) return true
+
+  const strippedNormalized = normalizeBlockedPath(stripped)
+  return strippedNormalized !== stripped && blocked.match(strippedNormalized)
+}