bazis 0.96.1

package/core/websocket/adapter/redis.adapter.ts

@@ -0,0 +1,218 @@
+import type { RedisClient } from "bun";
+import type { SessionState } from "../session-manager";
+import { createInstanceId, type WebSocketAdapter, type WebSocketAdapterHooks } from "./adapter.interface";
+import { RedisWebSocketOperations } from "./redis-operations";
+import { RedisRoomDeliveryStore, type RedisReliableDeliveryOptions } from "./redis-delivery-store";
+import { KEYS, UPDATE_ROOMS, DELETE_ROOMS } from "./redis-delivery-scripts";
+
+export interface RedisWebSocketAdapterOptions {
+  /** Optional host-owned command client isolating delivery from session I/O; same logical store required. */
+  readonly deliveryClient?: RedisClient;
+  /** Shared by the nodes of one application; isolate unrelated applications. */
+  readonly keyPrefix?: string;
+  /** Initial-write/deletion protection window, milliseconds. Default 60,000. */
+  readonly writeProtectionMs?: number;
+  /** Maximum encoded session record. Default 8 MiB. */
+  readonly maxSessionBytes?: number;
+  /** Maximum pub/sub packet bytes. Default 1 MiB. */
+  readonly maxPublishBytes?: number;
+  readonly operationTimeoutMs?: number;
+  readonly maxPendingOperations?: number;
+  readonly reliable?: RedisReliableDeliveryOptions;
+}
+
+// One Redis key per SID. The record survives until both reconnect TTL and the
+// initial-write window have elapsed. Expiring a key can therefore never make an
+// old snapshot eligible for an initial write again. All revision checks and
+// writes execute atomically in the same Lua invocation.
+const SAVE = KEYS + `
+local raw = redis.call('GET', KEYS[1])
+local next = cjson.decode(ARGV[1])
+local expected = tonumber(ARGV[2])
+local window = tonumber(ARGV[3])
+local clock = redis.call('TIME')
+local now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)
+if raw then
+  local current = cjson.decode(raw)
+  if current.deleted or next.revision <= current.revision then return 0 end
+  if expected >= 0 and expected ~= current.revision then return 0 end
+  if next.createdAt ~= current.createdAt or next.creationToken ~= current.creationToken then return 0 end
+else
+  if expected > 0 or next.revision ~= 1 then return 0 end
+  if next.createdAt <= now - window or next.createdAt > now + 1000 then return 0 end
+end
+local ttl = math.ceil(math.max(next.expiresAt, next.createdAt + window) - now)
+if ttl <= 0 then return 0 end
+${UPDATE_ROOMS}
+redis.call('SET', KEYS[1], cjson.encode({revision=next.revision, createdAt=next.createdAt, creationToken=next.creationToken, state=ARGV[1]}), 'PX', ttl)
+return 1
+`;
+
+const DELETE = KEYS + `
+local raw = redis.call('GET', KEYS[1])
+local current = raw and cjson.decode(raw) or nil
+local revision = tonumber(ARGV[1])
+local clock = redis.call('TIME')
+local now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)
+if current and revision >= 0 and revision < current.revision then return 0 end
+if revision < 0 then revision = current and current.revision + 1 or 1 end
+${DELETE_ROOMS}
+local created = current and current.createdAt or now
+local ttl = math.ceil(created + tonumber(ARGV[2]) - now)
+if ttl <= 0 then redis.call('DEL', KEYS[1]); return 1 end
+redis.call('SET', KEYS[1], cjson.encode({revision=revision, createdAt=created, deleted=true}), 'PX', ttl)
+return 1
+`;
+
+/**
+ * Redis/Valkey transport and atomic session storage using the host's native Bun
+ * RedisClient. The adapter owns only a duplicate required by Redis pub/sub mode;
+ * it never closes the supplied command client or clears application keys.
+ */
+export class RedisWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "redis";
+  readonly instanceId = createInstanceId("ws-redis");
+  readonly reliableRooms: RedisRoomDeliveryStore;
+  private readonly operations: RedisWebSocketOperations;
+  private readonly prefix: string;
+  private readonly channel: string;
+  private readonly writeProtectionMs: number;
+  private readonly maxSessionBytes: number;
+  private readonly maxPublishBytes: number;
+  private readonly deliveryClient: RedisClient;
+  private subscriber?: RedisClient;
+  private hooks?: WebSocketAdapterHooks;
+
+  constructor(private readonly client: RedisClient, options: RedisWebSocketAdapterOptions = {}) {
+    if (options.deliveryClient !== undefined && (!options.deliveryClient || typeof options.deliveryClient.send !== "function")) throw new Error("Invalid WebSocket deliveryClient.");
+    this.deliveryClient = options.deliveryClient ?? client;
+    this.prefix = options.keyPrefix ?? "bazis:ws";
+    if (!/^[a-zA-Z0-9:_-]{1,64}$/.test(this.prefix)) throw new Error("Invalid WebSocket Redis keyPrefix.");
+    this.channel = `${this.prefix}:broadcast`;
+    this.writeProtectionMs = positive(options.writeProtectionMs, 60_000, "writeProtectionMs");
+    this.maxSessionBytes = positive(options.maxSessionBytes, 8 * 1024 * 1024, "maxSessionBytes");
+    this.maxPublishBytes = positive(options.maxPublishBytes, 1024 * 1024, "maxPublishBytes");
+    this.operations = new RedisWebSocketOperations(client,
+      positive(options.operationTimeoutMs, 2000, "operationTimeoutMs"),
+      positive(options.maxPendingOperations, 64, "maxPendingOperations"));
+    this.reliableRooms = new RedisRoomDeliveryStore({
+      send: (command, args) => this.operations.run(() => this.deliveryClient.send(command, args)),
+    }, this.prefix, options.reliable);
+  }
+
+  async initialize(hooks: WebSocketAdapterHooks): Promise<void> {
+    if (this.subscriber) throw new Error("WebSocket Redis adapter is already initialized.");
+    if (this.deliveryClient !== this.client) {
+      const key = `${this.prefix}:connection-check:${this.instanceId}`;
+      const nonce = crypto.randomUUID();
+      await this.operations.send("SET", [key, nonce, "PX", "60000"]);
+      try {
+        if (await this.operations.run(() => this.deliveryClient.send("GET", [key])) !== nonce) throw new Error("WebSocket DELIVERY_STORE_MISMATCH.");
+      } finally { await this.operations.send("DEL", [key]); }
+    }
+    await this.reliableRooms.initialize();
+    let accepting = true;
+    let subscriber: RedisClient;
+    try {
+      subscriber = await this.operations.run(async () => {
+        const duplicate = await this.client.duplicate();
+        if (!accepting) { duplicate.close(); throw new Error("WebSocket subscription initialization expired."); }
+        return duplicate;
+      }) as RedisClient;
+    } finally { accepting = false; }
+    this.subscriber = subscriber;
+    this.hooks = hooks;
+    try {
+      await this.operations.run(() => subscriber.subscribe(this.channel, this.receive));
+    } catch (error) {
+      this.hooks = undefined;
+      this.subscriber = undefined;
+      subscriber.close();
+      throw error;
+    }
+  }
+
+  async publish(topic: string, payload: Uint8Array): Promise<void> {
+    if (payload.byteLength > this.maxPublishBytes || topic.length > 1024) throw new Error("WebSocket Redis publish exceeds limits.");
+    await this.operations.send("PUBLISH", [this.channel, JSON.stringify({
+      source: this.instanceId, topic, payload: Buffer.from(payload).toString("base64"),
+    })]);
+  }
+
+  async saveSession(state: SessionState): Promise<void> {
+    await this.save(state, -1);
+  }
+
+  async compareAndSwapSession(state: SessionState, expectedRevision: number): Promise<boolean> {
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) throw new Error("Invalid WebSocket expected revision.");
+    return this.save(state, expectedRevision);
+  }
+
+  async loadSession(sid: string): Promise<SessionState | null> {
+    const raw = await this.operations.send("GET", [this.key(sid)]) as string | null;
+    if (raw === null) return null;
+    if (Buffer.byteLength(raw) > this.maxSessionBytes * 2 + 2048) throw new Error("Stored WebSocket session exceeds limits.");
+    const record = JSON.parse(raw) as { deleted?: boolean; state?: string };
+    // Keep application JSON opaque to Lua/cjson: empty arrays must stay arrays.
+    return record.deleted || record.state === undefined ? null : JSON.parse(record.state) as SessionState;
+  }
+
+  async deleteSession(sid: string, revision?: number): Promise<void> {
+    if (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 0)) throw new Error("Invalid WebSocket deletion revision.");
+    await this.operations.send("EVAL", [DELETE, "1", this.key(sid), String(revision ?? -1), String(this.writeProtectionMs), this.prefix, sid]);
+  }
+
+  async healthCheck(): Promise<void> {
+    if (await this.operations.send("PING", []) !== "PONG") throw new Error("WebSocket store unavailable.");
+    await this.reliableRooms.healthCheck();
+  }
+
+  async close(): Promise<void> {
+    const subscriber = this.subscriber;
+    this.subscriber = undefined;
+    this.hooks = undefined;
+    if (subscriber) {
+      try { await this.operations.run(() => subscriber.unsubscribe(this.channel, this.receive)); }
+      finally { subscriber.close(); }
+    }
+  }
+
+  private async save(state: SessionState, expected: number): Promise<boolean> {
+    if (!Number.isSafeInteger(state.revision) || state.revision! < 1
+      || !Number.isFinite(state.createdAt) || !Number.isFinite(state.expiresAt)) throw new Error("Invalid WebSocket session version or timestamps.");
+    const encoded = JSON.stringify(state);
+    if (Buffer.byteLength(encoded) > this.maxSessionBytes) throw new Error("WebSocket session exceeds Redis storage limit.");
+    return Number(await this.operations.send("EVAL", [SAVE, "1", this.key(state.sid), encoded, String(expected), String(this.writeProtectionMs), this.prefix])) === 1;
+  }
+
+  private key(sid: string): string {
+    if (typeof sid !== "string" || sid.length === 0 || sid.length > 128) throw new Error("Invalid WebSocket session id.");
+    return `${this.prefix}:session:${encodeURIComponent(sid)}`;
+  }
+
+  private readonly receive = (message: string): void => {
+    if (!this.hooks || message.length > Math.ceil(this.maxPublishBytes * 4 / 3) + 4096) return;
+    try {
+      const data = JSON.parse(message) as { source?: unknown; topic?: unknown; payload?: unknown; kind?: unknown; sids?: unknown };
+      if (data.kind === "deliveries") {
+        if (Array.isArray(data.sids) && data.sids.length <= 1000 && data.sids.every((sid) => typeof sid === "string" && sid.length <= 128)) {
+          this.hooks.deliveriesReady?.(data.sids);
+        }
+        return;
+      }
+      if (typeof data.source !== "string" || data.source === this.instanceId
+        || typeof data.topic !== "string" || data.topic.length > 1024 || typeof data.payload !== "string") return;
+      const payload = Buffer.from(data.payload, "base64");
+      if (payload.byteLength > this.maxPublishBytes) return;
+      this.hooks.localPublish(data.topic, payload);
+    } catch {
+      // Invalid bus envelopes cannot escape a Redis callback into the process.
+    }
+  };
+}
+
+function positive(value: number | undefined, fallback: number, field: string): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`WebSocket Redis ${field} must be a positive integer.`);
+  return value;
+}

