@bakery-framework/core 1.0.0

package/src/compiler/tsconfig-sync.ts

@@ -0,0 +1,71 @@
+import { Bakery } from '../core/bakery'
+import { errorMsg, serveLog } from '../logger'
+import type { MapOf } from '../types'
+import { fs } from '../utils/fs'
+import { parseJSONC } from '../utils/jsonc'
+
+// 🚀 Hoisted Regexes
+const RE_ROOT_RELATIVE = /^(\.\/)?(\.server|api|node_modules)\//
+const RE_HTTP = /^https?:\/\//
+const RE_LEADING_SLASHES = /^(\.\/|\/)/
+const RE_RELATIVE = /^\.\.?\//
+const RE_TRAILING_WILDCARD = /\/?\*?$/
+
+// The application's tsconfig, resolved against its cwd. This used to write into
+// a tsconfig *inside the framework* — app-specific paths mutating a shipped
+// package file, which is also why running the test suite dirtied the tree.
+const APP_CONFIG_PATH = fs.resolve(process.cwd(), 'tsconfig.json')
+const APP_DIR = process.cwd()
+
+function buildPaths(): MapOf<string[]> {
+  const newPaths: MapOf<string[]> = {}
+
+  for (const [key, val] of Object.entries(Bakery.config.importMap)) {
+    if (RE_HTTP.test(val)) continue
+    // Values the server maps to a served URL ('/_client/utils.js') are not
+    // filesystem paths; turning them into tsconfig paths yields a directory
+    // that does not exist. Their type mapping belongs in tsconfig.base.json.
+    if (val.startsWith('/')) continue
+
+    const isDir = key.endsWith('/')
+    const tsKey = isDir ? `${key.slice(0, -1)}/*` : key
+
+    const absolutePath = RE_ROOT_RELATIVE.test(val)
+      ? fs.resolve(Bakery.root, val)
+      : fs.resolve(Bakery.serveRoot, val.replace(RE_LEADING_SLASHES, ''))
+
+    const relativePath = fs.relative(APP_DIR, absolutePath)
+
+    let tsVal = (RE_RELATIVE.test(relativePath) ? '' : './') + relativePath
+    if (isDir) tsVal = tsVal.replace(RE_TRAILING_WILDCARD, '/*')
+
+    newPaths[tsKey] = [tsVal]
+  }
+
+  return newPaths
+}
+
+export async function syncTSConfigPaths(): Promise<void> {
+  try {
+    const newPaths = buildPaths()
+    let appConfig: any = { compilerOptions: { paths: {} } }
+
+    if (fs.exists(APP_CONFIG_PATH)) {
+      appConfig = parseJSONC(await Bun.file(APP_CONFIG_PATH).text())
+    }
+
+    appConfig.compilerOptions ??= {}
+    delete appConfig.compilerOptions.baseUrl
+
+    const currentPaths = appConfig.compilerOptions.paths ?? {}
+
+    if (Bun.deepEquals(currentPaths, newPaths)) return
+
+    appConfig.compilerOptions.paths = newPaths
+    await Bun.write(APP_CONFIG_PATH, JSON.stringify(appConfig, null, 2))
+
+    serveLog.TSCONFIG_SYNCED()
+  } catch (err: any) {
+    serveLog.UNHANDLED_ERR({ error: `TSConfig sync error: ${errorMsg(err)}` })
+  }
+}

package/src/core/bakery.ts

