bazis 0.98.30 → 0.98.32

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,26 @@
 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(
-  roots: readonly BazisModuleRef[],
-  extraControllers?: readonly Class<object>[],
-): Class<object>[] {
+function collectModuleClasses(roots: readonly BazisModuleRef[], key: ClassListKey): 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 +34,21 @@ 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);
-      }
-    }
-  }
   return result;
 }
+
+/** Controller classes (`controllers` of `@Module`) of the module tree. */
+export function collectModuleControllers(roots: readonly BazisModuleRef[]): Class<object>[] {
+  return collectModuleClasses(roots, "controllers");
+}
+
+/** 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/grpc/Grpc.module.ts

@@ -5,10 +5,9 @@ import { collectGrpcControllers, GRPC_CONTROLLERS } from "./moduleControllers";
 
 /** gRPC counterpart of httpModule: controllers belong to their feature modules. */
 export function grpcModule(options: GrpcModuleOptions = {}): BazisModule {
-  const selected = collectGrpcControllers(options.imports ?? [], options.controllers);
+  const selected = collectGrpcControllers(options.imports ?? []);
   @Module({
     imports: options.imports,
-    grpcControllers: options.controllers,
     providers: [DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => {
       const container = resolver.resolve(SERVICE_PROVIDER);
       if (!(container instanceof DiContainer)) throw new TypeError("gRPC requires a module DI container.");

package/core/grpc/GrpcCall.ts

@@ -1,5 +1,11 @@
 import type { ModuleOwnedProviderActivation, ServiceProvider } from "../di";
 import type { GrpcContext } from "./contracts";
+import { GrpcError } from "./GrpcError";
+import type { AuthorizeCheck } from "../http/Authorization/metadata";
+import { ForbiddenError, UnauthorizedError } from "../http/Errors/HttpError";
+import { JwtError } from "../../library/jwt/errors";
+import { redactSensitive } from "../../library/redaction";
+import type { Logger } from "../kernel/logging/Logger";
 import type { MethodDefinition } from "./serviceDefinition";
 import { GrpcTransport } from "./GrpcTransport";
 import { GrpcStatus } from "./GrpcStatus";
@@ -14,13 +20,25 @@ export class GrpcCall {
     private readonly activation: ModuleOwnedProviderActivation<object>,
     private readonly provider: ServiceProvider,
     private readonly binding?: GrpcRequestBinding,
+    /** `@Authorize` checks of the controller and the method, in order. */
+    private readonly checks: readonly AuthorizeCheck[] = [],
+    private readonly logger?: Logger,
   ) {}
 
   cancel(): void { this.transport.cancel(GrpcStatus.UNAVAILABLE, "Server stopped."); }
 
   async run(): Promise<void> {
     const scope = this.provider.createScope();
-    const context = this.transport.context;
+    const info = this.transport.context;
+    const context: GrpcContext = Object.freeze({
+      ...info,
+      services: scope,
+      state: new Map<string, unknown>(),
+      header: (name: string) => {
+        const value = info.metadata.get(name)[0];
+        return typeof value === "string" ? value : undefined;
+      },
+    });
     let result: unknown;
     let failure: unknown;
     let failed = false;
@@ -35,6 +53,9 @@ export class GrpcCall {
       for await (const value of requests) yield bind(value);
     }
     try {
+      context.signal.throwIfAborted();
+      // Like HTTP: access is decided before the request is read.
+      await authorize(this.checks, context);
       context.signal.throwIfAborted();
       const input = this.definition.requestStream
         ? (this.binding ? validatedRequests() : requests)
@@ -62,7 +83,14 @@ export class GrpcCall {
       // Do not dispose dependencies while non-cooperative handler code is running.
       try { await scope.dispose(); } catch (error) { failure = error; failed = true; }
     }
-    if (failed) this.transport.fail(failure);
+    if (failed) {
+      // An intentional GrpcError and a cancelled call are not server failures;
+      // anything else is a bug and belongs in the log, like an HTTP 500.
+      if (!(failure instanceof GrpcError) && !context.signal.aborted) {
+        this.logger?.error("gRPC handler failed", { path: this.definition.path, error: redactSensitive(failure) });
+      }
+      this.transport.fail(failure);
+    }
     else {
       try {
         if (!this.definition.responseStream) await this.transport.write(result);
@@ -71,3 +99,24 @@ export class GrpcCall {
     }
   }
 }
+
+/**
+ * Runs the `@Authorize` checks: `false` and `ForbiddenError` are
+ * PERMISSION_DENIED, `UnauthorizedError` and `JwtError` (missing, malformed,
+ * expired token) are UNAUTHENTICATED. Any other error propagates as a bug.
+ */
+async function authorize(checks: readonly AuthorizeCheck[], context: GrpcContext): Promise<void> {
+  for (const check of checks) {
+    let allowed: boolean;
+    try {
+      allowed = await check(context);
+    } catch (error) {
+      if (error instanceof UnauthorizedError || error instanceof JwtError) {
+        throw new GrpcError(GrpcStatus.UNAUTHENTICATED, "Unauthenticated.");
+      }
+      if (error instanceof ForbiddenError) throw new GrpcError(GrpcStatus.PERMISSION_DENIED, "Permission denied.");
+      throw error;
+    }
+    if (!allowed) throw new GrpcError(GrpcStatus.PERMISSION_DENIED, "Permission denied.");
+  }
+}

package/core/grpc/GrpcClient.ts

@@ -2,6 +2,7 @@ import { connect, type ClientHttp2Session, type SecureClientSessionOptions } fro
 import type { GrpcCallOptions, GrpcClientOptions, GrpcResponse, GrpcResponseStream } from "./clientContracts";
 import { GrpcClientCall } from "./GrpcClientCall";
 import { GrpcError } from "./GrpcError";
+import { markUpstreamFailure } from "../http/Errors/upstreamFailure";
 import { GrpcStatus } from "./GrpcStatus";
 import { Metadata } from "./Metadata";
 import type { MethodDefinition, ServiceDefinition } from "./serviceDefinition";
@@ -114,10 +115,10 @@ export class GrpcClient {
       deadline = Math.min(deadline, explicit);
     }
     if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError("Invalid gRPC signal.");
-    if (options.signal?.aborted) throw new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled.");
-    if (deadline <= Date.now()) throw new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded.");
-    if (this.closed) throw new GrpcError(GrpcStatus.CANCELLED, "gRPC client is closed.");
-    if (this.calls.size >= this.callLimit) throw new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Too many concurrent gRPC calls.");
+    if (options.signal?.aborted) throw upstream(new GrpcError(GrpcStatus.CANCELLED, "RPC cancelled."));
+    if (deadline <= Date.now()) throw upstream(new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, "Deadline exceeded."));
+    if (this.closed) throw upstream(new GrpcError(GrpcStatus.CANCELLED, "gRPC client is closed."));
+    if (this.calls.size >= this.callLimit) throw upstream(new GrpcError(GrpcStatus.RESOURCE_EXHAUSTED, "Too many concurrent gRPC calls."));
     let session: ClientHttp2Session, stream: ReturnType<ClientHttp2Session["request"]>;
     try {
       session = this.session();
@@ -125,7 +126,7 @@ export class GrpcClient {
       const wireTimeout = remaining <= 99_999_999 ? `${remaining}m` : `${Math.ceil(remaining / 1000)}S`;
       stream = session.request({ ...metadata.toHttp2Headers(), ":method": "POST", ":path": method.path,
         "content-type": "application/grpc+proto", te: "trailers", "grpc-accept-encoding": "identity", "grpc-timeout": wireTimeout }, { endStream: false });
-    } catch { throw new GrpcError(GrpcStatus.UNAVAILABLE, "Unable to open gRPC connection."); }
+    } catch { throw upstream(new GrpcError(GrpcStatus.UNAVAILABLE, "Unable to open gRPC connection.")); }
     const call = new GrpcClientCall<T>(stream, method, { deadline, signal: options.signal, sendLimit: this.sendLimit, receiveLimit: this.receiveLimit }, () => {
       this.calls.delete(call);
       this.sessions.get(session)?.delete(call);
@@ -170,3 +171,8 @@ function metadataCopy(value: Metadata | undefined): Metadata {
   if (!(value instanceof Metadata)) throw new TypeError("Expected Bazis Metadata.");
   return value.clone();
 }
+
+/** A failed call of this client is a failure of another service for an HTTP request: 504 or 502. */
+function upstream(error: GrpcError): GrpcError {
+  return markUpstreamFailure(error, error.code === GrpcStatus.DEADLINE_EXCEEDED ? "timeout" : "failure");
+}

package/core/grpc/GrpcClientCall.ts

@@ -1,4 +1,5 @@
 import { constants, type Http2Session, type ClientHttp2Stream, type IncomingHttpHeaders } from "node:http2";
+import { markUpstreamFailure } from "../http/Errors/upstreamFailure";
 import type { GrpcResponseStream } from "./clientContracts";
 import { GrpcError } from "./GrpcError";
 import { GrpcStatus } from "./GrpcStatus";
@@ -83,6 +84,9 @@ export class GrpcClientCall<T> implements GrpcResponseStream<T> {
     if (!this.terminalHeaders) this.fail(new GrpcError(GrpcStatus.UNAVAILABLE, "gRPC connection closed before completion."));
   }
   fail(error: GrpcError): void {
+    // In an HTTP request this is a failure of another service: 504 or 502.
+    // Marked even after finish: the same error is rethrown to the caller.
+    markUpstreamFailure(error, error.code === GrpcStatus.DEADLINE_EXCEEDED ? "timeout" : "failure");
     if (this.finished) return;
     this.failure = error;
     this.abort.abort(error);

package/core/grpc/GrpcServer.ts

@@ -11,6 +11,8 @@ import type { MethodDefinition } from "./serviceDefinition";
 import { modelValidatorAdapter } from "../../library/validation";
 import { getGrpcRequestBinding } from "./GrpcBinding.contract";
 import { GrpcRequestBinding } from "./GrpcRequest.binding";
+import { resolveAuthorizeMeta, type AuthorizeCheck } from "../http/Authorization/metadata";
+import { LOGGER, type Logger } from "../kernel/logging/Logger";
 
 type Contribution = ModuleOwnedProviderContribution<GrpcControllerDefinition, object>;
 
@@ -24,7 +26,8 @@ export class GrpcServer implements HostedService {
   private readonly sendLimit: number;
   private readonly maxConcurrentCalls: number;
   private readonly shutdownTimeoutMs: number;
-  private readonly routes = new Map<string, { entry: Contribution; method: MethodDefinition; name: string | symbol; binding?: GrpcRequestBinding }>();
+  private readonly routes = new Map<string, { entry: Contribution; method: MethodDefinition; name: string | symbol; binding?: GrpcRequestBinding; checks: readonly AuthorizeCheck[] }>();
+  private readonly logger?: Logger;
   private readonly sessions = new Set<ServerHttp2Session>();
   private readonly active = new Map<GrpcCall, Promise<void>>();
   private state: "idle" | "starting" | "running" | "stopping" | "stopped" = "idle";
@@ -34,6 +37,7 @@ export class GrpcServer implements HostedService {
   private boundPort?: number;
 
   constructor(options: GrpcModuleOptions, private readonly provider: ServiceProvider, controllers: readonly Contribution[]) {
+    this.logger = provider.tryResolve(LOGGER);
     const address = options.address ?? "127.0.0.1:50051";
     const match = typeof address === "string" && /^(?:\[([^\]]+)\]|([^:[\]\s]+)):(\d{1,5})$/.exec(address);
     if (!match || Number(match[3]) > 65535 || options.address === null) throw new TypeError("gRPC address must be host:port or [IPv6]:port.");
@@ -68,7 +72,9 @@ export class GrpcServer implements HostedService {
           throw new TypeError(`gRPC request stream/DTO mismatch: ${method.path}.`);
         }
         const model = explicit ?? generated?.model;
-        this.routes.set(method.path, { entry, method, name, binding: model ? new GrpcRequestBinding(model, validator) : undefined });
+        const access = resolveAuthorizeMeta(entry.payload.controller, name);
+        const checks = access.allowAnonymous ? [] : access.authorize?.checks ?? [];
+        this.routes.set(method.path, { entry, method, name, binding: model ? new GrpcRequestBinding(model, validator) : undefined, checks });
       }
     }
     const tls = credentials.http2Options();
@@ -113,7 +119,7 @@ export class GrpcServer implements HostedService {
       reject(error instanceof GrpcError ? error.code : GrpcStatus.INVALID_ARGUMENT, error instanceof GrpcError ? error.message : "Invalid gRPC headers.");
       return;
     }
-    const execution = new GrpcCall(transport, route.method, route.name, route.entry.activation, this.provider, route.binding);
+    const execution = new GrpcCall(transport, route.method, route.name, route.entry.activation, this.provider, route.binding, route.checks, this.logger);
     const pending = execution.run().catch((error: unknown) => transport.fail(error))
       .finally(() => this.active.delete(execution));
     this.active.set(execution, pending);

package/core/grpc/GrpcTransport.ts

@@ -1,5 +1,5 @@
 import type { IncomingHttpHeaders, ServerHttp2Stream } from "node:http2";
-import type { GrpcContext } from "./contracts";
+import type { GrpcCallInfo } from "./contracts";
 import { Metadata } from "./Metadata";
 import { GrpcError } from "./GrpcError";
 import { GrpcStatus } from "./GrpcStatus";
@@ -7,7 +7,7 @@ import type { MethodDefinition } from "./serviceDefinition";
 
 /** Owns the standard five-byte gRPC envelope and one built-in HTTP/2 stream. */
 export class GrpcTransport {
-  readonly context: GrpcContext;
+  readonly context: GrpcCallInfo;
   private readonly abort = new AbortController();
   private sentHeaders = false;
   private ended = false;

package/core/grpc/contracts.ts

@@ -4,9 +4,10 @@ import type { ServerOptions, ServiceDefinition } from "./serviceDefinition";
 import type { Class, BazisModuleRef } from "../di";
 import type { ModelValidator } from "../http/Binding/modelValidator";
 import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+import type { AuthorizeContext } from "../http/Authorization/metadata";
 
-/** One instance per RPC, including the complete lifetime of a streaming RPC. */
-export interface GrpcContext {
+/** Transport facts of one RPC, before its DI scope exists. */
+export interface GrpcCallInfo {
   readonly metadata: Metadata;
   readonly signal: AbortSignal;
   readonly deadline: Date | number;
@@ -15,10 +16,16 @@ export interface GrpcContext {
   sendMetadata(metadata: Metadata): void;
 }
 
+/**
+ * One instance per RPC, including the complete lifetime of a streaming RPC.
+ * It is also what `@Authorize` checks see: `header(name)` reads text metadata,
+ * `services` is the RPC scope, `state` is shared with the handler.
+ */
+export interface GrpcContext extends GrpcCallInfo, AuthorizeContext {}
+
 export interface GrpcModuleOptions {
+  /** Modules whose `grpcControllers` are served (the whole tree). */
   readonly imports?: readonly BazisModuleRef[];
-  /** Normally contributed by feature-module grpcControllers. */
-  readonly controllers?: readonly Class<object>[];
   /** DTO validation, captured per server. Default: Bazis's modelValidatorAdapter. */
   readonly validator?: ModelValidator;
   /** host:port or [IPv6]:port, default 127.0.0.1:50051. Port 0 selects a free port. */

package/core/grpc/moduleControllers.ts

@@ -24,8 +24,8 @@ registerModuleOwnedProviderContributor((metadata, context) => {
 });
 
 /** @internal Discover only the feature tree published by this transport. */
-export function collectGrpcControllers(roots: readonly BazisModuleRef[], extra: readonly Class<object>[] = []): Set<Class<object>> {
-  const result = new Set(extra);
+export function collectGrpcControllers(roots: readonly BazisModuleRef[]): Set<Class<object>> {
+  const result = new Set<Class<object>>();
   const visited = new Set<BazisModuleRef>();
   const visit = (module: BazisModuleRef): void => {
     if (visited.has(module)) return;

package/core/http/Authorization/bearerToken.ts

@@ -1,11 +1,11 @@
-import type { HttpContext } from "../HttpContext/HttpContext";
+import type { AuthorizeContext } from "./metadata";
 
 /**
  * The token of an `Authorization: Bearer <token>` header, or `undefined`
  * without the header, with another scheme or with an empty token. The scheme
  * is case-insensitive (RFC 7235); surrounding spaces are trimmed.
  */
-export function bearerToken(ctx: Pick<HttpContext, "header">): string | undefined {
+export function bearerToken(ctx: Pick<AuthorizeContext, "header">): string | undefined {
   const match = /^\s*bearer\s+(\S+)\s*$/i.exec(ctx.header("authorization") ?? "");
   return match?.[1];
 }

package/core/http/Authorization/metadata.ts

@@ -1,4 +1,4 @@
-import type { HttpContext } from "../HttpContext/HttpContext";
+import type { ServiceScope } from "../../di";
 
 // Same one-line polyfill as the rest of the HTTP module: Bun executes TC39
 // decorators natively, but Symbol.metadata may be missing in the runtime.
@@ -6,6 +6,19 @@ import type { HttpContext } from "../HttpContext/HttpContext";
 
 const AUTHORIZE_META = Symbol.for("bazis:http:authorize");
 
+/**
+ * What an access check sees. An HTTP request (`HttpContext`) and a gRPC call
+ * (`GrpcContext`) both provide it, so one check protects both transports.
+ */
+export interface AuthorizeContext {
+  /** A request header (HTTP) or a text metadata value (gRPC), by case-insensitive name. */
+  header(name: string): string | undefined;
+  /** The DI scope of this request or call. */
+  readonly services: ServiceScope;
+  /** Values shared by the checks and the handler of this request or call. */
+  readonly state: Map<string, unknown>;
+}
+
 /**
  * Access check for `@Authorize`. Receives the request context and decides
  * whether to let it through. The HTTP kernel does not know *what* is checked
@@ -18,8 +31,10 @@ const AUTHORIZE_META = Symbol.for("bazis:http:authorize");
  *   (for example `UnauthorizedError` → `401` when there are no credentials at all).
  *
  * Dependencies (services, DB) come from `ctx.services` (the request scope).
+ * On a gRPC call `false`/`ForbiddenError` is PERMISSION_DENIED and
+ * `UnauthorizedError`/`JwtError` is UNAUTHENTICATED.
  */
-export type AuthorizeCheck = (ctx: HttpContext) => boolean | Promise<boolean>;
+export type AuthorizeCheck = (ctx: AuthorizeContext) => boolean | Promise<boolean>;
 
 /** Authorization requirement: one or more checks (all must pass). */
 export interface AuthorizeOptions {

package/core/http/Decorators/controller.ts

@@ -12,7 +12,7 @@ import { ownMeta } from "./metadata";
  * ```
  *
  * The controller is a regular DI service: register it in a module
- * (`controllers: [...]` on `BazisModule`, or `httpModule({ controllers: [...] })`)
+ * (`controllers: [...]` on `BazisModule`)
  * with scoped lifetime and declare constructor dependencies as usual — auto deps work.
  */
 export function Controller(prefix = "") {

package/core/http/Errors/upstreamFailure.ts

@@ -0,0 +1,22 @@
+/**
+ * Marks an error of a call to another service. The HTTP error boundary answers
+ * `504 Gateway Timeout` for a timeout and `502 Bad Gateway` otherwise, like it
+ * does for `HttpClientError`. Clients of other protocols (gRPC) set the mark,
+ * so the HTTP layer does not depend on them.
+ */
+export type UpstreamFailure = "timeout" | "failure";
+
+const UPSTREAM_FAILURE = Symbol.for("bazis.http.upstreamFailure");
+
+/** Sets the mark on `error` (non-enumerable) and returns it. */
+export function markUpstreamFailure<E extends object>(error: E, kind: UpstreamFailure): E {
+  Object.defineProperty(error, UPSTREAM_FAILURE, { value: kind, configurable: true });
+  return error;
+}
+
+/** The mark of an upstream failure, if any. */
+export function upstreamFailure(error: unknown): UpstreamFailure | undefined {
+  if (error === null || typeof error !== "object") return undefined;
+  const kind = (error as { [UPSTREAM_FAILURE]?: unknown })[UPSTREAM_FAILURE];
+  return kind === "timeout" || kind === "failure" ? kind : undefined;
+}

package/core/http/HttpServer.ts

@@ -19,7 +19,7 @@ import type { Router } from "./Routing/Router";
 import { parseRequestPath } from "./Routing/template";
 import { assertVersioningOptions, createVersionReader, type VersionReader } from "./Versioning/VersionReader";
 import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
-import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions } from "./options";
+import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
 import { HttpSetupError } from "./Errors/HttpError";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
@@ -96,7 +96,7 @@ export class HttpServer implements HostedService {
   private docs?: PreparedOpenApiDocs;
 
   constructor(
-    private readonly options: HttpModuleOptions,
+    private readonly options: HttpServerOptions,
     /** Root container: the per-request scope factory. */
     private readonly provider: ServiceProvider,
     /** Root resolver for optional kernel services (Environment). */
@@ -181,11 +181,11 @@ export class HttpServer implements HostedService {
       this.options.versioning,
       this.collectRouteComposer(),
     );
-    this.router = builder.build(this.options.controllers as readonly Class<object>[]);
+    this.router = builder.build(this.options.controllers);
     this.readVersion = createVersionReader(this.options.versioning);
     this.docs = prepareOpenApiDocs({
       option: this.options.docs,
-      controllers: this.options.controllers as readonly Class<object>[],
+      controllers: this.options.controllers,
       globalPrefix: this.options.prefix,
       versioning: this.options.versioning,
       environment: this.resolver.tryResolve(Environment),

package/core/http/Middleware/errorHandler.ts

@@ -3,6 +3,7 @@ import { redactSensitive, redactSensitiveText } from "../../../library/redaction
 import { HttpClientError, HttpErrorCode } from "../../../library/http-client/errors";
 import type { HttpContext } from "../HttpContext/HttpContext";
 import { HttpError } from "../Errors/HttpError";
+import { upstreamFailure } from "../Errors/upstreamFailure";
 import type { HttpMiddleware } from "./types";
 
 export interface ErrorHandlerOptions {
@@ -162,6 +163,8 @@ function unexpectedStatus(error: unknown, mapper?: (error: unknown) => number |
   if (error instanceof HttpClientError && error.code !== undefined) {
     return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   }
+  const upstream = upstreamFailure(error);
+  if (upstream !== undefined) return upstream === "timeout" ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   let mapped: number | undefined;
   try { mapped = mapper?.(error); } catch { mapped = undefined; }
   if (mapped !== undefined && Number.isInteger(mapped) && mapped >= 400 && mapped <= 599) return [mapped, REASONS[mapped] ?? (mapped >= 500 ? "Server Error" : "Client Error")];

package/core/http/httpModule.ts

@@ -1,10 +1,10 @@
 import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, collectModuleControllers, type BazisModule, type ProviderDefinition } from "../di";
 import { HttpServer } from "./HttpServer";
-import type { HttpModuleOptions } from "./options";
+import type { HttpModuleOptions, HttpServerOptions } from "./options";
 
 /**
- * Builds the HTTP module: discovers controllers from `imports` (and optional
- * `controllers` on feature modules) and registers the HttpServer hosted service.
+ * Builds the HTTP module: discovers the `controllers` of the modules in
+ * `imports` and registers the HttpServer hosted service.
  *
  * ```ts
  * @Module({
@@ -22,11 +22,9 @@ import type { HttpModuleOptions } from "./options";
  * ```
  */
 export function httpModule(options: HttpModuleOptions): BazisModule {
-  const allControllers = collectModuleControllers(options.imports ?? [], options.controllers);
-
-  const serverOptions: HttpModuleOptions = {
+  const serverOptions: HttpServerOptions = {
     ...options,
-    controllers: allControllers,
+    controllers: collectModuleControllers(options.imports ?? []),
   };
 
   const providers: ProviderDefinition[] = [
@@ -40,7 +38,6 @@ export function httpModule(options: HttpModuleOptions): BazisModule {
   @Module({
     imports: options.imports,
     providers,
-    controllers: options.controllers,
   })
   class HttpModule {}
 

package/core/http/index.ts

@@ -39,6 +39,7 @@ export { anyOf } from "./Authorization/anyOf";
 export {
   resolveAuthorizeMeta,
   type AuthorizeCheck,
+  type AuthorizeContext,
   type AuthorizeOptions,
   type ResolvedAuthorizeMeta,
 } from "./Authorization/metadata";
@@ -140,3 +141,4 @@ export {
   UnauthorizedError,
   UnsupportedMediaTypeError,
 } from "./Errors/HttpError";
+export { markUpstreamFailure, upstreamFailure, type UpstreamFailure } from "./Errors/upstreamFailure";

package/core/http/options.ts

@@ -56,11 +56,6 @@ export interface HttpModuleOptions {
    * Authorized/CORS-allowed clients can then inspect each redirect Location.
    */
   readonly inspectableRedirects?: boolean;
-  /**
-   * Controller classes (decorated with @Controller). Optional when controllers
-   * are declared on imported modules via `controllers` on `BazisModule`.
-   */
-  readonly controllers?: readonly Class<object>[];
   /** Request-model validator captured by this HTTP server instance. */
   readonly validator?: ModelValidator;
   /**
@@ -136,3 +131,8 @@ export interface HttpModuleOptions {
   /** Hosted-service startup phase (default 10 — after infrastructure). */
   readonly phase?: number;
 }
+
+/** @internal What `httpModule` hands to the server: the options plus the controllers it collected. */
+export interface HttpServerOptions extends HttpModuleOptions {
+  readonly controllers: readonly Class<object>[];
+}

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.32" }, 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.32",
   "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",