@nifrajs/core 2.0.0 → 2.1.0

package/src/server/server.ts

@@ -6,12 +6,17 @@ import {
   NIFRA_DEADLINE_HEADER,
   type RequestBudget,
 } from "../budget.ts"
+import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
 import {
+  type AroundCapabilityOptions,
   CAPABILITY_GUARD,
+  type CapabilityInterceptor,
   type CapabilityUseEvent,
   createCapabilityGuard,
+  DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS,
   normalizeRouteCapabilities,
+  type RegisteredCapabilityInterceptor,
 } from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
@@ -517,6 +522,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
   private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  private readonly capabilityInterceptors: RegisteredCapabilityInterceptor[]
+  private readonly capabilityObservers: EffectLifecycleObserver[]
   /** The installed effect-ledger runtime (owns the sink + per-route resolution + settle), or
    * `undefined` when the effect-ledger plugin is not installed. */
   private effectLedgerRuntime: EffectLedgerRuntime | undefined
@@ -579,6 +586,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.gracefulSignals = options.gracefulSignals ?? false
     this.capacityGate = options.admission
     this.onCapabilityUse = options.onCapabilityUse
+    this.capabilityInterceptors = []
+    this.capabilityObservers = []
     // The effect-ledger runtime is installed by `.use(effectLedger())`; a bare app never imports it, so
     // the ledger machinery tree-shakes out. Capability-declaring routes simply carry no ledger without it.
     this.effectLedgerRuntime = undefined
@@ -659,6 +668,40 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
+  /**
+   * Asynchronously admit each subsequent `executeCapability()` call before its owned effect runs.
+   * Interceptors receive token-only metadata plus an abort signal and must call `next()` exactly once
+   * to admit. Returning without `next()`, timing out, aborting, or throwing fails the effect closed.
+   */
+  aroundCapability(
+    interceptor: CapabilityInterceptor,
+    options: AroundCapabilityOptions = {},
+  ): this {
+    this.assertConfigurable("aroundCapability()")
+    if (typeof interceptor !== "function") {
+      throw new TypeError("aroundCapability interceptor must be a function")
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new RangeError("aroundCapability timeoutMs must be a positive safe integer")
+    }
+    // JS timers wrap larger delays to ~1ms, which would unexpectedly deny every effect.
+    this.capabilityInterceptors.push(
+      Object.freeze({ interceptor, timeoutMs: Math.min(timeoutMs, 2_147_483_647) }),
+    )
+    return this
+  }
+
+  /** Observe token-only admission/execution lifecycle events for subsequent capability routes. */
+  observeCapability(observer: EffectLifecycleObserver): this {
+    this.assertConfigurable("observeCapability()")
+    if (typeof observer !== "function") {
+      throw new TypeError("observeCapability observer must be a function")
+    }
+    this.capabilityObservers.push(observer)
+    return this
+  }
+
   /** Transform the handler's result before it is serialized. Order-scoped. */
   afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this {
     this.assertConfigurable("afterHandle()")
@@ -1120,6 +1163,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         method,
         path,
         this.onCapabilityUse,
+        this.idempotencyRuntime?.trackEffect,
+        Object.freeze([...this.capabilityInterceptors]),
+        Object.freeze([...this.capabilityObservers]),
       )
     }
     const hasDecorations = Reflect.ownKeys(routeDecorations).length > 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,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"