@nifrajs/core 1.13.0 → 2.0.0

package/src/server/plugin.ts

@@ -0,0 +1,92 @@
+/**
+ * Plugin definers and their types. A plugin is a function that augments an app (calling
+ * `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 { AnyServer } from "./server.ts"
+
+/**
+ * A nifra **plugin**: a function that augments an app - calling `use`/`derive`/`decorate` and/or
+ * registering routes - and returns it. Because `derive`/`decorate` are type-threaded, an **inline**
+ * `app.use((a) => a.derive(...).decorate(...))` carries the added context to handlers defined after
+ * it (the `use` overload is generic over the concrete `this`). Wrap with {@link definePlugin} to
+ * attach a name for idempotent dedupe (applying the same named plugin twice - e.g. transitively - is
+ * a no-op).
+ */
+export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer = In> = ((
+  app: In,
+) => Out) & { readonly pluginName?: string }
+
+/**
+ * A named type-identity plugin built with {@link defineIdentityPlugin}. It returns the same concrete
+ * server type it receives, preserving the caller's typed registry and context across `.use()` while
+ * still allowing the plugin to register runtime hooks or handlers.
+ */
+export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
+  readonly pluginName?: string
+}
+
+/**
+ * Name + ergonomics for a plugin that **adds typed context** (`derive`/`decorate`). `app.use(myPlugin)`
+ * applies it once; a second `use` of the same name is skipped (idempotent), so plugins can depend on each
+ * other without double-registering hooks.
+ *
+ * ```ts
+ * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * app.use(requestId)   // downstream handlers see c.requestId
+ * ```
+ *
+ * FOOTGUN: only use this for a plugin that adds context. For a plugin that **mounts routes/hooks but adds
+ * NO context** (an auth router, an audit logger), use {@link defineRouterPlugin} ({@link defineIdentityPlugin}).
+ * `definePlugin((app) => app.get(...))` infers `app: Server<any, any>`, so `.use()` returns `Server<any, any>`
+ * and your whole typed client silently collapses to `any` - no type error, no runtime error.
+ */
+export function definePlugin<In extends AnyServer, Out extends AnyServer>(
+  name: string,
+  apply: (app: In) => Out,
+): NifraPlugin<In, Out> {
+  return Object.assign(apply, { pluginName: name }) as NifraPlugin<In, Out>
+}
+
+/**
+ * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
+ * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
+ * add context types - e.g. one mounting an auth handler. It threads the caller's *concrete* server type
+ * through `use`, so routes declared after `app.use(plugin)` keep their types.
+ *
+ * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
+ * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
+ * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
+ *
+ * ```ts
+ * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
+ * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export function defineIdentityPlugin(
+  name: string,
+  apply: <S extends AnyServer>(app: S) => S,
+): IdentityPlugin {
+  return Object.assign(apply, { pluginName: name }) as IdentityPlugin
+}
+
+/**
+ * Alias of {@link defineIdentityPlugin} with a name that says what it's FOR: a plugin that **mounts
+ * routes/hooks but adds no context type** (an auth router, an audit logger). Use this - not
+ * {@link definePlugin} - for any such plugin, or the typed client silently collapses to `any`. The
+ * "identity" in {@link defineIdentityPlugin} refers to the type-identity it preserves; `defineRouterPlugin`
+ * is the same thing under a clearer name.
+ *
+ * Mount routes as a **side effect**, then return the app unchanged (registering via `.get`/`.post` would
+ * change the type away from the identity `S`; the mounted routes run but aren't in the caller's typed
+ * registry - that's the trade that keeps everything else typed):
+ *
+ * ```ts
+ * export const scim = defineRouterPlugin("scim", (app) => {
+ *   app.get("/scim/v2/Users", listUsers) // side effect: mounted at runtime
+ *   return app                           // return S unchanged → routes added after .use(scim) stay typed
+ * })
+ * const api = server().get("/a", h).use(scim).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export const defineRouterPlugin: typeof defineIdentityPlugin = defineIdentityPlugin

package/src/server/query.ts

@@ -0,0 +1,119 @@
+/**
+ * Query-string and urlencoded-form parsing. Pure request-shaping helpers with no server internals:
+ * the fast scanner for `c.query`, the repeated-key -> `string[]` promotion shared by query + form,
+ * and the byte-capped HTML-form reader. Split out of the server kernel so the file stays one domain.
+ */
+import { readBoundedBytes } from "./body.ts"
+import { jsonError, urlPartsOf } from "./http.ts"
+import type { RequestSource } from "./server.ts"
+
+// The query string ("?a=1", or "" when absent) - for lazily building `c.query` only when read.
+// The fragment (after the first `#`) bounds the search: a `?` that appears only inside the fragment
+// is NOT a query (matches WHATWG). Fragments never reach the server in `req.url`, so this is purely
+// for provable equivalence with `new URL(req.url).search`.
+export function searchOf(url: string): string {
+  return urlPartsOf(url).search
+}
+
+/** A query value: a single occurrence is a string; a repeated key promotes to a string[] so an
+ * array query schema (`t.array(t.string())`) can validate `?tag=a&tag=b` - last-wins silently
+ * dropped values before (audit 2026-06). Single-occurrence keys stay plain strings, so existing
+ * `t.string()` schemas are untouched; a repeated key against a string schema now FAILS validation
+ * (an explicit 400 beats silently picking one). */
+export type QueryValue = string | string[]
+
+/** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
+ * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key - the
+ * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
+ * case (direct assignment on a null-proto object creates an own property). */
+function setQueryValue(out: Record<string, QueryValue>, key: string, value: string): void {
+  const existing = out[key]
+  if (existing === undefined) {
+    out[key] = value
+  } else if (typeof existing === "string") {
+    out[key] = [existing, value]
+  } else {
+    existing.push(value)
+  }
+}
+
+function queryObjectFallback(search: string): Record<string, QueryValue> {
+  // Manual iteration instead of Object.fromEntries: repeated keys must promote to arrays
+  // (fromEntries is last-wins), and __proto__ needs the same own-property guard.
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  for (const [key, value] of new URLSearchParams(search)) {
+    setQueryValue(out, key, value)
+  }
+  return out
+}
+
+/**
+ * Build the plain object passed to query schemas. Plain ASCII-ish queries avoid
+ * `URLSearchParams` + iterator allocations; encoded queries fall back to the Web API so `+`,
+ * percent-decoding, malformed escapes, and empty-key behavior stay exact. Repeated keys promote
+ * to `string[]` on BOTH paths (see {@link setQueryValue}).
+ */
+// Shared empty result for no-query requests: frozen + null-prototype (same shape contract as the
+// populated path), allocated once instead of per request.
+const EMPTY_QUERY = Object.freeze(Object.create(null)) as Record<string, QueryValue>
+
+export function queryObjectOf(search: string): Record<string, QueryValue> {
+  const start = search.charCodeAt(0) === 63 /* ? */ ? 1 : 0
+  if (start >= search.length) return EMPTY_QUERY
+
+  for (let i = start; i < search.length; i++) {
+    const c = search.charCodeAt(i)
+    if (c === 37 /* % */ || c === 43 /* + */) return queryObjectFallback(search)
+  }
+
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  let pos = start
+  while (pos <= search.length) {
+    const amp = search.indexOf("&", pos)
+    const end = amp === -1 ? search.length : amp
+    if (end > pos) {
+      const eq = search.indexOf("=", pos)
+      const split = eq !== -1 && eq < end ? eq : end
+      const key = search.slice(pos, split)
+      const value = split === end ? "" : search.slice(split + 1, end)
+      setQueryValue(out, key, value)
+    }
+    if (amp === -1) break
+    pos = amp + 1
+  }
+  return out
+}
+
+/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+export function isUrlEncodedForm(contentType: string): boolean {
+  return (
+    contentType === "application/x-www-form-urlencoded" ||
+    contentType.startsWith("application/x-www-form-urlencoded;")
+  )
+}
+
+const FORM_DECODER = new TextDecoder()
+
+/**
+ * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
+ * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
+ * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ */
+export async function readBoundedForm(
+  req: RequestSource,
+  maxBytes: number,
+): Promise<Record<string, QueryValue> | Response> {
+  const read = await readBoundedBytes(req, maxBytes)
+  if (!read.ok) {
+    return read.status === 413
+      ? jsonError(413, "payload_too_large")
+      : jsonError(400, "invalid_content_length")
+  }
+  const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
+  // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);
+  // it never throws on junk input, so no try/catch is needed here.
+  for (const [key, value] of new URLSearchParams(FORM_DECODER.decode(read.bytes))) {
+    setQueryValue(out, key, value)
+  }
+  return out
+}

