@nifrajs/core 1.13.0 → 2.1.0

package/src/server/sse-hook.ts

@@ -0,0 +1,14 @@
+/**
+ * The `SseRuntime` contract - the streaming implementation that `.use(streaming())` installs (from
+ * `@nifrajs/core/sse`). `server.ts` type-imports only this, so the ReadableStream framing code stays
+ * out of a bare server bundle until a route opts in.
+ */
+import type { SSEContext, SSEInit, TypedSSEStream } from "./sse.ts"
+
+export interface SseRuntime {
+  response<Event>(
+    context: SSEContext,
+    run: (stream: TypedSSEStream<Event>) => void | Promise<void>,
+    init?: SSEInit,
+  ): Response
+}

package/src/server/sse.ts

@@ -21,6 +21,10 @@
  *       stream.signal.addEventListener("abort", () => { off(); resolve() }, { once: true }))
  *   }, { keepAlive: 15_000 }))
  */
+import { INSTALL_SSE } from "./install.ts"
+import type { IdentityPlugin } from "./plugin.ts"
+import type { AnyServer } from "./server.ts"
+import type { SseRuntime } from "./sse-hook.ts"
 
 /** One SSE frame. Every field is optional; `data` may be multi-line (emitted as multiple `data:` lines). */
 export interface SSEMessage {
@@ -188,3 +192,25 @@ export function sse(
   if (!headers.has("x-accel-buffering")) headers.set("x-accel-buffering", "no") // defeat proxy buffering
   return new Response(body, { status: init.status ?? 200, headers })
 }
+
+/** The install seam a server exposes so the `streaming()` plugin can hand it the runtime. */
+interface SseInstallable {
+  [INSTALL_SSE](runtime: SseRuntime): void
+}
+
+/**
+ * Enable `.sse()` streaming routes: `.use(streaming())` installs the SSE runtime. Without it, an
+ * `.sse()` route is a registration error, so the ReadableStream framing stays out of non-SSE bundles.
+ * The `sse()` / `typedSSEStream()` helpers ship from this same subpath for use inside handlers.
+ */
+export function streaming(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as SseInstallable)[INSTALL_SSE]({
+      response(context, run, init) {
+        return sse(context, (stream) => run(typedSSEStream(stream)), init)
+      },
+    })
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:streaming" }) as IdentityPlugin
+}

package/src/server/transport-lane.ts

