@nifrajs/core 5.11.0 → 5.12.1

package/src/server/static-response.ts

@@ -0,0 +1,36 @@
+export interface StaticResponseDefinition {
+  readonly status: number
+  readonly statusText: string
+  readonly headers: Headers
+}
+
+const definitions = new WeakMap<object, StaticResponseDefinition>()
+
+/**
+ * Declare a bodyless response with fixed status and headers.
+ * Caller-supplied Content-Length and Transfer-Encoding are rejected.
+ */
+export function staticResponse(init?: ResponseInit): () => Response {
+  const normalized = new Response(null, init)
+  for (const name of ["content-length", "transfer-encoding"]) {
+    if (normalized.headers.has(name)) {
+      throw new TypeError(`staticResponse cannot set the framing header "${name}"`)
+    }
+  }
+  const definition: StaticResponseDefinition = Object.freeze({
+    status: normalized.status,
+    statusText: normalized.statusText,
+    headers: new Headers(normalized.headers),
+  })
+  const handler = (): Response => createStaticResponse(definition)
+  definitions.set(handler, definition)
+  return Object.freeze(handler)
+}
+
+export function staticResponseDefinition(handler: unknown): StaticResponseDefinition | undefined {
+  return typeof handler === "function" ? definitions.get(handler) : undefined
+}
+
+export function createStaticResponse(definition: StaticResponseDefinition): Response {
+  return new Response(null, definition)
+}

package/src/server/websocket.ts

@@ -51,13 +51,30 @@ export interface NifraWebSocket<Data = unknown> {
   readonly raw: unknown
 }
 
+/**
+ * Per-server topic membership and broadcast adapter. The default {@link TopicRegistry} keeps sockets
+ * in this process; a custom adapter can bridge those operations to a shared fan-out service. The
+ * membership methods are synchronous because socket callbacks are synchronous; `publish` may be
+ * asynchronous, in which case callers can await `app.publish()`.
+ */
+export interface TopicAdapter {
+  /** Add an open socket to a topic; ignore `readyState >= 2` and make repeats idempotent. */
+  subscribe(topic: string, ws: NifraWebSocket): void
+  /** Remove a socket from one topic; repeated unsubscriptions must be idempotent. */
+  unsubscribe(topic: string, ws: NifraWebSocket): void
+  /** Drop every topic membership for a socket when it closes. */
+  unsubscribeAll(ws: NifraWebSocket): void
+  /** Broadcast a frame to the topic; asynchronous fan-out is returned to `app.publish()`. */
+  publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void | Promise<void>
+}
+
 /**
  * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** -
  * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load
- * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to
- * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.
+ * balancer) needs a {@link TopicAdapter} backed by a shared fan-out. The same registry instance is
+ * shared by an app's connections and its `publish`.
  */