package/src/server/registry.ts

@@ -1,4 +1,4 @@
-import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
+import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
 
 /**
@@ -16,12 +16,17 @@ export interface RouteInfo {
   readonly query: unknown
   readonly body: unknown
   readonly output: unknown
-  /** Union of the route's declared error-response body types (from `schema.errors`); `unknown` when the
-   * route declares none. Surfaced by the typed client as the failure `errorData`. */
+  /** The route's declared error bodies as a status-keyed record (from `schema.errors`, e.g.
+   * `{ 404: NotFound }`); `unknown` when the route declares none. The typed client turns this into
+   * a status-discriminated failure union. */
   readonly errors?: unknown
   /** The SSE event payload type (from `schema.sse`, declared via `app.sse()`); `never` for ordinary
    * routes. The typed client keys `.subscribe()` availability and its event type off this. */
   readonly sse?: unknown
+  /** The WebSocket message contract (from `app.ws()`'s `messageSchema`/`sendSchema`): `in` is what the
+   * client may send, `out` what the server pushes. Present only on WS entries (method key `"WS"`);
+   * the typed client keys `.ws()` availability and its frame types off this. */
+  readonly ws?: unknown
 }
 
 /** The accumulated, type-level map of every route on a Server: path → method → RouteInfo. */
@@ -46,12 +51,13 @@ type RegistryOutput<S extends RouteSchema, Output> = S extends {
   ? InferOutput<R>
   : Output
 
-/** The union of a route's declared error-response body types (`schema.errors` → `{status: schema}`), so the
- * typed client can surface the failure body. `unknown` when the route declares no `errors`. */
+/** A route's declared error-response body types as a STATUS-KEYED record (`schema.errors` →
+ * `{ 404: NotFound, 409: Conflict }`), so the typed client can discriminate the failure body by
+ * `status`, not just surface a union. `unknown` when the route declares no `errors`. */
 type RegistryErrors<S extends RouteSchema> = S extends {
   errors: infer E extends Record<number, StandardSchemaV1>
 }
-  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }[keyof E]
+  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
   : unknown
 
 /** The SSE event payload type from a route's `sse` schema; `never` for ordinary routes. */