@@ -0,0 +1,141 @@
+/** Opt-in versioned transport integration. Kept outside the server kernel's bare dependency graph. */
+import type { TransportCodec, TransportCodecRegistry } from "../transport-codec.ts"
+import { readBoundedBytes } from "./body.ts"
+import { jsonError } from "./http.ts"
+import { isResponseResult } from "./runtime-core.ts"
+import type { AnyServer, IdentityPlugin } from "./server.ts"
+
+interface TransportBodySource {
+  readonly headers: Pick<Headers, "get">
+  readonly body: ReadableStream<Uint8Array> | null
+  arrayBuffer(): Promise<ArrayBuffer>
+}
+
+export type TransportDecodeResult =
+  | { readonly matched: false }
+  | { readonly matched: true; readonly value: unknown }
+  | { readonly matched: true; readonly response: Response }
+
+export interface TransportRuntime {
+  responseCodec(accept: string | null): TransportCodec
+  decodeRequest(
+    source: TransportBodySource,
+    contentType: string,
+    maxBytes: number,
+  ): Promise<TransportDecodeResult>
+}
+
+export interface TransportCodecsOptions {
+  /** Maximum encoded request bytes. Keep aligned with `server({ maxBodyBytes })`. */
+  readonly maxBytes?: number
+}
+
+export function transportCodecs(
+  registry: TransportCodecRegistry,
+  options: TransportCodecsOptions = {},
+): IdentityPlugin {
+  const maxBytes = options.maxBytes ?? 1_000_000
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw new RangeError("transport maxBytes must be a non-negative safe integer")
+  }
+  const runtime: TransportRuntime = Object.freeze({
+    responseCodec(accept: string | null): TransportCodec {
+      try {
+        return registry.negotiate(accept)
+      } catch {
+        return registry.fallback
+      }
+    },
+    async decodeRequest(
+      source: TransportBodySource,
+      contentType: string,
+      maxBytes: number,
+    ): Promise<TransportDecodeResult> {
+      let codec: TransportCodec
+      try {
+        codec = registry.forContentType(contentType)
+      } catch {
+        return { matched: false }
+      }
+      if (codec.id === "json" && codec.version === 1 && codec.mediaType === "application/json")
+        return { matched: false }
+      const read = await readBoundedBytes(source, maxBytes)
+      if (!read.ok) {
+        return {
+          matched: true,
+          response: jsonError(
+            read.status,
+            read.status === 413 ? "payload_too_large" : "bad_request",
+          ),
+        }
+      }
+      try {
+        return {
+          matched: true,
+          value: codec.decode(new TextDecoder("utf-8", { fatal: true }).decode(read.bytes)),
+        }
+      } catch {
+        return {
+          matched: true,
+          response: jsonError(400, "invalid_transport_payload"),
+        }
+      }
+    },
+  })
+  const apply = <S extends AnyServer>(app: S): S => {
+    app.onRequest(async (request) => {
+      const contentType = request.headers.get("content-type") ?? ""
+      let requestCodec: TransportCodec
+      try {
+        requestCodec = registry.forContentType(contentType)
+      } catch {
+        return undefined
+      }
+      if (
+        requestCodec.id === "json" &&
+        requestCodec.version === 1 &&
+        requestCodec.mediaType === "application/json"
+      ) {
+        return undefined
+      }
+      const replacement = request.clone()
+      const decoded = await runtime.decodeRequest(request, contentType, maxBytes)
+      if (!decoded.matched) return undefined
+      if ("response" in decoded) return decoded.response
+
+      // Keep an untouched body branch while the bounded decoder consumes the other tee branch.
+      // Existing JSON validation lanes can then use their native `request.json()` fast path while
+      // receiving the already-decoded rich value without importing codec machinery into the kernel.
+      const headers: Record<string, string> = {}
+      replacement.headers.forEach((value, name) => {
+        headers[name] = value
+      })
+      headers["content-type"] = "application/json"
+      headers["content-length"] = "2"
+      delete headers["transfer-encoding"]
+      const normalized = new Request(replacement.url, {
+        method: replacement.method,
+        headers,
+        body: "{}",
+        signal: replacement.signal as never,
+      })
+      Object.defineProperty(normalized, "json", {
+        value: () => Promise.resolve(decoded.value),
+      })
+      return normalized
+    })
+    app.afterHandle((result, context) => {
+      if (result === undefined || result instanceof Response || isResponseResult(result))
+        return result
+      const codec = runtime.responseCodec(context.req.headers.get("accept"))
+      const headers = new Headers(context.set.headers)
+      headers.set("content-type", codec.mediaType)
+      return new Response(codec.encode(result), {
+        status: context.set.status ?? 200,
+        headers,
+      })
+    })
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:transport-codecs" }) as IdentityPlugin
+}

package/src/server/websocket.ts

@@ -16,6 +16,7 @@ import type {
   ValidationOutcome,
 } from "../schema/standard.ts"
 import { validateStandard } from "../schema/standard.ts"
+import { decodeTransportFrame, type TransportCodecRegistry } from "../transport-codec.ts"
 
 type MaybePromise<T> = T | Promise<T>
 
@@ -130,6 +131,7 @@ export interface WebSocketHandler<
   Data = unknown,
   Env = unknown,
   Schema extends StandardSchemaV1 | undefined = undefined,
