@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/utils/http/authorize.ts

@@ -4,13 +4,13 @@
  * One implementation, deliberately in core, for the same reason
  * `credential.ts` is here: the dashboard, db-explorer and analytics plugins
  * each need this guard, and per-plugin copies of security code drift. These
- * three had already drifted — one coerced its predicate's return with
+ * three had already drifted: one coerced its predicate's return with
  * `Boolean`, one gated on `!DEV` where the others read `PROD`, one swallowed a
  * `getClientIp` throw into an empty string and carried on. Each divergence is
  * resolved below toward the fail-closed reading, and each is marked as a
  * decision rather than left to look like a style choice.
  *
- * It owns *only* the predicate — no logins, no sessions, no backoff. The shared
+ * It owns *only* the predicate: no logins, no sessions, no backoff. The shared
  * key path is `credential.ts`; a plugin that offers both doors composes them.
  *
  * `getClientIp` is imported from `./ip` directly, never through this
@@ -37,7 +37,7 @@ export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
  * `'localhost'` used to be a member, back when the request's *hostname* was
  * compared against this set as well. A peer address is never the string
  * `localhost`, and accepting it meant `X-Forwarded-For: localhost` counted as
- * loopback under `trustProxy` — and, worse, that `new URL(req.url).hostname`
+ * loopback under `trustProxy`, and, worse, that `new URL(req.url).hostname`
  * did too. Bun builds that from the client's own `Host` header and
  * `DEFAULT_HOST` is 0.0.0.0, so any peer on the LAN could send
  * `Host: localhost` and be handed a database browser.