@@ -75,6 +81,30 @@ export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
   Response
 >
 
+/**
+ * The registry entry for a WebSocket route (stored under the pseudo-method key `"WS"`, so WS routes
+ * ride the same path → method map as HTTP routes - no extra Server generic). `in` is the client →
+ * server frame type: the `messageSchema`'s INPUT side, since that is what goes on the wire before
+ * validation transforms it. `out` is the server → client frame type from `sendSchema` (a type-level
+ * contract; the server's own sends are not runtime-validated). Either is `unknown` when undeclared.
+ */
+export type WsRouteInfoFor<
+  Path extends string,
+  In extends StandardSchemaV1 | undefined,
+  Out extends StandardSchemaV1 | undefined,
+> = {
+  readonly params: Params<Path>
+  readonly query: never
+  readonly body: never
+  readonly output: never
+  readonly errors: unknown
+  readonly sse: never
+  readonly ws: {
+    readonly in: In extends StandardSchemaV1 ? InferInput<In> : unknown
+    readonly out: Out extends StandardSchemaV1 ? InferOutput<Out> : unknown
+  }
+}
+
 /**
  * Merge a new route into the registry, combining methods that share a path.
  *

package/src/server/request-context.ts

@@ -0,0 +1,271 @@
+/**
+ * The runtime request context (`c`): the `RawContext` implementation the handler receives, its lazy
+ * `c.set` response-controls backing, and the bounded body readers behind `c.boundedBody`/`c.boundedJson`.
+ * Type-imports the kernel's spine (never its values) and pulls its primitives from `runtime-core`, so it
+ * sits below the server module in the graph.
+ */
+import type { RequestBudget } from "../budget.ts"
+import { drainCapped, parseContentLength, readBoundedBytes } from "./body.ts"
+import type { Platform } from "./context.ts"
+import { type CookieOptions, parseCookies, serializeCookie } from "./cookies.ts"
+import { jsonError } from "./http.ts"
+import { searchOf } from "./query.ts"
+import {
+  CONTEXT_SEARCH,
+  CONTEXT_SET,
+  fallbackWaitUntil,
+  getNeverAbortSignal,
+  getUnboundedRequestBudget,
+  headerOf,
+  requestOf,
+  TEXT_DECODER,
+} from "./runtime-core.ts"
+import type { CtxSet, RawContext, RequestSource } from "./server.ts"
+
+/** A fixed past instant for cookie deletion (`Expires`). A literal epoch - deterministic, unlike an
+ * argless `new Date()`. */
+const EPOCH = new Date(0)
+
+class LazyResponseControls implements CtxSet {
+  status?: number
+  _headers?: Record<string, string>
+  _cookies?: string[]
+
+  get headers(): Record<string, string> {
+    this._headers ??= {}
+    return this._headers
+  }
+
+  cookie(name: string, value: string, options?: CookieOptions): void {
+    // Secure-by-default: HttpOnly + Secure + SameSite=Lax + Path=/, overridable per call.
+    const merged: CookieOptions = {
+      httpOnly: true,
+      secure: true,
+      sameSite: "lax",
+      path: "/",
+      ...options,
+    }
+    this._cookies ??= []
+    this._cookies.push(serializeCookie(name, value, merged))
+  }
+
+  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void {
+    // Expire immediately; default Path=/, and match the original path/domain or the browser keeps it.
+    this._cookies ??= []
+    this._cookies.push(
+      serializeCookie(name, "", { path: "/", ...options, maxAge: 0, expires: EPOCH }),
+    )
+  }
+}
+
+/** Coerce `c.json`/`c.text`'s second arg - a status number (the common case) or a full `ResponseInit`. */
+function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
+  return typeof init === "number" ? { status: init } : init
+}
+
+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.
+  // Not `readonly`: the lifecycle replaces it with the validated/coerced value when a `params` schema is
+  // declared (`c.params` stays `readonly` to handlers via the `Context` interface).
+  declare params: Record<string, string>
+  declare body: unknown
+  private declare searchValue: string | undefined
+  private declare signalValue: AbortSignal | undefined
+  private declare budgetValue: RequestBudget | undefined
+  private declare platformValue: Platform | undefined
+
+  private declare setValue: CtxSet | undefined
+  private declare queryValue: unknown
+  private declare queryReady: boolean
+  private declare cookiesValue: Readonly<Record<string, string>> | undefined
+  private declare readonly source: RequestSource
+  private declare readonly maxBodyBytes: number
+
+  constructor(source: RequestSource, params: Record<string, string>, maxBodyBytes: number)
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    search: string | undefined,
+    signal: AbortSignal,
+    budget: RequestBudget,
+    platform: Platform | undefined,
+    maxBodyBytes: number,
+  )
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    searchOrMaxBodyBytes: string | number | undefined,
+    signal?: AbortSignal,
+    budget?: RequestBudget,
+    platform?: Platform,
+    maxBodyBytes?: number,
+  ) {
+    this.source = source
+    this.params = params
+    if (typeof searchOrMaxBodyBytes === "number") {
+      this.maxBodyBytes = searchOrMaxBodyBytes
+      return
+    }
+    if (searchOrMaxBodyBytes !== undefined) this.searchValue = searchOrMaxBodyBytes
+    this.signalValue = signal
+    this.budgetValue = budget
+    if (platform !== undefined) this.platformValue = platform
+    this.maxBodyBytes = maxBodyBytes as number
+  }
+
+  static native(
+    source: RequestSource,
+    params: Record<string, string>,
+    maxBodyBytes: number,
+  ): RequestContext {
+    return new RequestContext(source, params, maxBodyBytes)
+  }
+
+  [CONTEXT_SET](): CtxSet | undefined {
+    return this.setValue
+  }
+
+  get [CONTEXT_SEARCH](): string {
+    this.searchValue ??= searchOf(this.source.url)
+    return this.searchValue
+  }
+
+  get set(): CtxSet {
+    this.setValue ??= new LazyResponseControls()
+    return this.setValue
+  }
+
+  get signal(): AbortSignal {
+    return this.signalValue ?? getNeverAbortSignal()
+  }
+
+  get budget(): RequestBudget {
+    return this.budgetValue ?? getUnboundedRequestBudget()
+  }
+
+  get env(): unknown {
+    return this.platformValue?.env
+  }
+
+  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
+  }
+
+  get waitUntil(): (promise: Promise<unknown>) => void {
+    return this.platformValue?.waitUntil ?? fallbackWaitUntil
+  }
+
+  get req(): Request {
+    return requestOf(this.source)
+  }
+
+  get request(): Request {
+    return requestOf(this.source)
+  }
+
+  json(body: unknown, init?: ResponseInit | number): Response {
+    return Response.json(body, statusInit(init))
+  }
+
+  text(body: string, init?: ResponseInit | number): Response {
+    const i = statusInit(init)
+    // Default to text/plain; if the caller passes their own headers, they own the content-type.
+    if (i?.headers !== undefined) return new Response(body, i)
+    return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } })
+  }
+
+  get query(): unknown {
+    if (!this.queryReady) {
+      this.queryValue = new URLSearchParams(this[CONTEXT_SEARCH])
+      this.queryReady = true
+    }
+    return this.queryValue
+  }
+
+  set query(v: unknown) {
+    this.queryValue = v
+    this.queryReady = true
+  }
+
+  get cookies(): Readonly<Record<string, string>> {
+    this.cookiesValue ??= parseCookies(headerOf(this.source, "cookie"))
+    return this.cookiesValue
+  }
+
+  boundedBody(maxBytes?: number): Promise<Uint8Array> {
+    return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes)
+  }
+
+  boundedJson<T = unknown>(maxBytes?: number): Promise<T> {
+    return readBoundedJsonBodyOrThrow<T>(this.source, this.maxBodyBytes, maxBytes)
+  }
+}
+
+/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 `Response` (caught by
+ * `runLifecycle` as control flow, like `throw redirect(...)`), so a handler can't ignore the cap.
+ * The byte-cap itself lives in `./body.ts` (shared with the schema path and `verifyWebhook`). */
+async function readBoundedBodyOrThrow(
+  req: RequestSource,
+  maxBodyBytes: number,
+  maxBytes?: number,
+): Promise<Uint8Array> {
+  const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes)
+  if (r.ok) return r.bytes
+  throw r.status === 413
+    ? jsonError(413, "payload_too_large")
+    : jsonError(400, "invalid_content_length")
+}
+
+/** Backs `c.boundedJson`: `readBoundedBodyOrThrow` + `JSON.parse`, throwing a flat 400 on bad JSON. */
+async function readBoundedJsonBodyOrThrow<T>(
+  req: RequestSource,
+  maxBodyBytes: number,
+  maxBytes?: number,
+): Promise<T> {
+  const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes)
+  if (parsed instanceof Response) throw parsed
+  return parsed as T
+}
+
+/**
+ * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`.
+ * Non-chunked, framed requests with an in-cap `Content-Length` use the runtime-native `req.json()`;
+ * chunked or length-less requests fall back to the streaming byte-cap guard.
+ */
+export async function readBoundedJsonSource(
+  req: RequestSource,
+  maxBytes: number,
+): Promise<unknown | Response> {
+  const declared = headerOf(req, "content-length")
+  if (declared !== null) {
+    // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
+    // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
+    // "abc"->NaN, "-5", "1.5", "1e3", "0x10") is malformed -> 400, rather than silently falling
+    // through to the streaming guard - which is an UPPER-bound cap only, so a lying SMALLER length
+    // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
+    // hardens hand-built Requests (tests, the in-process client) and crafted input.
+    const length = parseContentLength(declared)
+    if (length === undefined) return jsonError(400, "invalid_content_length")
+    if (length > maxBytes) return jsonError(413, "payload_too_large")
+    const chunked = headerOf(req, "transfer-encoding") !== null
+    if (!chunked) {
+      try {
+        return await req.json()
+      } catch {
+        return jsonError(400, "invalid_json")
+      }
+    }
+  }
+  const body = req.body
+  if (body === null) return jsonError(400, "invalid_json")
+  const drained = await drainCapped(body, maxBytes)
+  if (!drained.ok) return jsonError(413, "payload_too_large")
+  try {
+    return JSON.parse(TEXT_DECODER.decode(drained.bytes))
+  } catch {
+    return jsonError(400, "invalid_json")
+  }
+}