-export class TopicRegistry {
+export class TopicRegistry implements TopicAdapter {
   private readonly topics = new Map<string, Set<NifraWebSocket>>()
   private readonly memberships = new WeakMap<NifraWebSocket, Set<string>>()
 
@@ -234,8 +251,8 @@ export type WebSocketUpgradeOutcome =
       readonly kind: "upgrade"
       readonly handler: WebSocketHandler
       readonly data: unknown
-      /** The app's pub/sub registry - the adapter wires `ws.subscribe` + close-cleanup to it. */
-      readonly pubsub: TopicRegistry
+      /** The app's topic adapter - the adapter wires `ws.subscribe` + close-cleanup to it. */
+      readonly pubsub: TopicAdapter
       /** The installed runtime's {@link attachWebSocket}, carried on the outcome so an adapter can wire
        * a standard socket without a static import of the WS implementation (which would defeat the
        * `.use(websocket())` tree-shaking). `@nifrajs/workers` may import `attachWebSocket` directly instead. */
@@ -259,7 +276,7 @@ export type WsAttach = (
   socket: StandardWebSocket,
   handler: WebSocketHandler,
   data: unknown,
-  options: { openNow: boolean; pubsub: TopicRegistry; maxPayloadBytes?: number | undefined },
+  options: { openNow: boolean; pubsub: TopicAdapter; maxPayloadBytes?: number | undefined },
 ) => NifraWebSocket
 
 /**
@@ -299,7 +316,7 @@ export function attachWebSocket<
   socket: StandardWebSocket,
   handler: WebSocketHandler<Data, Env, Schema, Send>,
   data: unknown,
-  options: { openNow: boolean; pubsub: TopicRegistry; maxPayloadBytes?: number | undefined },
+  options: { openNow: boolean; pubsub: TopicAdapter; maxPayloadBytes?: number | undefined },
 ): NifraWebSocket<Data> {
   const { pubsub } = options
   let ws!: NifraWebSocket<Data>
@@ -372,7 +389,11 @@ export function attachWebSocket<
   socket.addEventListener(
     "close",
     (event: { readonly code?: number; readonly reason?: string }) => {
-      pubsub.unsubscribeAll(ws) // drop topic subscriptions so the registry never holds a dead socket
+      try {
+        pubsub.unsubscribeAll(ws)
+      } catch (error) {
+        reportError(error)
+      }
       const [code, reason] = sentClose ?? [event.code ?? 1005, event.reason ?? ""]
       safe(() => handler.close?.(ws, code, reason))
     },

package/src/server/ws-adapter-view.ts

@@ -4,7 +4,7 @@
  * and outcome types carry the schemas and codecs the adapters never touch.
  */
 
-import type { TopicRegistry, WebSocketHandler, WebSocketUpgradeOutcome } from "./websocket.ts"
+import type { TopicAdapter, WebSocketHandler, WebSocketUpgradeOutcome } from "./websocket.ts"
 
 /** A received frame, normalized: text → `string`, binary → `Uint8Array`. */
 export type NifraWsData = string | Uint8Array
@@ -20,7 +20,7 @@ export interface NifraWs {
   readonly raw: unknown
 }
 
-/** The `TopicRegistry` surface the adapter wires `ws.subscribe` to. */
+/** The socket-membership surface the adapter wires `ws.subscribe` to. */
 export interface WsPubSub {
   subscribe(topic: string, ws: NifraWs): void
   unsubscribe(topic: string, ws: NifraWs): void
@@ -59,5 +59,5 @@ type Fits<View, Actual extends View> = Actual
 export type CoreFitsAdapterView = [
   Fits<WsUpgradeOutcome, WebSocketUpgradeOutcome>,
   Fits<NifraWsHandler, WebSocketHandler>,
-  Fits<WsPubSub, TopicRegistry>,
+  Fits<WsPubSub, TopicAdapter>,
 ]

package/src/server/ws-bun.ts

@@ -10,7 +10,7 @@ import {
   createWebSocketSender,
   exceedsPayloadCap,
   type NifraWebSocket,
-  type TopicRegistry,
+  type TopicAdapter,
   type WebSocketData,
   type WebSocketHandler,
 } from "./websocket.ts"
@@ -20,8 +20,8 @@ import type { BunWsHandlers } from "./ws-hook.ts"
  * `upgrade()`-seeded user data, and the memoized portable {@link NifraWebSocket} wrapper. */
 export interface BunWsData {
   readonly handler: WebSocketHandler
-  /** Mounted/modern upgrades carry this registry; old/manual fixtures may omit it. */
-  readonly pubsub?: TopicRegistry
+  /** Mounted/modern upgrades carry their topic adapter; old/manual fixtures may omit it. */
+  readonly pubsub?: TopicAdapter
   /** The inbound cap of the app this socket belongs to (the upgrade outcome's). Absent, the
    * listening app's applies. */
   readonly maxPayloadBytes?: number | undefined
@@ -79,18 +79,18 @@ function toBinaryData(message: ArrayBuffer | Uint8Array): Uint8Array {
  *
  * `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
+ * with no per-connection JS loop; otherwise they use the configured topic adapter. Native
  * mode is used only when no route validates outbound frames, so raw and validated sends are identical.
  */
 function wrapBunSocket(
   raw: BunSocket,
-  topics: TopicRegistry,
+  topics: TopicAdapter,
   handler: WebSocketHandler,
   nativePubsub: boolean,
 ): NifraWebSocket {
   let ws!: NifraWebSocket
-  // Mounted child apps carry their own TopicRegistry in the upgrade outcome. Keep the argument as a
-  // fallback for old/manual Bun upgrades, but use the per-connection registry for composed mounts.
+  // Mounted child apps carry their own topic adapter in the upgrade outcome. Keep the argument as a
+  // fallback for old/manual Bun upgrades, but use the per-connection adapter for composed mounts.
   const pubsub = raw.data.pubsub ?? topics
   const reportError = (error: unknown): void => reportWsError(error, ws, handler)
   const send = createWebSocketSender(
@@ -167,7 +167,7 @@ const BUN_TOO_BIG_REASON = "Received too big message"
  * `maxPayloadLength`; a socket whose app declares less is closed with `1009` here.
  */
 export function createBunWsHandlers(
-  topics: TopicRegistry,
+  topics: TopicAdapter,
   nativePubsub = false,
   app?: object,
 ): BunWsHandlers {
@@ -209,7 +209,13 @@ export function createBunWsHandlers(
       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) (ws.data.pubsub ?? topics).unsubscribeAll(nifra)
+      if (!nativePubsub) {
+        try {
+          ;(ws.data.pubsub ?? topics).unsubscribeAll(nifra)
+        } catch (error) {
+          reportWsError(error, nifra, ws.data.handler)
+        }
+      }
       // Bun's own maxPayloadLength reports 1006 here, whether it dropped the connection (up to 1.4.3)
       // or sent the peer a 1009 (from 1.4.4); the handler gets the 1009 every other payload cap reports.
       const oversize = code === 1006 && reason === BUN_TOO_BIG_REASON

package/src/server/ws-hook.ts

@@ -12,13 +12,14 @@ import type { ProtoPoisoning } from "./proto-guard.ts"
 import type {
   NifraWebSocket,
   StandardWebSocket,
+  TopicAdapter,
   TopicRegistry,
   WebSocketContext,
   WebSocketHandler,
   WsSender,
 } from "./websocket.ts"
 
-/** The Bun serve `websocket` callback trio, closed over one app's `TopicRegistry`. The `ws`
+/** The Bun serve `websocket` callback trio, closed over one app's topic adapter. 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 {
@@ -43,13 +44,13 @@ export interface WsRuntime {
   /** 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). `app` is
    * the listening server, whose mount table names the payload caps the listener has to admit. */
-  bunHandlers(topics: TopicRegistry, nativePubsub?: boolean, app?: object): BunWsHandlers
+  bunHandlers(topics: TopicAdapter, nativePubsub?: boolean, app?: object): BunWsHandlers
   /** `attachWebSocket` - wires a standard server socket (Workers `WebSocketPair`) to a handler. */
   attach(
     socket: StandardWebSocket,
     handler: WebSocketHandler,
     data: unknown,
-    options: { openNow: boolean; pubsub: TopicRegistry },
+    options: { openNow: boolean; pubsub: TopicAdapter },
   ): NifraWebSocket
   /** `webSocketSender` - `ws.send` for an adapter that wires its own sockets (Node, Deno). */
   sender: WsSender

package/src/server.ts

@@ -177,9 +177,11 @@ export type {
   SSEStream,
   TypedSSEStream,
 } from "./server/sse.ts"
+export { staticResponse } from "./server/static-response.ts"
 export type {
   NifraWebSocket,
   StandardWebSocket,
+  TopicAdapter,
   WebSocketContext,
   WebSocketData,
   WebSocketHandler,

package/src/tool-contract.ts

@@ -84,6 +84,11 @@ export interface ToolContractOptions<
   readonly description: string
   readonly input: InputSchema
   readonly output: OutputSchema
+  /**
+   * The capability a caller must hold to run the tool. Defaults to `tool.execute.<name>`, valid for
+   * any name made of lowercase segments joined by `.`, `-` or `_` (`list_orders`); a name with an
+   * empty segment (`a__b`, a trailing `-`) derives none and must pass one.
+   */
   readonly capability?: string
   readonly approval?: ToolApprovalPolicy
   readonly idempotency?: ToolIdempotencyPolicy<Input>
@@ -398,8 +403,13 @@ export function defineTool<
   if (!isStandardSchema(options.input) || !isStandardSchema(options.output)) {
     throw new TypeError("tool contract: input and output must implement Standard Schema")
   }
-  if (options.capability !== undefined && !validCapabilityId(options.capability)) {
-    throw new TypeError(`tool contract: invalid capability ${JSON.stringify(options.capability)}`)
+  const capability = options.capability ?? `${DEFAULT_CAPABILITY}.${options.name}`
+  if (typeof capability !== "string" || !validCapabilityId(capability)) {
+    throw new TypeError(
+      options.capability === undefined
+        ? `tool contract: name ${JSON.stringify(options.name)} derives no valid capability; pass \`capability\``
+        : `tool contract: invalid capability ${JSON.stringify(options.capability)}`,
+    )
   }
   const approval = validateApprovalPolicy(options.approval ?? { kind: "none" })
   const cost =
@@ -415,7 +425,7 @@ export function defineTool<
     description: options.description.trim(),
     input: options.input,
     output: options.output,
-    capability: options.capability ?? `${DEFAULT_CAPABILITY}.${options.name}`,
+    capability,
     approval,
     ...(options.idempotency === undefined ? {} : { idempotency: options.idempotency }),
     ...(cost === undefined ? {} : { cost }),

package/src/ws.ts

@@ -61,6 +61,7 @@ export function websocket(): IdentityPlugin {
 export type {
   NifraWebSocket,
   StandardWebSocket,
+  TopicAdapter,
   WebSocketContext,
   WebSocketData,
   WebSocketHandler,