@bakery-framework/core 1.0.0

package/src/utils/http/csrf.ts

@@ -0,0 +1,111 @@
+/**
+ * Cross-site request forgery guards.
+ *
+ * A `SameSite=Lax` cookie is still sent on top-level cross-site *navigations*,
+ * so it is not on its own sufficient to protect a state-changing endpoint —
+ * `<a href="/api/admin/delete?id=5">` or a cross-origin `<form>` POST both
+ * arrive with the victim's session attached.
+ */
+
+import { Try } from '../isomorphic/try'
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/** `Sec-Fetch-Site` values that mean the request did not come from another site. */
+const SAME_SITE_VALUES = new Set(['same-origin', 'same-site', 'none'])
+
+/**
+ * Returns a reason string when the request looks cross-site, or `null` when it
+ * is safe to process. Requests with neither `Origin` nor `Sec-Fetch-Site` (curl,
+ * server-to-server, older clients) are allowed — browsers always send at least
+ * one of them on a cross-origin request.
+ */
+export function checkSameOrigin(req: Request, url: URL): string | null {
+  const fetchSite = req.headers.get('sec-fetch-site')
+  if (fetchSite && !SAME_SITE_VALUES.has(fetchSite)) {
+    return `cross-site request rejected (Sec-Fetch-Site: ${fetchSite})`
+  }
+
+  const origin = req.headers.get('origin')
+  if (origin && origin !== 'null' && origin !== url.origin) {
+    return `cross-origin request rejected (Origin: ${origin})`
+  }
+
+  return null
+}
+
+/**
+ * Guard for endpoints that may change state. Safe methods pass through; unsafe
+ * ones must be same-origin.
+ */
+export function checkCsrf(req: Request, url: URL): string | null {
+  if (SAFE_METHODS.has(req.method)) return null
+  return checkSameOrigin(req, url)
+}
+
+/**
+ * An attacker-supplied header value, made safe to put in a reason string.
+ *
+ * Reason strings are logged, and the logger renders one record per line — so
+ * an `Origin` carrying a newline could forge additional log entries. Anything
+ * outside printable ASCII goes, and the result is capped: a rejection reason
+ * is a diagnostic, not a transcript.
+ */
+function safeEcho(value: string): string {
+  const clean = value.replace(/[^\x20-\x7e]/g, '')
+  return clean.length > 128 ? `${clean.slice(0, 128)}...` : clean
+}
+
+/**
+ * Origin guard for WebSocket upgrades — deliberately stricter than
+ * `checkSameOrigin`, and applied in `upgradeWebsocket` so every socket
+ * inherits it rather than each handler having to remember.
+ *
+ * WebSockets are exempt from the same-origin policy. Any page the developer
+ * visits can open `ws://localhost:3000/_livereload`, and until this existed
+ * one `{"type":"subscribe_logger"}` bought a live feed of the server log —
+ * failing SQL, table and column names, absolute source paths — plus the
+ * ability to reload every open browser. The only thing that separates the
+ * app's own page from an attacker's is `Origin`, which the browser sets on
+ * every handshake and page script cannot override.
+ *
+ * Three deliberate differences from `checkSameOrigin`:
+ *
+ * - **`Origin: null` is rejected.** That is what a sandboxed iframe, a `data:`
+ *   URL and a `file://` page send, so treating it as "no origin" would hand
+ *   the socket straight back to `<iframe sandbox srcdoc="...">` on the
+ *   attacker's page. It falls out of the parse below: `new URL('null')`
+ *   throws, and an unparseable origin fails closed.
+ * - **`Sec-Fetch-Site` is not consulted.** Browsers do not send it on the
+ *   handshake, so a value that *is* present came from a non-browser client
+ *   and is worth nothing.
+ * - **Hostnames are compared, not full origins.** A TLS-terminating reverse
+ *   proxy leaves the request looking like `http://app.example:3000` while the
+ *   browser reports `https://app.example`; comparing origins would refuse
+ *   every socket in that (very ordinary) deployment. The residual is an
+ *   attacker who already controls another port or scheme on the *same*
+ *   hostname, which is a different and much smaller threat than "any website
+ *   the developer visits".
+ *
+ * An **absent** `Origin` is allowed, and that is a decision rather than an
+ * oversight. A browser never omits it on a handshake, so its absence means the
+ * peer is not a browser — curl, a test, a CLI, a health check. Such a client
+ * can also set `Origin` to whatever it likes, so refusing the absent case buys
+ * no security at all while breaking every non-browser client. This check is
+ * worth exactly what a browser's inability to forge the header is worth, and
+ * handlers that need more (`/_analytics_ws` is the in-repo example) still
+ * authenticate in their own `canHandle`.
+ */
+export function checkWebSocketOrigin(req: Request, url: URL): string | null {
+  const origin = req.headers.get('origin')
+  if (!origin) return null
+
+  const rejected = `cross-origin WebSocket upgrade rejected (Origin: ${safeEcho(origin)})`
+
+  const parsed = Try(() => new URL(origin))
+  if (!parsed) return rejected
+
+  return parsed.hostname.toLowerCase() === url.hostname.toLowerCase()
+    ? null
+    : rejected
+}

