@bakery-framework/core 1.0.0

package/src/handlers/assets/image.ts

@@ -0,0 +1,136 @@
+import { Bakery } from '../../core'
+import { hostKey } from '../../core/bakery'
+import { errorMsg } from '../../logger'
+import { Math2 } from '../../utils/common'
+import { FileSystem as fs } from '../../utils/fs'
+import { response } from '../../utils/http'
+import { Handler, type Route } from '../core/$base'
+import { getStatic } from '../core/$static'
+
+const IS_IMAGE_REGEX = /(.*)\/(.*)(;(\d+))?\.(png|jpg|jpeg|webp|gif|bmp)$/i
+const IMAGE_CAPTURE = /^(.+?)([^/;.]+)(?:;(\d+))?\.([a-zA-Z0-9]+)$/i
+
+export class ImageHandler extends Handler {
+  static maxImageSize = 4096
+
+  static canHandle(path: string): boolean {
+    return IS_IMAGE_REGEX.test(path)
+  }
+
+  private static async lookUpImage(path: string) {
+    const key = hostKey(path)
+    if (!this.cache.has(key)) return
+
+    const cached = this.cache.get(key) as Route.Info
+    const parsed = await this.path(path)
+
+    if (parsed) {
+      const sourceFile = Bun.file(parsed.source)
+      const sourceMtime = sourceFile.lastModified
+      const cachedMtime = cached.file.lastModified
+
+      if (sourceMtime && cachedMtime && sourceMtime > cachedMtime) {
+        this.cache.delete(key)
+        return
+      }
+    }
+
+    if (fs.exists(cached.file)) return cached
+
+    this.cache.delete(key)
+  }
+
+  private static clampSize(size: number) {
+    return Math2.clamp(Math2.step(size, 32), 16, this.maxImageSize)
+  }
+
+  private static async path(path: string) {
+    const match = path.match(IMAGE_CAPTURE)
+    if (!match) return
+
+    const [_, dir, name, sizeStr, ext] = match
+    const size = sizeStr ? parseInt(sizeStr, 10) : null
+    const rel = `${dir.slice(1)}/${name}.${ext}`
+
+    // This handler outranks PublicHandler, so the containment and `.forbidden`
+    // checks must still apply — otherwise a protected image under public/ is
+    // served anyway, despite PublicHandler correctly refusing it. getStatic
+    // carries those checks so all the file-serving handlers share one spelling.
+    const resolved = await getStatic(`/${rel}`, [
+      Bakery.serveRoot,
+      Bakery.publicRoot,
+    ])
+
+    if (!resolved) return
+
+    const source = resolved.file
+
+    return { dir, name, size, ext, source }
+  }
+
+  static async handle(path: string) {
+    try {
+      const routeInfo = await this.lookUpImage(path)
+      if (routeInfo) return routeInfo.file
+
+      const parsed = await this.path(path)
+      if (!parsed) return response.error('Not Found')
+
+      const { size: sizeStr, source } = parsed
+      const size = sizeStr ? this.clampSize(sizeStr) : null
+
+      const sourceFile = Bun.file(source)
+      const sourceTime = sourceFile.lastModified
+
+      if (!sourceTime) return response.error('Not Found')
+
+      const cacheDir = fs.resolve(Bakery.cacheDir, 'images')
+      // Key on the resolved source, not the request path. The path carries the
+      // caller's raw `;NNN` size suffix *before* clamping, so `;16`, `;17`, `;18`…
+      // each produced a distinct id and re-encoded the whole source to WebP —
+      // an unbounded cache and unbounded CPU from one image URL.
+      const imageCacheId = Bun.hash(hostKey(source)).toString(36)
+
+      await fs.mkdir(cacheDir)
+
+      const masterPath = fs.resolve(cacheDir, `${imageCacheId}-main.webp`)
+
+      let masterFile = Bun.file(masterPath)
+      const masterMtime = masterFile.lastModified
+
+      if (!fs.exists(masterFile) || masterMtime < sourceTime) {
+        const imgObj = sourceFile.image()
+        await imgObj.webp({ quality: 80 }).write(masterPath)
+        masterFile = Bun.file(masterPath)
+      }
+
+      if (!size) return masterFile
+
+      const cachePath = fs.resolve(cacheDir, `${imageCacheId}-${size}.webp`)
+      let cacheFile = Bun.file(cachePath)
+      const cacheMtime = cacheFile.lastModified
+
+      if (!fs.exists(cacheFile) || cacheMtime < masterMtime) {
+        const imgObj = masterFile.image()
+        const meta = await imgObj.metadata()
+
+        const w = meta.width
+        const h = meta.height
+
+        const targetSize = Math.min(size, this.maxImageSize)
+        const shortest = Math.min(w, h)
+
+        const scale = Math.min(targetSize / shortest, 1)
+
+        const targetW = Math.round(w * scale)
+        const targetH = Math.round(h * scale)
+
+        await imgObj.resize(targetW, targetH).write(cachePath)
+        cacheFile = Bun.file(cachePath)
+      }
+      return cacheFile
+    } catch (e) {
+      return response.error(`Unexpected error: ${errorMsg(e)}`, 500)
+    }
+  }
+}