+  Send extends StandardSchemaV1 | undefined = undefined,
 > {
   /**
    * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not
@@ -159,6 +161,18 @@ export interface WebSocketHandler<
    * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).
    */
   messageSchema?: Schema
+  /**
+   * The **outbound** frame contract (server → client), a Standard Schema. Purely type-level: it types
+   * the frames the typed client's `.ws()` handle receives, and documents what this route pushes. The
+   * server does NOT runtime-validate its own sends - the inbound `messageSchema` guards the trust
+   * boundary; outbound honesty is the handler author's code, checked by tests.
+   */
+  sendSchema?: Send
+  /** Decode versioned transport frames before inbound schema validation. Omit for legacy JSON. */
+  transport?: {
+    readonly registry: TransportCodecRegistry
+    readonly maxBytes?: number
+  }
   open?(ws: NifraWebSocket<Data>): MaybePromise<void>
   message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>
   /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is
@@ -189,8 +203,20 @@ export type WebSocketUpgradeOutcome =
       readonly data: unknown
       /** The app's pub/sub registry — the adapter wires `ws.subscribe` + close-cleanup to it. */
       readonly pubsub: TopicRegistry
+      /** The installed runtime's {@link attachWebSocket}, carried on the outcome so an adapter can wire
+       * a standard socket without a static import of the WS implementation (which would defeat the
+       * `.use(websocket())` tree-shaking). `@nifrajs/workers` may import `attachWebSocket` directly instead. */
+      readonly attach: WsAttach
     }
 