package/src/server/respond.ts

@@ -0,0 +1,93 @@
+/**
+ * Response construction from a handler's return value: the header/cookie init, the fused-lane
+ * responders, the fast JSON path, and cookie append. Imports only the runtime-core primitives + the
+ * spine types, so the wire-response format lives in one module distinct from the request engine.
+ */
+import {
+  CONTEXT_SET,
+  EMPTY_RESPONSE_CONTROLS,
+  type HandlerResult,
+  isResponseResult,
+} from "./runtime-core.ts"
+import type { CtxSet, RawContext } from "./server.ts"
+
+/** Build the response headers init. The common path (no `c.set`) returns `undefined` so `Response`
+ * gets no `headers` at all. Cookies force a `Headers` object - multiple `Set-Cookie`s can't live in a
+ * `Record<string,string>` (the 2nd would overwrite the 1st), so they're `append`ed individually. */
+function headersInit(set: CtxSet): Record<string, string> | Headers | undefined {
+  const cookies = set._cookies
+  if (cookies === undefined || cookies.length === 0) return set._headers
+  const headers = new Headers(set._headers)
+  for (const cookie of cookies) headers.append("set-cookie", cookie)
+  return headers
+}
+
+// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
+// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
+// across responses: the Response constructor copies `init.headers` into its own list.
+const JSON_CT_HEADERS = new Headers({
+  "content-type": "application/json;charset=utf-8",
+})
+const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
+
+/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
+ * older hand-inlined stringify + Response construction on this lane while preserving the exact
+ * body/content-type contract; keep the generic fallback for non-JSON values. */
+export function fusedRespondNoSet(result: unknown): Response {
+  if (
+    result !== undefined &&
+    !(result instanceof Response) &&
+    typeof result === "object" &&
+    result !== null &&
+    !isResponseResult(result)
+  ) {
+    return Response.json(result)
+  }
+  return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS)
+}
+
+/** Fused-lane respond with a context: read `c.set` once; untouched (the common case) -> the fast
+ * JSON respond; touched -> the generic `toResponse` with those controls (statuses, headers, cookies). */
+export function fusedRespond(result: unknown, ctx: RawContext): Response {
+  const set = ctx[CONTEXT_SET]()
+  if (set === undefined) return fusedRespondNoSet(result)
+  return toResponse(result as HandlerResult, set)
+}
+
+export function toResponse(result: HandlerResult, set: CtxSet): Response {
+  if (isResponseResult(result)) {
+    return appendCookiesToResponse(result.toResponse(), set)
+  }
+  if (result instanceof Response) {
+    return appendCookiesToResponse(result, set)
+  }
+  const headers = headersInit(set)
+  const status = set.status ?? (result === undefined ? 204 : 200)
+  if (headers === undefined && result !== undefined) {
+    // Fast respond (profiled ~50 ns/req faster on every plain-JSON return): `JSON.stringify` + a
+    // prebuilt init beats `Response.json`'s internal init handling. Output is byte-identical -
+    // same body bytes, same probed content-type. `undefined` from stringify (a function/symbol
+    // result) delegates to Response.json so its TypeError contract stays the single source.
+    const body = JSON.stringify(result) as string | undefined
+    if (body !== undefined) {
+      return new Response(
+        body,
+        status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS },
+      )
+    }
+  }
+  const init: ResponseInit = headers === undefined ? { status } : { status, headers }
+  return result === undefined ? new Response(null, init) : Response.json(result, init)
+}
+
+export function appendCookiesToResponse(response: Response, set: CtxSet): Response {
+  // A handler may queue cookies (`c.set.cookie` - e.g. a session cookie) AND return its own Response
+  // (e.g. `redirect("/")` after login). Cookies accumulate additively, so append them to the
+  // 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) {
+    for (const cookie of cookies) response.headers.append("set-cookie", cookie)
+  }
+  return response
+}