package/src/handlers/assets/nm.ts

@@ -0,0 +1,73 @@
+import { bundleModule } from '../../compiler'
+import { Bakery } from '../../core/bakery'
+import { toHash } from '../../utils/common'
+import { fs } from '../../utils/fs'
+import { Handler } from '../core/$base'
+
+export class NMHandler extends Handler {
+  static get cacheDir() {
+    return fs.resolve(Bakery.cacheDir, 'nm_cache')
+  }
+
+  static canHandle(path: string) {
+    return path.startsWith('/_nm/')
+  }
+
+  /**
+   * Serve a browser-ready bundle of a file inside `node_modules`.
+   *
+   * **Why this does not call `getStatic`.** `getStatic` is the single writer of
+   * the containment + `.forbidden` pair, and three of the four handlers its doc
+   * comment names now go through it. This one cannot, and the reason is not
+   * the root (it takes a `roots` argument) — it is that `getStatic` answers
+   * "is there a plain file literally at this path", and `/_nm/` deliberately
+   * asks a different question. The entry here goes to `Bun.build`, which does
+   * Node resolution: `/_nm/pkg/sub` resolves to `pkg/sub/index.js`, and that is
+   * precisely what the import map's `"<pkg>/": "/_nm/<pkg>/"` prefix entry
+   * (`utils/http/dom.ts`) produces for an extensionless subpath import.
+   * `getStatic` returns `null` for that path — it is a directory — so routing
+   * through it would turn every extensionless subpath import into a 204.
+   * `nm.test.ts` pins both halves of that divergence.
+   *
+   * What *was* missing is the second half of the pair. Containment was spelled
+   * out here and was correct, but `.forbidden` was never checked, so `/_nm/*`
+   * was the one file-serving surface an operator could not pull offline with a
+   * marker file. Both checks are below, in `getStatic`'s order and with its
+   * semantics, against the `node_modules` root.
+   *
+   * The `.forbidden` walk has to happen *before* the cache lookup, not after:
+   * `getOrCreateCachedFile` answers from `.cache/nm_cache` without touching the
+   * source tree, so a marker dropped on an already-served package would
+   * otherwise be invisible until the cache was cleared.
+   */
+  static async handle(path: string) {
+    const nmPath = path.replace(/^\/_nm\//, 'node_modules/')
+    const nmRoot = fs.resolve(Bakery.root, 'node_modules')
+    const nodeModulesPath = fs.resolve(Bakery.root, nmPath)
+
+    // Strictly below the root, so `node_modules` itself is not an entry point.
+    // `getStatic` admits `file === root` and then rejects it as a directory;
+    // here the same answer has to come from the containment test, because
+    // nothing downstream stats the path.
+    if (!nodeModulesPath.startsWith(`${nmRoot}/`)) return undefined
+    if (fs.isForbidden(nodeModulesPath, nmRoot)) return undefined
+
+    const nmFile = Bun.file(nodeModulesPath)
+    const sourceMtime = fs.exists(nmFile) ? nmFile.lastModified : null
+
+    const cacheId = toHash(nmPath)
+    const cacheName = `${cacheId}.js`
+
+    const cached = await fs.getOrCreateCachedFile(
+      this.cacheDir,
+      cacheName,
+      sourceMtime,
+      async () => {
+        const module = await bundleModule(nodeModulesPath)
+        return module.success && module.content ? module.content : null
+      },
+    )
+
+    return cached || undefined
+  }
+}

package/src/handlers/assets/public.ts

@@ -0,0 +1,17 @@
+import { Bakery } from '../../core/bakery'
+import { response } from '../../utils/http'
+import { Handler } from '../core/$base'
+import { getStatic } from '../core/$static'
+
+export class PublicHandler extends Handler {
+  static canHandle(path: string) {
+    return path.startsWith('/uploads/')
+  }
+
+  static async handle(path: string) {
+    const resolved = await getStatic(path, Bakery.publicRoot)
+    if (!resolved) return response.error('Not Found')
+
+    return Bun.file(resolved.file)
+  }
+}

package/src/handlers/assets/static.ts

@@ -0,0 +1,86 @@
+import { Bakery, hostKey } from '../../core/bakery'
+import { matchBlockedCached } from '../../core/context'
+import { toHash } from '../../utils'
+import { fs } from '../../utils/fs'
+import { response } from '../../utils/http'
+import { Handler } from '../core/$base'
+import { ErrorHandler } from '../core/$error'
+import { getStatic } from '../core/$static'
+
+export class StaticHandler extends Handler {
+  static canHandle(): boolean {
+    return true
+  }
+
+  static get cacheDir() {
+    return fs.resolve(Bakery.cacheDir, 'static')
+  }
+
+  static async handle(path: string) {
+    // The router already ran this for every file-serving handler, but this
+    // check must stay: direct callers (tests, embedders) reach `handle`
+    // without the router gate. `matchBlockedCached` makes the overlap cost a
+    // per-request map hit rather than a second pair of glob matches.
+    // One read of the config getter: `blocked` and the serve root come from
+    // the same snapshot — getStatic's default `roots` would re-read it.
+    const cfg = Bakery.config
+    if (matchBlockedCached(cfg.blocked, path)) {
+      return response.error('Forbidden', 403)
+    }
+
+    const resolved = await getStatic(path, cfg.root)
+    if (!resolved) return response.error('Not Found')
+
+    const file = Bun.file(resolved.file)
+    const ext = fs.parse(path).ext
+
+    if (fs.isCompressible(ext)) {
+      const cacheName = `${toHash(hostKey(path))}${ext}`
+      const cached = await fs.getOrCreateCachedFile(
+        this.cacheDir,
+        cacheName,
+        file.lastModified,
+        () => file.arrayBuffer(),
+      )
+
+      if (cached) return cached
+    }
+
+    return file
+  }
+}
+
+export class DefaultErrorHandler extends ErrorHandler {
+  /**
+   * This is the fallback for every path with no more specific error handler,
+   * so it renders through the inherited `publicBody` like the rest of the
+   * error surface — `errorBody` carries the thrown error's stack (that is
+   * what the log wants), and handing it to the client verbatim gave any
+   * anonymous request source paths and query text in PROD.
+   */
+  static handle(_path: string, req: Request, error?: Handler.Error.Data) {
+    const ip = Bakery.server?.requestIP(req)?.address || 'Unknown'
+    const date = new Date().toDateString()
+
+    error ||= this.DEFAULT_ERROR
+
+    const errorPage = `
+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <title>Error ${error.errorCode} | Bakery 🚀</title>
+        </head>
+        <body style="margin: 2rem; font-family: sans-serif;">
+          <h1>${Bun.escapeHTML(`${error.errorCode} - ${error.errorText}`)}</h1>
+          <pre>${Bun.escapeHTML(this.publicBody(error))}</pre>
+          <hr />
+          <small>${Bun.escapeHTML(date)} - ${Bun.escapeHTML(ip)}</small>
+        </body>
+      </html>
+    `
+
+    return response.html(errorPage, error.errorCode)
+  }
+}

package/src/handlers/assets/ts.ts

@@ -0,0 +1,61 @@
+import { compile } from '../../compiler'
+import { Bakery, hostKey } from '../../core/bakery'
+import { toHash } from '../../utils/common'
+import { fs } from '../../utils/fs'
+import { response } from '../../utils/http'
+import { DynamicHandler } from '../core/$dynamic'
+
+const normalizePath = (path: string) =>
+  path.endsWith('.js') ? path.slice(0, -3) : path
+
+export class TSHandler extends DynamicHandler {
+  static get config() {
+    return {
+      ext: ['ts'],
+      dir: Bakery.serveRoot,
+    }
+  }
+
+  static get cacheDir() {
+    return fs.resolve(Bakery.cacheDir, 'ts_cache')
+  }
+
+  static async canHandle(path: string, req: Request) {
+    if (path.endsWith('.ts')) return true
+    return await super.canHandle(normalizePath(path), req)
+  }
+
+  static async handle(path: string) {
+    const info = await this.resolveRoute(normalizePath(path))
+    if (!info) return response.error('Not Found')
+
+    const file = info.file
+    const id = toHash(hostKey(info.path))
+    const cacheName = `${id}.js`
+    const fileOrig = fs.resolve(this.config.dir, info.path)
+
+    const cached = await fs.getOrCreateCachedFile(
+      this.cacheDir,
+      cacheName,
+      file.lastModified,
+      () => this.compileRoute(fileOrig),
+    )
+
+    // 500, not the default 404: the route exists, the server failed to build
+    // it, and a 404 sends the developer hunting for a missing file.
+    //
+    // The route is named because this branch was unreachable until
+    // `compileText` stopped throwing past it, and a nameless "Compilation
+    // Failed" is only half an answer: the diagnostic — file, line, column,
+    // source line — goes to the log as `compLog.COMPILE_FAIL`, and the two
+    // have to be joinable. Naming it discloses nothing a client did not
+    // already send: `info.path` is what it asked for. In production
+    // `publicBody` replaces the whole 5xx body anyway.
+    return cached || response.error(`Compilation Failed: ${info.path}`, 500)
+  }
+
+  /** Compile seam — ts.test.ts substitutes it to exercise the failure branch. */
+  static compileRoute(file: fs.AbsolutePath): Promise<string | null> {
+    return compile(file)
+  }
+}

package/src/handlers/assets/tsx.ts

@@ -0,0 +1,106 @@
+import { Bakery } from '../../core/bakery'
+import { isSafeHtml } from '../../core/jsx'
+import { is, jsonResponse } from '../../utils/common'
+import { fs } from '../../utils/fs'
+import { injectIfHtml, response } from '../../utils/http'
+import type { Handler } from '../core/$base'
+import { bustInDev, DynamicHandler } from '../core/$dynamic'
+import {
+  beginPageRoute,
+  DynamicErrorHandler,
+  markDevFile,
+  publicErrorData,
+} from '../core/$error'
+
+export class TSXHandler extends DynamicHandler {
+  static get config() {
+    return {
+      ext: ['tsx'],
+      dir: Bakery.serveRoot,
+    }
+  }
+
+  static handle = sharedHandler
+
+  static executeModule(file: fs.AbsolutePath, req: Request, body: any) {
+    return super.executeModule(bustInDev(file), req, body)
+  }
+}
+
+export class TSXErrorHandler extends DynamicErrorHandler {
+  static get config() {
+    return {
+      ext: ['tsx'],
+      dir: Bakery.serveRoot,
+      include: ['**/error.tsx', '**/error-*.tsx'],
+    }
+  }
+
+  static handle = sharedHandler
+
+  static executeModule(file: fs.AbsolutePath, req: Request, body: any) {
+    return super.executeModule(bustInDev(file), req, body)
+  }
+}
+
+//
+//
+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 filePath = info.path
+
+  const modulePath = fs.resolve(Bakery.serveRoot, filePath)
+  const params = info.getParams(path) || {}
+  markDevFile(params, filePath)
+  // Redacted before it becomes page data — see `publicErrorData`. The params
+  // are both substituted into the render and injected as `__PAGE_PARAMS__`.
+  // `errorData` is undefined for an ordinary page; Object.assign ignores that.
+  const finalParams = Object.assign(
+    {},
+    params,
+    errorData && publicErrorData(errorData),
+  )
+  const body = await this.params(req, finalParams)
+
+  const returned = await this.executeModule(modulePath, req, body)
+  if (returned === null) return response.error('Not Found')
+
+  // `createElement` returns `raw()` → a SafeHtml, which is a String
+  // *subclass*, so `is.object` (typeof === 'object') is true for it and an
+  // unwrapped JSX page got JSON-encoded instead of served as HTML. Unbox it
+  // here rather than widening `is.object`: `is.object([]) === true` is a
+  // deliberate decision that router.ts depends on.
+  const resData = isSafeHtml(returned) ? String(returned) : returned
+
+  const code = errorData?.errorCode || 200
+  if (is.object(resData)) {
+    return resData instanceof Response
+      ? resData
+      : jsonResponse(code, 'Success', resData)
+  }
+
+  const [hasTs, hasCss] = await Promise.all([
+    fs.exists(modulePath.replace(/\.tsx$/, '.ts')),
+    fs.exists(modulePath.replace(/\.tsx$/, '.css')),
+  ])
+
+  const style = filePath.replace(/\.tsx$/, '.css')
+  const tsUrl = filePath.replace(/\.tsx$/, '.js')
+
+  const html = await injectIfHtml(resData, params, {
+    body: hasTs ? `<script src="/${tsUrl}" type="module"></script>` : '',
+    head: hasCss ? `<link rel="stylesheet" href="/${style}">` : '',
+  })
+  if (html) return html
+
+  return is.string(resData)
+    ? response.text(resData)
+    : response.error('Not Found')
+}