@@ -0,0 +1,96 @@
+import { HandlerMap } from '../handlers/core/$registry'
+import { fs } from '../utils/fs'
+import { SharedMemoryPool } from '../utils/shared-pool'
+import { getConfig, resolveHostname } from './config'
+import { getAppVersion, hostStore } from './context'
+
+export type { HostContext } from './context'
+export { hostStore } from './context'
+
+/**
+ * Namespace a cache key by the current host.
+ *
+ * The hostname is resolved against `config.hosts` first, and an unconfigured
+ * one collapses to the unprefixed key. That is not cosmetic: this key becomes a
+ * **filename** in five handlers, and `getOrCreateCachedFile` writes three files
+ * per entry with no bound and no eviction. Prefixing the raw `Host` header let
+ * any client mint an unlimited number of cache entries — 25 requests for one
+ * path under 25 made-up hostnames took the cache directory from 9 files to 84.
+ *
+ * `resolveHostConfig` already carries this reasoning for the config cache; the
+ * file caches simply never got it. Collapsing is safe because an unconfigured
+ * host is served the base config, so its content is identical to the default
+ * bucket's.
+ */
+export function hostKey(path: string): string {
+  const host = resolveHostname(hostStore.getStore()?.hostname || '')
+  return host ? `${host}:${path}` : path
+}
+
+export function getHostname(
+  req: Request,
+  config?: Readonly<ProcessedAppConfig>,
+): string {
+  if (req.__hostname) return req.__hostname
+
+  let hostname = ''
+  const cfg = config ?? Bakery.config
+
+  if (cfg.trustProxy) {
+    const forwardedHost = req.headers.get('x-forwarded-host')
+    if (forwardedHost) {
+      hostname = forwardedHost.split(',')[0].trim().split(':')[0]
+    }
+  }
+
+  if (!hostname) {
+    const hostHeader = req.headers.get('host')
+    if (hostHeader) hostname = hostHeader.split(':')[0]
+    else hostname = new URL(req.url).hostname
+  }
+
+  return hostname
+}
+
+export const Bakery: globalThis.Bakery = {
+  get config(): Readonly<ProcessedAppConfig> {
+    return hostStore.getStore()?.config ?? getConfig()
+  },
+  get serveRoot() {
+    return this.config.root
+  },
+  get apiRoot() {
+    return fs.resolve(this.serveRoot, 'api')
+  },
+  get publicRoot() {
+    return fs.resolve(Bakery.root, 'public')
+  },
+  root: fs.cwd,
+  get version() {
+    return getAppVersion()
+  },
+  sharedPool: new SharedMemoryPool(1024 * 1024),
+  // The disposable directory is the hidden one, and the precious one is not.
+  // This is the reverse of the old `.bakery/cache` + `.data` pairing, and the
+  // reversal is the whole point: `.cache` is wiped by the framework itself on
+  // every version bump and dev<->prod switch, so a `rm -rf .*` or a "clean out
+  // the dotfiles" sweep does exactly what the framework already does. The
+  // database is not disposable, so it does not live behind a leading dot where
+  // such a sweep can reach it.
+  cacheDir: `${fs.cwd}/.cache`,
+  // Holds the database and its backups. Visible, and deliberately not under
+  // `.cache`: clearing a cache must never be able to destroy data.
+  dataDir: `${fs.cwd}/bakery`,
+  startNs: Bun.nanoseconds(),
+  handlers: {
+    fetch: new HandlerMap(),
+    error: new HandlerMap(),
+    websocket: new HandlerMap(),
+  },
+  shutdownHooks: [] as any[],
+  onShutdown(hook: () => Promise<void> | void) {
+    this.shutdownHooks.push(hook)
+  },
+}
+
+export default Bakery

package/src/core/cache-version.ts