+/** The socket-wiring signature the upgrade outcome carries (the installed runtime's `attach`). */
+export type WsAttach = (
+  socket: StandardWebSocket,
+  handler: WebSocketHandler,
+  data: unknown,
+  options: { openNow: boolean; pubsub: TopicRegistry },
+) => NifraWebSocket
+
 /**
  * A standard server-side `WebSocket` — the half returned by Deno's `Deno.upgradeWebSocket` and the
  * Workers `WebSocketPair`. {@link attachWebSocket} wires one to a nifra handler, so the Deno and Workers
@@ -297,7 +323,15 @@ export function wrapWebSocketMessageValidation(handler: WebSocketHandler): WebSo
   const validatingMessage = (ws: NifraWebSocket, raw: WebSocketData): MaybePromise<void> => {
     let parsed: unknown
     try {
-      parsed = JSON.parse(typeof raw === "string" ? raw : WS_MESSAGE_DECODER.decode(raw))
+      const text = typeof raw === "string" ? raw : WS_MESSAGE_DECODER.decode(raw)
+      parsed =
+        handler.transport === undefined
+          ? JSON.parse(text)
+          : decodeTransportFrame(text, handler.transport.registry, {
+              ...(handler.transport.maxBytes === undefined
+                ? {}
+                : { maxBytes: handler.transport.maxBytes }),
+            })
     } catch {
       return onInvalid?.(ws, [{ message: "invalid JSON" }], raw)
     }

package/src/server/ws-hook.ts

@@ -1,10 +1,11 @@
 /**
- * Lazy WebSocket runtime seam. `server.ts` never imports the WS implementation statically — the
- * `@nifrajs/core/ws` subpath entry registers it here on import. That keeps the WS dispatcher, pub/sub
- * registry, Bun socket plumbing, and message-schema validation out of the base server bundle for
- * apps that never call `app.ws()` (~1.5 KB gzipped on the minimal-app benchmark).
+ * WebSocket runtime contract. `server.ts` type-imports only this; the `.use(websocket())` plugin
+ * (from `@nifrajs/core/ws`) installs the implementation on a server instance via the `INSTALL_WS`
+ * symbol seam. That keeps the WS dispatcher, pub/sub registry, Bun socket plumbing, and
+ * message-schema validation out of the base server bundle for apps that never call `app.ws()`
+ * (~1.5 KB gzipped on the minimal-app benchmark).
  *
- * Only type imports below — this module must stay weightless, it is always in the base bundle.
+ * Only type declarations below - this module must stay weightless, it is always in the base bundle.
  */
 
 import type {
@@ -25,13 +26,13 @@ export interface BunWsHandlers {
 
 /** What `@nifrajs/core/ws` registers: everything `server.ts` and `toFetchHandler` need at runtime. */
 export interface WsRuntime {
-  /** `wrapWebSocketMessageValidation` — applied once at `app.ws()` registration. */
+  /** `wrapWebSocketMessageValidation` - applied once at `app.ws()` registration. */
   wrapHandler(handler: WebSocketHandler): WebSocketHandler
   /** One in-process pub/sub registry per app (backs `ws.subscribe` + `app.publish`). */
   createTopics(): TopicRegistry
   /** The Bun `websocket` config for `listen()` when the app has WS routes. */
   bunHandlers(topics: TopicRegistry): BunWsHandlers
-  /** `attachWebSocket` — wires a standard server socket (Workers `WebSocketPair`) to a handler. */
+  /** `attachWebSocket` - wires a standard server socket (Workers `WebSocketPair`) to a handler. */
   attach(
     socket: StandardWebSocket,
     handler: WebSocketHandler,
@@ -39,15 +40,3 @@ export interface WsRuntime {
     options: { openNow: boolean; pubsub: TopicRegistry },
   ): NifraWebSocket
 }
-
-let runtime: WsRuntime | undefined
-
-/** Called by `@nifrajs/core/ws` on import. Last registration wins (idempotent in practice — there is
- * one implementation; double-import is a no-op re-set of the same functions). */
-export function setWsRuntime(impl: WsRuntime): void {
-  runtime = impl
-}
-
-export function getWsRuntime(): WsRuntime | undefined {
-  return runtime
-}

package/src/server.ts

@@ -0,0 +1,92 @@
+/**
+ * Lean server entry for the common Nifra runtime.
+ *
+ * Use `@nifrajs/core/server` or the equivalent lean package root when building an HTTP app.
+ * Optional systems such as
+ * causality, invariants, manifests, reflection, and capability tooling live at
+ * their dedicated subpaths. Keeping this entry curated is intentional: do not
+ * export an opt-in module here unless the Server implementation already loads it.
+ */
+
+export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
+export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
+export type {
+  InferInput,
+  InferOutput,
+  StandardIssue,
+  StandardResult,
+  StandardSchemaV1,
+  StandardTypes,
+  ValidationOutcome,
+} from "./schema/standard.ts"
+export type {
+  Context,
+  Params,
+  Platform,
+  Prettify,
+  ResponseControls,
+  RouteSchema,
+} from "./server/context.ts"
+export {
+  type CookieOptions,
+  parseCookies,
+  serializeCookie,
+  signValue,
+  unsignValue,
+} from "./server/cookies.ts"
+export {
+  commonSecretPatterns,
+  jsonLogger,
+  type LogFields,
+  type Logger,
+  type RedactOptions,
+  redactLogFields,
+  silentLogger,
+} from "./server/logger.ts"
+export type { Registry, RouteInfo } from "./server/registry.ts"
+export {
+  type AdmissionController,
+  type AdmissionDecision,
+  type AnyServer,
+  type DurableObjectNamespaceLike,
+  defineIdentityPlugin,
+  definePlugin,
+  defineRouterPlugin,
+  type ExecutionContext,
+  type Handler,
+  type IdentityPlugin,
+  type McpPromptDescriptor,
+  type McpResourceDescriptor,
+  type Middleware,
+  type NifraPlugin,
+  type NodeServeOutcome,
+  type OnRequestResult,
+  type PromptArgument,
+  type PromptMessage,
+  type ResponseFinalization,
+  type RouteDescriptor,
+  type RunningServer,
+  type ScheduledController,
+  type ScheduledHandler,
+  Server,
+  type ServerOptions,
+  server,
+  type ToolAnnotations,
+  toFetchHandler,
+} from "./server/server.ts"
+export type {
+  SSEContext,
+  SSEInit,
+  SSEMessage,
+  SSEStream,
+  TypedSSEStream,
+} from "./server/sse.ts"
+export type {
+  NifraWebSocket,
+  StandardWebSocket,
+  WebSocketContext,
+  WebSocketData,
+  WebSocketHandler,
+  WebSocketUpgradeOutcome,
+} from "./server/websocket.ts"

package/src/transport-codec-rich.ts

@@ -0,0 +1,20 @@
+/** Opt-in rich-wire transport adapter. Kept separate so a bare server never bundles rich values. */
+import type { TransportCodec } from "./transport-codec.ts"
+import { parse as parseWire, stringify as stringifyWire, type WireDecodeLimits } from "./wire.ts"
+
+export interface RichWireCodecOptions {
+  readonly limits?: WireDecodeLimits
+}
+
+export function richWireCodec(options: RichWireCodecOptions = {}): TransportCodec {
+  const limits = Object.freeze({ ...(options.limits ?? {}) })
+  return Object.freeze({
+    id: "wire",
+    version: 1,
+    mediaType: "application/vnd.nifra.wire+json;v=1",
+    encode: stringifyWire,
+    decode(text: string): unknown {
+      return parseWire(text, limits)
+    },
+  })
+}

package/src/transport-codec.ts

@@ -0,0 +1,250 @@
+/**
+ * Versioned, bounded codecs shared by HTTP bodies, loader streams, and WebSocket frames. Plain JSON
+ * remains the zero-configuration fast path; rich wire is explicit and preserves non-JSON values.
+ */
+
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024
+const TOKEN = /^[a-z][a-z0-9_.-]{0,63}$/
+
+export interface TransportDecodeOptions {
+  readonly maxBytes?: number
+}
+
+export interface TransportCodec {
+  readonly id: string
+  readonly version: number
+  readonly mediaType: string
+  encode(value: unknown): string
+  decode(text: string): unknown
+}
+
+export class TransportCodecError extends TypeError {
+  constructor(message: string) {
+    super(message)
+    this.name = "TransportCodecError"
+  }
+}
+
+function maxBytesOf(options: TransportDecodeOptions): number {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+    throw new RangeError("transport maxBytes must be a non-negative safe integer")
+  return maxBytes
+}
+
+function byteLength(text: string): number {
+  return new TextEncoder().encode(text).byteLength
+}
+
+function assertBounded(text: string, options: TransportDecodeOptions): void {
+  if (byteLength(text) > maxBytesOf(options)) {
+    throw new TransportCodecError("transport payload exceeds maxBytes")
+  }
+}
+
+export const plainJsonCodec: TransportCodec = Object.freeze({
+  id: "json",
+  version: 1,
+  mediaType: "application/json",
+  encode(value: unknown): string {
+    const encoded = JSON.stringify(value)
+    if (encoded === undefined) throw new TransportCodecError("value is not JSON serializable")
+    return encoded
+  },
+  decode(text: string): unknown {
+    return JSON.parse(text)
+  },
+})
+
+export interface TransportCodecRegistry {
+  readonly fallback: TransportCodec
+  forContentType(contentType: string | null): TransportCodec
+  negotiate(accept: string | null): TransportCodec
+  byIdentity(id: string, version: number): TransportCodec
+}
+
+function canonicalMediaType(value: string): string {
+  return value
+    .split(";")
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean)
+    .join(";")
+}
+
+export function createTransportCodecRegistry(
+  codecs: readonly TransportCodec[],
+  fallback: TransportCodec = plainJsonCodec,
+): TransportCodecRegistry {
+  if (codecs.length === 0) throw new TypeError("transport codec registry cannot be empty")
+  const byMedia = new Map<string, TransportCodec>()
+  const byId = new Map<string, TransportCodec>()
+  for (const codec of codecs) {
+    if (!TOKEN.test(codec.id)) throw new TypeError("transport codec id is invalid")
+    if (!Number.isSafeInteger(codec.version) || codec.version < 1)
+      throw new TypeError("transport codec version must be a positive safe integer")
+    if (typeof codec.encode !== "function" || typeof codec.decode !== "function")
+      throw new TypeError("transport codec must provide encode and decode")
+    const media = canonicalMediaType(codec.mediaType)
+    const identity = `${codec.id}@${codec.version}`
+    if (byMedia.has(media) || byId.has(identity))
+      throw new TypeError("duplicate transport codec registration")
+    byMedia.set(media, codec)
+    byId.set(identity, codec)
+  }
+  if (!byId.has(`${fallback.id}@${fallback.version}`))
+    throw new TypeError("transport fallback must be registered")
+
+  const forContentType = (contentType: string | null): TransportCodec => {
+    if (contentType === null || contentType.trim() === "") return fallback
+    const canonical = canonicalMediaType(contentType)
+    const direct = byMedia.get(canonical)
+    if (direct !== undefined) return direct
+    const base = canonical.split(";")[0]
+    if (base === "application/json") {
+      const json = byId.get("json@1")
+      if (json !== undefined) return json
+    }
+    throw new TransportCodecError(`unsupported transport content type: ${contentType}`)
+  }
+
+  return Object.freeze({
+    fallback,
+    forContentType,
+    negotiate(accept: string | null) {
+      if (accept === null || accept.trim() === "" || accept.trim() === "*/*") return fallback
+      const candidates = accept
+        .split(",")
+        .map((candidate: string) => {
+          const quality = /;\s*q=([01](?:\.\d+)?)\s*$/iu.exec(candidate)
+          const q = quality === null ? 1 : Number(quality[1])
+          return {
+            media: quality === null ? candidate.trim() : candidate.slice(0, quality.index).trim(),
+            q,
+          }
+        })
+        .filter(
+          (candidate: { readonly media: string; readonly q: number }) =>
+            Number.isFinite(candidate.q) && candidate.q > 0 && candidate.q <= 1,
+        )
+        .sort(
+          (
+            a: { readonly media: string; readonly q: number },
+            b: { readonly media: string; readonly q: number },
+          ) => b.q - a.q,
+        )
+      for (const candidate of candidates) {
+        try {
+          return forContentType(candidate.media)
+        } catch {
+          // Try the next advertised representation.
+        }
+      }
+      throw new TransportCodecError("no acceptable transport codec")
+    },
+    byIdentity(id: string, version: number) {
+      const codec = byId.get(`${id}@${version}`)
+      if (codec === undefined)
+        throw new TransportCodecError(`unsupported transport codec: ${id}@${version}`)
+      return codec
+    },
+  })
+}
+
+export const defaultTransportCodecs: TransportCodecRegistry = createTransportCodecRegistry([
+  plainJsonCodec,
+])
+
+export function encodeTransportResponse(
+  value: unknown,
+  codec: TransportCodec = plainJsonCodec,
+  init: ResponseInit = {},
+): Response {
+  const headers = new Headers(init.headers as ConstructorParameters<typeof Headers>[0])
+  headers.set("content-type", codec.mediaType)
+  headers.set("vary", appendVary(headers.get("vary"), "accept"))
+  return new Response(codec.encode(value), { ...init, headers })
+}
+
+function appendVary(current: string | null, name: string): string {
+  if (current === null || current.trim() === "") return name
+  const values = current.split(",").map((value) => value.trim().toLowerCase())
+  return values.includes(name.toLowerCase()) ? current : `${current}, ${name}`
+}
+
+async function readBoundedText(
+  response: Response,
+  options: TransportDecodeOptions,
+): Promise<string> {
+  const maxBytes = maxBytesOf(options)
+  const declared = response.headers.get("content-length")
+  if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes)
+    throw new TransportCodecError("transport payload exceeds maxBytes")
+  if (response.body === null) return ""
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (!Number.isSafeInteger(total) || total > maxBytes) {
+        await reader.cancel()
+        throw new TransportCodecError("transport payload exceeds maxBytes")
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+}
+
+export async function decodeTransportResponse(
+  response: Response,
+  registry: TransportCodecRegistry = defaultTransportCodecs,
+  options: TransportDecodeOptions = {},
+): Promise<unknown> {
+  const codec = registry.forContentType(response.headers.get("content-type"))
+  const text = await readBoundedText(response, options)
+  return text === "" ? undefined : codec.decode(text)
+}
+
+interface TransportFrame {
+  readonly codec: string
+  readonly version: number
+  readonly payload: string
+}
+
+export function encodeTransportFrame(
+  value: unknown,
+  codec: TransportCodec = plainJsonCodec,
+): string {
+  return JSON.stringify({ codec: codec.id, version: codec.version, payload: codec.encode(value) })
+}
+
+export function decodeTransportFrame(
+  frame: string,
+  registry: TransportCodecRegistry = defaultTransportCodecs,
+  options: TransportDecodeOptions = {},
+): unknown {
+  assertBounded(frame, options)
+  const envelope = JSON.parse(frame) as Partial<TransportFrame>
+  if (
+    envelope === null ||
+    typeof envelope !== "object" ||
+    typeof envelope.codec !== "string" ||
+    !Number.isSafeInteger(envelope.version) ||
+    typeof envelope.payload !== "string"
+  ) {
+    throw new TransportCodecError("malformed transport frame")
+  }
+  assertBounded(envelope.payload, options)
+  return registry.byIdentity(envelope.codec, envelope.version as number).decode(envelope.payload)
+}

package/src/transport-plugin.ts

@@ -0,0 +1,2 @@
+/** Opt-in server integration for versioned transport codecs. */
+export { transportCodecs } from "./server/transport-lane.ts"