package/core/websocket/codec/binary.codec.ts

@@ -0,0 +1,87 @@
+import type { ClientPacket, ServerPacket } from "../types";
+import { PacketCodecError } from "../packet-codec";
+import type { PacketCodec } from "./packet-codec.interface";
+
+/** Binary wire format: 0x01 magic + uint32be length + UTF-8 JSON body */
+const MAGIC = 0x01;
+const HEADER_SIZE = 5;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function wrapJson(json: string): Uint8Array {
+  const body = encoder.encode(json);
+  const frame = new Uint8Array(HEADER_SIZE + body.length);
+  frame[0] = MAGIC;
+  new DataView(frame.buffer).setUint32(1, body.length, false);
+  frame.set(body, HEADER_SIZE);
+  return frame;
+}
+
+function unwrapJson(raw: string | Buffer | Uint8Array): string {
+  const bytes =
+    typeof raw === "string"
+      ? encoder.encode(raw)
+      : raw instanceof Buffer
+        ? new Uint8Array(raw)
+        : raw;
+
+  if (bytes.length < HEADER_SIZE || bytes[0] !== MAGIC) {
+    throw new PacketCodecError("Invalid binary packet frame");
+  }
+
+  const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1, false);
+  const end = HEADER_SIZE + length;
+  if (end > bytes.length) {
+    throw new PacketCodecError("Truncated binary packet frame");
+  }
+
+  return decoder.decode(bytes.subarray(HEADER_SIZE, end));
+}
+
+export class BinaryPacketCodec implements PacketCodec {
+  readonly name = "binary";
+
+  encodeServer(packet: Omit<ServerPacket, "v"> & { v?: 1 }): Uint8Array {
+    return wrapJson(JSON.stringify({ v: 1, ...packet }));
+  }
+
+  encodeClient(packet: Omit<ClientPacket, "v"> & { v?: 1 }): Uint8Array {
+    return wrapJson(JSON.stringify({ v: 1, ...packet }));
+  }
+
+  decodeClient(raw: string | Buffer | Uint8Array): ClientPacket {
+    const text = unwrapJson(raw);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new PacketCodecError("Invalid JSON in binary frame");
+    }
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new PacketCodecError("Packet must be a JSON object");
+    }
+
+    const packet = parsed as Partial<ClientPacket>;
+    if (packet.v !== 1) {
+      throw new PacketCodecError("Unsupported packet version");
+    }
+
+    if (packet.type !== "event" && packet.type !== "reconnect" && packet.type !== "ping" && packet.type !== "replay-ack") {
+      throw new PacketCodecError(`Unknown packet type: ${String(packet.type)}`);
+    }
+
+    return packet as ClientPacket;
+  }
+
+  isBinary(raw: string | Buffer | Uint8Array): boolean {
+    if (typeof raw === "string") {
+      return false;
+    }
+    const bytes = raw instanceof Buffer ? new Uint8Array(raw) : raw;
+    return bytes.length > 0 && bytes[0] === MAGIC;
+  }
+}
+
+export const binaryPacketCodec = new BinaryPacketCodec();

