@nifrajs/core 1.13.0 → 2.0.0

package/src/server/idempotency-lane.ts

@@ -0,0 +1,287 @@
+/**
+ * The opt-in idempotency request lane. Installed by `.use(idempotency())` and reached only by routes
+ * that declare `schema.idempotency`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the whole dedupe machinery out.
+ *
+ * The kernel resolves a route's declared idempotency at registration (via {@link IdempotencyRuntime.resolve})
+ * and, on the request path, hands a matched idempotent route to {@link IdempotencyRuntime.run}. Everything
+ * server-specific is supplied through {@link IdempotencyHost} so this module depends on no server internals.
+ */
+import { RouteConfigError } from "../errors.ts"
+import {
+  canonicalizeIdempotencyBody,
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  IdempotencyResponseTooLargeError,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+  validIdempotencyNamespace,
+} from "../idempotency.ts"
+import { readBoundedBytes } from "./body.ts"
+import type { Platform, RouteSchema } from "./context.ts"
+import { jsonError, urlPartsOf } from "./http.ts"
+import { INSTALL_IDEMPOTENCY } from "./install.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
+export interface ResolvedIdempotency {
+  readonly store: IdempotencyStore
+  readonly ttlMs: number
+  readonly headerName: string
+  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
+  readonly maxResponseBytes: number
+}
+
+/**
+ * What the dedupe lane needs from the server to run a fresh key: the app-wide body cap and a way to
+ * run the buffered request through the route's normal lanes to a concrete `Response`.
+ */
+export interface IdempotencyHost {
+  readonly maxBodyBytes: number
+  runLanes(
+    buffered: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+  ): Promise<Response>
+}
+
+/** The injected idempotency implementation the kernel calls through when the plugin is installed. */
+export interface IdempotencyRuntime {
+  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+  resolve(
+    schema: RouteSchema | undefined,
+    authenticated: boolean,
+    maxBodyBytes: number,
+  ): ResolvedIdempotency | undefined
+  /** The dedupe lane: read the key, fingerprint the request, consult the store, run/replay/reject. */
+  run<T>(
+    config: ResolvedIdempotency,
+    req: Request,
+    platform: Platform | undefined,
+    entry: unknown,
+    params: Record<string, string>,
+    search: string | undefined,
+    wrapResponse: (response: Response) => T,
+    host: IdempotencyHost,
+  ): Promise<T>
+}
+
+/** The install seam a server exposes so the `idempotency()` plugin can hand it a runtime. */
+interface IdempotencyInstallable {
+  [INSTALL_IDEMPOTENCY](runtime: IdempotencyRuntime): void
+}
+
+/**
+ * Enable request idempotency. Routes that declare `schema.idempotency` get the dedupe lane: a repeat
+ * `Idempotency-Key` replays the stored response instead of re-running the handler. Without this plugin,
+ * declaring `schema.idempotency` is a registration error (the safety gate can never be silently
+ * dropped). `store` is the app-wide default backing routes that do not pin their own; omit it for a
+ * shared in-process store (development/tests only - inject a durable store in production).
+ */
+export interface IdempotencyPluginOptions {
+  readonly store?: IdempotencyStore | undefined
+}
+
+export function idempotency(options?: IdempotencyPluginOptions): IdentityPlugin {
+  const runtime = createIdempotencyRuntime(options)
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as IdempotencyInstallable)[INSTALL_IDEMPOTENCY](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:idempotency" }) as IdentityPlugin
+}
+
+const RESPONSE_2XX_LOWER = 200
+const RESPONSE_2XX_UPPER = 300
+
+/**
+ * Build an idempotency runtime. `store` is the app-wide default backing routes that declare
+ * `schema.idempotency` without their own `store`; when omitted, a shared in-process
+ * {@link MemoryIdempotencyStore} is created lazily on first idempotent route.
+ */
+export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): IdempotencyRuntime {
+  const configuredStore = options?.store
+  let lazyStore: IdempotencyStore | undefined
+  const defaultStore = (): IdempotencyStore => {
+    if (configuredStore !== undefined) return configuredStore
+    lazyStore ??= new MemoryIdempotencyStore()
+    return lazyStore
+  }
+
+  return {
+    resolve(schema, authenticated, maxBodyBytes) {
+      const config = schema?.idempotency
+      if (config === undefined) return undefined
+      if (schema?.sse !== undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "streaming/SSE responses cannot be used on an idempotency route",
+        )
+      }
+      const store = config.store ?? defaultStore()
+      if (config.scope === "durable" && store.durability !== "durable") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          'durable idempotency requires a durable store (store.durability must be "durable")',
+        )
+      }
+      const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS
+      if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency ttlMs must be a finite positive number",
+        )
+      }
+      const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
+      try {
+        new Headers().set(headerName, "probe")
+      } catch {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency header name ${JSON.stringify(headerName)}`,
+        )
+      }
+      const namespace = config.namespace
+      if (namespace === undefined) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency namespace is required; use a principal resolver or an explicit shared scope",
+        )
+      }
+      if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+        )
+      }
+      if (authenticated && typeof namespace !== "function") {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "authenticated idempotency routes require a principal namespace resolver",
+        )
+      }
+      const maxResponseBytes = config.maxResponseBytes ?? maxBodyBytes
+      if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+        throw new RouteConfigError(
+          "INVALID_IDEMPOTENCY",
+          "idempotency maxResponseBytes must be a positive integer",
+        )
+      }
+      return Object.freeze({
+        store,
+        ttlMs,
+        headerName,
+        namespace,
+        maxResponseBytes,
+      })
+    },
+
+    async run(config, req, platform, entry, params, search, wrapResponse, host) {
+      const key = req.headers.get(config.headerName)
+      if (key === null || !validIdempotencyKey(key)) {
+        return wrapResponse(jsonError(400, "idempotency_key_required"))
+      }
+      const namespace =
+        typeof config.namespace === "function"
+          ? await config.namespace(req.clone(), platform)
+          : config.namespace
+      if (!validIdempotencyNamespace(namespace)) {
+        return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
+      }
+      const read = await readBoundedBytes(req, host.maxBodyBytes)
+      if (!read.ok) {
+        return wrapResponse(
+          jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"),
+        )
+      }
+      const url = urlPartsOf(req.url)
+      const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"))
+      const fingerprint = await computeIdempotencyFingerprint(
+        req.method,
+        `${url.pathname}${url.search}`,
+        canonicalBody,
+        req.headers.get("content-type") ?? "",
+      )
+
+      const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+      if (begin.state === "replay") {
+        return wrapResponse(
+          responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
+        )
+      }
+      if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
+      if (begin.state === "in-flight") {
+        return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
+      }
+      if (begin.state === "capacity") {
+        return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
+      }
+      const reservation = begin.reservation
+
+      // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+      // then run those lanes to a concrete Response.
+      const bufferedInit: RequestInit = {
+        method: req.method,
+        headers: req.headers,
+        signal: req.signal,
+      }
+      if (read.bytes.byteLength > 0)
+        bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+      const buffered = new Request(req.url, bufferedInit)
+      let response: Response
+      try {
+        response = await host.runLanes(buffered, platform, entry, params, search)
+      } catch (err) {
+        // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
+        // reservation so a retry isn't wedged, then re-throw.
+        await config.store.abandon({ namespace, key, reservation })
+        throw err
+      }
+      // Cache only successful responses; release the key on any error so the client can retry.
+      if (response.status >= RESPONSE_2XX_LOWER && response.status < RESPONSE_2XX_UPPER) {
+        let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+        try {
+          storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+        } catch (error) {
+          if (!(error instanceof IdempotencyResponseTooLargeError)) throw error
+          // The effect may already have happened, so never abandon and permit a duplicate execution.
+          // Commit a small terminal response under the winning key and return that same response now.
+          response = jsonError(507, "idempotency_response_too_large")
+          try {
+            storedResponse = await serializeResponse(response, {
+              maxBytes: config.maxResponseBytes,
+            })
+          } catch (terminalError) {
+            if (!(terminalError instanceof IdempotencyResponseTooLargeError)) throw terminalError
+            // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+            // status + replay safety without silently storing more bytes than the route permits.
+            response = new Response(null, { status: 507 })
+            storedResponse = await serializeResponse(response, {
+              maxBytes: config.maxResponseBytes,
+            })
+          }
+        }
+        const completed = await config.store.complete({
+          namespace,
+          key,
+          reservation,
+          response: storedResponse,
+        })
+        if (!completed) {
+          return wrapResponse(
+            jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }),
+          )
+        }
+      } else {
+        await config.store.abandon({ namespace, key, reservation })
+      }
+      return wrapResponse(response)
+    },
+  }
+}

package/src/server/install.ts

@@ -0,0 +1,28 @@
+/**
+ * Symbol-keyed install seams the opt-in feature plugins (`idempotency()`, `effectLedger()`) use to
+ * hand their runtime to a server. Kept in a dependency-free leaf, and keyed by symbol, so:
+ *   - the kernel can implement the seam without importing a feature's code (importing a bare symbol
+ *     never drags the lane's implementation into the base bundle), and
+ *   - the seam stays off the server's public typed surface (symbol-keyed methods are not part of it).
+ * Both sides reference the SAME registered symbol, so no module has to import the other.
+ */
+
+/** @internal Install the idempotency runtime on a server (called by the `idempotency()` plugin). */
+export const INSTALL_IDEMPOTENCY: unique symbol = Symbol.for("@nifrajs/core/install-idempotency")
+
+/** @internal Install the effect-ledger runtime on a server (called by the `effectLedger()` plugin). */
+export const INSTALL_EFFECT_LEDGER: unique symbol = Symbol.for(
+  "@nifrajs/core/install-effect-ledger",
+)
+
+/** @internal Install the MCP runtime on a server (called by the `mcp()` plugin). */
+export const INSTALL_MCP: unique symbol = Symbol.for("@nifrajs/core/install-mcp")
+
+/** @internal Install the SSE streaming runtime on a server (called by the `sse()` plugin). */
+export const INSTALL_SSE: unique symbol = Symbol.for("@nifrajs/core/install-sse")
+
+/** @internal Install the Node-direct renderer on a server (called by the `nodeDirect()` plugin). */
+export const INSTALL_NODE_DIRECT: unique symbol = Symbol.for("@nifrajs/core/install-node-direct")
+
+/** @internal Install the WebSocket runtime on a server (called by the `websocket()` plugin). */
+export const INSTALL_WS: unique symbol = Symbol.for("@nifrajs/core/install-ws")

package/src/server/ledger-lane.ts

@@ -0,0 +1,125 @@
+/**
+ * The opt-in per-request effect ledger. Installed by `.use(effectLedger())` and reached only by routes
+ * that declare `schema.capabilities`, so the kernel never statically imports this code: a bare
+ * `server()` tree-shakes the ledger machinery out.
+ *
+ * The kernel resolves a capability-declaring route's ledger wiring at registration (via
+ * {@link EffectLedgerRuntime.resolve}) and, on the request path, creates + attaches a ledger before the
+ * handler and settles it after (via {@link EffectLedgerRuntime.create}/`attach`/`settle`). Nothing here
+ * depends on server internals; the sink-error log is supplied per settle.
+ */
+import {
+  attachEffectLedger,
+  createRequestLedger,
+  DEFAULT_MAX_ENTRIES,
+  type EffectLedgerOptions,
+  type RequestLedger,
+} from "../ledger.ts"
+import { INSTALL_EFFECT_LEDGER } from "./install.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
+export interface ResolvedEffectLedger {
+  readonly sink: EffectLedgerOptions["sink"]
+  readonly maxEntries: number
+  readonly chain: boolean
+  /** The registered route pattern - what the sealed ledger names (never the concrete URL). */
+  readonly method: string
+  readonly path: string
+  /** The route's declared capability tokens, surfaced on the sealed ledger. */
+  readonly declared: readonly string[]
+}
+
+/** The injected effect-ledger implementation the kernel calls through when the plugin is installed. */
+export interface EffectLedgerRuntime {
+  /** Resolve a capability-declaring route into its ledger wiring, or `undefined` when it declares none. */
+  resolve(
+    capabilities: readonly string[],
+    method: string,
+    path: string,
+  ): ResolvedEffectLedger | undefined
+  /** Create the per-request ledger for a ledgered route. */
+  create(resolved: ResolvedEffectLedger): RequestLedger
+  /** Attach a ledger to the request context so `useCapability` can append to it. */
+  attach(context: object, ledger: RequestLedger): void
+  /** Seal the ledger and deliver it to the sink (empty ledgers are not delivered). */
+  settle<T>(
+    ledger: RequestLedger,
+    resolved: ResolvedEffectLedger,
+    value: T,
+    onSinkError: (fields: { method: string; path: string; name: string }) => void,
+  ): Promise<T>
+}
+
+/**
+ * Build an effect-ledger runtime from the app-wide options. `sink` receives the sealed, token-only
+ * ledger when a capability-declaring route settles with recorded entries; `maxEntries` bounds a single
+ * request's ledger; `chain` opts into the per-entry hash chain.
+ */
+export function createEffectLedgerRuntime(options: EffectLedgerOptions): EffectLedgerRuntime {
+  if (typeof options.sink !== "function") {
+    throw new TypeError("effectLedger.sink must be a function")
+  }
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+    throw new RangeError("effectLedger.maxEntries must be a positive safe integer")
+  }
+  const chain = options.chain ?? false
+  const sink = options.sink
+
+  return {
+    resolve(capabilities, method, path) {
+      if (capabilities.length === 0) return undefined
+      return Object.freeze({ sink, maxEntries, chain, method, path, declared: capabilities })
+    },
+    create(resolved) {
+      return createRequestLedger({
+        method: resolved.method,
+        path: resolved.path,
+        declared: resolved.declared,
+        maxEntries: resolved.maxEntries,
+        chain: resolved.chain,
+      })
+    },
+    attach(context, ledger) {
+      attachEffectLedger(context, ledger)
+    },
+    async settle(ledger, resolved, value, onSinkError) {
+      const sealed = await ledger.seal()
+      if (sealed.entries.length === 0) return value
+      try {
+        await resolved.sink(sealed)
+      } catch (err) {
+        // Token-only: the route pattern and the failure name - never entry payloads (there are none)
+        // and never the request. The ledger is observational, so a sink outage never fails the effect.
+        onSinkError({
+          method: resolved.method,
+          path: resolved.path,
+          name: err instanceof Error ? err.name : "Error",
+        })
+      }
+      return value
+    },
+  }
+}
+
+/** The install seam a server exposes so the `effectLedger()` plugin can hand it a runtime. */
+interface EffectLedgerInstallable {
+  [INSTALL_EFFECT_LEDGER](runtime: EffectLedgerRuntime): void
+}
+
+/**
+ * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a bounded,
+ * token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink receives the
+ * sealed ledger when the response settles (only when it recorded entries). Token-only by construction -
+ * capability ids, phases, counters, digests; never payloads, values, or the concrete URL (the route
+ * pattern is recorded). Without this plugin, capability-declaring routes simply carry no ledger.
+ */
+export function effectLedger(options: EffectLedgerOptions): IdentityPlugin {
+  const runtime = createEffectLedgerRuntime(options)
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as EffectLedgerInstallable)[INSTALL_EFFECT_LEDGER](runtime)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:effect-ledger" }) as IdentityPlugin
+}

package/src/server/mcp-hook.ts

@@ -0,0 +1,41 @@
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import type { Context, RouteSchema } from "./context.ts"
+import type {
+  McpPromptDescriptor,
+  McpResourceDescriptor,
+  PromptArgument,
+  RouteDescriptor,
+  ToolAnnotations,
+} from "./server-types.ts"
+
+export interface McpToolConfig {
+  readonly description: string
+  readonly input: StandardSchemaV1
+  readonly output?: StandardSchemaV1
+  readonly annotations?: ToolAnnotations
+}
+
+export interface McpToolPlan {
+  readonly path: string
+  readonly schema: RouteSchema
+  readonly run: (context: Context) => unknown
+  readonly descriptor: NonNullable<RouteDescriptor["tool"]>
+}
+
+export interface McpRuntime {
+  tool(
+    name: string,
+    config: McpToolConfig,
+    handler: (input: unknown, context: Context) => unknown,
+  ): McpToolPlan
+  resource(
+    uri: string,
+    config: { readonly name: string; readonly description?: string; readonly mimeType?: string },
+    read: McpResourceDescriptor["read"],
+  ): McpResourceDescriptor
+  prompt(
+    name: string,
+    config: { readonly description: string; readonly arguments?: readonly PromptArgument[] },
+    handler: McpPromptDescriptor["handler"],
+  ): McpPromptDescriptor
+}

package/src/server/node-outcome-hook.ts

@@ -0,0 +1,9 @@
+/** Lazy Node-direct renderer seam. The base server retains the typed method but not its renderer. */
+import type { NodeServeOutcome } from "./node-outcome.ts"
+import type { CtxSet } from "./server.ts"
+
+export interface NodeOutcomeRuntime {
+  toOutcome(result: unknown, set: CtxSet): NodeServeOutcome
+  fromResponse(response: Response): NodeServeOutcome
+  timeout(): NodeServeOutcome
+}

package/src/server/node-outcome.ts

@@ -0,0 +1,112 @@
+/**
+ * Node-direct outcome shaping: the `@nifrajs/node` bridge's render form and the `Response` -> outcome
+ * conversion. Mirrors `respond.ts` but skips the undici `Response` build where the adapter can write a
+ * plain-data render straight to the socket. Imports only runtime-core + respond + the spine types.
+ */
+import { appendCookiesToResponse } from "./respond.ts"
+import { type HandlerResult, isResponseResult } from "./runtime-core.ts"
+import type { CtxSet } from "./server.ts"
+
+/**
+ * What {@link Server.resolveNode} returns: either a plain-data render the `@nifrajs/node` adapter writes
+ * to the socket directly (`kind: "json"` - status + headers + cookies + a pre-stringified body, **no**
+ * undici `Response` built or drained), a marked buffered response body (`kind: "body"` - e.g.
+ * @nifrajs/web's non-deferred SSR HTML), or a `Response` (`kind: "response"`) for everything else
+ * (redirects, 404/405/errors, unmarked or streaming bodies). Internal to the nifra<->node bridge.
+ */
+export type NodeServeOutcome =
+  | { readonly kind: "response"; readonly response: Response }
+  | {
+      readonly kind: "json"
+      readonly status: number
+      /** `c.set.headers` backing, or `undefined` when the handler never set a header. */
+      readonly headers: Readonly<Record<string, string>> | undefined
+      /** Queued `Set-Cookie` lines, or `undefined`; the adapter emits one header line each. */
+      readonly cookies: readonly string[] | undefined
+      /** The JSON body already stringified, or `null` for an empty (204) response. */
+      readonly body: string | null
+    }
+  | {
+      readonly kind: "body"
+      readonly status: number
+      readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
+      readonly body: string | Uint8Array
+    }
+
+/**
+ * `finalize` for the node-direct path - mirror of `toResponse` that skips the `Response` build:
+ * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
+ * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
+ * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
+ * works on Node).
+ */
+export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutcome {
+  if (isResponseResult(result)) {
+    const body = result.toNodeBody?.()
+    if (body !== undefined) {
+      return {
+        kind: "body",
+        status: body.status,
+        headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+        body: body.body,
+      }
+    }
+    return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set))
+  }
+  if (result instanceof Response) {
+    return nodeOutcomeFromResponse(appendCookiesToResponse(result, set))
+  }
+  const status = set.status ?? (result === undefined ? 204 : 200)
+  return {
+    kind: "json",
+    status,
+    headers: set._headers,
+    cookies: set._cookies,
+    body: result === undefined ? null : JSON.stringify(result),
+  }
+}
+
+const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
+
+export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
+  const body = nodeResponseBody(response)
+  return body === undefined
+    ? { kind: "response", response }
+    : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body }
+}
+
+function nodeResponseBody(response: Response): string | Uint8Array | undefined {
+  if (response.bodyUsed) return undefined
+  const body = (response as { readonly [NODE_RESPONSE_BODY]?: unknown })[NODE_RESPONSE_BODY]
+  return typeof body === "string" || body instanceof Uint8Array ? body : undefined
+}
+
+function responseHeadersForNode(
+  response: Response,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  let headers: Record<string, string | readonly string[]> | undefined
+  response.headers.forEach((value, key) => {
+    headers ??= {}
+    headers[key] = value
+  })
+  const setCookies = response.headers.getSetCookie?.()
+  if (setCookies !== undefined && setCookies.length > 0) {
+    headers ??= {}
+    headers["set-cookie"] = setCookies
+  }
+  return headers
+}
+
+function appendCookiesToNodeHeaders(
+  headers: Readonly<Record<string, string | readonly string[]>> | undefined,
+  cookies: readonly string[] | undefined,
+): Readonly<Record<string, string | readonly string[]>> | undefined {
+  if (cookies === undefined || cookies.length === 0) return headers
+  const out: Record<string, string | readonly string[]> =
+    headers === undefined ? {} : { ...headers }
+  const existing = out["set-cookie"]
+  const setCookies =
+    existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing]
+  out["set-cookie"] = [...setCookies, ...cookies]
+  return out
+}