@nifrajs/core 0.1.0-alpha.1

package/src/server/ws-bun.ts

@@ -0,0 +1,106 @@
+/**
+ * Bun WebSocket plumbing — the `websocket` dispatcher config `listen()` hands to Bun's serve when
+ * the app has WS routes. Lives behind the `@nifrajs/core/ws` subpath (via `ws-hook.ts`) so the base
+ * bundle of a no-WebSocket app never ships it; `server.ts` only imports the **types** from here
+ * (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 type { BunWsHandlers } from "./ws-hook.ts"
+
+/** Per-connection state Bun's `websocket` callbacks read via `ws.data`: the matched handler, the
+ * `upgrade()`-seeded user data, and the memoized portable {@link NifraWebSocket} wrapper. */
+export interface BunWsData {
+  readonly handler: WebSocketHandler
+  data: unknown
+  nifra?: NifraWebSocket
+}
+
+/** Structural view of Bun's `ServerWebSocket` — keeps `Bun.*` types out of the public `.d.ts`
+ * (`listen()` casts for the same reason). The real socket satisfies this. */
+export interface BunSocket {
+  send(data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number
+  close(code?: number, reason?: string): void
+  readonly readyState: number
+  // readonly: we never reassign `ws.data` wholesale, only mutate its fields (`.nifra`, `.data`).
+  readonly data: BunWsData
+}
+
+/** Normalize a received binary frame to `Uint8Array` (Bun hands a `Buffer`, already one; an
+ * `ArrayBuffer` is wrapped). Text frames stay `string`. */
+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) => {
+      raw.send(data)
+    },
+    close: (code, reason) => raw.close(code, reason),
+    get readyState() {
+      return raw.readyState
+    },
+    subscribe: (topic) => topics.subscribe(topic, ws),
+    unsubscribe: (topic) => topics.unsubscribe(topic, ws),
+    get data() {
+      return raw.data.data
+    },
+    set data(value) {
+      raw.data.data = value
+    },
+    raw,
+  }
+  return ws
+}
+
+function reportWsError(error: unknown, ws: NifraWebSocket, handler: WebSocketHandler): void {
+  if (handler.error === undefined) return
+  try {
+    const result = handler.error(ws, error)
+    if (result instanceof Promise) result.catch(() => {}) // a throwing error handler is the last resort
+  } catch {
+    /* swallow: the error handler itself failed; nothing left to do but not crash */
+  }
+}
+
+/** Run a WS lifecycle callback, routing a sync throw or async rejection to `handler.error` so a
+ * failing callback never crashes the socket loop. */
+function dispatchWsCallback(
+  call: () => void | Promise<void>,
+  ws: NifraWebSocket,
+  handler: WebSocketHandler,
+): void {
+  try {
+    const result = call()
+    if (result instanceof Promise) result.catch((e: unknown) => reportWsError(e, ws, handler))
+  } catch (error) {
+    reportWsError(error, ws, handler)
+  }
+}
+
+/** 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 {
+  return {
+    open: (raw) => {
+      const ws = raw as BunSocket
+      const nifra = wrapBunSocket(ws, topics)
+      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 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)
+      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/ws-hook.ts

@@ -0,0 +1,53 @@
+/**
+ * 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).
+ *
+ * Only type imports below — this module must stay weightless, it is always in the base bundle.
+ */
+
+import type {
+  NifraWebSocket,
+  StandardWebSocket,
+  TopicRegistry,
+  WebSocketHandler,
+} from "./websocket.ts"
+
+/** The Bun serve `websocket` callback trio, closed over one app's `TopicRegistry`. The `ws`
+ * params are `unknown` so `Bun.*` types never leak into the public `.d.ts`; the implementation
+ * narrows to its structural `BunSocket` view. */
+export interface BunWsHandlers {
+  open(ws: unknown): void
+  message(ws: unknown, message: string | ArrayBuffer | Uint8Array): void
+  close(ws: unknown, code: number, reason: string): void
+}
+
+/** What `@nifrajs/core/ws` registers: everything `server.ts` and `toFetchHandler` need at runtime. */
+export interface WsRuntime {
+  /** `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. */
+  attach(
+    socket: StandardWebSocket,
+    handler: WebSocketHandler,
+    data: unknown,
+    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/ws.ts

@@ -0,0 +1,40 @@
+/**
+ * WebSocket runtime for `@nifrajs/core` — import once at your server entry to enable `app.ws()`:
+ *
+ *   import "@nifrajs/core/ws"
+ *
+ *   const app = server().ws("/chat", { message: (ws, data) => ws.send(data) })
+ *
+ * Why a subpath: an app that never uses WebSockets shouldn't ship the WS dispatcher, pub/sub
+ * registry, and Bun socket plumbing in its server bundle (~1.5 KB gzipped on the minimal-app size
+ * benchmark). Importing this module registers the runtime with the core server (idempotent);
+ * calling `app.ws()` without it fails loud at boot with a `WS_RUNTIME_MISSING` error pointing here.
+ *
+ * Serving adapters that wire standard sockets themselves (`@nifrajs/workers`) import
+ * `attachWebSocket` / `TopicRegistry` from here too.
+ */
+
+import {
+  attachWebSocket,
+  TopicRegistry,
+  wrapWebSocketMessageValidation,
+} from "./server/websocket.ts"
+import { createBunWsHandlers } from "./server/ws-bun.ts"
+import { setWsRuntime } from "./server/ws-hook.ts"
+
+setWsRuntime({
+  wrapHandler: wrapWebSocketMessageValidation,
+  createTopics: () => new TopicRegistry(),
+  bunHandlers: createBunWsHandlers,
+  attach: attachWebSocket,
+})
+
+export type {
+  NifraWebSocket,
+  StandardWebSocket,
+  WebSocketContext,
+  WebSocketData,
+  WebSocketHandler,
+  WebSocketUpgradeOutcome,
+} from "./server/websocket.ts"
+export { attachWebSocket, TopicRegistry, wrapWebSocketMessageValidation }