package/core/websocket/codec/json.codec.ts

@@ -0,0 +1,34 @@
+import type { ClientPacket, ServerPacket } from "../types";
+import {
+  decodeClientPacket as decodeJsonClient,
+  encodeClientPacket,
+  encodeServerPacket,
+  PacketCodecError,
+} from "../packet-codec";
+import type { PacketCodec } from "./packet-codec.interface";
+
+export class JsonPacketCodec implements PacketCodec {
+  readonly name = "json";
+
+  encodeServer(packet: Omit<ServerPacket, "v"> & { v?: 1 }): string {
+    return encodeServerPacket(packet);
+  }
+
+  encodeClient(packet: Omit<ClientPacket, "v"> & { v?: 1 }): string {
+    return encodeClientPacket(packet);
+  }
+
+  decodeClient(raw: string | Buffer | Uint8Array): ClientPacket {
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    return decodeJsonClient(text);
+  }
+
+  isBinary(raw: string | Buffer | Uint8Array): boolean {
+    void raw;
+    return false;
+  }
+}
+
+export const jsonPacketCodec = new JsonPacketCodec();
+
+export { PacketCodecError };

package/core/websocket/codec/packet-codec.interface.ts

@@ -0,0 +1,17 @@
+import type { ClientPacket, ServerPacket } from "../types";
+
+export interface PacketCodec {
+  readonly name: string;
+  encodeServer(packet: Omit<ServerPacket, "v"> & { v?: 1 }): string | Uint8Array;
+  encodeClient(packet: Omit<ClientPacket, "v"> & { v?: 1 }): string | Uint8Array;
+  decodeClient(raw: string | Buffer | Uint8Array): ClientPacket;
+  isBinary(raw: string | Buffer | Uint8Array): boolean;
+}
+
+export function payloadToBytes(payload: string | Uint8Array): Uint8Array {
+  return typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+}
+
+export function payloadToText(payload: string | Uint8Array): string {
+  return typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+}

