@bakery-framework/core 1.0.0

package/src/global.d.ts

@@ -0,0 +1,374 @@
+import type { Handler } from './handlers/core/$base'
+import type * as HandlerError from './handlers/core/$error'
+import type * as HandlerRegistry from './handlers/core/$registry'
+import type * as HandlerWs from './handlers/core/$websocket'
+import type * as _logger from './logger/logger'
+import type * as _plugins from './plugins/types'
+import type { Session } from './session'
+import type { MapOf, MixedPromise } from './types'
+
+/**
+ * File-local, deliberately not global and not exported: its only two uses are
+ * the two definitions below it. A global `type Override` is the kind of name a
+ * consuming app is likely to want for itself.
+ */
+type Override<T, U> = Omit<T, keyof U> & U
+
+declare global {
+  // Bound on globalThis by core/init.ts, which is why they are declared and
+  // not imported. `createElement` and `Fragment` additionally *have* to be
+  // global: tsconfig sets jsxFactory/jsxFragmentFactory, and the classic JSX
+  // runtime resolves those names in global scope.
+  //
+  // `var req: Request` and `var body: any` used to live here too. Nothing ever
+  // assigned them — not init.ts, not client/utils.ts, nothing — so
+  // `req.headers.get('host')` typechecked anywhere in the codebase and threw
+  // `ReferenceError: req is not defined` when it ran. A global that only
+  // exists in the type system is worse than no global at all.
+  var createElement: typeof import('./core/jsx').createElement
+  var Fragment: typeof import('./core/jsx').Fragment
+  var html: typeof import('./core/jsx').html
+
+  // JsonResponse and ISFunction are declared once, in shared.d.ts — the
+  // browser runtime needs them too. MapOf, Wrapped and MixedPromise are not
+  // global at all any more; they are imported from ./types above.
+  //
+  // `Mutable<T>` used to sit here. It had one declaration and zero consumers
+  // anywhere in the repo, so it is deleted rather than moved.
+
+  type InjectScript = {
+    src: string
+    module?: boolean
+    async?: boolean
+    defer?: boolean
+    inBody?: boolean
+  }
+
+  type HostEntry = {
+    root?: string
+    importMap?: Record<string, string>
+    middleware?: ((
+      req: Request,
+      server: Bun.Server<any>,
+    ) => MixedPromise<Response | void>)[]
+    onRequest?(req: Request): MixedPromise<any>
+    onError?(error: Handler.Error.Data): MixedPromise<any>
+    head?: string
+    body?: string
+    proxy?: Record<string, string>
+    blocked?: string[]
+    rateLimit?:
+      | {
+          max: number
+          refill: number
+          keyBy?: (req: Request) => string
+        }
+      | false
+  }
+
+  type AppConfig = {
+    root?: string
+
+    port?: number
+
+    host?: string
+
+    importMap?: Record<string, string>
+
+    backups?: number
+
+    proxy?: Record<string, string>
+
+    head?: string
+
+    body?: string
+
+    onStart?(): MixedPromise<void>
+
+    onRequest?(req: Request): MixedPromise<any>
+
+    onError?(error: Handler.Error.Data): MixedPromise<any>
+
+    onShutdown?(): MixedPromise<void>
+
+    middleware?: ((
+      req: Request,
+      server: Bun.Server<any>,
+    ) => MixedPromise<Response | void>)[]
+
+    plugins?: ServerPlugin[]
+
+    websocket?: Bun.WebSocketHandler<any>
+
+    maxBodySize?: number
+
+    // `maxCacheSize?: number` was declared and defaulted to 500 here, and read
+    // by nothing: the route LRUs size themselves and the tiered cache takes its
+    // own options. Deleted rather than wired up — there is no single cache it
+    // plausibly governs, and a knob that silently does nothing is worse than an
+    // absent one. Removing it before the first publish is a docs note; after,
+    // it is a breaking change.
+
+    blocked?: string[]
+
+    rateLimit?:
+      | {
+          max: number
+          refill: number
+          keyBy?: (req: Request) => string
+        }
+      | false
+
+    trustProxy?: boolean
+
+    /**
+     * Where the ORM finds the app's schema — a file, or a folder containing
+     * `index.ts`. Relative paths resolve against the app's cwd. Omit it (or
+     * leave it empty) to auto-detect `orm/` then `schema.ts`.
+     *
+     * A plain string, deliberately: core must never depend on `@bakery-framework/orm`,
+     * which depends on core, and a path carries no type from it. The ORM reads
+     * this through `schemaFromConfig`. A configured path that does not exist is
+     * a hard error rather than a fall back to auto-detect — otherwise a typo
+     * makes the sync engine generate a fresh schema at the wrong path while the
+     * real one sits untouched.
+     */
+    schema?: string
+
+    hosts?: Record<string, HostEntry>
+  }
+
+  type ServerPlugin = _plugins.ServerPlugin
+
+  interface Bakery {
+    server?: Bun.Server<any>
+    readonly sharedPool: import('./utils/shared-pool').SharedMemoryPool
+    readonly cacheDir: string
+    readonly dataDir: string
+    readonly version: string
+    readonly root: string
+    readonly serveRoot: string
+    readonly apiRoot: string
+    readonly publicRoot: string
+    readonly config: ProcessedAppConfig
+    readonly handlers: {
+      readonly fetch: HandlerRegistry.HandlerMap
+      readonly error: HandlerRegistry.HandlerMap<
+        | typeof HandlerError.ErrorHandler
+        | typeof HandlerError.DynamicErrorHandler
+      >
+      readonly websocket: HandlerRegistry.HandlerMap<
+        typeof HandlerWs.WebSocketHandler
+      >
+    }
+    onShutdown(hook: () => Promise<void> | void): void
+    readonly shutdownHooks: (() => Promise<void> | void)[]
+    readonly startNs: number
+  }
+
+  // DBSchema / DBOptionals are declared by the orm package (its own
+  // globals.d.ts), not here: core must not reference orm, which depends on core.
+
+  type LoggerEntry = _logger.LoggerEntry
+  type LogLevels = _logger.LogLevels
+
+  type ResponseFn = {
+    (body?: Bun.BodyInit | null, init?: ResponseInit): Response
+    json: ((status: number, message: string, data?: any) => Response) & {
+      success: <T>(message: string, data?: T, status?: number) => Response
+      error: <T>(status?: number, message?: string, data?: T) => Response
+    }
+    html: (html: string, status?: number, init?: ResponseInit) => Response
+    text: (text: string, status?: number, init?: ResponseInit) => Response
+    href: (url: string, status?: 301 | 302 | 307 | 308) => Response
+    type: (body: any, contentType: string, init?: ResponseInit) => Response
+    error: (
+      error: string | Error,
+      code?: number,
+      init?: ResponseInit,
+    ) => Response
+  }
+
+  type ApiCallback<T = any> = (
+    req: Request,
+    body: MapOf<any>,
+    server: Bun.Server<any>,
+  ) => MixedPromise<T>
+
+  namespace JSX {
+    type Element = string
+
+    interface ElementChildrenAttribute {
+      children: MapOf<any>
+    }
+
+    interface HTMLAttributes {
+      class?: string
+      className?: string
+      id?: string
+      style?: string | Record<string, string | number>
+      children?: any
+      tabindex?: number | string
+      title?: string
+
+      [key: `data-${string}`]: string | undefined
+      [key: `aria-${string}`]: string | undefined
+
+      [key: string]: any
+    }
+
+    interface AnchorAttributes extends HTMLAttributes {
+      href?: string
+      target?: string
+      rel?: string
+    }
+    interface ImgAttributes extends HTMLAttributes {
+      src?: string
+      alt?: string
+      width?: string | number
+      height?: string | number
+      loading?: 'lazy' | 'eager'
+    }
+    interface InputAttributes extends HTMLAttributes {
+      type?: string
+      value?: any
+      name?: string
+      placeholder?: string
+      disabled?: boolean
+      required?: boolean
+      checked?: boolean
+      autocomplete?: string
+    }
+    interface FormAttributes extends HTMLAttributes {
+      action?: string
+      method?: 'GET' | 'POST' | 'get' | 'post'
+      enctype?: string
+    }
+    interface ScriptAttributes extends HTMLAttributes {
+      src?: string
+      type?: string
+      defer?: boolean
+      async?: boolean
+    }
+    interface LinkAttributes extends HTMLAttributes {
+      rel?: string
+      href?: string
+      as?: string
+      type?: string
+    }
+    interface MetaAttributes extends HTMLAttributes {
+      name?: string
+      content?: string
+      charset?: string
+      property?: string
+    }
+
+    interface IntrinsicElements {
+      html: HTMLAttributes & { lang?: string }
+      head: HTMLAttributes
+      body: HTMLAttributes
+      title: HTMLAttributes
+      meta: MetaAttributes
+      link: LinkAttributes
+      script: ScriptAttributes
+
+      div: HTMLAttributes
+      span: HTMLAttributes
+      p: HTMLAttributes
+      h1: HTMLAttributes
+      h2: HTMLAttributes
+      h3: HTMLAttributes
+      h4: HTMLAttributes
+      h5: HTMLAttributes
+      h6: HTMLAttributes
+      ul: HTMLAttributes
+      ol: HTMLAttributes
+      li: HTMLAttributes
+
+      a: AnchorAttributes
+      img: ImgAttributes
+      button: HTMLAttributes & {
+        type?: 'button' | 'submit' | 'reset'
+        disabled?: boolean
+      }
+      input: InputAttributes
+      textarea: InputAttributes & {
+        rows?: number | string
+        cols?: number | string
+      }
+      form: FormAttributes
+      select: HTMLAttributes & {
+        name?: string
+        disabled?: boolean
+        required?: boolean
+        multiple?: boolean
+      }
+      option: HTMLAttributes & {
+        value?: any
+        selected?: boolean
+        disabled?: boolean
+      }
+
+      br: HTMLAttributes
+      hr: HTMLAttributes
+
+      [elemName: string]: HTMLAttributes
+    }
+  }
+
+  // Defined as getters on process.env by core/init.ts, and substituted into
+  // browser bundles by the compiler's `defines`. The client used to redeclare
+  // `ImportMeta.env` with its own incompatible shape, which is TS2687/TS2717 —
+  // suppressed, like everything else in a .d.ts, by skipLibCheck.
+  interface ImportMetaEnv {
+    readonly DEV: boolean
+    readonly PROD: boolean
+    readonly WORKER: boolean
+    readonly DEV_WORKER: boolean
+    readonly THREAD_WORKER: boolean
+    readonly THREAD_ID: string
+    readonly TEST: boolean
+    readonly MODE: 'production' | 'development' | 'dev-worker' | 'thread-worker'
+    // `readonly SERVE_ROOT: string` was declared here. Nothing defines it —
+    // not init.ts, not the compiler's `defines` — and nothing reads it, so any
+    // code that trusted the declaration would have got `undefined` typed as
+    // `string`. The resolved root is `Bakery.serveRoot`; use that.
+    /** Compiler define; the only one the browser bundle reads. */
+    readonly BAKERY_VERSION: string
+  }
+
+  interface SessionData extends MapOf<any> {}
+
+  interface Request {
+    startNs: number
+    session: Session<SessionData>
+    __hostname?: string
+  }
+
+  type HandlerName = string & {}
+  type HrefPath = string & {}
+  type UpgradeData = MapOf<any> | undefined | void
+  type WebSocketData<T> = {
+    this: typeof HandlerWs.WebSocketHandler
+    type: 'websocket'
+    orig: HandlerName
+    path: HrefPath
+    data: T
+  }
+
+  type ProcessedAppConfig = Override<
+    Required<AppConfig>,
+    {
+      blocked: Bun.Glob
+    }
+  >
+
+  type ServerWebSocket<T = MapOf<any>> = Override<
+    Bun.ServerWebSocket,
+    { data: WebSocketData<T> }
+  >
+
+  interface Blob {
+    slice(start: number, end?: number, contentType?: string): Blob
+  }
+}

