@nifrajs/core 3.5.0 → 4.0.2

package/src/server/not-found.ts

@@ -0,0 +1,121 @@
+/**
+ * The `notFound()` handler's rules:
+ * - Only for a `404`: a wrong method stays a `405`, a malformed path a `400`, a mount's `404` its own.
+ * - It sees the request line and headers, never the body: an unrouted request has no body limit.
+ * - A method token no route could take gets the default `404`, as it skips `onRequest` hooks.
+ * - A `2xx` is sent as a `404`; a `3xx`, `410` or other error status is sent as built.
+ * - Fails closed: a throw or an unsendable value is logged and answered with the plain `500`.
+ */
+import { type ErrorLogDetail, emitRequestErrorLog } from "./bare-error-lane.ts"
+import type { Platform } from "./context.ts"
+import { plainError } from "./http.ts"
+import { INSTALL_NOT_FOUND } from "./install.ts"
+import type { Logger } from "./logger.ts"
+import {
+  answerNotFound,
+  type NotFoundHandler,
+  type NotFoundLane,
+  notFoundInput,
+} from "./not-found-answer.ts"
+import type { IdentityPlugin } from "./plugin.ts"
+import type { ResponseResult } from "./runtime-core.ts"
+import type { AnyServer, MaybePromise, RequestSource } from "./server.ts"
+
+export type { NotFoundHandler, NotFoundInput } from "./not-found-answer.ts"
+
+/** The kernel state the lane reads. Fixed at construction, so reading it per miss is three loads. */
+interface NotFoundHost {
+  readonly requestTimeoutMs: number
+  readonly logger: Logger
+  readonly errorLogDetail: ErrorLogDetail
+}
+
+/** The install seam a server exposes so the `notFound()` plugin can hand it the lane. */
+interface NotFoundInstallable {
+  [INSTALL_NOT_FOUND](lane: NotFoundLane): void
+  readonly notFoundLane?: NotFoundLane
+  readonly routePrefix: string
+}
+
+/**
+ * Answer requests no route matched with a handler of your own: `app.use(notFound(handler))`.
+ *
+ * ```ts
+ * import { notFound } from "@nifrajs/core/not-found"
+ *
+ * const app = server().use(
+ *   notFound(({ pathname }) => Response.json({ ok: false, error: "no_such_route", pathname })),
+ * )
+ * ```
+ *
+ * The answer is a `404` whatever `2xx` status the handler gives it; see the module notes for the
+ * full rules. The server's `requestTimeoutMs` bounds an async handler and aborts `input.signal`.
+ *
+ * A server takes one handler, and it belongs to the server that listens: applying `notFound()` a
+ * second time throws, and so does applying it inside a `group()` (a miss has no prefix to scope it
+ * to). A server composed into another with `merge()` does not carry its handler along.
+ */
+export function notFound<Env = unknown>(handler: NotFoundHandler<Env>): IdentityPlugin {
+  if (typeof handler !== "function") throw new TypeError("notFound() needs a handler function")
+  const lane: NotFoundLane = <T>(
+    host: unknown,
+    source: RequestSource,
+    pathname: string,
+    platform: Platform<unknown> | undefined,
+    wrap: (response: Response | ResponseResult) => T,
+    onTimeout: () => T,
+  ): MaybePromise<T> => {
+    const { requestTimeoutMs, logger, errorLogDetail } = host as NotFoundHost
+    const env = platform as Platform<Env> | undefined
+    const failed = (error: unknown): T => {
+      // A logger that throws must not decide the answer: the fault is still the plain `500`.
+      try {
+        emitRequestErrorLog(logger, errorLogDetail, error, { req: source })
+      } catch {}
+      return wrap(plainError(500, "internal_error"))
+    }
+    if (requestTimeoutMs === 0) {
+      return answerNotFound(handler, notFoundInput(source, pathname, env), wrap, failed)
+    }
+    const controller = new AbortController()
+    const answer = answerNotFound(
+      handler,
+      notFoundInput(source, pathname, env, controller.signal),
+      wrap,
+      failed,
+    )
+    if (!(answer instanceof Promise)) return answer
+    // The same bound a matched route gets: abort the signal, answer the timeout, discard the late
+    // result. Both arms are attached, so a handler that settles after the deadline is still observed.
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        controller.abort()
+        resolve(onTimeout())
+      }, requestTimeoutMs)
+      answer.then(
+        (value) => {
+          clearTimeout(timer)
+          resolve(value)
+        },
+        (error) => {
+          clearTimeout(timer)
+          reject(error)
+        },
+      )
+    })
+  }
+  const apply = <S extends AnyServer>(app: S): S => {
+    const host = app as unknown as NotFoundInstallable
+    if (host.notFoundLane !== undefined) {
+      throw new TypeError("notFound() is already applied to this server")
+    }
+    if (host.routePrefix !== "") {
+      throw new TypeError(
+        "notFound() inside a group answers nothing - apply it to the parent server",
+      )
+    }
+    host[INSTALL_NOT_FOUND](lane)
+    return app
+  }
+  return apply as IdentityPlugin
+}

