@nifrajs/core 2.0.0 → 2.2.0

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>
 
@@ -167,6 +168,11 @@ export interface WebSocketHandler<
    * 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
@@ -317,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/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,284 @@
+/**
+ * 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, options?: ErrorOptions) {
+    super(message, options)
+    this.name = "TransportCodecError"
+  }
+}
+
+/**
+ * Run a decode step and normalize whatever it throws into {@link TransportCodecError}.
+ *
+ * Decoding is the one place this module touches attacker-controlled bytes, and the primitives it
+ * delegates to raise their own native types — `JSON.parse` throws `SyntaxError`, a BYO codec throws
+ * whatever it likes. Every other failure here is a `TransportCodecError`, so letting those escape
+ * would mean a malformed payload — the single most likely hostile input — is the one case that slips
+ * past a caller catching the documented error type. The original is kept as `cause`, so the parse
+ * failure stays diagnosable; a codec already speaking the contract is re-thrown untouched.
+ */
+function decodeOrThrow<T>(decode: () => T, message: string): T {
+  try {
+    return decode()
+  } catch (cause) {
+    if (cause instanceof TransportCodecError) throw cause
+    throw new TransportCodecError(message, { cause })
+  }
+}
+
+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 decodeOrThrow(
+    () => new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    "transport payload is not valid UTF-8",
+  )
+}
+
+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)
+  if (text === "") return undefined
+  return decodeOrThrow(
+    () => codec.decode(text),
+    `malformed transport body for codec ${codec.id}@${codec.version}`,
+  )
+}
+
+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 = decodeOrThrow(
+    () => JSON.parse(frame),
+    "malformed transport 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")
+  }
+  const payload = envelope.payload
+  assertBounded(payload, options)
+  const codec = registry.byIdentity(envelope.codec, envelope.version as number)
+  return decodeOrThrow(
+    () => codec.decode(payload),
+    `malformed transport frame payload for codec ${codec.id}@${codec.version}`,
+  )
+}

package/src/transport-plugin.ts

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