@@ -0,0 +1,119 @@
+import { readdir, rm } from 'node:fs/promises'
+import { serveLog } from '../logger/serve-log'
+import { Try } from '../utils/common'
+import { fs } from '../utils/fs'
+import { Bakery } from './bakery'
+import { getAppVersion, getFrameworkVersion } from './context'
+
+/**
+ * Discard `.cache/` when the thing that produced it has changed.
+ *
+ * Its own module, and that is the fix rather than an organisational
+ * preference. This used to live in `config.ts` and run from `initConfig()`,
+ * which is far too late: `cache/shared-db.ts` opens `.cache/shared-cache.db`
+ * at **import** time, so by the time the check ran the process was already
+ * holding a handle to a file inside the directory it was about to delete. On
+ * Windows that delete fails with `EBUSY`, node's recursive walk stops at the
+ * locked entry, and everything it had not reached yet survived — including
+ * `html/`, the compiled-page cache, which is exactly what a version bump has
+ * to discard.
+ *
+ * Now `shared-db.ts` awaits this before opening the database, and `initConfig`
+ * still calls it for the case where nothing has touched the cache yet. It is
+ * memoised, so whichever gets there first does the work and the other is free.
+ */
+let done: Promise<void> | null = null
+
+export function checkCacheVersion(): Promise<void> {
+  done ??= run()
+  return done
+}
+
+/** Test seam: forget that the check ran, so a fixture can exercise it again. */
+export function __resetCacheVersionCheck(): void {
+  done = null
+}
+
+async function run(): Promise<void> {
+  // Workers inherit a directory the master already validated. Re-running here
+  // would race the master's own wipe.
+  if (import.meta.env.WORKER) return
+
+  // Read from `Bakery.cacheDir`, never re-derived from `fs.cwd`. This value is
+  // handed straight to a recursive delete below, and it used to be a
+  // hand-written copy of the constant in `core/bakery.ts` — two sources of
+  // truth for a `rm -rf`. Renaming the cache directory in one place and not the
+  // other would have pointed this delete at whatever the stale literal named.
+  const cacheDir = Bakery.cacheDir
+  const markerPath = `${cacheDir}/server.json`
+
+  const current = {
+    mode: import.meta.env.DEV ? 'development' : 'production',
+    // The app's version and the framework's are both here, and they are
+    // different files on purpose: keying on the app alone meant
+    // `bun update @bakery-framework/core` left a cache compiled by the previous
+    // framework version, with nothing to invalidate it.
+    version: getAppVersion(),
+    framework: getFrameworkVersion(),
+  }
+
+  const [err, prev] = await Try.catch(() => Bun.file(markerPath).json())
+  const stale =
+    err ||
+    !prev ||
+    prev.mode !== current.mode ||
+    prev.version !== current.version ||
+    prev.framework !== current.framework
+
+  if (!stale) return
+
+  const survivors = await wipe(cacheDir)
+  if (!fs.exists(cacheDir)) await fs.mkdir(cacheDir)
+
+  // The marker is written **only** when the directory is actually empty.
+  //
+  // It used to be written unconditionally, right after a delete whose every
+  // error was swallowed — so a failed wipe produced a file asserting the cache
+  // was current, and nothing ever tried again. A stale compiled page then
+  // outlived the upgrade that was supposed to remove it, silently and
+  // permanently. Leaving the old marker in place costs one retry per boot and
+  // is the only honest option: the cache is not current, so nothing should say
+  // it is.
+  if (survivors.length) {
+    serveLog.CACHE_WIPE_INCOMPLETE({
+      dir: cacheDir,
+      files: survivors.join(', '),
+    })
+    return
+  }
+
+  await Bun.write(markerPath, `${JSON.stringify(current, null, 2)}\n`)
+}
+
+/**
+ * Empty `dir`, entry by entry. Returns whatever is still there.
+ *
+ * Per-entry rather than one recursive call on the directory itself, because a
+ * single locked file otherwise shields every entry the walk had not yet
+ * reached — the failure is ordering-dependent, so it presents as "sometimes the
+ * cache clears".
+ */
+export const __wipeCacheDir = wipe
+
+async function wipe(dir: string): Promise<string[]> {
+  if (!fs.exists(dir)) return []
+  const [readErr, entries] = await Try.catch(() => readdir(dir))
+  if (readErr || !entries) return ['<unreadable>']
+
+  for (const entry of entries) {
+    // Errors are deliberately not swallowed *silently* here — each failure is
+    // collected and reported by the caller.
+    await Try.catch(() =>
+      rm(`${dir}/${entry}`, { recursive: true, force: true }),
+    )
+  }
+
+  const [rereadErr, left] = await Try.catch(() => readdir(dir))
+  if (rereadErr) return ['<unreadable>']
+  return left ?? []
+}