package/core/websocket/decorators.ts

@@ -0,0 +1,165 @@
+import type { WsMiddleware } from "./middleware";
+import type { BazisSocket } from "./types";
+
+// Bun runs TC39 decorators natively, but Symbol.metadata may be absent.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const GATEWAY_META = Symbol.for("bazis:ws:gateway");
+const HANDLERS_META = Symbol.for("bazis:ws:handlers");
+
+/** Per-message rate limit (fixed window). */
+export interface WsRateLimit {
+  readonly limit: number;
+  readonly windowMs: number;
+  /** Custom bucket key; defaults to `${socket.id}:${event}`. */
+  readonly key?: (socket: BazisSocket) => string;
+}
+
+export interface WebSocketGatewayOptions {
+  /** Logical namespace. Default: "/". */
+  readonly namespace?: string;
+  /** HTTP upgrade path. Default: "/ws" + namespace ("/ws", "/ws/chat"). */
+  readonly path?: string;
+  /** Allowed origins for the upgrade. Default: app/server origins. */
+  readonly cors?: { origins?: string[]; credentials?: boolean };
+  /** Gateway-level upgrade middleware. */
+  readonly middleware?: WsMiddleware[];
+  /** Max inbound payload bytes. Default: 64 KiB. */
+  readonly maxPayloadBytes?: number;
+  /** Max outbound frame bytes; defaults to maxPayloadBytes. */
+  readonly maxOutboundPayloadBytes?: number;
+  /** Session TTL for reconnect. Default: 2h. */
+  readonly sessionTtlMs?: number;
+}
+
+/**
+ * Validates/transforms a message body before the handler runs. Return the
+ * (possibly coerced) value, or throw to reject. The client receives a generic
+ * validation error by default; applications may explicitly opt into exposing
+ * details for trusted development environments. Deliberately framework-
+ * agnostic: wrap `@/library/validation`, a DTO class, or any schema you like.
+ */
+export type WsBodyValidator = (
+  body: unknown,
+  /** Aborted when message processing is cancelled or times out. */
+  signal?: AbortSignal,
+) => unknown | Promise<unknown>;
+
+export interface MessageHandlerDecl {
+  readonly propertyKey: string | symbol;
+  readonly events: string[];
+  readonly rateLimit?: WsRateLimit;
+  readonly validate?: WsBodyValidator;
+}
+
+interface GatewayCarrier {
+  [GATEWAY_META]?: WebSocketGatewayOptions;
+  [HANDLERS_META]?: MessageHandlerDecl[];
+}
+
+export interface SubscribeMessageOptions {
+  readonly rateLimit?: WsRateLimit;
+  readonly validate?: WsBodyValidator;
+}
+
+/** Marks a class as a WebSocket gateway (analogous to `@Controller`). */
+export function WebSocketGateway(options: WebSocketGatewayOptions = {}) {
+  return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {
+    (context.metadata as GatewayCarrier)[GATEWAY_META] = options;
+  };
+}
+
+function ownHandlers(carrier: GatewayCarrier): MessageHandlerDecl[] {
+  if (!Object.prototype.hasOwnProperty.call(carrier, HANDLERS_META)) {
+    carrier[HANDLERS_META] = carrier[HANDLERS_META] ? [...carrier[HANDLERS_META]] : [];
+  }
+  return carrier[HANDLERS_META]!;
+}
+
+/**
+ * Subscribes a method to one or more events. The handler is called by
+ * positional convention: `(socket, body, ack)` — declare only what you need.
+ * Returning a value auto-acks when the client packet carried an `id`.
+ */
+export function SubscribeMessage(event: string | readonly string[], options?: SubscribeMessageOptions) {
+  return (_value: (this: never, ...args: never[]) => unknown, context: ClassMethodDecoratorContext): void => {
+    if (context.static) {
+      throw new Error("@SubscribeMessage cannot be applied to static methods.");
+    }
+    ownHandlers(context.metadata as GatewayCarrier).push({
+      propertyKey: context.name,
+      events: Array.isArray(event) ? [...event] : [event as string],
+      ...(options?.rateLimit ? { rateLimit: options.rateLimit } : {}),
+      ...(options?.validate ? { validate: options.validate } : {}),
+    });
+  };
+}
+
+export function getWebSocketGatewayMetadata(ctor: object): WebSocketGatewayOptions | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | GatewayCarrier
+    | undefined;
+  return metadata?.[GATEWAY_META];
+}
+
+export function getGatewayMessageHandlers(ctor: object): readonly MessageHandlerDecl[] {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | GatewayCarrier
+    | undefined;
+  return metadata?.[HANDLERS_META] ?? [];
+}
+
+/** Normalizes a namespace to a leading-slash form ("chat" -> "/chat", "" -> "/"). */
+export function normalizeNamespace(namespace: string | undefined): string {
+  const value = namespace?.trim();
+  if (!value || value === "/") {
+    return "/";
+  }
+  const normalized = value.startsWith("/") ? value : `/${value}`;
+  if (normalized.includes("\0") || normalized.includes("?") || normalized.includes("#")) {
+    throw new Error("WebSocket namespace contains an invalid separator.");
+  }
+  return normalized;
+}
+
+export interface ResolvedGatewayOptions {
+  readonly namespace: string;
+  readonly path: string;
+  readonly cors?: { origins?: string[]; credentials?: boolean };
+  readonly middleware: WsMiddleware[];
+  readonly maxPayloadBytes: number;
+  readonly maxOutboundPayloadBytes?: number;
+  readonly sessionTtlMs: number;
+}
+
+const DEFAULT_MAX_PAYLOAD_BYTES = 64 * 1024;
+const DEFAULT_SESSION_TTL_MS = 2 * 60 * 60 * 1000;
+
+export function resolveWebSocketGatewayOptions(options: WebSocketGatewayOptions): ResolvedGatewayOptions {
+  const namespace = normalizeNamespace(options.namespace);
+  const path = options.path ?? (namespace === "/" ? "/ws" : `/ws${namespace}`);
+  if (!path.startsWith("/") || path.includes("\0") || path.includes("?") || path.includes("#")) {
+    throw new Error(`WebSocket path "${path}" must be an absolute path without query/hash separators.`);
+  }
+  const maxPayloadBytes = positiveOption(options.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES, "maxPayloadBytes");
+  const sessionTtlMs = positiveOption(options.sessionTtlMs, DEFAULT_SESSION_TTL_MS, "sessionTtlMs");
+  return {
+    namespace,
+    path,
+    ...(options.cors ? { cors: options.cors } : {}),
+    middleware: options.middleware ?? [],
+    maxPayloadBytes,
+    maxOutboundPayloadBytes: positiveOption(options.maxOutboundPayloadBytes, maxPayloadBytes, "maxOutboundPayloadBytes"),
+    sessionTtlMs,
+  };
+}
+
+function positiveOption(value: number | undefined, fallback: number, field: string): number {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`WebSocket ${field} must be a positive number.`);
+  }
+  return Math.floor(value);
+}