package/src/utils/http/dom.ts

@@ -0,0 +1,238 @@
+import { LRUCache } from '../../cache/lru'
+import { Bakery, hostStore } from '../../core/bakery'
+import type { MapOf } from '../../types'
+import { is } from '../common/misc'
+import { Try } from '../common/try'
+import { fs } from '../fs'
+import { escapeScriptJson } from '../isomorphic/escape'
+
+// Keyed by hostname, which comes from the Host header — bounded so a client
+// cannot grow it without limit by varying that header per request.
+const headBodyCache = new LRUCache<string, { head: string; body: string }>(64)
+
+export function clearHeadBodyCache() {
+  headBodyCache.clear()
+}
+
+export { headBodyCache }
+
+type PackageJson = {
+  name: string
+  version: string
+  main?: string
+  module?: string
+  browser?: string | MapOf<string>
+  dependencies?: MapOf<string>
+  devDependencies?: MapOf<string>
+}
+
+let depMap = ''
+
+const hostDepMaps = new Map<string, string>()
+
+/**
+ * Normalise one import-map entry, for both the process-level map and the
+ * per-host maps.
+ *
+ * There used to be two copies of this, and they had drifted into disagreeing
+ * about *what* they tested: `initHostImportMaps` switched on the entry key,
+ * `initImportMap` tested the entry value. `{ foo: './.server/client/utils' }`
+ * was rewritten by one path and silently left alone by the other. One helper,
+ * two callers, so they cannot disagree again.
+ *
+ * The `.server/client/utils` special cases both copies carried are gone rather
+ * than reconciled. `.server/` is the pre-split layout: those two string
+ * literals were the last references to it anywhere in `packages`, `apps`,
+ * `docs` or `tests`, and the directory they name no longer exists, so a value
+ * pointing at it is a broken path either way. It normalises as an ordinary
+ * relative specifier now.
+ *
+ * `@client/utils` stays, and stays keyed on the *key*: it is a live alias — it
+ * is the default `importMap` entry in `core/config.ts` — and the browser
+ * runtime is served from a fixed URL, so the target is not the app's to choose.
+ */
+function normalizeImportEntry(key: string, value: unknown): [string, string] {
+  const cleanKey = key.replace(/\*$/, '')
+  const cleanVal = String(value).replace(/\*$/, '')
+
+  if (cleanKey === '@client/utils') return [cleanKey, '/_client/utils.js']
+
+  return [
+    cleanKey,
+    cleanVal.replace(/^\.(?=\/)/, '').replace(/^(?!(?:\/|https?:\/\/))/, '/'),
+  ]
+}
+
+export function initHostImportMaps() {
+  hostDepMaps.clear()
+  clearHeadBodyCache()
+  const hosts = Bakery.config.hosts
+  if (!hosts || !Object.keys(hosts).length) return
+
+  const base = JSON.parse(depMap)
+  const npmImports = base.imports || {}
+
+  for (const [hostname, entry] of Object.entries(hosts)) {
+    if (!entry.importMap) continue
+
+    const imports: Record<string, string> = { ...npmImports }
+    for (const [k, v] of Object.entries(entry.importMap)) {
+      const [key, value] = normalizeImportEntry(k, v)
+      imports[key] = value
+    }
+
+    hostDepMaps.set(hostname, JSON.stringify({ imports }))
+  }
+}
+
+function resolveDepModule(pkgData: PackageJson, baseMod: string): string {
+  if (is.string(pkgData.browser)) return pkgData.browser as string
+
+  if (is.object(pkgData.browser)) {
+    const cleanBase = baseMod.replace(/^\.\//, '')
+    const browserField = pkgData.browser as MapOf<string>
+    const lookupKeys = [baseMod, `./${cleanBase}`, cleanBase]
+    const matchedOverride = lookupKeys.find(key => browserField[key])
+
+    return matchedOverride ? browserField[matchedOverride] : baseMod
+  }
+
+  return baseMod
+}
+
+export async function initImportMap() {
+  const pkgContent = await Try(() =>
+    Bun.file(fs.resolve(fs.cwd, 'package.json')).json(),
+  )
+  const pkg: any = pkgContent || {}
+  const map = Bakery.config.importMap || {}
+  const deps = pkg.dependencies || {}
+
+  const resolvedMap: MapOf<string> = {}
+
+  const imports = await Promise.all(
+    Object.keys(deps).map(async dep => {
+      const pkgData = await Try(
+        Bun.file(`./node_modules/${dep}/package.json`).json(),
+      )
+
+      return { dep, pkgData: pkgData as PackageJson | null }
+    }),
+  )
+
+  for (const { dep, pkgData } of imports) {
+    if (!pkgData) continue
+
+    const actualName = pkgData.name || dep
+    resolvedMap[`${actualName}/`] = `/_nm/${actualName}/`
+
+    const baseMod = pkgData.module || pkgData.main || 'index.js'
+    const mod = resolveDepModule(pkgData, baseMod)
+
+    const finalMod = typeof mod === 'string' ? mod : 'index.js'
+    resolvedMap[actualName] =
+      `/_nm/${actualName}/${finalMod.replace(/^\.\//, '')}`
+  }
+
+  for (const [k, v] of Object.entries(map)) {
+    const [key, value] = normalizeImportEntry(k, v)
+    resolvedMap[key] = value
+  }
+
+  depMap = JSON.stringify({ imports: resolvedMap })
+}
+
+export namespace DOMTools {
+  export function importMap() {
+    const hostname = hostStore.getStore()?.hostname
+    const map = (hostname && hostDepMaps.get(hostname)) || depMap
+    return `<script type="importmap">${map}</script>`
+  }
+
+  export function params(params: MapOf<string>) {
+    const newParams: MapOf<string> = {}
+
+    for (const [k, v] of Object.entries(params)) {
+      if (k.startsWith('$$')) continue
+      newParams[k] = v
+    }
+
+    // Was a hand-rolled `JSON.stringify(...).replace(/</g, ...)`, which is the
+    // same job `escapeScriptJson` already does for every other inline-script
+    // payload — its docstring even said "Mirrors utils/http/dom.ts". The two
+    // had drifted: this copy never escaped U+2028/U+2029.
+    return `<script>window.__PAGE_PARAMS__ = ${escapeScriptJson(newParams)}</script>`
+  }
+
+  type HTMLContent = {
+    content: string
+    responseInit: ResponseInit & { headers?: any }
+  }
+
+  const RX_IS_HTML = /<[a-z/][\s\S]*>/i
+  const RX_IS_SVG_XML = /^\s*<(\?xml|svg|math)/i
+
+  /** Content types `injectIfHtml` treats as an HTML document. */
+  export function isHTMLContentType(contentType: string): boolean {
+    return (
+      contentType.startsWith('text/html') ||
+      contentType.startsWith('application/xhtml+xml')
+    )
+  }
+
+  /**
+   * ResponseInit carrying `data`'s status and headers, minus Content-Length —
+   * injection changes the body length, so a stale value must not survive into
+   * the rebuilt Response. Shared by the buffered and streamed injection paths
+   * so the two cannot drift on which headers survive.
+   */
+  export function htmlResponseInit(
+    data: Response,
+  ): ResponseInit & { headers: Headers } {
+    const headers = new Headers(data.headers)
+    headers.delete('content-length')
+    return { status: data.status, statusText: data.statusText, headers }
+  }
+
+  async function checkBlobHtml(data: Blob): Promise<string> {
+    const type = data.type || ''
+    const isHtml = isHTMLContentType(type)
+
+    return isHtml ? await data.text() : ''
+  }
+
+  async function checkResponseHtml(
+    data: Response,
+  ): Promise<{ html: string; init: ResponseInit }> {
+    const contentType = data.headers.get('content-type') || ''
+
+    if (!isHTMLContentType(contentType)) return { html: '', init: {} }
+
+    return {
+      html: await data.text(),
+      init: htmlResponseInit(data),
+    }
+  }
+
+  export async function isHTML(
+    data: string | Response | Blob,
+  ): Promise<HTMLContent> {
+    if (is.string(data)) {
+      const sample = (data as string).slice(0, 512)
+      const isHtml = RX_IS_HTML.test(sample) && !RX_IS_SVG_XML.test(sample)
+      return { content: isHtml ? (data as string) : '', responseInit: {} }
+    }
+
+    if (data instanceof Blob) {
+      const html = await checkBlobHtml(data as Blob)
+      return { content: html, responseInit: {} }
+    }
+
+    if (data instanceof Response) {
+      const res = await checkResponseHtml(data as Response)
+      return { content: res.html, responseInit: res.init }
+    }
+
+    return { content: '', responseInit: {} }
+  }
+}

package/src/utils/http/escape.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-facing path for the escaping primitives.
+ *
+ * The implementation lives in `utils/isomorphic/escape` because the browser
+ * bundle needs it too; server code imports it from here (or from `@server/utils`)
+ * so callers don't have to know which side of that boundary it sits on.
+ */
+export { escapeHtml, escapeScriptJson } from '../isomorphic/escape'

package/src/utils/http/etag.ts

@@ -0,0 +1,318 @@
+import { LRUCache } from '../../cache/lru'
+import type { MapOf, MixedPromise } from '../../types'
+import { ASYNC_COMPRESSION_MIN, COMPRESSION_MAP, fs } from '../fs'
+
+export namespace ETag {
+  function tag(response: Response): Response {
+    ;(response as any).__notModified__ = true
+    return response
+  }
+
+  export function isNotModified(response: Response): boolean {
+    return !!(response as any).__notModified__
+  }
+
+  export function fromText(content: string | Uint8Array): string {
+    const hash = Bun.hash(content)
+    return `W/"${hash.toString(36)}"`
+  }
+
+  /** The one writer of the file-etag format — `fromFile` and the negotiation
+   * memo below must agree byte-for-byte, or a warm hit would break every
+   * `If-None-Match` a cold response handed out. */
+  function fileTag(size: number, mtime: number): string {
+    return `W/"${size.toString(36)}-${(mtime || 0).toString(36)}"`
+  }
+
+  export function fromFile(file: Bun.BunFile): string {
+    return fileTag(file.size, file.lastModified)
+  }
+
+  export function check(req: Request, etag: string): Response | null {
+    const ifNoneMatch = req.headers.get('if-none-match')
+    if (ifNoneMatch) {
+      const clientEtags = ifNoneMatch
+        .split(',')
+        .map(s => s.trim().replace(/^W\//, ''))
+      const cleanEtag = etag.replace(/^W\//, '')
+
+      if (clientEtags.includes(cleanEtag) || clientEtags.includes('*')) {
+        return tag(
+          new Response(null, {
+            status: 304,
+            headers: {
+              ETag: etag,
+              'Cache-Control': 'no-cache',
+            },
+          }),
+        )
+      }
+    }
+    return null
+  }
+
+  export function sendResponse(req: Request, response: Response): Response {
+    const etag = response.headers.get('ETag')
+    if (!etag) return response
+
+    // getSetCookie() keeps each cookie separate. `.get()` joins them with ", ",
+    // which then gets written back as one malformed header.
+    const cookies = response.headers.getSetCookie()
+    response = isNotModified(response) ? response : check(req, etag) || response
+
+    if (!response.headers.has('Cache-Control')) {
+      response.headers.set('Cache-Control', 'no-cache')
+    }
+
+    if (cookies.length && !response.headers.has('Set-Cookie')) {
+      for (const cookie of cookies) {
+        response.headers.append('Set-Cookie', cookie)
+      }
+    }
+
+    return response
+  }
+
+  type VariantStat = { size: number; mtime: number }
+  type VariantRecord = { encoding: string; ext: string } & VariantStat
+
+  /**
+   * Per-base-path record of which compressed siblings exist, anchored on the
+   * base file's mtime. `getOrCreateCachedFile` — the only writer of these
+   * files — writes the raw file and every variant together in one
+   * `Promise.all`, so the base mtime changes whenever the variant set does;
+   * that makes the mtime the invalidation signal, and no write-side hook is
+   * needed (fs.ts stays unaware of this module, keeping the dependency arrow
+   * fs ← etag one-way).
+   *
+   * An `LRUCache`, not a Map: base paths derive from request paths via the
+   * hostKey'd cache names, and an unbounded map keyed on client-derived input
+   * is what convention 6 forbids. 512 entries covers the working set of
+   * distinct cached assets at ~100 bytes each.
+   *
+   * Only *complete* variant sets are recorded. A partial set means either a
+   * build caught mid-write (the trio lands over a few ms) or user-authored
+   * precompressed siblings next to a served `.gz` — in both cases the set can
+   * change without the base mtime moving, so those fall back to per-request
+   * probing, which is exactly the pre-memo behavior.
+   */
+  type NegotiationEntry = { mtime: number; variants: VariantRecord[] }
+  const negotiationMemo = new LRUCache<string, NegotiationEntry>(512)
+
+  /**
+   * One stat, and the values are kept rather than discarded: a `BunFile`
+   * caches its stat on first property access (~66us fresh, ~40ns after), so
+   * routing the probe through `fs.exists` — which stats a throwaway instance —
+   * made every served variant pay a second, identical stat in `fromFile`.
+   * Same existence predicate as `fs.exists`; note a missing file reports
+   * size 0 and a far-future sentinel `lastModified`, never 0.
+   */
+  function statVariant(path: string): VariantStat | null {
+    const file = Bun.file(path)
+    const mtime = file.lastModified
+    const size = file.size
+    if ((mtime && mtime < Date.now()) || size > 0) return { size, mtime }
+    return null
+  }
+
+  let probeVariant: (path: string) => VariantStat | null = statVariant
+
+  /**
+   * Test seam (convention 9): lets etag.test.ts count sibling probes without
+   * module-mocking `bun` or `node:fs` — which is process-global and never
+   * unwinds. Same shape as `fs.__setForbiddenProbe`.
+   */
+  export function __setVariantProbe(fn: (path: string) => VariantStat | null) {
+    probeVariant = fn
+  }
+
+  export function __resetVariantProbe() {
+    probeVariant = statVariant
+  }
+
+  /** Test seam: the memo is process-global and mtime-keyed, so tests that
+   * rebuild fixtures at the same path must start from a clean slate. */
+  export function __clearNegotiationMemo() {
+    negotiationMemo.clear()
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: content negotiation — one branch per encoding outcome
+  function negotiateFile(file: Bun.BunFile, req?: Request) {
+    const fileName = file.name || 'file'
+
+    const matchedExt = COMPRESSION_MAP.find(c => fileName.endsWith(c.ext))?.ext
+
+    if (!req || !matchedExt) {
+      return {
+        resolvedFile: file,
+        fileHeaders: {} as MapOf<any>,
+        etag: undefined as string | undefined,
+      }
+    }
+
+    const basePath = fileName.slice(0, -matchedExt.length)
+    const ext = basePath.split('.').pop() || ''
+    const acceptEncoding = req.headers.get('Accept-Encoding') || ''
+
+    const fileHeaders: MapOf<any> = {
+      'Content-Type': fs.getMimeType(ext),
+      'Cache-Control': 'no-cache',
+    }
+
+    const baseFile = Bun.file(basePath)
+    let resolvedFile = baseFile
+    let etag: string | undefined
+
+    if (fs.isCompressible(ext)) {
+      // The freshness anchor, and the only stat this function performs on a
+      // warm hit. The instance doubles as the identity-path `resolvedFile`,
+      // so `fromFile` in `sendFile` reads the same cached stat rather than
+      // paying a second one.
+      const baseMtime = baseFile.lastModified
+      const baseExists = Boolean(
+        (baseMtime && baseMtime < Date.now()) || baseFile.size > 0,
+      )
+
+      // The memo is consulted only for a base that exists right now, and only
+      // when its recorded mtime matches the anchor exactly — a wiped cache
+      // dir (missing base reports the far-future sentinel mtime) or any
+      // rewrite falls through to a fresh probe.
+      let entry = baseExists ? negotiationMemo.get(basePath) : undefined
+      if (entry && entry.mtime !== baseMtime) {
+        entry = undefined
+      }
+
+      if (!entry) {
+        const variants: VariantRecord[] = []
+        for (const { encoding, ext: compExt } of COMPRESSION_MAP) {
+          const stat = probeVariant(`${basePath}${compExt}`)
+          if (stat) variants.push({ encoding, ext: compExt, ...stat })
+        }
+        entry = { mtime: baseMtime, variants }
+        if (baseExists && variants.length === COMPRESSION_MAP.length) {
+          negotiationMemo.set(basePath, entry)
+        } else {
+          // A deleted base (cache-dir wipe) or a partial set: drop any stale
+          // record so nothing ever resolves to a remembered variant whose
+          // files are gone.
+          negotiationMemo.delete(basePath)
+        }
+      }
+
+      // `variants` is in COMPRESSION_MAP order, so client preference
+      // resolution is unchanged from the probe loop it replaces.
+      for (const variant of entry.variants) {
+        if (acceptEncoding.includes(variant.encoding)) {
+          resolvedFile = Bun.file(`${basePath}${variant.ext}`)
+          fileHeaders['Content-Encoding'] = variant.encoding
+          etag = fileTag(variant.size, variant.mtime)
+          break
+        }
+      }
+    }
+
+    return { resolvedFile, fileHeaders, etag }
+  }
+
+  export function sendFile(file: Bun.BunFile, req?: Request): Response {
+    const {
+      resolvedFile,
+      fileHeaders,
+      etag: negotiated,
+    } = negotiateFile(file, req)
+
+    const headers: MapOf<any> = fileHeaders
+
+    const etag = negotiated || ETag.fromFile(resolvedFile)
+    headers.ETag = etag
+
+    if (req) {
+      const conditionalRes = ETag.check(req, etag)
+      if (conditionalRes) return conditionalRes
+    }
+
+    return new Response(resolvedFile, { headers })
+  }
+
+  /**
+   * Returns synchronously on every path that does not compress — no request,
+   * small body, unsupported Accept-Encoding, and crucially the 304
+   * short-circuit — and returns a Promise only when compression actually
+   * runs on a body large enough to offload (`ASYNC_COMPRESSION_MIN`). The
+   * one call site that can receive either (`processResponse`) awaits.
+   */
+  export function sendText(
+    text: string,
+    req?: Request,
+    type = '',
+    status = 200,
+  ): MixedPromise<Response> {
+    type ||= 'text/plain; charset=utf-8'
+    if (
+      typeof status !== 'number' ||
+      Number.isNaN(status) ||
+      status < 100 ||
+      status > 599
+    ) {
+      status = 200
+    }
+
+    let appliedExt = ''
+    let encoder: ((text: string) => Uint8Array) | null = null
+    let encoderAsync: ((text: string) => Promise<Uint8Array>) | null = null
+    let encodingName = ''
+    const headers: MapOf<any> = {
+      'Content-Type': type,
+    }
+
+    // Negotiation only — no compression yet. The ext suffix the etag embeds
+    // is decided by the Accept-Encoding header alone, so the 304 check can
+    // run first: a client that already holds the body must not cost a
+    // zstd pass whose output is then thrown away.
+    if (req && text.length > 1024) {
+      const acceptEncoding = req.headers.get('Accept-Encoding') || ''
+
+      for (const {
+        encoding,
+        ext,
+        compress,
+        compressAsync,
+      } of COMPRESSION_MAP) {
+        if (acceptEncoding.includes(encoding) && compress) {
+          encoder = compress as any
+          encoderAsync = compressAsync as any
+          encodingName = encoding
+          appliedExt = ext
+          break
+        }
+      }
+    }
+
+    const baseEtag = ETag.fromText(text)
+    const finalEtag = appliedExt ? `${baseEtag}${appliedExt}` : baseEtag
+    headers.ETag = finalEtag
+
+    if (req) {
+      const conditionalRes = ETag.check(req, finalEtag)
+      if (conditionalRes) return conditionalRes
+    }
+
+    if (encoder) {
+      headers['Content-Encoding'] = encodingName
+
+      // Off the request thread for large bodies: the sync pass measured
+      // ~700us of event-loop stall per 135KB response. Below the cutoff the
+      // pool round-trip costs more than the stall it removes — numbers on
+      // `ASYNC_COMPRESSION_MIN` in fs.ts.
+      if (encoderAsync && text.length >= ASYNC_COMPRESSION_MIN) {
+        return encoderAsync(text).then(
+          payload => new Response(payload as any, { headers, status }),
+        )
+      }
+
+      return new Response(encoder(text) as any, { headers, status })
+    }
+
+    return new Response(text, { headers, status })
+  }
+}