@nifrajs/core 2.13.0 → 3.1.0

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
@@ -33,11 +39,24 @@ function toBinaryData(message: ArrayBuffer | Uint8Array): Uint8Array {
 }
 
 /** 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) => {
+function wrapBunSocket(
+  raw: BunSocket,
+  topics: TopicRegistry,
+  handler: WebSocketHandler,
+): 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
@@ -86,19 +105,19 @@ export function createBunWsHandlers(topics: TopicRegistry): BunWsHandlers {
   return {
     open: (raw) => {
       const ws = raw as BunSocket
-      const nifra = wrapBunSocket(ws, topics)
+      const nifra = wrapBunSocket(ws, topics, ws.data.handler)
       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 nifra = ws.data.nifra ?? wrapBunSocket(ws, topics, ws.data.handler)
       const data: WebSocketData = typeof message === "string" ? message : toBinaryData(message)
       dispatchWsCallback(() => ws.data.handler.message?.(nifra, data), nifra, ws.data.handler)
     },
     close: (raw, code, reason) => {
       const ws = raw as BunSocket
-      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics)
+      const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics, ws.data.handler)
       topics.unsubscribeAll(nifra) // drop topic subscriptions so the registry never holds a dead socket
       dispatchWsCallback(() => ws.data.handler.close?.(nifra, code, reason), nifra, ws.data.handler)
     },

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,
@@ -71,6 +71,7 @@ export {
   type VercelHandler,
 } from "./server/platform-adapters.ts"
 export type { Registry, RouteInfo } from "./server/registry.ts"
+export { type PlainRender, type ResponseResult, 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()