package/core/websocket/explorer.ts

@@ -0,0 +1,126 @@
+import {
+  getGatewayMessageHandlers,
+  getWebSocketGatewayMetadata,
+  resolveWebSocketGatewayOptions,
+  type WsBodyValidator,
+  type WsRateLimit,
+} from "./decorators";
+import type { WsMiddleware } from "./middleware";
+
+export interface CompiledWsHandler {
+  events: string[];
+  handler: (...args: unknown[]) => unknown;
+  handlerName: string | symbol;
+  /** Declared parameter count; drives positional `(socket, body, ack)` binding. */
+  arity: number;
+  rateLimit?: WsRateLimit;
+  validate?: WsBodyValidator;
+}
+
+export interface RegisteredNamespace {
+  namespace: string;
+  path: string;
+  gatewayInstance: unknown;
+  handlers: Map<string, CompiledWsHandler>;
+  middleware: WsMiddleware[];
+  corsOrigins: string[];
+  maxPayloadBytes: number;
+  maxOutboundPayloadBytes?: number;
+  sessionTtlMs: number;
+}
+
+/**
+ * Compiles gateway instances into per-namespace handler maps (event -> handler).
+ * Handler binding is positional `(socket, body, ack)` by arity — no parameter
+ * decorators (TC39 decorators do not support them).
+ */
+export class WebSocketExplorer {
+  public explore(gatewayInstances: readonly unknown[]): RegisteredNamespace[] {
+    const namespaces: RegisteredNamespace[] = [];
+    const namespacesByName = new Map<string, string>();
+    const namespacesByPath = new Map<string, string>();
+
+    for (const instance of gatewayInstances) {
+      const gatewayClass = (instance as { constructor: object } | null)?.constructor;
+      if (!gatewayClass) {
+        continue;
+      }
+      const metadata = getWebSocketGatewayMetadata(gatewayClass);
+      if (!metadata) {
+        continue;
+      }
+
+      const resolved = resolveWebSocketGatewayOptions(metadata);
+      const gatewayName = (gatewayClass as { name?: string }).name ?? "?";
+      const duplicateNamespace = namespacesByName.get(resolved.namespace);
+      if (duplicateNamespace !== undefined) {
+        throw new Error(
+          `Duplicate WebSocket namespace "${resolved.namespace}" on gateways "${duplicateNamespace}" and "${gatewayName}".`,
+        );
+      }
+      const duplicatePath = namespacesByPath.get(resolved.path);
+      if (duplicatePath !== undefined) {
+        throw new Error(
+          `Duplicate WebSocket path "${resolved.path}" on gateways "${duplicatePath}" and "${gatewayName}".`,
+        );
+      }
+      namespacesByName.set(resolved.namespace, gatewayName);
+      namespacesByPath.set(resolved.path, gatewayName);
+      const handlers = new Map<string, CompiledWsHandler>();
+
+      for (const decl of getGatewayMessageHandlers(gatewayClass)) {
+        const method = (instance as Record<string | symbol, unknown>)[decl.propertyKey];
+        if (typeof method !== "function") {
+          continue;
+        }
+        const compiled: CompiledWsHandler = {
+          events: decl.events,
+          handler: (method as (...args: unknown[]) => unknown).bind(instance),
+          handlerName: decl.propertyKey,
+          arity: method.length,
+          ...(decl.rateLimit ? { rateLimit: decl.rateLimit } : {}),
+          ...(decl.validate ? { validate: decl.validate } : {}),
+        };
+        if (decl.rateLimit !== undefined) {
+          assertRateLimit(decl.rateLimit, gatewayName, decl.propertyKey);
+        }
+        for (const event of decl.events) {
+          if (typeof event !== "string" || event.trim().length === 0) {
+            throw new Error(`@SubscribeMessage event on ${gatewayName}.${String(decl.propertyKey)} must not be empty.`);
+          }
+          if (handlers.has(event)) {
+            throw new Error(
+              `Duplicate @SubscribeMessage("${event}") in gateway "${(gatewayClass as { name?: string }).name ?? "?"}"`,
+            );
+          }
+          handlers.set(event, compiled);
+        }
+      }
+
+      namespaces.push({
+        namespace: resolved.namespace,
+        path: resolved.path,
+        gatewayInstance: instance,
+        handlers,
+        middleware: resolved.middleware,
+        // Empty means "inherit the server/module default". An explicit
+        // gateway wildcard remains ["*"] and deliberately overrides it.
+        corsOrigins: resolved.cors?.origins ? [...resolved.cors.origins] : [],
+        maxPayloadBytes: resolved.maxPayloadBytes,
+        maxOutboundPayloadBytes: resolved.maxOutboundPayloadBytes,
+        sessionTtlMs: resolved.sessionTtlMs,
+      });
+    }
+
+    return namespaces;
+  }
+}
+
+function assertRateLimit(rateLimit: WsRateLimit, gateway: string, method: string | symbol): void {
+  if (!Number.isInteger(rateLimit.limit) || rateLimit.limit <= 0) {
+    throw new Error(`WebSocket rateLimit.limit on ${gateway}.${String(method)} must be a positive integer.`);
+  }
+  if (!Number.isFinite(rateLimit.windowMs) || rateLimit.windowMs <= 0) {
+    throw new Error(`WebSocket rateLimit.windowMs on ${gateway}.${String(method)} must be positive.`);
+  }
+}