package/src/server/plugin.ts

@@ -3,7 +3,9 @@
  * `use`/`derive`/`decorate` and/or registering routes) and returns it; these helpers attach a name
  * for idempotent dedupe and pin the type-threading so `.use()` preserves the caller's typed server.
  */
-import type { Registry } from "./registry.ts"
+import type { Method } from "../router/router.ts"
+import type { RouteSchema } from "./context.ts"
+import type { AddRoute, Registry, RouteInfoFor } from "./registry.ts"
 import type { AnyServer, Server } from "./server.ts"
 
 /**
@@ -62,6 +64,48 @@ export function defineContextPlugin<D extends object>(
   return Object.assign(apply, { pluginName: name }) as ContextPlugin<D>
 }
 
+declare const METHOD_ROUTES: unique symbol
+
+/**
+ * What `all()` and `method()` from `@nifrajs/core/methods` return: a plugin for `app.use()` that
+ * registers one handler under the methods `M` of `Path`. It is opaque - apply it with `use`, which
+ * reads the route's types from it and adds them to the app's registry.
+ */
+export interface MethodRoutesPlugin<
+  M extends string,
+  Path extends string,
+  S extends RouteSchema,
+  Output,
+  Ctx,
+> {
+  readonly [METHOD_ROUTES]: {
+    readonly methods: M
+    readonly path: Path
+    readonly schema: S
+    readonly output: Output
+    /** The context the handler was written against; the app must provide at least this. */
+    readonly context: (context: Ctx) => void
+  }
+}
+
+/** The standard methods among `M`, as the registry keys them. A custom token contributes none. */
+type StandardMethodOf<M extends string> = Extract<Uppercase<M>, Method>
+
+/**
+ * The registry after a {@link MethodRoutesPlugin} is applied: `Path` gains the standard methods
+ * among `M`. A method outside the standard set is served but not typed, so it adds nothing.
+ */
+export type WithMethodRoutes<
+  R extends Registry,
+  M extends string,
+  Path extends string,
+  S extends RouteSchema,
+  Output,
+  HookOutput,
+> = [StandardMethodOf<M>] extends [never]
+  ? R
+  : AddRoute<R, StandardMethodOf<M>, Path, RouteInfoFor<Path, S, Output, HookOutput>>
+
 declare const COLLAPSED: unique symbol
 
 /**

package/src/server/proto-guard.ts

@@ -28,11 +28,12 @@ export function parseJsonGuarded(text: string, policy: ProtoPoisoning): unknown
 }
 
 /**
- * The policy applied to an already-parsed value - the native-`json()` lane, which never holds the
- * raw text, and the transport codecs, which parse with their own decoder. Escapes are resolved by
- * the time a key is an own property, so a `\u`-spelled `__proto__` and a literal one look identical
- * here. Cost is one iterative pass over the value's object nodes; `"ignore"` skips even that.
- * Throws the reject singleton; callers map it to their lane's flat error.
+ * The policy applied to an already-parsed JSON value - the native-`json()` lane, which never holds
+ * the raw text. Escapes are resolved by the time a key is an own property, so a `\u`-spelled
+ * `__proto__` and a literal one look identical here. Cost is one iterative pass over the value's
+ * object nodes; `"ignore"` skips even that. The walk assumes a tree, which JSON always is; a
+ * transport codec's output goes through {@link guardDecodedValue}. Throws the reject singleton;
+ * callers map it to their lane's flat error.
  */
 export function guardParsedValue(value: unknown, policy: ProtoPoisoning): unknown {
   if (policy === "ignore") return value
@@ -81,10 +82,10 @@ function sweep(root: unknown, policy: "reject" | "strip"): unknown {
     // `for-in`, not `Object.keys()`: the keys array would be an allocation per node (~2x the whole
     // walk on measured bodies, both engines, at realistic widths; V8 only prefers `Object.keys` on
     // 200+-property dictionary-mode objects). On JSON.parse output the two enumerate identically -
-    // own enumerable string keys, nothing enumerable on the prototype chain. A custom transport
-    // codec could hand `guardParsedValue` an object with enumerable INHERITED properties; `for-in`
-    // sweeps those too, which only over-sweeps - a poisoned inherited subtree rejects rather than
-    // slips through. A *non-enumerable* own `__proto__` is the one shape this misses, and it is
+    // own enumerable string keys, nothing enumerable on the prototype chain. Were a value with
+    // enumerable INHERITED properties handed in, `for-in` would sweep those too, which only
+    // over-sweeps - a poisoned inherited subtree rejects rather than slips through. A
+    // *non-enumerable* own `__proto__` is the one shape this misses, and it is
     // not the poisoning shape: `JSON.parse` never produces one, and the merges that carry the
     // payload onward (spread, `Object.assign`, key loops) copy enumerable own keys only.
     for (const key in record) {
@@ -116,3 +117,121 @@ function sweep(root: unknown, policy: "reject" | "strip"): unknown {
   }
   return root
 }
+
+/** How many nodes shared references may add to a decoded value, counted as a tree walk visits it. */
+const MAX_SHARED_EXPANSION = 100_000
+
+/** Thrown (reused singleton, mapped like {@link POISONED}) for a decoded value no tree walk can finish,
+ * or one holding a pattern the caller did not allow. */
+const NOT_A_TREE = /* @__PURE__ */ new Error("decoded_value_not_a_tree")
+
+/** Marks a node whose subtree is still being walked: meeting it again then is a cycle. */
+const ON_PATH = -1
+
+interface DecodedFrame {
+  readonly node: object
+  readonly children: readonly object[]
+  next: number
+  size: number
+}
+
+/**
+ * The policy for a value a transport codec decoded. Unlike `JSON.parse` output that can be a graph -
+ * a codec that keeps references, as the rich wire codec does, returns shared nodes and cycles - while
+ * everything downstream (validators, handlers, serializers) walks a body as a tree. So a cycle is
+ * refused, and shared nodes may add at most {@link MAX_SHARED_EXPANSION} nodes to the tree they expand
+ * to: forty levels of doubled references fit in 2KB and expand to 2^40 paths. Map and Set members are
+ * walked like properties. These shape rules hold under every policy, `"ignore"` included.
+ *
+ * A `RegExp` is refused unless `patterns` allows it: a pattern from the client is code, and one with
+ * catastrophic backtracking stalls the event loop the moment anything runs it.
+ */
+export function guardDecodedValue(
+  value: unknown,
+  policy: ProtoPoisoning,
+  patterns = false,
+): unknown {
+  if (value === null || typeof value !== "object") return value
+  const sizes = new Map<object, number>()
+  const frames: DecodedFrame[] = [openDecoded(value, policy, patterns, sizes)]
+  let expanded = 0
+  for (let frame = frames.at(-1); frame !== undefined; frame = frames.at(-1)) {
+    const child = frame.children[frame.next]
+    if (child !== undefined) {
+      frame.next++
+      const known = sizes.get(child)
+      if (known === undefined) frames.push(openDecoded(child, policy, patterns, sizes))
+      else if (known === ON_PATH) throw NOT_A_TREE
+      else frame.size += known
+      continue
+    }
+    frames.pop()
+    sizes.set(frame.node, frame.size)
+    const parent = frames.at(-1)
+    if (parent === undefined) expanded = frame.size
+    else parent.size += frame.size
+  }
+  if (expanded - sizes.size > MAX_SHARED_EXPANSION) throw NOT_A_TREE
+  return value
+}
+
+function openDecoded(
+  node: object,
+  policy: ProtoPoisoning,
+  patterns: boolean,
+  sizes: Map<object, number>,
+): DecodedFrame {
+  if (!patterns && node instanceof RegExp) throw NOT_A_TREE
+  sizes.set(node, ON_PATH)
+  return { node, children: decodedChildren(node, policy), next: 0, size: 1 }
+}
+
+function decodedChildren(node: object, policy: ProtoPoisoning): object[] {
+  const children: object[] = []
+  const add = (value: unknown): void => {
+    if (value !== null && typeof value === "object") children.push(value)
+  }
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) add(node[i])
+    return children
+  }
+  if (node instanceof Map) {
+    for (const [key, value] of node) {
+      add(key)
+      add(value)
+    }
+    return children
+  }
+  if (node instanceof Set) {
+    for (const item of node) add(item)
+    return children
+  }
+  // Binary and scalar wrappers carry no keys to poison; `for-in` over a typed array would enumerate
+  // every index.
+  if (
+    ArrayBuffer.isView(node) ||
+    node instanceof ArrayBuffer ||
+    node instanceof Date ||
+    node instanceof RegExp ||
+    node instanceof URL
+  ) {
+    return children
+  }
+  for (const key in node) {
+    const value: unknown = Reflect.get(node, key)
+    if (
+      policy !== "ignore" &&
+      (key === "__proto__" ||
+        (key === "constructor" &&
+          value !== null &&
+          typeof value === "object" &&
+          Object.hasOwn(value, "prototype")))
+    ) {
+      if (policy === "reject") throw POISONED
+      Reflect.deleteProperty(node, key)
+      continue
+    }
+    add(value)
+  }
+  return children
+}