package/src/core/config.ts

@@ -0,0 +1,296 @@
+import { log } from '../logger'
+import { errorMsg, serveLog } from '../logger/serve-log'
+import { Try } from '../utils/common'
+import {
+  DEFAULT_BLOCKED_GLOBS,
+  DEFAULT_DB_BACKUPS,
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  DEFAULT_RATE_LIMIT,
+} from '../utils/constants'
+import { fs } from '../utils/fs'
+import { checkCacheVersion } from './cache-version'
+import { hostStore } from './context'
+
+export const NOOP = () => {}
+
+const defaultConfig: Required<AppConfig> = {
+  port: DEFAULT_PORT,
+  host: DEFAULT_HOST,
+  maxBodySize: 20 * 1024 * 1024,
+  middleware: [],
+  backups: DEFAULT_DB_BACKUPS,
+  blocked: [],
+  head: '',
+  body: '',
+  plugins: [],
+  onStart: NOOP,
+  onError(e) {
+    const host = hostStore.getStore()?.hostname || 'global'
+    log({ level: 'warn', by: host, msg: e.errorBody })
+  },
+  onShutdown: NOOP,
+  // `maxCacheSize: 500` used to sit here. Nothing in the framework ever read
+  // it — not the route LRUs, not the tiered cache — so it was a knob that
+  // typechecked, appeared in completion, and did nothing. Removed from
+  // `AppConfig` at the same time; `defaultConfig` is `Required<AppConfig>`, so
+  // the two can only move together.
+  importMap: {
+    // Served by VirtualAssetHandler; the framework's own files are no longer
+    // reachable at an app-relative '.server/...' path.
+    '@client/utils': '/_client/utils.js',
+  },
+  onRequest: NOOP,
+  proxy: {},
+  rateLimit: DEFAULT_RATE_LIMIT,
+  trustProxy: false,
+  // Empty means auto-detect, matching `head`/`body` above. There is no default
+  // *path* to give here: the default behaviour is the probe itself.
+  schema: '',
+  root: 'src',
+  hosts: {},
+  websocket: {
+    message: NOOP,
+    open: NOOP,
+    close: NOOP,
+    drain: NOOP,
+  },
+}
+
+let cachedConfig: ProcessedAppConfig | null = null
+const hostConfigCache = new Map<string, Readonly<ProcessedAppConfig>>()
+
+let configLoadError: string | null = null
+
+/**
+ * The import failure recorded by the most recent `initConfig()` run, when a
+ * `server.config.ts` was *present but failed to load*. DEV-only by
+ * construction — in PROD that same condition throws out of `initConfig()`
+ * instead of being recorded. Read by `runStartupBanner()` so the warning is
+ * restated where the developer is actually looking, not just in scrollback.
+ */
+export function getConfigLoadError(): string | null {
+  return configLoadError
+}
+
+/**
+ * `hosts` folded to lower case, memoised against the object it came from.
+ *
+ * Keyed on identity rather than rebuilt per request because `hosts` is frozen
+ * for the process lifetime — except under `__setTestConfig`, where a new object
+ * arrives and the identity check rebuilds rather than serving a stale map.
+ */
+let hostLookup: {
+  source: Record<string, HostEntry>
+  entries: Map<string, HostEntry>
+} | null = null
+
+export function clearHostConfigCache(): void {
+  cachedConfig = null
+  hostConfigCache.clear()
+  hostLookup = null
+}
+
+export async function initConfig(): Promise<Readonly<ProcessedAppConfig>> {
+  if (cachedConfig) return cachedConfig
+
+  await checkCacheVersion()
+  hostConfigCache.clear()
+
+  // Resolved against the application's cwd, not relative to this file. A
+  // static '../../server.config.ts' reached out of the framework into the app,
+  // which breaks as soon as the framework is a package rather than a directory
+  // inside the app. Absence is tolerated: the defaults below are a usable
+  // config, and zero-config boot is a supported feature.
+  const configPath = fs.resolve(process.cwd(), 'server.config.ts')
+  let serverConfig: any = {}
+  configLoadError = null
+
+  if (await Bun.file(configPath).exists()) {
+    const [error, loaded] = await Try.catch(import(configPath))
+    if (error) {
+      // Present-but-broken is not absence. This used to log one line and boot
+      // on `defaultConfig` — port 3000, no plugins, no hosts — so the
+      // developer debugged the vanished dashboard instead of the config that
+      // never parsed. In PROD that boot must not happen: the throw lands in
+      // the entry's existing catch (prod.ts / threads.ts / worker.ts), which
+      // logs and exits 1. In DEV a crash would just loop the watcher, so boot
+      // — loudly, and leave the error for the startup banner to restate.
+      const message = errorMsg(error)
+      if (import.meta.env.PROD) {
+        throw new Error(
+          `server.config.ts exists but failed to import — refusing to start on the default config.\n  file: ${configPath}\n${message}`,
+        )
+      }
+      configLoadError = message
+      serveLog.CONFIG_BROKEN({ file: configPath, error: message })
+    } else {
+      serverConfig = loaded?.default ?? {}
+    }
+  }
+  const overriden = { ...defaultConfig, ...serverConfig } as Required<AppConfig>
+
+  overriden.importMap = Object.assign(
+    { '@client/utils': '/_client/utils.js' },
+    serverConfig.importMap || {},
+  )
+
+  const blockedGlob = [
+    ...DEFAULT_BLOCKED_GLOBS,
+    ...overriden.blocked.map(pattern =>
+      pattern.startsWith('**/') ? pattern : `**/${pattern}`,
+    ),
+  ].join(',')
+
+  cachedConfig = Object.assign(overriden, {
+    blocked: new Bun.Glob(`{${blockedGlob}}`),
+    root: fs.resolve(overriden.root),
+  })
+
+  return Object.freeze(cachedConfig)
+}
+
+let testOverrides: Partial<ProcessedAppConfig> | null = null
+
+/**
+ * Test seam, symmetric with `__setTestDb` in `@bakery-framework/orm`.
+ *
+ * The resolved config is frozen, so a test that needs to exercise a
+ * config-dependent branch cannot simply assign to it. The alternative was
+ * `mock.module('./core/config', …)`, which is process-global and never
+ * restored — one file doing that left `Bakery.config` undefined for every test
+ * file loaded after it, and the suite stayed green only because Bun happened
+ * to order that file last.
+ *
+ * Always pair with `__resetTestConfig()` in `afterAll`.
+ */
+export function __setTestConfig(overrides: Partial<ProcessedAppConfig>): void {
+  testOverrides = overrides
+}
+
+export function __resetTestConfig(): void {
+  testOverrides = null
+}
+
+export function getConfig(): Readonly<ProcessedAppConfig> {
+  if (!cachedConfig) {
+    throw new Error('Config has not been initialized. Call initConfig() first.')
+  }
+
+  if (testOverrides) {
+    return Object.freeze({ ...cachedConfig, ...testOverrides })
+  }
+
+  return cachedConfig
+}
+
+function mergeHostConfig(
+  base: ProcessedAppConfig,
+  entry: HostEntry,
+): Readonly<ProcessedAppConfig> {
+  const merged: any = { ...base }
+
+  if (entry.root) merged.root = fs.resolve(entry.root)
+  if (entry.importMap)
+    merged.importMap = { ...base.importMap, ...entry.importMap }
+  if (entry.middleware) merged.middleware = entry.middleware
+  if (entry.onRequest) merged.onRequest = entry.onRequest
+  if (entry.onError) merged.onError = entry.onError
+  if (entry.head !== undefined) merged.head = entry.head
+  if (entry.body !== undefined) merged.body = entry.body
+  if (entry.proxy) merged.proxy = entry.proxy
+  if (entry.rateLimit !== undefined) merged.rateLimit = entry.rateLimit
+  if (entry.blocked) {
+    const blockedGlob = [
+      ...DEFAULT_BLOCKED_GLOBS,
+      ...entry.blocked.map(p => (p.startsWith('**/') ? p : `**/${p}`)),
+    ].join(',')
+    merged.blocked = new Bun.Glob(`{${blockedGlob}}`)
+  }
+
+  return Object.freeze(merged)
+}
+
+/**
+ * The configured host entry for an already-lowercased hostname, or undefined.
+ *
+ * A Map built from `Object.entries` rather than a lookup on `hosts` itself:
+ * own enumerable keys only, so `Host: constructor` cannot reach a prototype
+ * member and get merged as if it were a host entry. That is what the previous
+ * `Object.hasOwn` guard bought, and it is preserved here.
+ *
+ * If two keys differ only in case, the first one declared wins.
+ */
+function lookupHostEntry(
+  hosts: Record<string, HostEntry>,
+  hostname: string,
+): HostEntry | undefined {
+  if (!hostLookup || hostLookup.source !== hosts) {
+    const entries = new Map<string, HostEntry>()
+    for (const [key, entry] of Object.entries(hosts)) {
+      const normalized = key.toLowerCase()
+      if (!entries.has(normalized)) entries.set(normalized, entry)
+    }
+    hostLookup = { source: hosts, entries }
+  }
+
+  return hostLookup.entries.get(hostname)
+}
+
+/**
+ * The canonical form of `hostname` if the app declares it under `hosts`, and
+ * `''` otherwise — including when no `hosts` are configured at all.
+ *
+ * Same reasoning as `resolveHostConfig` below, which already refuses to cache
+ * an unknown hostname: the value arrives on the `Host` header, so anything
+ * derived from it that is *kept* — a config entry, a cache key, a file on disk
+ * — has to be bounded by the configured set, or an unauthenticated client can
+ * grow it without limit. Collapsing unknown hosts to `''` puts them all in one
+ * bucket, which is correct because they all get the base config and therefore
+ * the same content.
+ *
+ * Folded with `toLowerCase` for the reason spelled out below: hostnames are
+ * case-insensitive, so `EXAMPLE.com` and `example.com` must be one key, not two.
+ */
+export function resolveHostname(hostname: string): string {
+  // No config yet (a unit test that never called `initConfig`) means no `hosts`
+  // to match against, which is the same answer as an unconfigured host.
+  if (!hostname || !cachedConfig) return ''
+  const hosts = getConfig().hosts
+  if (!hosts) return ''
+  const key = hostname.toLowerCase()
+  return lookupHostEntry(hosts, key) ? key : ''
+}
+
+export function resolveHostConfig(
+  hostname: string,
+): Readonly<ProcessedAppConfig> {
+  const base = getConfig()
+  const hosts = base.hosts
+  if (!hosts || !Object.keys(hosts).length) return base
+
+  // Hostnames are case-insensitive (RFC 4343) and nothing upstream normalises
+  // the Host header, so a request to `EXAMPLE.com` used to miss an
+  // `example.com` entry and silently fall back to the base config. Both sides
+  // fold to lower case — `toLowerCase`, not `toLocaleLowerCase`, which would
+  // map `I` to a dotless `ı` in a Turkish locale.
+  const key = hostname.toLowerCase()
+
+  const cached = hostConfigCache.get(key)
+  if (cached) return cached
+
+  const entry = lookupHostEntry(hosts, key)
+  if (!entry) {
+    // Deliberately NOT cached. The hostname comes straight from the Host
+    // header, so caching unknown values let any client grow this map without
+    // bound — one request per made-up hostname until the process runs out of
+    // memory. Known hosts are a fixed, small set, so only those are cached.
+    // Normalising above keeps that bound honest: without it, `EXAMPLE.com` and
+    // `example.com` would occupy two entries for one configured host.
+    return base
+  }
+
+  const merged = mergeHostConfig(base as ProcessedAppConfig, entry)
+  hostConfigCache.set(key, merged)
+  return merged
+}