bazis 0.98.29 → 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.29" }, 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/kernel/Kernel.ts

@@ -28,6 +28,8 @@ export interface KernelRuntimeOptions {
   readonly signals: readonly NodeJS.Signals[];
   readonly unhandledErrorPolicy: UnhandledErrorPolicy;
   readonly startupReport: boolean;
+  /** Start the infrastructure and the schema only, then stop (BAZIS_SCHEMA_ONLY). */
+  readonly schemaOnly?: boolean;
 }
 
 interface StopRequest {
@@ -101,9 +103,19 @@ export class Kernel {
       // Async singletons first: hosted services and controllers take them
       // through constructors, which resolve synchronously.
       await awaitAbortable(this.container.initializeAsyncSingletons(), abortController.signal);
-      await this.coordinator.start(abortController.signal, this.options.shutdownTimeoutMs);
+      await this.coordinator.start(abortController.signal, this.options.shutdownTimeoutMs, this.options.schemaOnly === true);
       coordinatorStarted = true;
       this.startupMs = performance.now() - this.timings.buildStartedAt;
+      if (this.options.schemaOnly === true) {
+        // The application itself never started: no lifetime callbacks, no
+        // STARTED event, no report. run() stops right away with exit code 0.
+        this.container.tryResolve(LOGGER)?.info("schema only: infrastructure and schema are ready, stopping (BAZIS_SCHEMA_ONLY)", {
+          hostedServices: this.coordinator.startedHostedCount,
+          startupMs: Number(this.startupMs.toFixed(1)),
+        });
+        this.state = "started";
+        return;
+      }
       await this.lifetime.notifyStarted(abortController.signal);
       await this.container.resolve(EventBus).publish(
         APPLICATION_STARTED,
@@ -222,16 +234,21 @@ export class Kernel {
 
   private async runShutdownSequence(request: StopRequest): Promise<void> {
     const errors: unknown[] = [];
+    // A schema-only start never announced the application, so it does not
+    // announce its stop either.
+    const announced = this.options.schemaOnly !== true;
     try {
-      await this.lifetime.notifyStopping();
+      if (announced) await this.lifetime.notifyStopping();
     } catch (error) {
       errors.push(error);
     }
     try {
-      await this.container.resolve(EventBus).publish(APPLICATION_STOPPING, {
-        ...(request.signal === undefined ? {} : { signal: request.signal }),
-        exitCode: request.exitCode,
-      });
+      if (announced) {
+        await this.container.resolve(EventBus).publish(APPLICATION_STOPPING, {
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+          exitCode: request.exitCode,
+        });
+      }
     } catch (error) {
       errors.push(error);
     }
@@ -249,7 +266,7 @@ export class Kernel {
     }
 
     try {
-      await this.lifetime.notifyStopped();
+      if (announced) await this.lifetime.notifyStopped();
     } catch (error) {
       errors.push(error);
     }
@@ -287,6 +304,10 @@ export class Kernel {
         return request.exitCode;
       }
 
+      if (this.options.schemaOnly === true) {
+        // The schema is in place: nothing to serve, stop as a finished job.
+        this.requestStop(this.stopRequested ?? { exitCode: 0 });
+      }
       const request = await new Promise<StopRequest>((resolve) => {
         // lifetime.stop() or a process signal may have fired during start().
         if (this.stopRequested) {

package/core/kernel/KernelBuilder.ts

@@ -6,6 +6,7 @@ import { ConfigRegistry } from "./config/ConfigRegistry";
 import { argsSource, envSource } from "./config/sources";
 import { Environment } from "./Environment";
 import { EventBus } from "./events/EventBus";
+import { KernelError } from "./errors";
 import { HealthService } from "./health/HealthService";
 import { Kernel, type KernelTimings } from "./Kernel";
 import { ConsoleLogger } from "./logging/ConsoleLogger";
@@ -46,6 +47,7 @@ export class KernelBuilder {
   private validateOnBuild = true;
   private overrides: readonly ProviderDefinition[] = [];
   private startupReport?: boolean;
+  private schemaOnly?: boolean;
   private logger?: Logger;
 
   public constructor(private readonly rootModule: RootModuleInput) {}
@@ -65,6 +67,7 @@ export class KernelBuilder {
     if (options.unhandledErrorPolicy !== undefined) this.unhandledErrorPolicy = options.unhandledErrorPolicy;
     if (options.validateOnBuild !== undefined) this.validateOnBuild = options.validateOnBuild;
     if (options.startupReport !== undefined) this.startupReport = options.startupReport;
+    if (options.schemaOnly !== undefined) this.schemaOnly = options.schemaOnly;
     return this;
   }
 
@@ -177,6 +180,17 @@ export class KernelBuilder {
       signals: this.signals,
       unhandledErrorPolicy: this.unhandledErrorPolicy,
       startupReport: this.startupReport ?? !environment.isProduction,
+      schemaOnly: this.schemaOnly ?? schemaOnlyFromProcess(),
     });
   }
 }
+
+/** BAZIS_SCHEMA_ONLY: `1`/`true` or `0`/`false`/unset; anything else is a mistake worth stopping for. */
+function schemaOnlyFromProcess(): boolean {
+  const raw = process.env.BAZIS_SCHEMA_ONLY;
+  if (raw === undefined || raw === "") return false;
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true") return true;
+  if (normalized === "0" || normalized === "false") return false;
+  throw new KernelError(`BAZIS_SCHEMA_ONLY must be 1, true, 0 or false, got ${JSON.stringify(raw.slice(0, 40))}.`);
+}

package/core/kernel/LifecycleCoordinator.ts

@@ -55,16 +55,21 @@ export class LifecycleCoordinator {
     return this.rollbackStartedAt === undefined ? 0 : performance.now() - this.rollbackStartedAt;
   }
 
-  public async start(signal?: AbortSignal, rollbackTimeoutMs = 0): Promise<void> {
+  /**
+   * `infrastructureOnly` starts only hosted services with a negative phase
+   * (connections and the database schema) and no lifecycle hooks.
+   */
+  public async start(signal?: AbortSignal, rollbackTimeoutMs = 0, infrastructureOnly = false): Promise<void> {
     signal?.throwIfAborted();
     validateOptionsOnStart(this.resolver);
-    const hosted = resolveHostedServices(this.resolver);
+    const resolved = resolveHostedServices(this.resolver);
+    const hosted = infrastructureOnly ? resolved.filter((service) => (service.phase ?? 0) < 0) : resolved;
     // Background failures go to the application logger, like HTTP errors.
     const logger = this.resolver.tryResolve?.(LOGGER);
     if (logger) for (const service of hosted) service.useDiagnostics?.(logger);
     const validation = validateHostedServicePlan(hosted, signal);
     if (validation) await awaitAbortable(validation, signal);
-    this.hooks = this.resolver.resolveAll(LIFECYCLE_HOOK);
+    this.hooks = infrastructureOnly ? [] : this.resolver.resolveAll(LIFECYCLE_HOOK);
 
     try {
       for (let index = 0; index < this.hooks.length; index += 1) {

package/core/kernel/types/KernelOptions.ts

@@ -20,4 +20,12 @@ export interface KernelOptions {
   readonly validateOnBuild?: boolean;
   /** Startup report in the console. Default: only outside production. */
   readonly startupReport?: boolean;
+  /**
+   * Start only the infrastructure and the database schema (hosted services with
+   * a negative phase: connections, migrations, `ensureCreated`), then stop with
+   * exit code 0. HTTP, background services and lifecycle hooks do not run.
+   * For a deployment step with the schema owner's credentials.
+   * Default: the BAZIS_SCHEMA_ONLY variable (`1`/`true`), otherwise false.
+   */
+  readonly schemaOnly?: boolean;
 }

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/library/orm/Schema/MigrationRunner.ts

@@ -130,10 +130,24 @@ export class MigrationRunner {
   }
 
   private async ensureHistory(): Promise<void> {
+    // CREATE TABLE IF NOT EXISTS needs the CREATE privilege on the schema even
+    // when the table exists, so an application user with data rights only
+    // could never start. Create the table only when it is missing.
+    const [found] = await this.provider.query(`SELECT to_regclass(${this.param(0)}) IS NOT NULL AS present`, [this.quote(HISTORY_TABLE)]);
+    if (found?.present === true) {
+      return;
+    }
     await this.provider.execute(
       `CREATE TABLE IF NOT EXISTS ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")} TEXT PRIMARY KEY, ${this.quote("AppliedAt")} TEXT NOT NULL)`,
       [],
-    );
+    ).catch((error: unknown) => {
+      if (sqlState(error) !== "42501") throw error;
+      throw new OrmError(
+        `The migration history table "${HISTORY_TABLE}" does not exist and this database user may not create it (PostgreSQL 42501). ` +
+          "Run the first start with the schema owner's credentials (BAZIS_SCHEMA_ONLY=1 applies the schema and exits), or grant CREATE on the schema.",
+        { cause: error },
+      );
+    });
   }
 
   private async loadApplied(): Promise<Set<string>> {
@@ -168,6 +182,11 @@ export class MigrationRunner {
   }
 }
 
+function sqlState(error: unknown): string | undefined {
+  const code = (error as { errno?: unknown; code?: unknown } | null)?.errno ?? (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" ? code : undefined;
+}
+
 /** Names the failed migration; its transaction was rolled back, earlier ones stay applied. */
 function migrationFailed(subject: string, error: unknown): unknown {
   // An unknown COMMIT outcome must not be reported as a rollback.

package/library/orm/Schema/SchemaAdmission.ts

@@ -73,7 +73,12 @@ export class SchemaAdmissionEngine {
     // The PostgreSQL message names objects, not row values (those stay in its detail field).
     const reason = `${describeOperation(operation)} failed${sqlState ? ` with PostgreSQL ${sqlState}` : ""}${error instanceof Error && error.message ? `: ${error.message}` : ""}`;
     if (["23502", "23503", "23505", "23514"].includes(sqlState)) return new SchemaAdmissionError("ORM_SCHEMA_ADDITIVE_DATA_VIOLATION", `Existing PostgreSQL data violates the declared additive schema change: ${reason}. Fix the data, then start again.`);
-    return new SchemaAdmissionError(operation.kind === "createSchema" || operation.kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", `PostgreSQL additive schema admission failed: ${reason}.`);
+    // 42501: an application user with data rights only. The schema change is
+    // right; it has to be applied by a user that owns the tables.
+    const hint = sqlState === "42501"
+      ? " This database user may not change the schema: apply the change with the schema owner's credentials (BAZIS_SCHEMA_ONLY=1 applies the schema and exits), or grant the rights."
+      : "";
+    return new SchemaAdmissionError(operation.kind === "createSchema" || operation.kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", `PostgreSQL additive schema admission failed: ${reason}.${hint}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.29",
+  "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",