@nifrajs/core 2.14.1 → 3.2.0

package/src/server/validation.ts

@@ -0,0 +1,19 @@
+import type { StandardIssue } from "../schema/standard.ts"
+import { type ResponseResult, status } from "./runtime-core.ts"
+
+function validationIssues(issues: ReadonlyArray<StandardIssue>): {
+  ok: false
+  error: string
+  issues: unknown[]
+} {
+  const serialized = issues.map((issue) => {
+    const path = issue.path?.map((seg) => String(typeof seg === "object" ? seg.key : seg))
+    return path !== undefined ? { message: issue.message, path } : { message: issue.message }
+  })
+  return { ok: false, error: "validation", issues: serialized }
+}
+
+/** The shared 422 response result used by every body-validation lane. */
+export function plainValidationError(issues: ReadonlyArray<StandardIssue>): ResponseResult {
+  return status(422, validationIssues(issues))
+}

package/src/server/websocket.ts

@@ -164,10 +164,18 @@ export interface WebSocketHandler<
   /**
    * 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.
+   * server does NOT runtime-validate its own sends by default - the inbound `messageSchema` guards the
+   * trust boundary; outbound honesty is the handler author's code. Set {@link validateSend} to opt into
+   * a synchronous runtime check of JSON text/UTF-8 binary frames.
    */
   sendSchema?: Send
