bazis 0.98.30 → 0.98.31

package/core/app/runApp.ts

@@ -1,6 +1,7 @@
 import {
   collectModuleUiProfiles,
   collectModuleControllers,
+  collectModuleGateways,
   DI,
   Global,
   Module,
@@ -12,7 +13,8 @@ import { missingCacheModuleCheck } from "../cache/http/missingCacheModuleCheck";
 import { httpModule, useModelValidator, type HttpModuleOptions, type ModelValidator } from "../http";
 import { grpcModule, type GrpcModuleOptions } from "../grpc";
 import { buildHttpOpenApiDocument } from "../http/OpenApi/openApiDocument";
-import { KernelBuilder, Bazis, type KernelOptions, type ValidatableConfig } from "../kernel";
+import { KernelBuilder, Bazis, KernelError, type KernelOptions, type ValidatableConfig } from "../kernel";
+import { websocketModule, type WebSocketOptions } from "../websocket";
 import {
   isUiProfileAuthoringClass,
   type UiProfileV1,
@@ -39,6 +41,12 @@ export interface RunAppOptions {
   readonly http?: HttpModuleOptions;
   /** gRPC server; discovers feature-module grpcControllers, independently of HTTP. */
   readonly grpc?: GrpcModuleOptions;
+  /**
+   * WebSocket settings (authentication, adapter, limits). Gateways are
+   * collected from the `gateways` of the modules and served on the HTTP
+   * listener whenever a module declares one; this option only tunes them.
+   */
+  readonly websocket?: WebSocketOptions;
   /** Kernel options (environment, shutdown timeout, signals, ...). */
   readonly kernel?: KernelOptions;
   /**
@@ -88,6 +96,17 @@ export interface RunAppOptions {
   readonly ui?: RunAppUiOptions;
 }
 
+/** Adds the WebSocket module when a module declares gateways; settings alone without gateways are a mistake. */
+function withWebSocket(root: BazisModuleRef, options: WebSocketOptions | undefined): BazisModuleRef {
+  if (collectModuleGateways([root]).length === 0) {
+    if (options !== undefined) {
+      throw new KernelError("runApp: websocket options are set, but no module declares gateways. Add gateways: [ChatGateway] to the module that owns the gateway.");
+    }
+    return root;
+  }
+  return { imports: [root, websocketModule({ ...options, imports: [root] })] };
+}
+
 function withUiRuntime(
   root: BazisModuleRef,
   option: RunAppOptions["ui"],
@@ -279,8 +298,9 @@ export function composeApp(root: BazisModuleRef, options: RunAppOptions = {}): B
     // behavior after startup.
     useModelValidator(validator);
 
+    const gatewayRoot = withWebSocket(appRoot, options.websocket);
     const httpAppRoot = withUiRuntime(
-      { imports: [appRoot, ...(options.http.imports ?? [])] },
+      { imports: [gatewayRoot, ...(options.http.imports ?? [])] },
       options.ui,
       options.http,
     );

package/core/di/index.ts

@@ -24,6 +24,7 @@ export {
   createContainer,
   type CreateContainerOptions,
   collectModuleControllers,
+  collectModuleGateways,
   collectModuleConfigs,
   collectModuleUiProfiles,
   Global,

package/core/di/module/collectModuleControllers.ts

@@ -1,16 +1,30 @@
 import type { Class } from "../token";
 import type { BazisModuleRef } from "./types";
 
+type ClassListKey = "controllers" | "gateways";
+
 /**
- * Collects controller classes from the module tree (the module itself plus `imports`,
- * recursively). Duplicates by class reference are dropped.
+ * Collects the classes of one declarative list (`controllers`, `gateways`) from
+ * the module tree (the module itself plus `imports`, recursively). Duplicates by
+ * class reference are dropped.
  */
-export function collectModuleControllers(
+function collectModuleClasses(
   roots: readonly BazisModuleRef[],
-  extraControllers?: readonly Class<object>[],
+  key: ClassListKey,
+  extra?: readonly Class<object>[],
 ): Class<object>[] {
   const seen = new Set<Class<object>>();
   const result: Class<object>[] = [];
+  const add = (list: readonly Class<object>[] | undefined): void => {
+    if (!list) return;
+    for (let index = 0; index < list.length; index += 1) {
+      const entry = list[index] as Class<object>;
+      if (!seen.has(entry)) {
+        seen.add(entry);
+        result.push(entry);
+      }
+    }
+  };
 
   const visit = (moduleRef: BazisModuleRef, loaded: Set<BazisModuleRef>): void => {
     if (loaded.has(moduleRef)) {
@@ -24,30 +38,25 @@ export function collectModuleControllers(
         visit(imports[index] as BazisModuleRef, loaded);
       }
     }
-
-    const controllers = moduleRef.controllers;
-    if (controllers) {
-      for (let index = 0; index < controllers.length; index += 1) {
-        const controller = controllers[index] as Class<object>;
-        if (!seen.has(controller)) {
-          seen.add(controller);
-          result.push(controller);
-        }
-      }
-    }
+    add(moduleRef[key]);
   };
 
   for (let index = 0; index < roots.length; index += 1) {
     visit(roots[index] as BazisModuleRef, new Set());
   }
-  if (extraControllers) {
-    for (let index = 0; index < extraControllers.length; index += 1) {
-      const controller = extraControllers[index] as Class<object>;
-      if (!seen.has(controller)) {
-        seen.add(controller);
-        result.push(controller);
-      }
-    }
-  }
+  add(extra);
   return result;
 }
+
+/** Controller classes of the module tree; `extraControllers` are appended once. */
+export function collectModuleControllers(
+  roots: readonly BazisModuleRef[],
+  extraControllers?: readonly Class<object>[],
+): Class<object>[] {
+  return collectModuleClasses(roots, "controllers", extraControllers);
+}
+
+/** WebSocket gateway classes (`gateways` of `@Module`) of the module tree. */
+export function collectModuleGateways(roots: readonly BazisModuleRef[]): Class<object>[] {
+  return collectModuleClasses(roots, "gateways");
+}

package/core/di/module/createContainer.ts

@@ -144,6 +144,14 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
       }
     }
 
+    const gateways = moduleRef.gateways;
+    if (gateways) {
+      for (let index = 0; index < gateways.length; index += 1) {
+        // One instance per gateway: it keeps connection state across requests.
+        collection.add(singleton(gateways[index] as Class<object>));
+      }
+    }
+
     const background = moduleRef.background;
     if (background) {
       for (let index = 0; index < background.length; index += 1) {

package/core/di/module/index.ts

@@ -26,7 +26,7 @@ export {
   type ModuleOwnedProviderContributor,
 } from "./moduleOwnedProviderContributors";
 export { createContainer, type CreateContainerOptions } from "./createContainer";
-export { collectModuleControllers } from "./collectModuleControllers";
+export { collectModuleControllers, collectModuleGateways } from "./collectModuleControllers";
 export { collectModuleConfigs } from "./collectModuleConfigs";
 export { collectModuleUiProfiles } from "./collectModuleUiProfiles";
 export {

package/core/di/module/types/BazisModule.ts

@@ -29,6 +29,13 @@ export interface BazisModuleMetadata {
    * backward compatibility.
    */
   readonly controllers?: readonly Class<object>[];
+  /**
+   * WebSocket gateways of the module (classes with `@WebSocketGateway`).
+   * Registered as singletons in this module, so a gateway sees the module's
+   * providers like a controller does; `websocketModule` collects them from
+   * `imports` and serves them on the HTTP listener.
+   */
+  readonly gateways?: readonly Class<object>[];
   /**
    * `@UiProfile()` declarations owned by this module. The DI layer keeps them
    * opaque; `runApp` resolves their controller/request/response references and

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.30" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.31" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/scripts/di-generate.ts

@@ -212,7 +212,7 @@ let explicitRequestModelRoots = new Set<ts.ClassDeclaration>();
 let agentCodegenSources: AgentCodegenSource[] = [];
 
 const ROUTE_DECORATORS = new Set(["Get", "Post", "Put", "Patch", "Delete", "Options", "Head", "All"]);
-const CODEGEN_CHANNEL_DECORATORS = new Set(["Controller", "GrpcController", "Agent", "Tool", "Prompt", "RequestModel", "UiProfile"]);
+const CODEGEN_CHANNEL_DECORATORS = new Set(["Controller", "GrpcController", "WebSocketGateway", "Agent", "Tool", "Prompt", "RequestModel", "UiProfile"]);
 const PRIMITIVE_QUERY_TYPES: Record<string, HttpBindingSpec["type"]> = {
   string: "string",
   number: "number",
@@ -867,7 +867,7 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
     if (!object || visitedModules.has(object)) return;
     visitedModules.add(object);
     const properties = propertiesOf(object);
-    for (const name of ["controllers", "grpcControllers", "background", "tools"]) {
+    for (const name of ["controllers", "grpcControllers", "gateways", "background", "tools"]) {
       const classes = properties.get(name);
       if (classes && ts.isArrayLiteralExpression(classes)) for (const entry of classes.elements) record(entry);
     }

package/core/websocket/DESIGN.md

@@ -22,22 +22,21 @@ export class ChatGateway {
 }
 ```
 
-Register it next to HTTP:
+Declare it in its module, like a controller; `runApp` serves it on the HTTP listener:
 
 ```ts
-import { Module } from "@/core/di";
-import { httpModule } from "@/core/http";
-import { websocketModule } from "@/core/websocket";
-
-@Module({
-  imports: [
-    httpModule({ port: 3000 }),
-    websocketModule({ gateways: [ChatGateway] }),
-  ],
-})
-export class AppModule {}
+import { Module, singleton } from "@/core/di";
+
+@Module({ gateways: [ChatGateway], providers: [singleton(ChatHistory)] })
+export class ChatModule {}
+
+await runApp(AppModule, { http: { port: 3000 }, websocket: { requireAuth: true, authenticator } });
 ```
 
+Without `runApp`, `websocketModule({ imports: [ChatModule], ... })` next to
+`httpModule` does the same. Services send with `WebSocketService`:
+`this.ws.to("user:ann").emit("order-paid", { id })`.
+
 The gateway above upgrades on `/ws/chat`.
 
 ## Handler Convention
@@ -102,7 +101,7 @@ default, `replayDelivery: "transport"`.
 ### Client-confirmed replay
 
 Opt in with `?replay=client-ack` on each connection, or require it for all clients
-with `websocketModule({ gateways, replayDelivery: "client-ack" })`. The adapter
+with `runApp({ websocket: { replayDelivery: "client-ack" } })`. The adapter
 must support CAS. A saved client-ack session cannot reconnect in transport mode;
 such an upgrade returns 409. Invalid/duplicate replay query values return 400.
 
@@ -151,7 +150,7 @@ Pass an existing native Bun RedisClient from the host infrastructure:
 const adapter = new RedisWebSocketAdapter(hostRedisClient, {
   keyPrefix: "my-app:ws", // same on participating nodes; distinct per application
 });
-const module = websocketModule({ gateways, adapter, replayDelivery: "client-ack" });
+await runApp(AppModule, { http: {}, websocket: { adapter, replayDelivery: "client-ack" } });
 ```
 
 The adapter owns only a duplicate connection for pub/sub. Closing the adapter

package/core/websocket/WebSocketService.ts

@@ -0,0 +1,47 @@
+import type { WebSocketServer } from "./ws-server";
+import type { SocketBroadcast } from "./types";
+import type { ReliableBroadcastOptions, ReliableBroadcastReceipt } from "./reliable-delivery";
+
+/** `to(room)` of one namespace, usable from any service. */
+export interface WebSocketNamespace {
+  readonly name: string;
+  to(room: string): SocketBroadcast;
+}
+
+/**
+ * Sends events to rooms from outside a gateway handler: a service, an HTTP
+ * controller or a background job. Registered by `websocketModule` and exported
+ * globally, so any service can take it in its constructor.
+ *
+ * ```ts
+ * this.ws.to("user:ann").emit("order-paid", { id });            // one namespace
+ * this.ws.namespace("chat").to("general").emit("message", m);   // a chosen one
+ * ```
+ */
+export class WebSocketService {
+  public constructor(private readonly server: WebSocketServer) {}
+
+  /** The broadcaster of a namespace (`"chat"` and `"/chat"` are the same). */
+  public namespace(name: string): WebSocketNamespace {
+    const server = this.server;
+    return {
+      name,
+      to(room: string): SocketBroadcast {
+        return {
+          emit: (event, data) => server.broadcast(name, room, event, data),
+          emitReliable: (event, data, options: ReliableBroadcastOptions): Promise<ReliableBroadcastReceipt> =>
+            server.broadcastReliable(name, room, event, data, options),
+        };
+      },
+    };
+  }
+
+  /** `to(room)` of the only namespace; with several, name one with `namespace()`. */
+  public to(room: string): SocketBroadcast {
+    const names = this.server.namespaceNames;
+    if (names.length !== 1) {
+      throw new Error(`WebSocketService.to(room) needs exactly one namespace, found ${names.length} (${names.join(", ")}); use namespace(name).to(room).`);
+    }
+    return this.namespace(names[0] as string).to(room);
+  }
+}

package/core/websocket/adapter/redis-delivery-store.ts

@@ -56,13 +56,13 @@ export class RedisRoomDeliveryStore implements ReliableRoomDelivery {
     if (!deliveryUuid.test(request.messageId) || !Number.isSafeInteger(request.expiresAt)
       || typeof request.namespace !== "string" || request.namespace.length > 256 || request.namespace.includes("\0")
       || typeof request.room !== "string" || !request.room.length || request.room.length > 256 || request.room.includes("\0")
-      || typeof request.excludeSid !== "string" || request.excludeSid.length > 128
+      || (request.excludeSid !== undefined && (typeof request.excludeSid !== "string" || request.excludeSid.length > 128))
       || request.packet.type !== "event" || typeof request.packet.event !== "string" || !request.packet.event.length
       || request.packet.event.length > 256) throw new WebSocketDeliveryError("INVALID_PUBLICATION");
     const packet = JSON.stringify({ ...request.packet, v: 1, namespace: request.namespace, deliveryId: request.messageId });
     if (Buffer.byteLength(packet) > this.limits.maxQueueBytes) throw new WebSocketDeliveryError("QUEUE_CAPACITY");
     const metadata = JSON.stringify({ messageId: request.messageId, expiresAt: request.expiresAt,
-      namespace: request.namespace, room: request.room, excludeSid: request.excludeSid });
+      namespace: request.namespace, room: request.room, excludeSid: request.excludeSid ?? "" });
     const fingerprint = canonicalJsonHashV1("bazis.websocket.publication/v1", { metadata: JSON.parse(metadata), packet: JSON.parse(packet) });
     const result = await this.operations.send("EVAL", [PUBLISH, "0", this.prefix, metadata, JSON.stringify(this.limits), fingerprint, packet]) as string[];
     if (result[0] !== "OK") throw new WebSocketDeliveryError(result[0] ?? "STORE_PROTOCOL");

package/core/websocket/index.ts

@@ -48,7 +48,8 @@ export {
   type WebSocketServerStats,
   type WsConnectionData,
 } from "./ws-server";
-export { websocketModule, type WebSocketModuleConfig } from "./websocketModule";
+export { websocketModule, type WebSocketModuleConfig, type WebSocketOptions } from "./websocketModule";
+export { WebSocketService, type WebSocketNamespace } from "./WebSocketService";
 export { TopicCache, topicCache, type TopicCacheOptions, type TopicCacheStats } from "./topic-cache";
 export {
   encodeServerPacket,

package/core/websocket/middleware.ts

@@ -1,4 +1,6 @@
 import type { SocketUser } from "./types";
+import { JwtError } from "../../library/jwt";
+import { UnauthorizedError } from "../http";
 
 const MAX_SOCKET_USER_ID_LENGTH = 256;
 
@@ -110,15 +112,24 @@ export function createWsAuthMiddleware(
   options?: { required?: boolean; allowQueryToken?: boolean },
 ): WsMiddleware {
   return async (ctx, next) => {
-    const user = await authenticator(
-      extractWebSocketToken(ctx.request, { allowQueryToken: options?.allowQueryToken }),
-      {
-        signal: ctx.signal,
-        namespace: ctx.namespace,
-        path: ctx.path,
-        request: ctx.request,
-      },
-    );
+    let user: SocketUser | null;
+    try {
+      user = await authenticator(
+        extractWebSocketToken(ctx.request, { allowQueryToken: options?.allowQueryToken }),
+        {
+          signal: ctx.signal,
+          namespace: ctx.namespace,
+          path: ctx.path,
+          request: ctx.request,
+        },
+      );
+    } catch (error) {
+      // A bad or expired token is a refusal, not a server failure.
+      if (error instanceof JwtError || error instanceof UnauthorizedError) {
+        throw new WsUpgradeError("Unauthorized", 401);
+      }
+      throw error;
+    }
     if (user !== null && !isValidSocketUser(user)) {
       throw new WsUpgradeError("Unauthorized", 401);
     }

package/core/websocket/reliable-delivery.ts

@@ -16,7 +16,8 @@ export interface ReliableBroadcastReceipt {
 export interface ReliableRoomPublication extends ReliableBroadcastOptions {
   readonly namespace: string;
   readonly room: string;
-  readonly excludeSid: string;
+  /** The publishing session; omitted for a publication from a service. */
+  readonly excludeSid?: string;
   readonly packet: ServerPacket;
 }
 

package/core/websocket/websocketModule.ts

@@ -1,14 +1,16 @@
 import {
   DI,
+  collectModuleGateways,
   markGlobal,
   Module,
-  singleton,
-  type Class,
   type BazisModule,
+  type BazisModuleRef,
   type ProviderDefinition,
   type ServiceResolver,
 } from "../di";
 import { WEBSOCKET_UPGRADE } from "../http";
+import { LOGGER } from "../kernel";
+import { WebSocketService } from "./WebSocketService";
 import { WebSocketExplorer } from "./explorer";
 import { WebSocketServer, type WebSocketMemoryLimits } from "./ws-server";
 import type { WsAccessTokenAuthenticator, WsMiddleware } from "./middleware";
@@ -19,11 +21,10 @@ import type { WebSocketDiagnostic } from "./reliable-delivery";
 
 export interface WebSocketModuleConfig {
   /**
-   * Gateway classes decorated with `@WebSocketGateway`. Each is registered as a
-   * singleton (with auto-resolved constructor dependencies) and explored for
-   * `@SubscribeMessage` handlers.
+   * Modules whose `gateways` (classes with `@WebSocketGateway`) are served.
+   * The whole tree is searched, like `httpModule` searches for controllers.
    */
-  readonly gateways: readonly Class<object>[];
+  readonly imports?: readonly BazisModuleRef[];
   /** Kernel-owned upgrade policy using DI; runs before gateway middleware. */
   readonly middlewareFactory?: (services: ServiceResolver) => WsMiddleware;
   /** Upgrade-time authentication; `null`/omitted means anonymous connections. */
@@ -47,29 +48,39 @@ export interface WebSocketModuleConfig {
   readonly exposeHandlerErrors?: boolean;
 }
 
+/** Server-wide WebSocket settings of `runApp({ websocket })`; gateways come from the modules. */
+export type WebSocketOptions = Omit<WebSocketModuleConfig, "imports">;
+
 /**
- * Registers WebSocket gateways and shares the HTTP listener for upgrades.
+ * Serves the gateways declared by the modules of `imports` on the shared HTTP
+ * listener. `runApp` installs it next to the HTTP module whenever a module
+ * declares `gateways`; `runApp({ websocket })` passes the settings.
  *
  * ```ts
- * @Module({ imports: [httpModule({ ... }), websocketModule({ gateways: [ChatGateway] })] })
- * class AppModule {}
+ * @Module({ gateways: [ChatGateway], providers: [singleton(ChatHistory)] })
+ * class ChatModule {}
  * ```
  *
  * The built `WebSocketServer` is exposed under {@link WEBSOCKET_UPGRADE}; the
  * HTTP server resolves it and wires `Bun.serve({ websocket })` automatically.
+ * `WebSocketService` is exported globally for sending from services.
  */
 export function websocketModule(config: WebSocketModuleConfig): BazisModule {
+  const gateways = collectModuleGateways(config.imports ?? []);
+  if (gateways.length === 0) {
+    throw new Error("websocketModule: no module of imports declares gateways. Add gateways: [ChatGateway] to the module that owns the gateway.");
+  }
   const providers: ProviderDefinition[] = [
-    ...config.gateways.map((Gateway) => singleton(Gateway)),
     DI.singleton(
       DI.factoryProviderWithResolver(WEBSOCKET_UPGRADE, [], (resolver) => {
-        const instances = config.gateways.map((Gateway) => resolver.resolve(Gateway));
+        const instances = gateways.map((Gateway) => resolver.resolve(Gateway));
         const namespaces = new WebSocketExplorer().explore(instances);
         if (config.middlewareFactory) {
           const middleware = config.middlewareFactory(resolver);
           if (typeof middleware !== "function") throw new Error("WebSocket middlewareFactory must return middleware.");
           for (const namespace of namespaces) namespace.middleware.unshift(middleware);
         }
+        const logger = resolver.tryResolve(LOGGER);
         return new WebSocketServer({
           namespaces,
           authenticator: config.authenticator ?? null,
@@ -82,14 +93,23 @@ export function websocketModule(config: WebSocketModuleConfig): BazisModule {
           ...(config.onDiagnostic ? { onDiagnostic: config.onDiagnostic } : {}),
           ...(config.limits ? { limits: config.limits } : {}),
           ...(config.exposeHandlerErrors !== undefined ? { exposeHandlerErrors: config.exposeHandlerErrors } : {}),
+          ...(logger ? { logger } : {}),
         });
       }),
     ),
+    DI.singleton(
+      DI.factoryProviderWithResolver(WebSocketService, [], (resolver) => {
+        const upgrade = resolver.resolve(WEBSOCKET_UPGRADE);
+        if (!(upgrade instanceof WebSocketServer)) throw new Error("WebSocketService needs the WebSocketServer registered by websocketModule.");
+        return new WebSocketService(upgrade);
+      }),
+    ),
   ];
 
   // Global + exported so the HTTP module can resolve the upgrade port without
-  // importing the websocket module (one-way: websocket builds on http).
-  @Module({ providers, exports: [WEBSOCKET_UPGRADE] })
+  // importing the websocket module (one-way: websocket builds on http), and
+  // any service can take WebSocketService.
+  @Module({ imports: config.imports, providers, exports: [WEBSOCKET_UPGRADE, WebSocketService] })
   class WebSocketModule {}
 
   return markGlobal(WebSocketModule);

package/core/websocket/ws-server.ts

@@ -40,7 +40,11 @@ import { InMemoryWebSocketAdapter } from "./adapter/in-memory.adapter";
 import type { PacketCodec } from "./codec/packet-codec.interface";
 import { payloadToBytes, payloadToText } from "./codec/packet-codec.interface";
 import { jsonPacketCodec } from "./codec/json.codec";
-import { WebSocketDeliveryError, type WebSocketDiagnostic, type ReliableSessionOwner } from "./reliable-delivery";
+import { WebSocketDeliveryError, type WebSocketDiagnostic, type ReliableBroadcastOptions, type ReliableBroadcastReceipt, type ReliableSessionOwner } from "./reliable-delivery";
+import type { Logger } from "../kernel";
+import { redactSensitive } from "../../library/redaction";
+import { normalizeNamespace } from "./decorators";
+import type { OutgoingPacket } from "./socket-wrapper";
 
 export interface WebSocketMemoryLimits {
   readonly maxRateLimitBuckets?: number;
@@ -93,6 +97,8 @@ export interface WebSocketServerOptions {
   limits?: WebSocketMemoryLimits;
   /** Expose validator/handler exception messages. Disabled by default. */
   exposeHandlerErrors?: boolean;
+  /** Receives unexpected handler and upgrade failures (redacted). */
+  logger?: Logger;
 }
 
 export interface WebSocketServerStats {
@@ -352,10 +358,76 @@ export class WebSocketServer {
       if (handshakeController.signal.aborted && this.closed) {
         return new Response("WebSocket service unavailable", { status: 503 });
       }
+      this.options.logger?.error("WebSocket upgrade failed", { path: registered.path, error: redactSensitive(error) });
       return new Response("WebSocket upgrade failed", { status: 500 });
     }
   }
 
+  /** Namespaces served by this server, normalized (`/chat`). */
+  public get namespaceNames(): readonly string[] {
+    return [...this.namespacesByName.keys()];
+  }
+
+  /**
+   * Sends an event to every member of a room from outside a handler (a service,
+   * a controller, a background job). Delivery is the same as `socket.to(room)`:
+   * live members of this node and, through the adapter, of other nodes;
+   * offline members get it queued for reconnect replay.
+   */
+  public broadcast(namespace: string, room: string, event: string, data?: unknown): void {
+    const registered = this.requireNamespace(namespace);
+    this.publishToRoom(registered, room, { type: "event", namespace: registered.namespace, event, data }, outboundLimit(registered));
+  }
+
+  /** `socket.to(room).emitReliable` from outside a handler; needs the adapter capability. */
+  public async broadcastReliable(namespace: string, room: string, event: string, data: unknown, options: ReliableBroadcastOptions): Promise<ReliableBroadcastReceipt> {
+    const registered = this.requireNamespace(namespace);
+    const store = this.adapter.reliableRooms;
+    if (!store) throw new WebSocketDeliveryError("RELIABLE_DELIVERY_UNAVAILABLE");
+    const packet: OutgoingPacket = { type: "event", namespace: registered.namespace, event, data };
+    if (payloadBytes(this.codec.encodeServer({ ...packet, deliveryId: options.messageId })) > outboundLimit(registered)) {
+      throw new WebSocketDeliveryError("PAYLOAD_CAPACITY");
+    }
+    try {
+      const receipt = await store.publish({ ...options, namespace: registered.namespace, room, packet: { ...packet, v: 1 } });
+      this.diagnose("reliable-published", receipt.duplicate ? 0 : receipt.recipients);
+      return receipt;
+    } catch (error) {
+      this.diagnose("reliable-rejected");
+      throw error;
+    }
+  }
+
+  private requireNamespace(namespace: string): RegisteredNamespace {
+    if (this.closed || !this.initialized) throw new Error("WebSocket server is not running.");
+    const registered = this.namespacesByName.get(normalizeNamespace(namespace));
+    if (!registered) throw new Error(`Unknown WebSocket namespace "${namespace}"; registered: ${this.namespaceNames.join(", ")}.`);
+    return registered;
+  }
+
+  /**
+   * Fan-out to a room: the offline queue first (strict, so a rejection is not
+   * hidden behind a partial live delivery), then live members of this node,
+   * then other nodes through the adapter. `origin` is excluded, like `to()`.
+   */
+  private publishToRoom(registered: RegisteredNamespace, room: string, packet: OutgoingPacket, maxPayloadBytes: number, origin?: ServerWebSocket<WsConnectionData>): void {
+    const namespace = registered.namespace;
+    const topic = this.topics.get(namespace, room);
+    const payload = this.codec.encodeServer(packet);
+    const bytes = payloadToBytes(payload);
+    if (bytes.byteLength > maxPayloadBytes) {
+      throw new Error("WebSocket broadcast payload exceeds the namespace limit.");
+    }
+    const admission = this.sessionManager.enqueueToOfflineRoomMembers(namespace, room, { v: 1, ...packet }, origin?.data.sid, bytes.byteLength, true);
+    if (admission.truncated) {
+      this.diagnose("queue-rejected");
+      throw new WebSocketDeliveryError("OFFLINE_QUEUE_CAPACITY");
+    }
+    if (origin) origin.publish(topic, payload);
+    else this.bunServer?.publish(topic, this.codec.isBinary(payload) ? payload : payloadToText(payload));
+    this.trackAdapterOperation(this.adapter.publish(topic, bytes));
+  }
+
   private async performUpgrade(
     request: Request,
     server: Server<WsConnectionData>,
@@ -590,30 +662,10 @@ export class WebSocketServer {
         }
       },
       broadcast: (room, packet) => {
-        if (signal?.aborted) {
+        if (signal?.aborted || !registered) {
           return;
         }
-        const namespace = ws.data.namespace;
-        const topic = this.topics.get(namespace, room);
-        const payload = this.codec.encodeServer(packet);
-        const bytes = payloadToBytes(payload);
-        if (bytes.byteLength > maxPayloadBytes) {
-          throw new Error("WebSocket broadcast payload exceeds the namespace limit.");
-        }
-        const admission = this.sessionManager.enqueueToOfflineRoomMembers(
-          namespace,
-          room,
-          { v: 1, ...packet },
-          ws.data.sid,
-          bytes.byteLength,
-          true,
-        );
-        if (admission.truncated) {
-          this.diagnose("queue-rejected");
-          throw new WebSocketDeliveryError("OFFLINE_QUEUE_CAPACITY");
-        }
-        ws.publish(topic, payload);
-        this.trackAdapterOperation(this.adapter.publish(topic, bytes));
+        this.publishToRoom(registered, room, packet, maxPayloadBytes, ws);
       },
       broadcastReliable: async (room, packet, options) => {
         signal?.throwIfAborted();
@@ -1241,6 +1293,11 @@ export class WebSocketServer {
       const cause = error instanceof WsDispatchError ? error.cause : error;
       if (cause instanceof WebSocketDeliveryError) this.sendError(ws, cause.message, packet.id, cause.code);
       else this.sendError(ws, this.options.exposeHandlerErrors === true && rawMessage ? rawMessage : safeMessage, packet.id);
+      // A validation failure is the client's mistake; anything else is ours and
+      // belongs in the log, like an unhandled HTTP error.
+      if (!(error instanceof WsDispatchError && error.kind === "validation") && !(cause instanceof WebSocketDeliveryError)) {
+        this.options.logger?.error("WebSocket handler failed", { namespace: ws.data.namespace, event: packet.event, error: redactSensitive(cause) });
+      }
     }
     throwIfAborted(signal);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.30",
+  "version": "0.98.31",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",