@nifrajs/core 5.10.0 → 5.12.0

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/single-copy-register.ts

@@ -14,10 +14,12 @@
  * 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.
+ * covers the whole graph. When Bun starts a filtered workspace script below the app root, the
+ * registrar finds the nearest ancestor package declaring `nifra.singleCopy` and passes that root to
+ * the resolver instead of planning against the workspace package's manifest.
  *
- * `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.
+ * `nifra check` recognizes this public specifier and verifies checkout-local relative preloads before
+ * treating them as proof that the runtime arm is armed.
  *
  * A declared package that cannot be collapsed (two versions, or a file with no counterpart in the
  * app's copy) prints one warning per package naming both copies. Set

package/src/single-copy.ts

@@ -130,7 +130,7 @@ export interface SingleCopyPlan {
 }
 
 export interface SingleCopyOptions {
-  /** The app root whose copy wins. Defaults to `process.cwd()`. */
+  /** The app root whose copy wins. Defaults to its nearest declaration, or `process.cwd()` if none. */
   readonly cwd?: string
   /** Package names or `@scope/*` patterns. Defaults to the `nifra.singleCopy` declaration. */
   readonly packages?: readonly string[]
@@ -179,6 +179,21 @@ const singleCopyField = (cwd: string): unknown => {
   return isRecord(nifra) ? nifra.singleCopy : undefined
 }
 
+/** Find the declaring app when a Bun workspace script runs from a package directory. */
+const singleCopyProjectRoot = (cwd: string): string => {
+  const start = resolve(cwd)
+  let current = start
+  for (let depth = 0; depth < MAX_ANCESTOR_DIRS; depth++) {
+    const pkg = readJsonSync(join(current, "package.json"))
+    const nifra = pkg?.nifra
+    if (isRecord(nifra) && Object.hasOwn(nifra, "singleCopy")) return realpathOrSelf(current)
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return realpathOrSelf(start)
+}
+
 /**
  * The declaration, read from `package.json` - deliberately NOT from `nifra.config.ts`.
  *
@@ -266,6 +281,34 @@ function preloadEntries(value: string): readonly string[] {
   return entries
 }
 
+/** Accept the public entry, or a relative source preload that is itself the registrar. */
+function isSingleCopyRegistrar(entry: string, cwd: string): boolean {
+  if (entry === SINGLE_COPY_REGISTER_SPECIFIER) return true
+  if (!entry.startsWith(".")) return false
+  let source: string
+  try {
+    source = readFileSync(resolve(cwd, entry), "utf8")
+  } catch {
+    return false
+  }
+  const lines = source
+    .replaceAll("\r\n", "\n")
+    .split("\n")
+    .map((line) => line.trim())
+  const importsRegistrar = lines.some((line) => {
+    const statement = line.endsWith(";") ? line.slice(0, -1) : line
+    return (
+      statement === 'import { registerSingleCopy } from "./single-copy"' ||
+      statement === "import { registerSingleCopy } from './single-copy'"
+    )
+  })
+  const callsRegistrar = lines.some((line) => {
+    const statement = line.endsWith(";") ? line.slice(0, -1) : line
+    return statement === "registerSingleCopy()"
+  })
+  return importsRegistrar && callsRegistrar
+}
+
 /**
  * Read the runtime proof out of `bunfig.toml`.
  *
@@ -294,7 +337,10 @@ export function readSingleCopyRegistration(cwd: string): SingleCopyRegistration
       section = heading.trim()
       continue
     }
-    if (value === undefined || !preloadEntries(value).includes(SINGLE_COPY_REGISTER_SPECIFIER))
+    if (
+      value === undefined ||
+      !preloadEntries(value).some((entry) => isSingleCopyRegistrar(entry, cwd))
+    )
       continue
     if (section === "test") test = true
     else if (section === "") run = true
@@ -726,7 +772,9 @@ const strictFromEnv = (): boolean => {
  * anything loads, and a `no-counterpart` file fails its own import.
  */
 export function registerSingleCopy(options: SingleCopyOptions = {}): SingleCopyPlan {
-  const root = realpathOrSelf(resolve(options.cwd ?? process.cwd()))
+  // Bun runs `--filter` scripts from the workspace package directory. Resolve the declaration root
+  // first so the preload still pins packages against the application tree that owns bunfig.toml.
+  const root = realpathOrSelf(resolve(options.cwd ?? singleCopyProjectRoot(process.cwd())))
   const strict = options.strict ?? (readSingleCopyStrict(root) || strictFromEnv())
   const warned = processSet(WARNED)
   const emit = (key: string, message: string): void => {

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,