package/src/handlers/assets/google-font.ts

@@ -0,0 +1,225 @@
+import { LRUCache } from '../../cache/lru'
+import { Bakery } from '../../core/bakery'
+import { toHash } from '../../utils/common/case'
+import { COMPRESSION_MAP, FileSystem as fs } from '../../utils/fs'
+import { response } from '../../utils/http'
+import { Handler } from '../core/$base'
+
+/**
+ * The Google Fonts CSS endpoints this proxy is willing to forward to.
+ *
+ * `css` is the v1 API, `css2` the current one, `icon` the Material icon
+ * stylesheet. Everything else on `fonts.googleapis.com` — and anything at all
+ * once the path is attacker-supplied — is refused, because this handler is an
+ * unauthenticated outbound fetch from the server's own IP and the path used to
+ * be forwarded verbatim.
+ */
+const GF_CSS_PATHS = new Set(['css', 'css2', 'icon'])
+
+/**
+ * The documented Google Fonts query parameters.
+ *
+ * Google answers `200` for a request carrying parameters it does not know, so
+ * before this list every `?family=Roboto&junk=<n>` was a fresh cache key *and*
+ * a fresh outbound request: six junk requests were measured producing six keys
+ * and eighteen files. Names are compared raw, without percent-decoding — a
+ * name spelled `%66amily` simply fails the list, which is the safe direction.
+ */
+const GF_CSS_PARAMS = new Set([
+  'display',
+  'effect',
+  'family',
+  'icon_names',
+  'subset',
+  'text',
+])
+
+const GF_MAX_PARAMS = 12
+const GF_MAX_QUERY = 512
+const GF_MAX_GSTATIC_PATH = 256
+
+/**
+ * A path under `fonts.gstatic.com`, as the rewritten CSS references it —
+ * `s/roboto/v47/KFOmCnqEu92Fr1Mu4mxK.woff2`.
+ *
+ * Every segment must start with an alphanumeric, which is what rules out `..`
+ * and an empty segment (`//`) without a second pass over the string, and the
+ * extension list keeps this to font payloads.
+ */
+const GF_GSTATIC_PATH =
+  /^[a-zA-Z0-9][a-zA-Z0-9._-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*\.(?:woff2?|ttf|otf|eot|svg)$/
+
+/**
+ * How many distinct upstream assets this handler will keep on disk.
+ *
+ * `getOrCreateCachedFile` writes three files per entry (raw, `.zst`, `.gz`)
+ * and nothing ever removed them, so the cache directory grew with the number
+ * of distinct request URLs — which is to say, without bound. The allow-lists
+ * above shrink the key space but do not close it: a family *name* is still
+ * free text, and a wrong one costs a 400 from Google rather than a rejection
+ * here. This is the bound, in the shape convention 6 asks for.
+ *
+ * The index is per-process and the files are not, so a restart forgets which
+ * files it was tracking. That leaves at most one generation of stale files
+ * behind rather than an unbounded pile, and re-requesting an entry re-adopts
+ * it; a cache directory is disposable by design.
+ */
+const GF_MAX_ENTRIES = 256
+
+const cacheIndex = new LRUCache<string, string>(
+  GF_MAX_ENTRIES,
+  (_key, rawPath) => {
+    void fs.rm(rawPath, { force: true })
+    for (const { ext } of COMPRESSION_MAP) {
+      void fs.rm(`${rawPath}${ext}`, { force: true })
+    }
+  },
+)
+
+/** Record a cache entry against the bound, evicting the oldest if it is full. */
+function trackCacheEntry(cacheDir: string, cacheName: string): void {
+  const rawPath = fs.resolve(cacheDir, cacheName)
+  cacheIndex.set(rawPath, rawPath)
+}
+
+/**
+ * Test seams for the bound, in the `__`-prefixed style of `__setTestConfig`.
+ *
+ * Every other branch of this handler is reachable from a test through
+ * `handle()` — the allow-lists refuse before anything is fetched. The eviction
+ * path is not: reaching it legitimately means 257 successful round trips to
+ * Google, which is not a unit test. These let one assert the bound holds and
+ * that an evicted entry takes its `.zst`/`.gz` companions with it.
+ */
+export const __gfTrackCacheEntry = trackCacheEntry
+export const __gfCacheIndex: ReadonlyMap<string, string> = cacheIndex
+export const __gfMaxEntries = GF_MAX_ENTRIES
+
+/**
+ * The query, validated and put in a canonical order, or `null` if it carries
+ * anything undocumented.
+ *
+ * Pairs are sorted as raw text rather than re-encoded through
+ * `URLSearchParams`: sorting collapses `?family=X&display=swap` and
+ * `?display=swap&family=X` onto one cache key and one upstream request, while
+ * leaving each pair's bytes exactly as the client sent them. Re-encoding would
+ * turn the `:`, `@` and `;` of a `family=Roboto:wght@400;700` axis spec into
+ * percent escapes and change the request going upstream, which is not a thing
+ * to do on a live third-party API for a cosmetic win.
+ */
+function canonicalQuery(search: string): string | null {
+  const raw = search.startsWith('?') ? search.slice(1) : search
+  if (!raw) return ''
+  if (raw.length > GF_MAX_QUERY) return null
+
+  const pairs = raw.split('&')
+  if (pairs.length > GF_MAX_PARAMS) return null
+
+  for (const pair of pairs) {
+    const name = pair.split('=')[0]
+    if (!GF_CSS_PARAMS.has(name)) return null
+  }
+
+  return `?${pairs.sort().join('&')}`
+}
+
+export class GoogleFontHandler extends Handler {
+  static get cacheDir() {
+    return fs.resolve(Bakery.cacheDir, 'gf_cache')
+  }
+
+  static canHandle(path: string): boolean {
+    return path === '/_gf' || path.startsWith('/_gf/')
+  }
+
+  static async handle(path: string, req: Request) {
+    if (path.startsWith('/_gf/gstatic/')) {
+      return this.handleGstatic(path)
+    }
+
+    const rawPath = path.slice('/_gf'.length)
+    const strippedPath = rawPath.startsWith('/') ? rawPath.slice(1) : rawPath
+    const gfPath = strippedPath || 'css2'
+
+    if (!GF_CSS_PATHS.has(gfPath)) {
+      return response.error('Unknown Google Fonts endpoint', 404)
+    }
+
+    const url = new URL(req.url)
+    const searchQuery = canonicalQuery(url.search)
+    if (searchQuery === null) {
+      return response.error('Unsupported Google Fonts query', 400)
+    }
+
+    const cacheKey = `${gfPath}${searchQuery}`
+    const cacheName = `${toHash(cacheKey)}.css`
+    const cacheDir = this.cacheDir
+
+    const cached = await fs.getOrCreateCachedFile(
+      cacheDir,
+      cacheName,
+      null,
+      async () => {
+        const gfUrl = `https://fonts.googleapis.com/${gfPath}${searchQuery}`
+
+        const res = await fetch(gfUrl, {
+          headers: {
+            'User-Agent':
+              'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+              ' (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+          },
+        })
+
+        if (!res.ok) return null
+
+        let css = await res.text()
+        css = css.replace(/https?:\/\/fonts\.gstatic\.com/g, '/_gf/gstatic')
+
+        return css
+      },
+    )
+
+    if (!cached) return response.error('Failed to fetch Google Fonts CSS', 502)
+
+    trackCacheEntry(cacheDir, cacheName)
+    return cached
+  }
+
+  private static async handleGstatic(path: string) {
+    const gstaticPath = path.slice('/_gf/gstatic/'.length)
+
+    // Refused before `this.cacheDir` is read, so a rejection costs neither a
+    // config lookup nor a path resolution.
+    if (
+      gstaticPath.length > GF_MAX_GSTATIC_PATH ||
+      !GF_GSTATIC_PATH.test(gstaticPath)
+    ) {
+      return response.error('Unknown Google Fonts asset', 404)
+    }
+
+    const cacheDir = fs.resolve(this.cacheDir, 'gstatic')
+    const cacheExt = `${fs.parse(gstaticPath).ext || '.bin'}`
+    const cacheName = `${toHash(gstaticPath)}${cacheExt}`
+
+    const cached = await fs.getOrCreateCachedFile(
+      cacheDir,
+      cacheName,
+      null,
+      async () => {
+        const gfUrl = `https://fonts.gstatic.com/${gstaticPath}`
+        const res = await fetch(gfUrl)
+
+        if (!res.ok) return null
+
+        return res.arrayBuffer()
+      },
+    )
+
+    if (!cached) {
+      return response.error('Failed to fetch Google Fonts asset', 502)
+    }
+
+    trackCacheEntry(cacheDir, cacheName)
+    return cached
+  }
+}