@nifrajs/middleware 4.0.2 → 5.1.0

package/dist/token-auth.js

@@ -1,23 +1,18 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance";
 import { defineIdentityPlugin } from "@nifrajs/core/server";
-import { bearerToken, guardName } from "./_utils.js";
+import { bearerToken, guardName, installAuthGuard } from "./_utils.js";
 function createTokenAuth(config) {
-    // Per-request principal cache: verify runs once (in beforeHandle), reads are free + can't desync.
+    // Per-request principal cache: verify runs once, in the guard; reads are free and can't desync.
     const store = new WeakMap();
     const reject = () => Response.json({ ok: false, error: "unauthorized" }, {
         status: 401,
         headers: config.challenge !== undefined ? { "www-authenticate": config.challenge } : {},
     });
-    const plugin = defineIdentityPlugin(guardName(config.name), (app) => app.beforeHandle(async (c) => {
-        const token = config.extract(c.req);
+    const plugin = defineIdentityPlugin(guardName(config.name), (app) => installAuthGuard(app, config.name, config.optional, store, (header) => {
+        const token = config.extract(header);
         // Empty string is treated as "no credential" - never passed to verify.
-        const principal = token !== undefined && token !== "" ? await config.verify(token) : null;
-        if (principal !== null && principal !== undefined) {
-            store.set(c.req, principal);
-            return undefined; // authorized - continue to the handler
-        }
-        return config.optional ? undefined : reject(); // 401 short-circuits (skips the handler)
-    }));
+        return token !== undefined && token !== "" ? config.verify(token) : null;
+    }, reject));
     const instrumented = config.optional
         ? plugin
         : withRouteAssurance(plugin, {
@@ -44,7 +39,7 @@ export function bearer(options) {
     const realm = options.realm ?? "api";
     return createTokenAuth({
         name: "bearer",
-        extract: (request) => bearerToken(request.headers.get("authorization")) ?? undefined,
+        extract: (header) => bearerToken(header("authorization")) ?? undefined,
         verify: options.verify,
         optional: options.optional === true,
         challenge: `Bearer realm="${realm}"`,
@@ -88,7 +83,7 @@ export function apiKey(options) {
     const verify = "keys" in options ? staticKeyVerify(options.keys) : options.verify;
     return createTokenAuth({
         name: "apiKey",
-        extract: (request) => request.headers.get(header) ?? undefined,
+        extract: (get) => get(header) ?? undefined,
         verify,
         optional: options.optional === true,
     });

package/dist/token-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-auth.js","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"token-auth.js","sourceRoot":"","sources":["../src/token-auth.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/middleware",
-  "version": "4.0.2",
+  "version": "5.1.0",
   "description": "Composable middleware for nifra - auth, CSRF, JWT/JWKS, IP restriction, CORS, body limits, response cache, timing, and operational helpers.",
   "keywords": [
     "bun",
@@ -49,10 +49,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/schema": "4.0.2"
+    "@nifrajs/schema": "5.1.0"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^4.0.2"
+    "@nifrajs/core": "^5.1.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*",

package/src/_utils.ts

@@ -1,7 +1,13 @@
 export type MaybePromise<T> = T | Promise<T>
 
-import type { NodeResponseContext } from "@nifrajs/core/server"
-import { parseCookies as parseCoreCookies } from "@nifrajs/core/server"
+import type { AnyServer, NodeResponseContext } from "@nifrajs/core/server"
+import {
+  authenticated,
+  markAuthenticatedRequest,
+  parseCookies as parseCoreCookies,
+  rejected,
+  writableResponse,
+} from "@nifrajs/core/server"
 
 export const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"])
 
@@ -30,6 +36,47 @@ export function guardName(base: string): string {
   return `${base}#${guardInstances}`
 }
 
+/** One request header by name, or `null`: what a credential extractor reads. */
+export type HeaderGet = (name: string) => string | null
+
+/**
+ * Install a credential guard. Required, it is an `authenticate()` stage, so a request without a
+ * principal is refused before its body or query is read or validated, and before any `derive` or
+ * `beforeHandle`. Optional never refuses, so it stays a `beforeHandle` that records a principal when
+ * the request carries one.
+ */
+export function installAuthGuard<P>(
+  app: AnyServer,
+  id: string,
+  optional: boolean,
+  store: WeakMap<Request, P>,
+  verify: (header: HeaderGet) => MaybePromise<P | null | undefined>,
+  refuse: () => Response,
+): AnyServer {
+  if (optional) {
+    return app.beforeHandle(async (c: { readonly req: Request }) => {
+      const principal = await verify((name) => c.req.headers.get(name))
+      if (principal !== null && principal !== undefined) {
+        store.set(c.req, principal)
+        markAuthenticatedRequest(c.req)
+      }
+      return undefined
+    })
+  }
+  return app.authenticate({
+    id,
+    mode: "async",
+    run: async (input) => {
+      const principal = await verify((name) => input.headers.get(name))
+      if (principal === null || principal === undefined) {
+        return rejected("unauthenticated", refuse())
+      }
+      store.set(input.request, principal)
+      return authenticated(principal)
+    },
+  })
+}
+
 /** Shared with core so auth/CSRF middleware gets the allocation-light cookie scanner too. */
 export const parseCookies = parseCoreCookies
 
@@ -163,40 +210,19 @@ export async function verifyHmacSha256(
 }
 
 /**
- * Apply header mutations to a response, in place when possible. Framework-built responses
- * (`new Response`, `Response.json`) have mutable headers across every runtime - so the common path
- * mutates `res` directly and returns it, allocating nothing. Only an *immutable*-headers response
- * (`Response.redirect()`/`Response.error()`, or a proxied `fetch()` response on Node/Deno/workerd -
- * never on Bun) makes `.set`/`.append` throw; that path clones into a fresh `Headers` + `Response`,
- * exactly the old always-clone behavior. `apply` runs once either way (immutability is all-or-nothing
- * - the first mutation throws before any partial change), so a mutation chain is safe to pass.
+ * Apply header mutations to the copy of `res` this request owns (`writableResponse`): a body-bearing
+ * response with mutable headers is written in place, a body-less one (sendable any number of times,
+ * so possibly shared) or one with guarded headers is copied first. Pass the `request` being answered
+ * so a copy already made for it is reused.
  */
-export function withHeaders(res: Response, apply: (headers: Headers) => void): Response {
-  const responseHeaders = res.headers
-  const probe = "x-nifra-header-probe"
-  let previous: string | null = null
-  let mutable = true
-  try {
-    previous = responseHeaders.get(probe)
-    responseHeaders.set(probe, "1")
-    if (previous === null) responseHeaders.delete(probe)
-    else responseHeaders.set(probe, previous)
-  } catch {
-    mutable = false
-    try {
-      if (previous === null) responseHeaders.delete(probe)
-      else responseHeaders.set(probe, previous)
-    } catch {
-      // The guarded response rejected cleanup; the clone below is authoritative.
-    }
-  }
-  if (!mutable) {
-    const headers = new Headers(res.headers)
-    apply(headers)
-    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
-  }
-  apply(responseHeaders)
-  return res
+export function withHeaders(
+  res: Response,
+  apply: (headers: Headers) => void,
+  request?: Request,
+): Response {
+  const target = writableResponse(res, request)
+  apply(target.headers)
+  return target
 }
 
 /**

package/src/admission.ts

@@ -103,8 +103,10 @@ const NO_LAG: () => number = () => 0
 /**
  * Event-loop-lag sampler. By default it measures timer drift using only Web/JS runtime primitives, so
  * it works under Node ESM, Bun, Deno, and workers without a hidden CommonJS `require` fallback. An
- * injected histogram remains available for deterministic tests or a runtime-native monitor. Each read
- * returns recent mean lag and resets the sampling window.
+ * injected histogram remains available for deterministic tests or a runtime-native monitor. A read
+ * returns the mean lag of the samples taken since the previous read and starts a new window; a read
+ * with no new sample since then returns the same value again, so every request that arrives between
+ * two samples of a lagging loop sees the lag.
  */
 export function createEventLoopLagSampler(
   resolutionMs = 20,
@@ -127,11 +129,15 @@ export function createEventLoopLagSampler(
     // A metrics sampler must never keep a Node/Bun process alive by itself. Browser/Deno numeric timer
     // handles simply do not expose `unref`.
     ;(timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.()
+    let latest = 0
     return () => {
-      const mean = samples === 0 ? 0 : totalLagMs / samples
+      // An empty window is not a healthy loop: a burst of requests reads between two ticks.
+      if (samples === 0) return latest
+      const mean = totalLagMs / samples
       totalLagMs = 0
       samples = 0
-      return Number.isFinite(mean) ? mean : 0
+      latest = Number.isFinite(mean) ? mean : 0
+      return latest
     }
   }
   let histogram: LoopDelayHistogram | undefined
@@ -142,10 +148,14 @@ export function createEventLoopLagSampler(
   }
   if (histogram === undefined) return NO_LAG
   histogram.enable()
+  let latest = 0
   return () => {
     const meanNs = histogram.mean
+    // A histogram reads NaN until it records a sample after a reset: the window is still open.
+    if (!Number.isFinite(meanNs)) return latest
     histogram.reset()
-    return Number.isFinite(meanNs) ? Math.max(0, meanNs / 1e6 - resolutionMs) : 0
+    latest = Math.max(0, meanNs / 1e6 - resolutionMs)
+    return latest
   }
 }
 

package/src/basic-auth.ts

@@ -3,6 +3,7 @@ import { defineIdentityPlugin, type IdentityPlugin } from "@nifrajs/core/server"
 import {
   decodeBase64,
   guardName,
+  installAuthGuard,
   jsonError,
   type MaybePromise,
   quotedHeaderValue,
@@ -39,9 +40,9 @@ function reject(realm: string): Response {
   return jsonError(401, "unauthorized", { "www-authenticate": challenge(realm) })
 }
 
-function credentials(request: Request): { username: string; password: string } | null {
-  const header = request.headers.get("authorization")
-  if (header?.startsWith("Basic ") !== true) return null
+function credentials(header: string | null): { username: string; password: string } | null {
+  // The auth-scheme is case-insensitive (RFC 9110 section 11.1): `basic` and `BASIC` are Basic too.
+  if (header == null || header.slice(0, 6).toLowerCase() !== "basic ") return null
   const raw = decodeBase64(header.slice(6).trim())
   if (raw === null) return null
   let decoded: string
@@ -89,16 +90,17 @@ export function basicAuth<P>(
       : staticVerifier(options.username, options.password, options.principal ?? options.username)
 
   const plugin = defineIdentityPlugin(guardName("basicAuth"), (app) =>
-    app.beforeHandle(async (c: { readonly req: Request }) => {
-      const parsed = credentials(c.req)
-      const principal =
-        parsed === null ? null : await (await verifyPromise)(parsed.username, parsed.password)
-      if (principal !== null && principal !== undefined) {
-        store.set(c.req, principal)
-        return undefined
-      }
-      return optional ? undefined : reject(realm)
-    }),
+    installAuthGuard(
+      app,
+      "basicAuth",
+      optional,
+      store,
+      async (header) => {
+        const parsed = credentials(header("authorization"))
+        return parsed === null ? null : (await verifyPromise)(parsed.username, parsed.password)
+      },
+      () => reject(realm),
+    ),
   )
   const instrumented = optional
     ? plugin

package/src/cache-control.ts

@@ -11,6 +11,9 @@ export interface CacheControlOptions {
   readonly respectExisting?: boolean
 }
 
+// Named per call, so a second, differently configured instance applies instead of being deduped.
+let instances = 0
+
 /**
  * Set a `Cache-Control` header on matching responses. `value` is either a fixed directive string or a
  * function of the request (return `undefined` to leave a response untouched - e.g. cache by path).
@@ -31,7 +34,7 @@ export function cacheControl(
   const methods = new Set((options.methods ?? ["GET", "HEAD"]).map((m) => m.toUpperCase()))
   const statusOk = options.status ?? ((status: number) => status >= 200 && status < 300)
   const respectExisting = options.respectExisting !== false
-  return defineRouterPlugin("cacheControl", (app) => {
+  return defineRouterPlugin(`cacheControl#${++instances}`, (app) => {
     // A fixed directive needs nothing from the request beyond the method, so it ships as one
     // portable header hook. A dynamic directive's resolver takes a real `Request`, which only the
     // Web response walk carries - it keeps the full `onResponse` contract (and its cost).
@@ -51,7 +54,7 @@ export function cacheControl(
               if (respectExisting && res.headers.has("cache-control")) return res
               const directive = value(req)
               if (directive === undefined) return res
-              return withHeaders(res, (headers) => headers.set("cache-control", directive))
+              return withHeaders(res, (headers) => headers.set("cache-control", directive), req)
             },
           }
     return app.use(middleware)

package/src/cache.ts

@@ -1,4 +1,4 @@
-import type { Middleware } from "@nifrajs/core/server"
+import { isAuthenticatedRequest, type Middleware } from "@nifrajs/core/server"
 import { type MaybePromise, withHeaders } from "./_utils.ts"
 
 export interface CachedResponse {
@@ -66,7 +66,7 @@ export class MemoryResponseCache implements ResponseCacheStore {
 
 export interface CacheOptions {
   readonly store: ResponseCacheStore
-  /** Time to live in milliseconds. */
+  /** Maximum time to live in milliseconds; response freshness can shorten it. */
   readonly ttlMs: number
   /** Methods cached. Default `["GET", "HEAD"]`. */
   readonly methods?: readonly string[]
@@ -80,7 +80,8 @@ export interface CacheOptions {
   readonly maxBytes?: number
   /** Respect request `Cache-Control: no-cache/no-store`. Default `true`. */
   readonly respectRequestCacheControl?: boolean
-  /** Respect response `Cache-Control: private/no-store`. Default `true`. */
+  /** Respect response private/no-store/no-cache and max-age/s-maxage freshness. Default `true`.
+   * Responses requiring validation bypass this cache, which has no revalidation transport. */
   readonly respectResponseCacheControl?: boolean
   /** Cache responses with `Set-Cookie`. Default `false`. */
   readonly cacheSetCookie?: boolean
@@ -89,7 +90,9 @@ export interface CacheOptions {
    * personalized response (RFC 9111 §3.5), or it would be replayed to other users. Leave this off unless
    * the cached route is genuinely the same for every caller. */
   readonly cacheAuthenticated?: boolean
-  /** Credential headers that make a request private. Defaults to Authorization, Cookie, and x-api-key. */
+  /** Credential headers that make a request private. Defaults to Authorization, Cookie, and x-api-key.
+   * A response to a request an authentication stage accepted (or an integration marked with
+   * `markAuthenticatedRequest`) is treated as private too, whichever header carried the credential. */
   readonly authenticatedHeaders?: readonly string[]
   /** Response header for cache status. Default `"x-nifra-cache"`; set `false` to disable. */
   readonly cacheStatusHeader?: string | false
@@ -107,10 +110,30 @@ function cacheControlHas(headers: Headers, names: readonly string[]): boolean {
   const parts = value
     .toLowerCase()
     .split(",")
-    .map((part) => part.trim().split("=", 1)[0])
+    .map((part) => part.trim().split("=", 1)[0]?.trim())
   return names.some((name) => parts.includes(name))
 }
 
+function responseLifetimeMs(headers: Headers, ttlMs: number): number {
+  if (cacheControlHas(headers, ["private", "no-store", "no-cache"])) return 0
+  const directives = headers.get("cache-control")?.split(",") ?? []
+  // This is a shared cache: s-maxage takes precedence over max-age. Ambiguous freshness is stale.
+  for (const name of ["s-maxage", "max-age"]) {
+    const matches = directives.filter(
+      (part) => part.trim().split("=", 1)[0]?.trim().toLowerCase() === name,
+    )
+    if (matches.length === 0) continue
+    if (matches.length !== 1) return 0
+    const raw = matches[0]?.slice(matches[0].indexOf("=") + 1).trim() ?? ""
+    const value = raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw
+    const seconds = parseLength(value)
+    if (seconds === undefined || !Number.isFinite(seconds)) return 0
+    const age = parseLength(headers.get("age")) ?? 0
+    return Math.min(ttlMs, Math.max(0, seconds - age) * 1000)
+  }
+  return ttlMs
+}
+
 function appendVary(headers: Headers, vary: readonly string[]): void {
   if (vary.length === 0) return
   const existing = headers
@@ -257,9 +280,10 @@ function withStatusHeader(
   res: Response,
   header: string | false,
   status: "HIT" | "MISS" | "BYPASS",
+  request?: Request,
 ): Response {
   if (header === false) return res
-  return withHeaders(res, (headers) => headers.set(header, status))
+  return withHeaders(res, (headers) => headers.set(header, status), request)
 }
 
 /**
@@ -308,25 +332,33 @@ export function cache(options: CacheOptions): Middleware {
       requestKeys.set(req, key)
       const entry = await store.get(key)
       if (entry === undefined) return undefined
+      const cachedHeaders = new Headers([...entry.headers])
       // Never replay a personalized entry before route-scoped authentication runs. Public entries
       // remain eligible (and are explicitly marked by their response Cache-Control metadata).
       if (
         !cacheAuthenticated &&
         hasAuthentication(req) &&
-        !cacheControlHas(new Headers(entry.headers as Array<[string, string]>), [
-          "public",
-          "s-maxage",
-        ])
+        !cacheControlHas(cachedHeaders, ["public", "s-maxage"])
       ) {
         return undefined
       }
-      if (Date.now() >= entry.expiresAt) {
+      const lifetimeMs = respectResponseCacheControl
+        ? responseLifetimeMs(cachedHeaders, ttlMs)
+        : ttlMs
+      if (
+        lifetimeMs === 0 ||
+        Date.now() >= Math.min(entry.expiresAt, entry.storedAt + lifetimeMs)
+      ) {
         await store.delete?.(key)
         return undefined
       }
       hits.add(req)
-      const headers = new Headers([...entry.headers])
-      headers.set("age", String(Math.max(0, Math.floor((Date.now() - entry.storedAt) / 1000))))
+      const headers = cachedHeaders
+      const age = parseLength(headers.get("age")) ?? 0
+      headers.set(
+        "age",
+        String(age + Math.max(0, Math.floor((Date.now() - entry.storedAt) / 1000))),
+      )
       if (cacheStatusHeader !== false) headers.set(cacheStatusHeader, "HIT")
       return new Response(req.method === "HEAD" ? null : entry.body.slice(), {
         status: entry.status,
@@ -343,46 +375,54 @@ export function cache(options: CacheOptions): Middleware {
       if (!methods.has(req.method.toUpperCase())) return res
       if (!statusOk(res.status)) return res
       if (respectRequestCacheControl && cacheControlHas(req.headers, ["no-store"])) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
-      if (respectResponseCacheControl && cacheControlHas(res.headers, ["private", "no-store"])) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+      const lifetimeMs = respectResponseCacheControl
+        ? responseLifetimeMs(res.headers, ttlMs)
+        : ttlMs
+      if (lifetimeMs === 0) {
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       if (!cacheSetCookie && res.headers.has("set-cookie")) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       // A response-declared Vary must be represented in the lookup key. If the caller did not opt
       // those request headers into `vary`, bypass storage instead of replaying one representation to
       // another request. `Vary: *` is never cacheable by a shared cache.
       if (!responseVaryMatchesKey(res.headers, vary)) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       // Shared-cache safety (RFC 9111 §3.5): never store a response to an authenticated request
-      // (Authorization or Cookie) unless it's explicitly public - otherwise a personalized 200 leaks
-      // across users. Opt in with `cacheAuthenticated: true` for a route that's the same for everyone.
+      // unless it's explicitly public - otherwise a personalized 200 leaks across users. A credential
+      // header outside `authenticatedHeaders` is caught by the authentication stage that accepted it,
+      // because a hit is served before that stage runs. Opt in with `cacheAuthenticated: true` for a
+      // route that's the same for everyone.
       if (
         !cacheAuthenticated &&
-        hasAuthentication(req) &&
+        (hasAuthentication(req) || isAuthenticatedRequest(req)) &&
         !cacheControlHas(res.headers, ["public", "s-maxage"])
       ) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
       const declared = parseLength(res.headers.get("content-length"))
       if (declared !== undefined && declared > maxBytes) {
-        return withStatusHeader(res, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(res, cacheStatusHeader, "BYPASS", req)
       }
+      const storedAt = Date.now()
       const captured = await readBytesCapped(res, maxBytes)
       if (!("bytes" in captured)) {
-        return withStatusHeader(captured.response, cacheStatusHeader, "BYPASS")
+        return withStatusHeader(captured.response, cacheStatusHeader, "BYPASS", req)
       }
       const body = captured.bytes
       const capturedResponse = captured.response
+      const expiresAt = storedAt + lifetimeMs
+      if (Date.now() >= expiresAt) {
+        return withStatusHeader(capturedResponse, cacheStatusHeader, "BYPASS", req)
+      }
 
       const headers = new Headers(capturedResponse.headers)
-      headers.delete("age")
       if (cacheStatusHeader !== false) headers.delete(cacheStatusHeader)
       appendVary(headers, vary)
-      const now = Date.now()
       const key = requestKeys.get(req) ?? keyOf(req)
       requestKeys.delete(req)
       await store.set(key, {
@@ -390,8 +430,8 @@ export function cache(options: CacheOptions): Middleware {
         statusText: res.statusText,
         headers: [...headers.entries()],
         body,
-        expiresAt: now + ttlMs,
-        storedAt: now,
+        expiresAt,
+        storedAt,
       })
       const outgoing = new Headers(capturedResponse.headers)
       appendVary(outgoing, vary)

package/src/compression.ts

@@ -179,10 +179,90 @@ async function compressRawBody(
     },
     cancel: (reason) => reader.cancel(reason),
   })
-  return new Response(source.pipeThrough(new CompressionStream("gzip")), {
-    status: response.status,
-    statusText: response.statusText,
-    headers: gzipHeaders(response.headers),
+  const zlib = zlibModule()
+  return new Response(
+    zlib === undefined
+      ? source.pipeThrough(new CompressionStream("gzip"))
+      : syncFlushedGzip(zlib, source),
+    {
+      status: response.status,
+      statusText: response.statusText,
+      headers: gzipHeaders(response.headers),
+    },
+  )
+}
+
+interface GzipStream {
+  write(chunk: Uint8Array): boolean
+  flush(kind: number, callback: () => void): void
+  end(): void
+  destroy(): void
+  on(event: "data", listener: (chunk: Uint8Array) => void): unknown
+  once(event: "end" | "error", listener: (error?: unknown) => void): unknown
+}
+
+interface Zlib {
+  createGzip(): GzipStream
+  readonly constants: { readonly Z_SYNC_FLUSH: number }
+}
+
+const isZlib = (value: unknown): value is Zlib =>
+  typeof value === "object" &&
+  value !== null &&
+  "createGzip" in value &&
+  typeof value.createGzip === "function" &&
+  "constants" in value &&
+  typeof value.constants === "object" &&
+  value.constants !== null &&
+  "Z_SYNC_FLUSH" in value.constants
+
+let zlibLookup: { readonly zlib: Zlib | undefined } | undefined
+
+function zlibModule(): Zlib | undefined {
+  if (zlibLookup !== undefined) return zlibLookup.zlib
+  let zlib: Zlib | undefined
+  try {
+    const proc: unknown = Reflect.get(globalThis, "process")
+    const load: unknown =
+      typeof proc === "object" && proc !== null ? Reflect.get(proc, "getBuiltinModule") : undefined
+    const module: unknown = typeof load === "function" ? load.call(proc, "node:zlib") : undefined
+    if (isZlib(module)) zlib = module
+  } catch {}
+  zlibLookup = { zlib }
+  return zlib
+}
+
+/** `CompressionStream` holds deflate output until its window fills or the input closes, so a
+ * streamed shell would not reach the client until the whole page did. A sync flush after each
+ * upstream chunk emits what that chunk compressed to, at the cost of a few bytes per flush. */
+function syncFlushedGzip(
+  zlib: Zlib,
+  source: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const reader = source.getReader()
+  const gzip = zlib.createGzip()
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      gzip.on("data", (chunk) => controller.enqueue(chunk))
+      gzip.once("error", (error) => controller.error(error))
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read()
+      if (done) {
+        await new Promise((resolve) => {
+          gzip.once("end", resolve)
+          gzip.end()
+        })
+        controller.close()
+        return
+      }
+      gzip.write(value)
+      await new Promise<void>((resolve) => gzip.flush(zlib.constants.Z_SYNC_FLUSH, resolve))
+    },
+    cancel(reason) {
+      gzip.destroy()
+      return reader.cancel(reason)
+    },
   })
 }
 

package/src/conditional.ts

@@ -55,10 +55,14 @@ export function conditionalResponse(
   if (response.status < 200 || response.status >= 300) return response
   if (!isFresh(request, options)) {
     if (options.etag === undefined && modified === undefined) return response
-    return withHeaders(response, (headers) => {
-      if (options.etag !== undefined) headers.set("etag", options.etag)
-      if (modified !== undefined) headers.set("last-modified", modified)
-    })
+    return withHeaders(
+      response,
+      (headers) => {
+        if (options.etag !== undefined) headers.set("etag", options.etag)
+        if (modified !== undefined) headers.set("last-modified", modified)
+      },
+      request,
+    )
   }
   const headers = new Headers(response.headers)
   if (options.etag !== undefined) headers.set("etag", options.etag)

package/src/content-negotiation.ts

@@ -37,7 +37,9 @@ function parseMediaType(value: string, qDefault = 1): ParsedMediaType | undefine
   if (slash <= 0 || slash === media.length - 1) return undefined
   const type = media.slice(0, slash)
   const subtype = media.slice(slash + 1)
-  if (!/^[\w!#$&^_.+-]+$/.test(type) || !/^[\w!#$&^_.+*-]+$/.test(subtype)) return undefined
+  // `*/*` is the one legal type wildcard; `*/json` names no media range.
+  const typeOk = type === "*" ? subtype === "*" : /^[\w!#$&^_.+-]+$/.test(type)
+  if (!typeOk || !/^[\w!#$&^_.+*-]+$/.test(subtype)) return undefined
 
   let q = qDefault
   const parameters = new Map<string, string>()