package/src/server/query.ts

@@ -110,6 +110,55 @@ export function queryObjectOf(search: string): Record<string, QueryValue> {
   return out
 }
 
+/**
+ * `application/json` or an `application/*+json` type, with or without parameters, compared as a media
+ * type rather than searched as a substring. A substring test also matches `text/plain; x=application/json`,
+ * whose essence is `text/plain` - a type a browser sends cross-origin with credentials and no preflight,
+ * so a JSON route would parse a body no CORS policy ever saw.
+ */
+export function isJsonMediaType(contentType: string): boolean {
+  // The spellings common clients send, by exact match.
+  if (
+    contentType === "application/json" ||
+    contentType === "application/json; charset=utf-8" ||
+    contentType === "application/json;charset=UTF-8"
+  ) {
+    return true
+  }
+  // Every other lowercase `application/json` spelling, parameters or not, without slicing or lowercasing.
+  if (contentType.startsWith("application/json")) {
+    let delimiter = 16
+    while (delimiter < contentType.length) {
+      const char = contentType.charCodeAt(delimiter)
+      if (char !== 32 /* SP */ && char !== 9 /* HTAB */) break
+      delimiter++
+    }
+    if (delimiter === contentType.length || contentType.charCodeAt(delimiter) === 59 /* ; */) {
+      return true
+    }
+  }
+  // Lowercase `application/*+json` spellings by the same rules as the parse below, without allocating.
+  if (contentType.startsWith("application/")) {
+    const params = contentType.indexOf(";", 12)
+    let end = params === -1 ? contentType.length : params
+    while (end > 12) {
+      const char = contentType.charCodeAt(end - 1)
+      if (char !== 32 /* SP */ && char !== 9 /* HTAB */) break
+      end--
+    }
+    if (end >= 17 && contentType.startsWith("+json", end - 5)) {
+      const space = contentType.indexOf(" ", 12)
+      if (space === -1 || space >= end) return true
+    }
+  }
+  const semi = contentType.indexOf(";")
+  const essence = (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase()
+  return (
+    essence === "application/json" ||
+    (essence.startsWith("application/") && essence.endsWith("+json") && !essence.includes(" "))
+  )
+}
+
 /** `application/x-www-form-urlencoded`, with or without a charset suffix. */
 export function isUrlEncodedForm(contentType: string): boolean {
   return (

package/src/server/registry.ts

@@ -1,6 +1,6 @@
 import type { BinaryResponse, RawResponse } from "../binary.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
-import type { Params, RouteSchema } from "./context.ts"
+import type { Params, RoutePaths, RouteSchema } from "./context.ts"
 import type { StatusResponse } from "./runtime-core.ts"
 
 /**
@@ -196,10 +196,25 @@ export type WsRouteInfoFor<
  * `.merge()` them (each group is a short chain; a merge is one `R & R2` intersection with no
  * per-call context work), or contract-first `implement()` (the registry is one object type declared
  * upfront - no grow-R-per-call, so no ceiling at all).
+ *
+ * A path ending in optional parameters is keyed once per concrete path it serves (`RoutePaths`), all
+ * sharing the one route info, so `/users/:id?` adds `/users` and `/users/:id`.
  */
 export type AddRoute<
   R extends Registry,
   Method extends string,
   Path extends string,
   Info extends RouteInfo,
-> = R & { [P in Path]: { [M in Method]: Info } }
+> = R & { [P in RoutePaths<Path>]: { [M in Method]: Info } }
+
+/** Join a group prefix and a route path the way `Server.group` does at runtime: a group's `/` route
+ * serves the prefix itself (no trailing slash), every other path is appended verbatim. */
+export type JoinRoutePath<Prefix extends string, Path extends string> = Path extends "/"
+  ? Prefix
+  : `${Prefix}${Path}`
+
+/** Re-key a registry under a static path prefix. Route info (params, schemas, responses) is carried
+ * unchanged: a prefix is static text, so it adds no params and cannot change any route's contract. */
+export type PrefixRegistry<Prefix extends string, R extends Registry> = {
+  [Path in keyof R & string as JoinRoutePath<Prefix, Path>]: R[Path]
+}

package/src/server/request-context.ts

@@ -157,6 +157,15 @@ function responseTextContentType(): string {
  * passes no headers of their own. */
 const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
 
+/** Where a serving adapter that shares one platform across requests leaves its socket-peer lookup.
+ * `c.clientIp` calls it with the request when a handler reads the address, so a request whose
+ * handler never reads it costs the adapter neither a lookup nor a platform object of its own. */
+export const PLATFORM_PEER = Symbol()
+
+export type PeerPlatform = Platform & {
+  readonly [PLATFORM_PEER]?: (source: RequestSource) => string | undefined
+}
+
 export class RequestContext implements RawContext {
   // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
   // constructor initializes only the eager request state, while lazy fields remain absent until used.
@@ -167,13 +176,16 @@ export class RequestContext implements RawContext {
   private declare searchValue: string | undefined
   private declare signalValue: AbortSignal | undefined
   private declare budgetValue: RequestBudget | undefined
-  private declare platformValue: Platform | undefined
+  private declare platformValue: PeerPlatform | undefined
+  private declare peerValue: string | undefined
 
   private declare setValue: CtxSet | undefined
   private declare queryValue: unknown
   private declare queryReady: boolean
   private declare headersValue: Record<string, string> | undefined
   private declare cookiesValue: Readonly<Record<string, string>> | undefined
+  declare jsonReply: Response | undefined
+  declare jsonBody: unknown
   private declare readonly source: RequestSource
   private declare readonly maxBodyBytes: number
   private declare readonly protoPoisoning: ProtoPoisoning
@@ -268,8 +280,12 @@ export class RequestContext implements RawContext {
 
   get clientIp(): string | undefined {
     // The server resolves the trust declaration into `platform.clientIp` before the context is built,
-    // so this getter just surfaces the already-derived value (raw socket peer by default).
-    return this.platformValue?.clientIp
+    // so this getter just surfaces the already-derived value (raw socket peer by default). A platform
+    // shared across requests holds no address of its own and is asked for this request's peer, once:
+    // the answer is kept, so a read after the socket closed agrees with one before it.
+    const platform = this.platformValue
+    this.peerValue ??= platform?.clientIp ?? platform?.[PLATFORM_PEER]?.(this.source)
+    return this.peerValue
   }
 
   get waitUntil(): (promise: Promise<unknown>) => void {
@@ -312,19 +328,27 @@ export class RequestContext implements RawContext {
    */
   json(body: unknown, init?: ResponseInit | number): Response {
     const i = statusInit(init)
-    if (!DEFERS_RESPONSE) return Response.json(body, i)
-    const defer = deferredResponderFor()
-    if (defer === undefined) return Response.json(body, i)
-    // The same bytes `Response.json` would produce, kept one step short of it so the direct writer
-    // can have them. `JSON.stringify` returns `undefined` for a value with no JSON form (`undefined`,
-    // a function, a symbol) - exactly the case where `Response.json` throws, so hand it back the
-    // throw rather than inventing a body. The content-type is the runtime's own, read off
-    // `Response.json` once, so a deferred response carries the same one byte for byte.
-    const text = JSON.stringify(body) as string | undefined
-    if (text === undefined) return Response.json(body, i)
-    const headers = ownHeaderRecord(i?.headers, responseJsonContentType())
-    if (headers === undefined) return Response.json(body, i)
-    return defer(text, i?.status ?? 200, headers)
+    let reply: Response | undefined
+    if (DEFERS_RESPONSE) {
+      const defer = deferredResponderFor()
+      // The same bytes `Response.json` would produce, kept one step short of it so the direct
+      // writer can have them. `JSON.stringify` returns `undefined` for a value with no JSON form
+      // (`undefined`, a function, a symbol) - exactly the case where `Response.json` throws, so it
+      // gets the throw rather than an invented body. The content-type is the runtime's own, read
+      // off `Response.json` once, so a deferred response carries the same one byte for byte.
+      const text = defer === undefined ? undefined : (JSON.stringify(body) as string | undefined)
+      const headers =
+        text === undefined ? undefined : ownHeaderRecord(i?.headers, responseJsonContentType())
+      if (defer !== undefined && text !== undefined && headers !== undefined) {
+        reply = defer(text, i?.status ?? 200, headers)
+      }
+    }
+    reply ??= Response.json(body, i)
+    // Remembered so a response contract holds the value to the route's schema: this is the
+    // framework's JSON helper, not a raw-Response escape hatch.
+    this.jsonBody = body
+    this.jsonReply = reply
+    return reply
   }
 
   /**
@@ -370,6 +394,10 @@ export class RequestContext implements RawContext {
     return this.cookiesValue
   }
 
+  set cookies(value: Readonly<Record<string, string>>) {
+    this.cookiesValue = value
+  }
+
   boundedBody(maxBytes?: number): Promise<Uint8Array> {
     return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes)
   }

package/src/server/request-lineage.ts

@@ -0,0 +1,15 @@
+/** Each request an `onRequest` hook returned in place of the one it was handed, mapped to that one. */
+const REPLACED = new WeakMap<Request, Request>()
+
+export function recordRequestReplacement(replacement: Request, replaced: Request): void {
+  REPLACED.set(replacement, replaced)
+}
+
+/**
+ * The request an `onRequest` hook returned this one in place of, or `undefined` for the request the
+ * exchange began with. Response hooks receive the request the route ran with, so a middleware that
+ * keyed state on the request its `onRequest` saw walks back from there to find it.
+ */
+export function replacedRequestOf(request: Request): Request | undefined {
+  return REPLACED.get(request)
+}

package/src/server/request-target.ts

@@ -0,0 +1,46 @@
+/**
+ * Dot segments in a request target, resolved the way a WHATWG URL parser resolves them.
+ *
+ * Bun and workerd hand an app a request whose URL is already parsed: a client that sends
+ * `/users/../posts`, `/users/%2e%2e/posts` or `/users/..\posts` is asking for `/posts`, and that
+ * is the URL the app sees. Node's `IncomingMessage.url` and Deno's `Request.url` carry the target
+ * exactly as it was sent. Routing the raw text on those runtimes and the parsed text on the others
+ * sends one request to two different handlers - with two different sets of guards - depending on
+ * where the app runs. So a raw target is resolved before anything reads it, and every runtime routes
+ * the same path.
+ *
+ * No imports: `@nifrajs/node` carries a generated copy of this module, since it never depends on
+ * core at runtime.
+ */
+
+// A `.` or `..` segment (`%2e` counts as a dot, in either case), or a backslash, which a WHATWG
+// parser reads as a `/` in an http(s) path.
+const DOT_SEGMENT = /\\|\/(?:\.|%2e){1,2}(?:[/?#]|$)/i
+
+/**
+ * Whether `target` - an absolute URL or an origin-form `/path?query` - may hold a `.` or `..`
+ * segment, raw or percent-encoded, or a backslash: what a WHATWG parser would rewrite. Never false
+ * when the path has one. It can be true when only the query looks like one (`?next=/../x`):
+ * resolving that target leaves its path and query as they are, apart from the characters a parser
+ * always percent-encodes.
+ */
+export function hasDotSegment(target: string): boolean {
+  // One regex pass: measured faster on Node and Deno than substring scans that gate it.
+  return DOT_SEGMENT.test(target)
+}
+
+/**
+ * `target` with its dot segments resolved and its backslashes read as `/`, by the platform's own
+ * WHATWG parser. An origin-form target stays origin-form (the fragment, which no client sends,
+ * dropped); an absolute URL comes back absolute. The parser also percent-encodes what it always
+ * encodes, which is what Bun and workerd deliver for the same request. A target that is neither -
+ * `*`, or text no URL parser accepts - comes back as it arrived: there is no path to resolve.
+ */
+export function resolveDotSegments(target: string): string {
+  if (target.charCodeAt(0) === 47 /* / */) {
+    // Appended to an origin, not resolved against one: `//host/..` must stay a path on this origin.
+    const url = new URL(`http://localhost${target}`)
+    return url.pathname + url.search
+  }
+  return URL.canParse(target) ? new URL(target).href : target
+}

package/src/server/respond.ts

@@ -52,6 +52,7 @@ const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
  */
 export function buildStaticResponseHeaders(
   record: Readonly<Record<string, string>>,
+  inherited?: Readonly<Record<string, string>>,
 ): StaticResponseHeaders {
   const frozen = Object.freeze({ ...record })
   const jsonHeaders = new Headers({ ...frozen, "content-type": JSON_CONTENT_TYPE })
@@ -61,6 +62,7 @@ export function buildStaticResponseHeaders(
     entries: Object.freeze(Object.entries(frozen)),
     jsonHeaders,
     jsonInit200: { status: 200, headers: jsonHeaders },
+    inherited,
     responseJsonInit200: () => {
       responseJson ??= {
         status: 200,
@@ -138,7 +140,9 @@ function applyStaticDefaults(headers: Headers, statics: StaticResponseHeaders):
   const entries = statics.entries
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i]!
-    if (!headers.has(entry[0])) headers.set(entry[0], entry[1])
+    // Absent, or still an enclosing scope's value rather than one the request set: this one applies.
+    if (headers.get(entry[0]) === (statics.inherited?.[entry[0]] ?? null))
+      headers.set(entry[0], entry[1])
   }
 }
 
@@ -555,8 +559,15 @@ export function appendCookiesToResponse(response: Response, set: CtxSet): Respon
   // returned Response - otherwise the canonical set-session-then-redirect pattern would silently drop
   // the cookie. (Other `c.set` fields stay the returned Response's own concern.)
   const cookies = set._cookies
-  if (cookies !== undefined && cookies.length > 0) {
+  if (cookies === undefined || cookies.length === 0) return response
+  try {
     for (const cookie of cookies) response.headers.append("set-cookie", cookie)
+    return response
+  } catch {
+    // Guarded `Headers` (`Response.redirect()`, a raw `fetch()` result) reject every write, so the
+    // first append throws with nothing applied and the cookies land on a mutable copy instead.
+    const clone = new Response(response.body, response)
+    for (const cookie of cookies) clone.headers.append("set-cookie", cookie)
+    return stamped(clone)
   }
-  return response
 }