@@ -51,7 +51,7 @@ export function isLoopback(req: Request): boolean {
   // DECISION (divergence 3): a throw returns `false` immediately rather than
   // falling through with `ip = ''`. `getClientIp` reads config and the live
   // server, either of which may be absent (tests, early boot). The two spell
-  // the same answer today, because `LOOPBACK.has('')` is false — but only by
+  // the same answer today, because `LOOPBACK.has('')` is false, but only by
   // coincidence, and the fall-through invites a later edit that adds a second
   // source of evidence below this line and silently consults it on the
   // indeterminate path. Returning here says the answer is settled: no address
@@ -71,31 +71,38 @@ export function isLoopback(req: Request): boolean {
  */
 export function defaultAuthorize(req: Request): boolean {
   // DECISION (divergence 2): gate on `PROD`, not `!DEV`, and read it at call
-  // time — the mode flags are accessors on `process.env` (`core/init.ts`), so
+  // time. The mode flags are accessors on `process.env` (`core/init.ts`), so
   // they are process state and tests flip them.
   //
   // The two spellings look interchangeable because `init.ts` derives them as
   // complements (`PROD = !isDev && !--dev-worker`). They are not, because they
   // are *independently settable* accessors and the test fixtures set them one
-  // at a time: `asDev` flips `DEV` alone and leaves the ambient `PROD` — which
-  // under `bun test` is `true` — in place. In that state `!DEV` admits a
+  // at a time: `asDev` flips `DEV` alone and leaves the ambient `PROD` (which
+  // under `bun test` is `true`) in place. In that state `!DEV` admits a
   // loopback caller and `PROD` denies, so `PROD` is both the fail-closed
   // reading and the one that literally names the condition it means, rather
   // than inferring production from the absence of development.
   //
-  // Hence `!== false` rather than a plain truthiness test, which is the one
-  // place a bare `PROD` gate would be *weaker* than `!DEV`. The flag does not
-  // exist until `core/init.ts` has run, and `if (undefined)` falls straight
-  // through to the loopback check — so an uninitialised process would open the
-  // door that an initialised production one keeps shut. `init.ts` defines
-  // `PROD` as a real boolean (`accessor(!isDev && !hasDevWorkerArg)`), so
-  // "explicitly false" is a statement only a booted development server can
-  // make. Unset is not evidence of development; it is no evidence at all.
+  // Hence a test for the *positive* development marker rather than a truthiness
+  // test on `PROD`, which is the one place a bare `PROD` gate would be weaker
+  // than `!DEV`. The flags do not exist until `core/init.ts` has run, and
+  // `if (undefined)` falls straight through to the loopback check, so an
+  // uninitialized process would open the door an initialized production one
+  // keeps shut. Unset is not evidence of development; it is no evidence at all.
+  //
+  // This read `PROD !== false` while the flags were real booleans. Bun 1.4
+  // rejects accessor descriptors on `process.env`, so they are `'1'`/`''`
+  // strings now (see `core/init.ts`), and `!== false` is true for *every*
+  // string, including the `''` a development server sets, so the gate would
+  // have denied on loopback in development while still looking correct.
+  // `DEV === '1'` is the same statement in the encoding that survives: only a
+  // booted development server sets it, and production (`''`) and never-booted
+  // (`undefined`) both fail it.
   //
   // `isLoopback` would very likely deny on its own there, having no config or
   // server to read an address from. That is a second line of defence, not this
   // one's excuse: a guard should not depend on another guard's failure mode.
-  if (import.meta.env.PROD !== false) return false
+  if (import.meta.env.DEV !== '1') return false
   return isLoopback(req)
 }
 
@@ -116,7 +123,7 @@ export async function isAuthorized(
   try {
     // DECISION (divergence 1): `=== true`, never `Boolean(...)`. The predicate
     // comes from application code and `AuthorizeFn`'s return type is only
-    // advice — an untyped, transpiled or `as any` predicate can hand back
+    // advice: an untyped, transpiled or `as any` predicate can hand back
     // anything. `Boolean` admits every truthy non-boolean, so a check that
     // answers with a status string denies on `""` and *grants* on `"no"`, and
     // one that answers with a count grants on any non-zero. Admission is the

package/src/utils/http/cors.ts

@@ -1,8 +1,8 @@
 /**
  * Cross-origin resource sharing.
  *
- * Bakery already ships the pieces of an API server — `ApiHandler`, sessions,
- * CSRF, rate limiting — and had no way to serve one to a browser on another
+ * Bakery already ships the pieces of an API server (`ApiHandler`, sessions,
+ * CSRF, rate limiting), and had no way to serve one to a browser on another
  * origin. This is that.
  *
  * Two halves, and both are needed: a preflight `OPTIONS` has to be answered
@@ -22,8 +22,8 @@ export interface CorsOptions {
   /**
    * Origins allowed to read responses.
    *
-   * `'*'` is honoured literally, and is refused in combination with
-   * `credentials` — see `resolveOrigin`. A function receives the request's
+   * `'*'` is honored literally, and is refused in combination with
+   * `credentials`. See `resolveOrigin`. A function receives the request's
    * `Origin` and returns the value to echo, or `null` to deny.
    */
   origin: string | string[] | ((origin: string) => string | null)
@@ -45,7 +45,7 @@ const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
  * The value for `Access-Control-Allow-Origin`, or `null` to send nothing.
  *
  * **`'*'` with credentials is refused rather than silently downgraded.** The
- * browser rejects that pairing anyway, so honouring it would produce a request
+ * browser rejects that pairing anyway, so honoring it would produce a request
  * that fails in the client with a CORS error and a server that believes it
  * allowed the call. Echoing the origin instead would be a *quiet widening* of
  * what the app asked for. Returning null makes the misconfiguration visible as
@@ -97,7 +97,7 @@ export function corsHeaders(
 /**
  * The response to a preflight, or `null` if this is not one.
  *
- * A preflight is `OPTIONS` *with* `Access-Control-Request-Method` — plain
+ * A preflight is `OPTIONS` *with* `Access-Control-Request-Method`: plain
  * `OPTIONS` is a normal request and must fall through to routing, or an app
  * with its own OPTIONS route would find it shadowed.
  *

package/src/utils/http/credential.ts

@@ -4,14 +4,14 @@
  *
  * One implementation, deliberately in core: the db-explorer and analytics
  * plugins each need it and per-plugin copies of security code drift. It owns
- * *only* the comparison — no logins, no sessions, no backoff.
+ * *only* the comparison: no logins, no sessions, no backoff.
  *
  * A credential is presented three ways, in this order of preference:
  *
  *   - `x-<name>` header (scriptable, never logged by default)
  *   - `Authorization: Bearer <credential>`
  *   - `?<name>=<credential>` query, for a human opening a URL in a browser
- *     who cannot set a header — the caller is expected to strip it from the
+ *     who cannot set a header. The caller is expected to strip it from the
  *     URL client-side; it *does* reach server logs, which is documented, and
  *     the header forms exist for anything automated.
  *
@@ -20,7 +20,7 @@
  * variable unset must mean "off", not "open".
  *
  * The compare is constant-time. A plain `===` on a secret is a timing oracle,
- * and `timingSafeEqual` costs one line — but it throws on length mismatch, so
+ * and `timingSafeEqual` costs one line, but it throws on length mismatch, so
  * the length is checked first (which leaks only the length, never the bytes).
  */
 
@@ -41,7 +41,7 @@ export function credentialMatches(
 /**
  * Pull a presented credential off a request: the `x-<name>` header, a Bearer
  * token, or the `<name>` query parameter, in that order. Returns `null` when
- * none is present. `name` is the header/query key — `db-key`, `analytics-key`.
+ * none is present. `name` is the header/query key: `db-key`, `analytics-key`.
  */
 export function readCredential(req: Request, name: string): string | null {
   const header = req.headers.get(`x-${name}`)

package/src/utils/http/csrf.ts

@@ -2,7 +2,7 @@
  * 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 —
+ * 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.
  */
@@ -17,7 +17,7 @@ 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
+ * 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 {
@@ -46,7 +46,7 @@ export function checkCsrf(req: Request, url: URL): string | null {
 /**
  * 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
+ * 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.
@@ -57,14 +57,13 @@ function safeEcho(value: string): string {
 }
 
 /**
- * Origin guard for WebSocket upgrades — deliberately stricter than
+ * 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
+ * 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.
@@ -89,7 +88,7 @@ function safeEcho(value: string): string {
  *
  * 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
+ * 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

package/src/utils/http/dom.ts

@@ -7,7 +7,7 @@ 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
+// 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)
 
@@ -22,12 +22,12 @@ let depMap = ''
 const hostDepMaps = new Map<string, string>()
 
 /**
- * Normalise one import-map entry, for both the process-level map and the
+ * Normalize one import-map entry, for both the process-level map and the
  * per-host maps.
  *
  * One helper, two callers, deliberately: they used to be separate copies that
- * had drifted into testing different things — one switched on the entry key,
- * the other on the entry value — so the same input normalised two ways
+ * had drifted into testing different things (one switched on the entry key,
+ * the other on the entry value), so the same input normalized two ways
  * depending on which path saw it.
  *
  * `@client/utils` is keyed on the *key*: it is a live alias, the default
@@ -75,12 +75,12 @@ let installedCache: Promise<string[]> | null = null
  *
  * Read from `node_modules` rather than from `dependencies`, and the difference
  * is the whole point: a package can be installed and imported without being
- * declared — a transitive one, or a dependency someone forgot to add — and the
+ * declared (a transitive one, or a dependency someone forgot to add), and the
  * browser's failure for a specifier the map misses names its own rule rather
  * than the missing entry: *"Failed to resolve module specifier 'pkg'. Relative
  * references must start with either "/", "./", or "../"."*
  *
- * Cheap — one `readdir` per scope, no `package.json` reads — and memoised per
+ * Cheap: one `readdir` per scope, no `package.json` reads, and memoized per
  * process besides: the import map reads it at boot, `bundleModule` on every
  * bundle (as its `external` list), and a `readdir` sweep per bundle is pure
  * waste. A dev restart is a new process, so an install still shows up.
@@ -122,7 +122,7 @@ async function readInstalledPackages(): Promise<string[]> {
  *
  * **Resolution happens at the other end of the URL, and rewriting happens
  * nowhere.** An entry maps a package to `/_nm/<name>`; `NMHandler` hands that to
- * `Bun.build`, which applies real browser resolution — `exports` maps,
+ * `Bun.build`, which applies real browser resolution: `exports` maps,
  * conditions, the `browser` field. Naming an entry file here instead would mean
  * reimplementing all of that, badly.
  *
@@ -168,7 +168,7 @@ export namespace DOMTools {
 
     // 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
+    // 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>`
   }
@@ -190,7 +190,7 @@ export namespace DOMTools {
   }
 
   /**
-   * ResponseInit carrying `data`'s status and headers, minus Content-Length —
+   * 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.

package/src/utils/http/etag.ts

@@ -17,7 +17,7 @@ export namespace ETag {
     return `W/"${hash.toString(36)}"`
   }
 
-  /** The one writer of the file-etag format — `fromFile` and the negotiation
+  /** 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 {
@@ -78,8 +78,8 @@ export namespace ETag {
 
   /**
    * 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
+   * 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
@@ -92,7 +92,7 @@ export namespace ETag {
    *
    * 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
+   * 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.
    */
@@ -102,8 +102,7 @@ export namespace ETag {
   /**
    * 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`.
+   * 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.
    */
@@ -119,7 +118,7 @@ export namespace ETag {
 
   /**
    * Test seam (convention 9): lets etag.test.ts count sibling probes without
-   * module-mocking `bun` or `node:fs` — which is process-global and never
+   * 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) {
@@ -136,7 +135,7 @@ export namespace ETag {
     negotiationMemo.clear()
   }
 
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: content negotiation — one branch per encoding outcome
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: content negotiation, one branch per encoding outcome
   function negotiateFile(file: Bun.BunFile, req?: Request) {
     const fileName = file.name || 'file'
 
@@ -174,7 +173,7 @@ export namespace ETag {
       )
 
       // 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
+      // 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
@@ -231,13 +230,55 @@ export namespace ETag {
       if (conditionalRes) return conditionalRes
     }
 
+    // Range handling itself lives in Bun.serve, not here: any Response whose
+    // body is a *path-backed* BunFile is sliced by the runtime (206 with
+    // Content-Range on a satisfiable single range, 416 past EOF), including
+    // the negotiated compressed variants above (the range then addresses the
+    // encoded bytes, which is what RFC 9110 says a range means). What the
+    // runtime does not do is advertise: a plain 200 or a HEAD said nothing,
+    // so players that probe HEAD for `Accept-Ranges` before attempting seeks
+    // never tried. Advertised here because this is the one funnel every
+    // file-serving handler's BunFile passes through, and only here: an
+    // in-memory Blob or a `sendText` string body ignores Range entirely
+    // (served whole, 200), which is why `.name` gates the claim.
+    //
+    // Skipped when Bun's own range path is about to answer (a GET carrying a
+    // single-range `Range`): that path appends its own `Accept-Ranges: bytes`
+    // to the 206/416, and setting it here too emitted `bytes, bytes`.
+    //
+    // A **multipart** range (`bytes=0-1,10-11`) is carved back out of the
+    // skip: Bun does not do multipart (it serves the whole file as a 200 and
+    // appends nothing), so the skip left that response advertising nothing at
+    // all, which reads as "ranges not supported" to the one client that just
+    // demonstrated it wants them. Found by a downstream smoke test. The comma
+    // is the entire multipart grammar, so this cannot drift from Bun's own
+    // parse the way a real Range parser here could; RFC-legal multipart gets
+    // the 200-with-advertisement it deserves. What stays excluded-and-silent
+    // is a *malformed* single range (`Range: potato`), also served whole by
+    // Bun, but that requester sent garbage, and mirroring Bun's full validity
+    // judgment here is exactly the second-parser drift this comment refuses.
+    // HEAD ignores `Range` and gets the header even when one is present.
+    const rangeValue = req?.headers.get('range')
+    if (
+      resolvedFile.name &&
+      !(
+        req &&
+        req.method === 'GET' &&
+        rangeValue !== null &&
+        rangeValue !== undefined &&
+        !rangeValue.includes(',')
+      )
+    ) {
+      headers['Accept-Ranges'] = 'bytes'
+    }
+
     return new Response(resolvedFile, { headers })
   }
 
   /**
-   * Returns synchronously on every path that does not compress — no request,
+   * 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
+   * 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.
    */
@@ -265,7 +306,7 @@ export namespace ETag {
       'Content-Type': type,
     }
 
-    // Negotiation only — no compression yet. The ext suffix the etag embeds
+    // 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.
@@ -302,7 +343,7 @@ export namespace ETag {
 
       // 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
+      // 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(

package/src/utils/http/html.ts

@@ -4,7 +4,16 @@ import { Try } from '../common/try'
 import { DOMTools, headBodyCache } from './dom'
 import { ETag } from './etag'
 
-function injectBrand(res: Response) {
+/**
+ * Mark `res` as already carrying the head/body injects, so `injectIfHtml` ( * and therefore `processResponse`, which every response funnels through)  * hands it back untouched.
+ *
+ * Exported for the one caller that means "never", not "already":
+ * `DefaultErrorHandler` brands its production error page so the import map is
+ * not spliced into it. That map names every installed package (an inventory
+ * of the app's module layout), and the page carries no scripts for it (or the
+ * client bundle) to serve anyway.
+ */
+export function injectBrand(res: Response) {
   return Object.defineProperty(res, '__injected__', {
     value: true,
     enumerable: false,
@@ -19,7 +28,7 @@ function isInjected(res: Response) {
  * Rebuild `res` with `status`, carrying the injection brand across.
  *
  * `Response.status` is read-only, so changing it means constructing a new
- * Response — and a plain rebuild silently drops the `__injected__` marker,
+ * Response, and a plain rebuild silently drops the `__injected__` marker,
  * which is the only thing stopping `processResponse` running the page through
  * `injectIfHtml` a second time and emitting two import maps and two copies of
  * the client bundle. That is why this lives next to the brand rather than at
@@ -40,7 +49,7 @@ export function withStatus(res: Response, status: number): Response {
 /**
  * Server-controlled markup injected into the document. Deliberately a separate
  * argument from `params`: `params` is request-derived (for GET it is the query
- * string), so `$$head`-style keys arriving from a client must never be honoured.
+ * string), so `$$head`-style keys arriving from a client must never be honored.
  */
 export interface HtmlInjects {
   head?: string
@@ -73,7 +82,7 @@ export interface HtmlInjects {
  *                                       have sent
  *
  * Buffered responses carry a strong content ETag for the 304 machinery.
- * Streamed responses carry none — see `streamedResponse` for why that is not
+ * Streamed responses carry none. See `streamedResponse` for why that is not
  * faked.
  */
 export const STREAM_THRESHOLD_BYTES = 64 * 1024
@@ -85,7 +94,7 @@ export async function injectIfHtml(
 ): Promise<Response | null> {
   if (data instanceof Response && isInjected(data)) return data
 
-  // {{param}} substitution (and only that — the __PAGE_PARAMS__ script is a
+  // {{param}} substitution (and only that: the __PAGE_PARAMS__ script is a
   // head fragment either way) needs the whole document in one string, so a
   // params-bearing call takes the buffered path regardless of size.
   const hasParams = !!params && Object.keys(params).length > 0
@@ -123,7 +132,7 @@ export async function injectIfHtml(
   return bufferedResponse(content, params, injects, responseInit)
 }
 
-/** The one writer of the buffered injection Response — main path and the
+/** The one writer of the buffered injection Response: main path and the
  * streamed path's fallback both come through here. */
 function bufferedResponse(
   content: string,
@@ -178,7 +187,7 @@ function getConfigInjects() {
 /**
  * The final head/body fragments for one document: config injects + the
  * __PAGE_PARAMS__ script + per-call injects, with `<!--prio-->` resolved.
- * Computed once per response, up front — the streamed path must not defer this
+ * Computed once per response, up front: the streamed path must not defer this
  * into a pull callback, where the AsyncLocalStorage host context that
  * `getConfigInjects` and `DOMTools.importMap` read may no longer be live.
  */
@@ -227,7 +236,7 @@ function spliceBodyEnd(html: string, body: string): string {
  * each window and the final carry. */
 function rewriteFontsUrls(html: string): string {
   // Both alternatives in RX_GFONTS require the literal `fonts.goog`, so this
-  // substring check cannot skip a document the regex would have matched — and
+  // substring check cannot skip a document the regex would have matched, and
   // most documents have no Google Fonts link at all.
   if (!html.includes('fonts.goog')) return html
   return html.replace(RX_GFONTS, () => GFONTS_REWRITE)
@@ -261,8 +270,8 @@ export function assembleHtml(
 // The exact same three rewrites as `assembleHtml`, in the same order, without
 // holding the document in memory. The head splice happens on a bounded probe
 // (the tag is near the start of any real document) using the same
-// `spliceHead`; the body-end insert and the fonts rewrite — the two passes
-// that force a scan to the end of the document — run as chunk-boundary-safe
+// `spliceHead`; the body-end insert and the fonts rewrite (the two passes
+// that force a scan to the end of the document) run as chunk-boundary-safe
 // text stages over the same regexes. Content inserted by the body stage flows
 // through the fonts stage but not back through the body stage, which is
 // exactly the buffered path's head → body → fonts ordering.
@@ -272,7 +281,7 @@ export function assembleHtml(
  * that can be left dangling at a chunk boundary. */
 const BODY_END_HOLDBACK = '</body>'.length - 1
 
-/** Longest text RX_GFONTS can match, minus one — any incomplete match prefix
+/** Longest text RX_GFONTS can match, minus one: any incomplete match prefix
  * at a window edge is at most this long, so holding back this many characters
  * guarantees no match is ever split across two windows. */
 const FONTS_HOLDBACK = 'https://fonts.googleapis.com/css2'.length - 1
@@ -281,7 +290,7 @@ const FONTS_HOLDBACK = 'https://fonts.googleapis.com/css2'.length - 1
  * Read the response body until either EOF or enough bytes to commit to
  * streaming. Streaming needs two things the probe establishes: proof the body
  * is actually large (unless Content-Length already said so), and a `<head…>`
- * match — the no-head fallback prepends to the very start of the document,
+ * match, the no-head fallback prepends to the very start of the document,
  * which a stream that has begun emitting can no longer do. Anything that fails
  * those checks is drained and handed to the buffered path, whose output is the
  * long-standing behavior.
@@ -367,7 +376,7 @@ async function* tailText(
     }
   } finally {
     // Reached on normal EOF (no-op) and when the consumer cancels the response
-    // mid-stream — in which case the source must be cancelled too.
+    // mid-stream: in which case the source must be canceled too.
     await Try(() => reader.cancel())
   }
 }
@@ -382,9 +391,9 @@ async function* withPrefix(
 
 /**
  * Streaming equivalent of `spliceBodyEnd`: insert before the first literal
- * `</body>` (in original casing — the insert slices around the match rather
+ * `</body>` (in original casing, the insert slices around the match rather
  * than reconstructing it), else append at the very end. Once inserted the
- * stage is a passthrough, so content it inserted is never rescanned — matching
+ * stage is a passthrough, so content it inserted is never rescanned: matching
  * the buffered path's single non-global replace.
  */
 async function* bodyEndStage(
@@ -424,7 +433,7 @@ async function* bodyEndStage(
 /**
  * Streaming equivalent of `rewriteFontsUrls`. Complete matches that start in
  * the emittable region are rewritten (a complete match cannot be invalidated
- * or extended by later input — the pattern has no unbounded or trailing
+ * or extended by later input: the pattern has no unbounded or trailing
  * parts); matches or match prefixes inside the holdback stay in the carry for
  * the next window, and the final carry goes through the shared
  * `rewriteFontsUrls` itself.
@@ -452,7 +461,7 @@ async function* fontsStage(
 
     // The same fast gate the buffered path uses: no `fonts.goog` in the
     // window means no match in it, and the emit/carry split below does not
-    // depend on match presence — a match *prefix* dangling at the window edge
+    // depend on match presence, a match *prefix* dangling at the window edge
     // sits inside the holdback either way.
     if (window.includes('fonts.goog')) {
       rx.lastIndex = 0
@@ -477,8 +486,8 @@ async function* fontsStage(
 /**
  * Wrap the staged text into a streaming Response.
  *
- * Deliberately no ETag: a content hash would require buffering the body — the
- * thing this path exists to avoid — and deriving one from anything less (say,
+ * Deliberately no ETag: a content hash would require buffering the body (the
+ * thing this path exists to avoid), and deriving one from anything less (say,
  * source file size+mtime) would keep serving 304s after the config-injected
  * head/body fragments change. Large streamed pages are also where conditional
  * revalidation matters least. Callers relying on the 304 machinery get it on
@@ -494,7 +503,7 @@ function streamedResponse(
   // Buffered responses get `Cache-Control: no-cache` from ETag.sendResponse
   // (guarded the same way: only when the handler set nothing itself). With no
   // ETag that hook never fires here, and a validator-less page left without a
-  // cache policy is open to heuristic caching — a stale page, not just a
+  // cache policy is open to heuristic caching: a stale page, not just a
   // missed 304.
   if (!headers.has('Cache-Control')) {
     headers.set('Cache-Control', 'no-cache')

package/src/utils/http/ip.ts

@@ -15,7 +15,7 @@ const TRUSTED_HEADERS = [
 export function getClientIp(req: Request): string {
   // `Bakery.config`, not `getConfig()`: this runs inside the request's host
   // store, and the process config is the wrong answer under `hosts`. It was
-  // the only reader of the two that disagreed — `getHostname` and the
+  // the only reader of the two that disagreed: `getHostname` and the
   // session's `Secure` flag both read the host's `trustProxy`, so one host
   // could have its hostname and cookie resolved from its own config while
   // its client IP was resolved from the base one.