package/src/handlers/assets/virtual-asset.ts

@@ -0,0 +1,104 @@
+import { Strings } from '../../cache/string'
+import { bundleModule } from '../../compiler'
+import { Bakery } from '../../core/bakery'
+import { frameworkPath } from '../../core/paths'
+import type { MapOf } from '../../types'
+import { toHash } from '../../utils'
+import { FileSystem as fs } from '../../utils/fs'
+import { Handler } from '../core/$base'
+
+export class VirtualAssetHandler extends Handler {
+  static canHandle(path: string) {
+    if (!import.meta.env.DEV && path === '/_client/livereload.js') return false
+    return path.startsWith('/_client/') || path.startsWith('/_virtual/')
+  }
+
+  static get cacheDir() {
+    return fs.resolve(Bakery.cacheDir, 'virtual')
+  }
+
+  static get clientAssets(): MapOf<string> {
+    // frameworkPath, not Bakery.root: these ship with the framework, so they
+    // must resolve relative to it rather than to the application's cwd.
+    const assets: MapOf<string> = {
+      '/_client/utils.js': frameworkPath('client/utils.ts'),
+    }
+    if (import.meta.env.DEV) {
+      assets['/_client/livereload.js'] = frameworkPath('client/livereload.ts')
+    }
+    return assets
+  }
+
+  static async handleClientAsset(path: string) {
+    const masterPath = this.clientAssets[path]
+    if (!masterPath) return null
+
+    const masterFile = Bun.file(masterPath)
+    if (!fs.exists(masterFile)) return null
+
+    const parsed = fs.parse(masterPath)
+    const fileId = `client-${parsed.name}.js`
+
+    const cachedFile = await fs.getOrCreateCachedFile(
+      this.cacheDir,
+      fileId,
+      masterFile.lastModified,
+      async function bundleClient() {
+        // Bundled, not merely transpiled: these are browser entry points, and
+        // the browser cannot resolve the relative imports a transpile leaves
+        // behind — they resolve against the page URL, return the HTML
+        // fallback, and fail strict MIME checking for module scripts.
+        const built = await bundleModule(masterPath as fs.AbsolutePath)
+        return built.success && built.content ? built.content : null
+      },
+    )
+
+    if (!cachedFile) return null
+
+    const routeInfo = new Handler.Route.Info(cachedFile.name!, path.slice(1))
+
+    this.cache.set(path, routeInfo)
+    return routeInfo
+  }
+
+  static async handleVirtualAsset(path: string) {
+    const id = path.slice('/_virtual/'.length)
+    const resolvedPath = Strings.getValue(id)
+    if (!resolvedPath) return null
+
+    const assetFile = Bun.file(resolvedPath)
+    if (!fs.exists(assetFile)) return null
+
+    const ext = fs.parse(resolvedPath).ext
+    const cacheName = `${toHash(resolvedPath)}${ext}`
+
+    const cachedFile = await fs.getOrCreateCachedFile(
+      this.cacheDir,
+      cacheName,
+      assetFile.lastModified,
+      async function getVirtualAsset() {
+        return assetFile.arrayBuffer()
+      },
+    )
+
+    if (!cachedFile) return null
+
+    const routeInfo = new Handler.Route.Info(cachedFile.name!, path.slice(1))
+
+    this.cache.set(path, routeInfo)
+    return routeInfo
+  }
+
+  static async getRouteInfo(path: string) {
+    if (path.startsWith('/_client/')) return await this.handleClientAsset(path)
+    if (path.startsWith('/_virtual/'))
+      return await this.handleVirtualAsset(path)
+  }
+
+  static async handle(path: string) {
+    const route = this.cache.get(path)
+    if (route?.valid) return route.file
+
+    return (await this.getRouteInfo(path))?.file
+  }
+}