+  /**
+   * Opt-in runtime enforcement for {@link sendSchema}. Invalid JSON, schema failures, and async
+   * validators are dropped before the native socket's `send()` runs and reported to `error()` when it
+   * exists. This is a development/contract check for the server's own output, not an inbound security
+   * boundary. It is off by default and requires `sendSchema` at registration.
+   */
+  validateSend?: boolean
   /** Decode versioned transport frames before inbound schema validation. Omit for legacy JSON. */
   transport?: {
     readonly registry: TransportCodecRegistry
@@ -246,24 +254,19 @@ function toBinary(raw: unknown): Uint8Array {
  * `open` event (Deno). Lifecycle callbacks are error-isolated - a throw (or async rejection) routes to
  * `error()` and never tears the process down; binary frames are normalized to `Uint8Array`.
  */
-export function attachWebSocket(
+export function attachWebSocket<
+  Data = unknown,
+  Env = unknown,
+  Schema extends StandardSchemaV1 | undefined = undefined,
+  Send extends StandardSchemaV1 | undefined = undefined,
+>(
   socket: StandardWebSocket,
-  handler: WebSocketHandler,
+  handler: WebSocketHandler<Data, Env, Schema, Send>,
   data: unknown,
   options: { openNow: boolean; pubsub: TopicRegistry; maxPayloadBytes?: number },
-): NifraWebSocket {
+): NifraWebSocket<Data> {
   const { pubsub } = options
-  const ws: NifraWebSocket = {
-    send: (payload) => socket.send(payload),
-    close: (code, reason) => socket.close(code, reason),
-    get readyState() {
-      return socket.readyState
-    },
-    subscribe: (topic) => pubsub.subscribe(topic, ws),
-    unsubscribe: (topic) => pubsub.unsubscribe(topic, ws),
-    data,
-    raw: socket,
-  }
+  let ws!: NifraWebSocket<Data>
   const reportError = (error: unknown): void => {
     if (handler.error === undefined) return
     try {
@@ -273,6 +276,24 @@ export function attachWebSocket(
       /* the error handler itself failed - last resort, swallow */
     }
   }
+  const send = createWebSocketSender(
+    (payload) => socket.send(payload),
+    handler.sendSchema,
+    handler.validateSend,
+    handler.transport,
+    reportError,
+  )
+  ws = {
+    send,
+    close: (code, reason) => socket.close(code, reason),
+    get readyState() {
+      return socket.readyState
+    },
+    subscribe: (topic) => pubsub.subscribe(topic, ws),
+    unsubscribe: (topic) => pubsub.unsubscribe(topic, ws),
+    data: data as Data,
+    raw: socket,
+  }
   const safe = (call: () => MaybePromise<void>): void => {
     try {
       const r = call()
@@ -300,7 +321,13 @@ export function attachWebSocket(
         return
       }
     }
-    safe(() => handler.message?.(ws, payload))
+    safe(() =>
+      (
+        handler.message as
+          | ((socket: NifraWebSocket<Data>, value: WebSocketData) => MaybePromise<void>)
+          | undefined
+      )?.(ws, payload),
+    )
   })
   socket.addEventListener(
     "close",
@@ -321,6 +348,89 @@ export function attachWebSocket(
 const WS_MESSAGE_DECODER = new TextDecoder()
 const WS_PAYLOAD_ENCODER = new TextEncoder()
 
+type WebSocketSendPayload = string | ArrayBufferView | ArrayBuffer
+
+const OUTBOUND_VALIDATION_ERROR = "outbound WebSocket frame failed sendSchema validation"
+
+function outboundValueOf(
+  payload: WebSocketSendPayload,
+  transport: WebSocketHandler["transport"],
+): unknown {
+  const text =
+    typeof payload === "string"
+      ? payload
+      : WS_MESSAGE_DECODER.decode(
+          payload instanceof ArrayBuffer
+            ? new Uint8Array(payload)
+            : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength),
+        )
+  return transport === undefined
+    ? JSON.parse(text)
+    : decodeTransportFrame(text, transport.registry, {
+        ...(transport.maxBytes === undefined ? {} : { maxBytes: transport.maxBytes }),
+      })
+}
+
+/**
+ * Build the socket's send function once. The disabled path returns the native sender directly, so
+ * the default type-only contract adds no per-frame branch or schema work. Runtime validation is
+ * deliberately synchronous: a socket `send()` cannot await an async Standard Schema without changing
+ * the portable API, so an async result fails closed and is never sent.
+ */
+export function createWebSocketSender(
+  send: (payload: WebSocketSendPayload) => void,
+  schema: StandardSchemaV1 | undefined,
+  enabled: boolean | undefined,
+  transport: WebSocketHandler["transport"],
+  onError: (error: unknown) => void,
+): (payload: WebSocketSendPayload) => void {
+  if (enabled !== true || schema === undefined) return send
+  let reporting = false
+  const reportFailure = (error: unknown): void => {
+    // An error handler may try to send a diagnostic. Do not recurse forever when that diagnostic also
+    // violates the same outbound contract. EVERY failure path reports through here - a path that calls
+    // `onError` directly reopens that recursion for the one rejection shape it happens to cover.
+    if (reporting) return
+    reporting = true
+    try {
+      onError(error)
+    } finally {
+      reporting = false
+    }
+  }
+  return (payload) => {
+    let value: unknown
+    try {
+      value = outboundValueOf(payload, transport)
+    } catch {
+      reportFailure(new Error(OUTBOUND_VALIDATION_ERROR))
+      return
+    }
+
+    let outcome: ValidationOutcome<unknown> | Promise<ValidationOutcome<unknown>>
+    try {
+      outcome = validateStandard(schema, value) as
+        | ValidationOutcome<unknown>
+        | Promise<ValidationOutcome<unknown>>
+    } catch {
+      reportFailure(new Error(OUTBOUND_VALIDATION_ERROR))
+      return
+    }
+    if (outcome instanceof Promise) {
+      // Do not await or send later: the portable `send()` contract is synchronous. Attach a rejection
+      // handler so a validator that rejects cannot become an unhandled process-level rejection.
+      outcome.catch(() => {})
+      reportFailure(new Error(`${OUTBOUND_VALIDATION_ERROR}; validator must be synchronous`))
+      return
+    }
+    if (!outcome.ok) {
+      reportFailure(new Error(OUTBOUND_VALIDATION_ERROR))
+      return
+    }
+    send(payload)
+  }
+}
+
 /**
  * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame -
  * parse as JSON, run the Standard Schema, then call the user's `message` with the typed value, or

package/src/server/ws-bun.ts

@@ -5,7 +5,13 @@
  * (erased). No `Bun.*` calls here - the runtime seam stays in `server.ts` (see runtime-boundary.test).
  */
 
-import type { NifraWebSocket, TopicRegistry, WebSocketData, WebSocketHandler } from "./websocket.ts"
+import {
+  createWebSocketSender,
+  type NifraWebSocket,
+  type TopicRegistry,
+  type WebSocketData,
+  type WebSocketHandler,
+} from "./websocket.ts"
 import type { BunWsHandlers } from "./ws-hook.ts"
 
 /** Per-connection state Bun's `websocket` callbacks read via `ws.data`: the matched handler, the
@@ -22,6 +28,10 @@ export interface BunSocket {
   send(data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number
   close(code?: number, reason?: string): void
   readonly readyState: number
+  // Bun's native (uWebSockets) topic pub/sub - used only in native-pubsub mode (no per-socket
+  // outbound validation), where `app.publish` routes through the Bun server's `publish`.
+  subscribe(topic: string): void
+  unsubscribe(topic: string): void
   // readonly: we never reassign `ws.data` wholesale, only mutate its fields (`.nifra`, `.data`).
   readonly data: BunWsData
 }
@@ -32,18 +42,43 @@ function toBinaryData(message: ArrayBuffer | Uint8Array): Uint8Array {
   return message instanceof Uint8Array ? message : new Uint8Array(message)
 }
 
-/** Wrap a Bun `ServerWebSocket` as the portable {@link NifraWebSocket} handed to WS callbacks. */
-function wrapBunSocket(raw: BunSocket, topics: TopicRegistry): NifraWebSocket {
-  const ws: NifraWebSocket = {
-    send: (data) => {
+/**
+ * Wrap a Bun `ServerWebSocket` as the portable {@link NifraWebSocket} handed to WS callbacks.
+ *
+ * `nativePubsub` selects the topic backend: in native mode `subscribe`/`unsubscribe` go straight to
+ * Bun's own (uWebSockets) pub/sub so a broadcast via the Bun server's `publish` reaches this socket
+ * with no per-connection JS loop; otherwise they use the runtime-neutral {@link TopicRegistry}. Native
+ * mode is used only when no route validates outbound frames, so raw and validated sends are identical.
+ */
+function wrapBunSocket(
+  raw: BunSocket,
+  topics: TopicRegistry,
+  handler: WebSocketHandler,
+  nativePubsub: boolean,
+): NifraWebSocket {
+  let ws!: NifraWebSocket
+  const reportError = (error: unknown): void => reportWsError(error, ws, handler)
+  const send = createWebSocketSender(
+    (data) => {
       raw.send(data)
     },
+    handler.sendSchema,
+    handler.validateSend,
+    handler.transport,
+    reportError,
+  )
+  ws = {
+    send,
     close: (code, reason) => raw.close(code, reason),
     get readyState() {
       return raw.readyState
     },
-    subscribe: (topic) => topics.subscribe(topic, ws),
-    unsubscribe: (topic) => topics.unsubscribe(topic, ws),
+    subscribe: nativePubsub
+      ? (topic) => raw.subscribe(topic)
+      : (topic) => topics.subscribe(topic, ws),
+    unsubscribe: nativePubsub
+      ? (topic) => raw.unsubscribe(topic)
+      : (topic) => topics.unsubscribe(topic, ws),
     get data() {
       return raw.data.data
     },
@@ -80,26 +115,43 @@ function dispatchWsCallback(
   }
 }
 
-/** The shared Bun `websocket` dispatcher config for one app - each connection's
- * `ws.data.handler` is the matched route's handler, set by `server.upgrade`. */
-export function createBunWsHandlers(topics: TopicRegistry): BunWsHandlers {
+/**
+ * The shared Bun `websocket` dispatcher config for one app - each connection's `ws.data.handler` is
+ * the matched route's handler, set by `server.upgrade`.
+ *
+ * `nativePubsub` (set by `listen()` when the app has no validated-send route) makes subscriptions use
+ * Bun's own pub/sub; there the registry holds nothing and Bun auto-drops native subscriptions on
+ * close, so the `unsubscribeAll` sweep is skipped.
+ */
+export function createBunWsHandlers(topics: TopicRegistry, nativePubsub = false): BunWsHandlers {
   return {
     open: (raw) => {
       const ws = raw as BunSocket
-      const nifra = wrapBunSocket(ws, topics)
+      const nifra = wrapBunSocket(ws, topics, ws.data.handler, nativePubsub)
       ws.data.nifra = nifra
       dispatchWsCallback(() => ws.data.handler.open?.(nifra), nifra, ws.data.handler)
     },
     message: (raw, message) => {
       const ws = raw as BunSocket
-      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics)
+      const handler = ws.data.handler
+      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics, handler, nativePubsub)
       const data: WebSocketData = typeof message === "string" ? message : toBinaryData(message)
-      dispatchWsCallback(() => ws.data.handler.message?.(nifra, data), nifra, ws.data.handler)
+      // Hottest WS path - dispatch inline rather than through `dispatchWsCallback` so no per-frame
+      // closure is allocated. Same contract: a sync throw or async rejection routes to `handler.error`.
+      try {
+        const result = handler.message?.(nifra, data)
+        if (result instanceof Promise)
+          result.catch((e: unknown) => reportWsError(e, nifra, handler))
+      } catch (error) {
+        reportWsError(error, nifra, handler)
+      }
     },
     close: (raw, code, reason) => {
       const ws = raw as BunSocket
-      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics)
-      topics.unsubscribeAll(nifra) // drop topic subscriptions so the registry never holds a dead socket
+      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics, ws.data.handler, nativePubsub)
+      // Registry mode: drop topic subscriptions so it never holds a dead socket. Native mode: Bun
+      // unsubscribes the socket from every topic on close, so there is nothing to sweep here.
+      if (!nativePubsub) topics.unsubscribeAll(nifra)
       dispatchWsCallback(() => ws.data.handler.close?.(nifra, code, reason), nifra, ws.data.handler)
     },
   }

package/src/server/ws-hook.ts

@@ -30,8 +30,9 @@ export interface WsRuntime {
   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
+  /** The Bun `websocket` config for `listen()` when the app has WS routes. `nativePubsub` routes
+   * `ws.subscribe` through Bun's own pub/sub (set when no route validates outbound frames). */
+  bunHandlers(topics: TopicRegistry, nativePubsub?: boolean): BunWsHandlers
   /** `attachWebSocket` - wires a standard server socket (Workers `WebSocketPair`) to a handler. */
   attach(
     socket: StandardWebSocket,

package/src/server.ts

@@ -45,7 +45,7 @@ export {
   type ScheduledHandler,
   toFetchHandler,
 } from "./server/edge.ts"
-export { pathnameOf, type UrlParts, urlPartsOf } from "./server/http.ts"
+export { isSameOriginPath, pathnameOf, type UrlParts, urlPartsOf } from "./server/http.ts"
 export {
   commonSecretPatterns,
   jsonLogger,
@@ -70,7 +70,13 @@ export {
   toVercelHandler,
   type VercelHandler,
 } from "./server/platform-adapters.ts"
-export type { Registry, RouteInfo } from "./server/registry.ts"
+export type { Registry, ResponseMapFor, RouteInfo, RouteInfoFor } from "./server/registry.ts"
+export {
+  type PlainRender,
+  type ResponseResult,
+  type StatusResponse,
+  status,
+} from "./server/runtime-core.ts"
 export {
   type AdmissionController,
   type AdmissionDecision,

package/src/single-copy-register.ts

@@ -0,0 +1,24 @@
+/**
+ * Side-effect entry (`@nifrajs/core/single-copy/register`): install the single-copy resolver into the
+ * Bun runtime.
+ *
+ * Preload it - never import it from application code:
+ *
+ * ```toml
+ * # bunfig.toml
+ * preload = ["@nifrajs/core/single-copy/register"]
+ * [test]
+ * preload = ["@nifrajs/core/single-copy/register"]
+ * ```
+ *
+ * A resolver only affects imports that have not resolved yet, and a module's own imports resolve
+ * before its body runs. Registering from inside application code would therefore miss exactly the
+ * imports it exists to redirect. `preload` runs before the entry point, which is the only moment that
+ * covers the whole graph.
+ *
+ * `nifra check` reads this specifier out of `bunfig.toml` as the proof that the runtime arm is armed,
+ * so the string above is a contract rather than a suggestion.
+ */
+import { registerSingleCopy } from "./single-copy"
+
+registerSingleCopy()