bazis 0.96.1

package/core/websocket/socket-wrapper.ts

@@ -0,0 +1,314 @@
+import type { ServerWebSocket } from "bun";
+import type { BazisSocket, ReplayDelivery, ServerPacket, SocketBroadcast, SocketContext, SocketUser } from "./types";
+import type { PacketCodec } from "./codec/packet-codec.interface";
+import { payloadToBytes } from "./codec/packet-codec.interface";
+import type { TopicCache } from "./topic-cache";
+import { WebSocketDeliveryError, type ReliableBroadcastOptions, type ReliableBroadcastReceipt } from "./reliable-delivery";
+
+/** A server frame minus the wire version (filled in by the codec). */
+export type OutgoingPacket = Omit<ServerPacket, "v"> & { v?: 1 };
+
+export interface WsConnectionData {
+  sid: string;
+  connId: string;
+  namespace: string;
+  context: SocketContext;
+  rooms: Set<string>;
+  isReconnect?: boolean;
+  /** Runtime bookkeeping; not part of the public socket context. */
+  opened?: boolean;
+  closed?: boolean;
+  /** Fail-closed after a message deadline so queued handlers cannot continue. */
+  messageProcessingStopped?: boolean;
+  /** Immutable authentication authority for reconnect ownership checks. */
+  principal?: SocketUser;
+  /** Aborts socket-owned lifecycle effects once the physical connection closes. */
+  lifetimeController: AbortController;
+  replayDelivery?: ReplayDelivery;
+  /** Bounded by replay queue size; receipts are valid only on the issuing connection. */
+  sentReplayIds?: Set<string>;
+  sentReliableIds?: Set<string>;
+  recentReliableAcks?: Set<string>;
+  replaying?: boolean;
+}
+
+export interface WrapSocketOptions {
+  codec: PacketCodec;
+  /** Per-message cancellation. Omitted for lifecycle hooks. */
+  signal?: AbortSignal;
+  send: (payload: string | Uint8Array) => void;
+  maxRoomNameLength?: number;
+  maxRoomsPerSession?: number;
+  /**
+   * Fan-out to a room, excluding the originating socket (Socket.IO `to()`
+   * semantics). Local delivery uses `ws.publish`, the adapter handles other
+   * nodes, and offline members of the room are queued for reconnect replay.
+   */
+  broadcast: (room: string, packet: OutgoingPacket) => void;
+  broadcastReliable?: (room: string, packet: OutgoingPacket, options: ReliableBroadcastOptions) => Promise<ReliableBroadcastReceipt>;
+  disconnect?: (code: number, reason: string) => void;
+  onRoomsChanged?: (sid: string, rooms: ReadonlySet<string>) => void;
+}
+
+class SocketBroadcastImpl implements SocketBroadcast {
+  constructor(
+    private readonly namespace: string,
+    private readonly room: string,
+    private readonly broadcast: WrapSocketOptions["broadcast"],
+    private readonly signal?: AbortSignal,
+    private readonly reliable?: WrapSocketOptions["broadcastReliable"],
+  ) {}
+
+  emit(event: string, data?: unknown): void {
+    if (this.signal?.aborted) {
+      return;
+    }
+    this.broadcast(this.room, { type: "event", namespace: this.namespace, event, data });
+  }
+
+  async emitReliable(event: string, data: unknown, options: ReliableBroadcastOptions): Promise<ReliableBroadcastReceipt> {
+    this.signal?.throwIfAborted();
+    if (!this.reliable) throw new WebSocketDeliveryError("RELIABLE_DELIVERY_UNAVAILABLE");
+    return this.reliable(this.room, { type: "event", namespace: this.namespace, event, data }, options);
+  }
+}
+
+export class BazisSocketImpl implements BazisSocket {
+  private dataTarget?: SocketContext;
+  private dataProxy?: SocketContext;
+  private dataProxyCache?: WeakMap<object, object>;
+
+  constructor(
+    private readonly ws: ServerWebSocket<WsConnectionData>,
+    private readonly topics: TopicCache,
+    private readonly options: WrapSocketOptions,
+  ) {}
+
+  get id(): string {
+    return this.ws.data.sid;
+  }
+
+  get connId(): string {
+    return this.ws.data.connId;
+  }
+
+  get namespace(): string {
+    return this.ws.data.namespace;
+  }
+
+  get data(): SocketContext {
+    const context = this.ws.data.context;
+    if (!this.options.signal) {
+      return context;
+    }
+    if (this.dataTarget !== context || !this.dataProxy) {
+      const signal = this.options.signal;
+      this.dataTarget = context;
+      this.dataProxyCache = new WeakMap<object, object>();
+      this.dataProxy = abortAwareProxy(context, signal, this.dataProxyCache);
+    }
+    return this.dataProxy;
+  }
+
+  get rooms(): ReadonlySet<string> {
+    // ReadonlySet is a compile-time contract only; exposing the live Set lets
+    // plain JavaScript (or a cast) bypass join/leave, persistence and abort.
+    return new Set(this.ws.data.rooms);
+  }
+
+  get signal(): AbortSignal | undefined {
+    return this.options.signal;
+  }
+
+  emit(event: string, data?: unknown): void {
+    if (this.options.signal?.aborted) {
+      return;
+    }
+    const payload = this.options.codec.encodeServer({
+      type: "event",
+      namespace: this.namespace,
+      event,
+      data,
+    });
+    this.options.send(payload);
+  }
+
+  to(room: string): SocketBroadcast {
+    assertRoomName(room, this.options.maxRoomNameLength);
+    return new SocketBroadcastImpl(this.namespace, room, this.options.broadcast, this.options.signal, this.options.broadcastReliable);
+  }
+
+  in(room: string): SocketBroadcast {
+    return this.to(room);
+  }
+
+  join(room: string): void {
+    if (this.options.signal?.aborted) {
+      return;
+    }
+    assertRoomName(room, this.options.maxRoomNameLength);
+    const maxRooms = this.options.maxRoomsPerSession ?? 256;
+    if (!this.ws.data.rooms.has(room) && this.ws.data.rooms.size >= maxRooms) {
+      throw new Error(`WebSocket room limit exceeded (${maxRooms}).`);
+    }
+    const topic = this.topics.get(this.namespace, room);
+    this.ws.subscribe(topic);
+    this.ws.data.rooms.add(room);
+    this.options.onRoomsChanged?.(this.ws.data.sid, this.ws.data.rooms);
+  }
+
+  leave(room: string): void {
+    if (this.options.signal?.aborted) {
+      return;
+    }
+    assertRoomName(room, this.options.maxRoomNameLength);
+    const topic = this.topics.get(this.namespace, room);
+    this.ws.unsubscribe(topic);
+    this.ws.data.rooms.delete(room);
+    this.topics.delete(this.namespace, room);
+    this.options.onRoomsChanged?.(this.ws.data.sid, this.ws.data.rooms);
+  }
+
+  disconnect(code = 1000, reason = "server disconnect"): void {
+    if (this.options.signal?.aborted) {
+      return;
+    }
+    if (this.options.disconnect) this.options.disconnect(code, reason);
+    else this.ws.close(code, reason);
+  }
+}
+
+export function wrapSocket(
+  ws: ServerWebSocket<WsConnectionData>,
+  topics: TopicCache,
+  options: WrapSocketOptions,
+): BazisSocket {
+  return new BazisSocketImpl(ws, topics, options);
+}
+
+export function createConnectionData(
+  namespace: string,
+  context: SocketContext,
+  sid: string = crypto.randomUUID(),
+  replayDelivery: ReplayDelivery = "transport",
+): WsConnectionData {
+  return {
+    sid,
+    connId: crypto.randomUUID(),
+    namespace,
+    context: cloneSocketContext(context),
+    principal: cloneSocketUser(context.user),
+    lifetimeController: new AbortController(),
+    rooms: new Set<string>(),
+    replayDelivery,
+  };
+}
+
+export function restoreRoomSubscriptions(
+  ws: ServerWebSocket<WsConnectionData>,
+  topics: TopicCache,
+): void {
+  for (const room of ws.data.rooms) {
+    ws.subscribe(topics.get(ws.data.namespace, room));
+  }
+}
+
+/** Removes subscriptions owned by the connection before rebinding its SID. */
+export function detachRoomSubscriptions(
+  ws: ServerWebSocket<WsConnectionData>,
+  topics: TopicCache,
+): void {
+  for (const room of ws.data.rooms) {
+    ws.unsubscribe(topics.get(ws.data.namespace, room));
+  }
+}
+
+export function applySessionToConnection(
+  ws: ServerWebSocket<WsConnectionData>,
+  sid: string,
+  context: SocketContext,
+  rooms: string[],
+): void {
+  ws.data.sid = sid;
+  ws.data.context = cloneSocketContext(context);
+  ws.data.rooms = new Set(rooms);
+  ws.data.isReconnect = true;
+  ws.data.sentReplayIds = undefined;
+  ws.data.sentReliableIds = undefined;
+  ws.data.recentReliableAcks = undefined;
+}
+
+function cloneSocketContext(context: SocketContext): SocketContext {
+  return {
+    ...context,
+    ...(context.user ? { user: cloneSocketUser(context.user) } : {}),
+  };
+}
+
+function cloneSocketUser(user: SocketUser | undefined): SocketUser | undefined {
+  return user ? { ...user } : undefined;
+}
+
+function abortAwareProxy<T extends object>(
+  value: T,
+  signal: AbortSignal,
+  cache: WeakMap<object, object>,
+): T {
+  const cached = cache.get(value);
+  if (cached) {
+    return cached as T;
+  }
+  const proxy = new Proxy(value, {
+    get: (target, property, receiver) => {
+      const nested = Reflect.get(target, property, receiver) as unknown;
+      return isPlainMutableObject(nested)
+        ? abortAwareProxy(nested, signal, cache)
+        : nested;
+    },
+    set: (target, property, next, receiver) =>
+      signal.aborted ? true : Reflect.set(target, property, next, receiver),
+    deleteProperty: (target, property) =>
+      signal.aborted ? true : Reflect.deleteProperty(target, property),
+    defineProperty: (target, property, descriptor) =>
+      signal.aborted ? true : Reflect.defineProperty(target, property, descriptor),
+    setPrototypeOf: (target, prototype) =>
+      signal.aborted ? true : Reflect.setPrototypeOf(target, prototype),
+  });
+  cache.set(value, proxy);
+  return proxy;
+}
+
+function isPlainMutableObject(value: unknown): value is object {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  return Array.isArray(value) || prototype === Object.prototype || prototype === null;
+}
+
+export function sendPayload(
+  ws: ServerWebSocket<WsConnectionData>,
+  payload: string | Uint8Array,
+): void {
+  trySendPayload(ws, payload);
+}
+
+/** Internal acceptance check: Bun's -1 is queued backpressure, 0 is a drop. */
+export function trySendPayload(
+  ws: ServerWebSocket<WsConnectionData>,
+  payload: string | Uint8Array,
+): boolean {
+  return ws.send(typeof payload === "string" ? payload : payloadToBytes(payload)) !== 0;
+}
+
+function assertRoomName(room: string, maxLength = 256): void {
+  if (room.length === 0) {
+    throw new Error("WebSocket room name must not be empty.");
+  }
+  if (room.length > maxLength) {
+    throw new Error(`WebSocket room name exceeds ${maxLength} characters.`);
+  }
+  if (room.includes("\0")) {
+    throw new Error("WebSocket room name contains an invalid separator.");
+  }
+}

package/core/websocket/topic-cache.ts

@@ -0,0 +1,59 @@
+import { normalizeNamespace } from "./decorators";
+
+const SEP = "\0";
+
+export interface TopicCacheOptions {
+  readonly maxTopics?: number;
+}
+
+export interface TopicCacheStats {
+  readonly topics: number;
+}
+
+export class TopicCache {
+  private readonly cache = new Map<string, string>();
+  private readonly maxTopics: number;
+
+  public constructor(options: TopicCacheOptions = {}) {
+    this.maxTopics = options.maxTopics !== undefined && Number.isFinite(options.maxTopics) && options.maxTopics > 0
+      ? Math.floor(options.maxTopics)
+      : 10_000;
+  }
+
+  get(namespace: string, room: string): string {
+    const ns = normalizeNamespace(namespace);
+    const key = `${ns}${SEP}${room}`;
+    const cached = this.cache.get(key);
+    if (cached) {
+      return cached;
+    }
+    const topic = key;
+    this.ensureCapacity(key);
+    this.cache.set(key, topic);
+    return topic;
+  }
+
+  delete(namespace: string, room: string): void {
+    this.cache.delete(`${normalizeNamespace(namespace)}${SEP}${room}`);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  getStats(): TopicCacheStats {
+    return { topics: this.cache.size };
+  }
+
+  private ensureCapacity(nextKey: string): void {
+    if (this.cache.size < this.maxTopics || this.cache.has(nextKey)) {
+      return;
+    }
+    const oldest = this.cache.keys().next().value as string | undefined;
+    if (oldest !== undefined) {
+      this.cache.delete(oldest);
+    }
+  }
+}
+
+export const topicCache = new TopicCache();

package/core/websocket/types.ts

@@ -0,0 +1,122 @@
+import type { ReliableBroadcastOptions, ReliableBroadcastReceipt } from "./reliable-delivery";
+
+/**
+ * WebSocket wire protocol (v1) and the public `BazisSocket` surface.
+ * Self-contained: no framework runtime types leak into the wire format.
+ */
+
+export type ReplayDelivery = "transport" | "client-ack";
+
+export interface ReplayAcknowledgement {
+  /** UUIDs actually received on this physical connection; acknowledge after processing. */
+  deliveryIds: string[];
+}
+
+export interface ClientPacket {
+  v: 1;
+  type: "event" | "reconnect" | "ping" | "replay-ack";
+  namespace?: string;
+  event?: string;
+  data?: unknown;
+  /** Correlation id for acknowledgements. */
+  id?: string;
+}
+
+export interface ServerPacket {
+  v: 1;
+  type: "event" | "ack" | "connected" | "reconnected" | "error" | "pong";
+  namespace?: string;
+  event?: string;
+  data?: unknown;
+  /** Echoes the client packet id on ack/error. */
+  id?: string;
+  /** Session id, sent on connected/reconnected. */
+  sid?: string;
+  /** Replay prefix in reconnected; overflow follows as ordinary packets. */
+  missed?: ServerPacket[];
+  /** Stable replay identity, separate from request/response correlation id. */
+  deliveryId?: string;
+  /** Negotiated replay semantics, advertised by connected/reconnected. */
+  replayDelivery?: ReplayDelivery;
+  /** Number of replay packets in this reconnect, including subsequent event frames. */
+  replayCount?: number;
+}
+
+export interface ReconnectPacketData {
+  sid?: string;
+  token?: string;
+}
+
+/** Authenticated principal attached at upgrade. */
+export interface SocketUser {
+  readonly id: string;
+  readonly [key: string]: unknown;
+}
+
+/** Per-connection state available to gateways (user + custom upgrade data). */
+export interface SocketContext {
+  user?: SocketUser;
+  [key: string]: unknown;
+}
+
+/**
+ * Completes the packet's single acknowledgement using the selected codec.
+ * A handler declaring this third parameter and returning undefined waits for
+ * the callback within messageHandlingTimeoutMs. Ignored without a packet id,
+ * after cancellation, or after a return value/callback already replied.
+ */
+export type AckCallback = (response?: unknown, error?: { message: string; code?: string }) => void;
+
+/** Chainable broadcast target: `socket.to(room).emit(...)`. */
+export interface SocketBroadcast {
+  emit(event: string, data?: unknown): void;
+  emitReliable(event: string, data: unknown, options: ReliableBroadcastOptions): Promise<ReliableBroadcastReceipt>;
+}
+
+/**
+ * Stable gateway-facing socket API (we never expose Bun's `ServerWebSocket`).
+ * `id` is the session id (stable across reconnects); `connId` is the physical
+ * connection.
+ */
+export interface BazisSocket {
+  readonly id: string;
+  readonly connId: string;
+  readonly namespace: string;
+  readonly data: SocketContext;
+  readonly rooms: ReadonlySet<string>;
+  /** Aborted when the current message is cancelled or exceeds its deadline. */
+  readonly signal?: AbortSignal;
+  emit(event: string, data?: unknown): void;
+  to(room: string): SocketBroadcast;
+  in(room: string): SocketBroadcast;
+  join(room: string): void;
+  leave(room: string): void;
+  disconnect(code?: number, reason?: string): void;
+}
+
+/** Gateway lifecycle hooks (all optional, duck-typed at runtime). */
+export interface OnGatewayInit {
+  onGatewayInit?(): void | Promise<void>;
+}
+export interface OnGatewayConnection {
+  handleConnection?(socket: BazisSocket): void | Promise<void>;
+}
+export interface OnGatewayDisconnect {
+  handleDisconnect?(socket: BazisSocket, reason: string): void | Promise<void>;
+}
+export interface OnGatewayShutdown {
+  onGatewayShutdown?(): void | Promise<void>;
+}
+
+export function hasOnGatewayInit(value: unknown): value is Required<OnGatewayInit> {
+  return typeof (value as OnGatewayInit | null)?.onGatewayInit === "function";
+}
+export function hasHandleConnection(value: unknown): value is Required<OnGatewayConnection> {
+  return typeof (value as OnGatewayConnection | null)?.handleConnection === "function";
+}
+export function hasHandleDisconnect(value: unknown): value is Required<OnGatewayDisconnect> {
+  return typeof (value as OnGatewayDisconnect | null)?.handleDisconnect === "function";
+}
+export function hasOnGatewayShutdown(value: unknown): value is Required<OnGatewayShutdown> {
+  return typeof (value as OnGatewayShutdown | null)?.onGatewayShutdown === "function";
+}

package/core/websocket/websocketModule.ts

@@ -0,0 +1,96 @@
+import {
+  DI,
+  markGlobal,
+  Module,
+  singleton,
+  type Class,
+  type BazisModule,
+  type ProviderDefinition,
+  type ServiceResolver,
+} from "../di";
+import { WEBSOCKET_UPGRADE } from "../http";
+import { WebSocketExplorer } from "./explorer";
+import { WebSocketServer, type WebSocketMemoryLimits } from "./ws-server";
+import type { WsAccessTokenAuthenticator, WsMiddleware } from "./middleware";
+import type { WebSocketAdapter } from "./adapter/adapter.interface";
+import type { PacketCodec } from "./codec/packet-codec.interface";
+import type { ReplayDelivery } from "./types";
+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.
+   */
+  readonly gateways: readonly Class<object>[];
+  /** Kernel-owned upgrade policy using DI; runs before gateway middleware. */
+  readonly middlewareFactory?: (services: ServiceResolver) => WsMiddleware;
+  /** Upgrade-time authentication; `null`/omitted means anonymous connections. */
+  readonly authenticator?: WsAccessTokenAuthenticator | null;
+  /** Reject anonymous upgrades. Requires `authenticator` and fails fast without it. */
+  readonly requireAuth?: boolean;
+  /** Accept `?token=` during upgrade. Disabled by default because URLs leak. */
+  readonly allowQueryToken?: boolean;
+  /** Default allowed origins when a gateway does not specify its own. */
+  readonly cors?: { origins?: string[] };
+  /** Pluggable broadcast/session adapter (defaults to in-memory, single-node). */
+  readonly adapter?: WebSocketAdapter;
+  /** Wire codec (defaults to JSON). */
+  readonly codec?: PacketCodec;
+  /** Default replay confirmation mode. A client can opt in with ?replay=client-ack. */
+  readonly replayDelivery?: ReplayDelivery;
+  readonly onDiagnostic?: (event: WebSocketDiagnostic) => void;
+  /** In-process memory bounds for sessions, rooms, topics and rate-limit buckets. */
+  readonly limits?: WebSocketMemoryLimits;
+  /** Expose validator/handler exception text to clients. Default false. */
+  readonly exposeHandlerErrors?: boolean;
+}
+
+/**
+ * Registers WebSocket gateways and shares the HTTP listener for upgrades.
+ *
+ * ```ts
+ * @Module({ imports: [httpModule({ ... }), websocketModule({ gateways: [ChatGateway] })] })
+ * class AppModule {}
+ * ```
+ *
+ * The built `WebSocketServer` is exposed under {@link WEBSOCKET_UPGRADE}; the
+ * HTTP server resolves it and wires `Bun.serve({ websocket })` automatically.
+ */
+export function websocketModule(config: WebSocketModuleConfig): BazisModule {
+  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 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);
+        }
+        return new WebSocketServer({
+          namespaces,
+          authenticator: config.authenticator ?? null,
+          requireAuth: config.requireAuth ?? false,
+          allowQueryToken: config.allowQueryToken ?? false,
+          ...(config.cors?.origins ? { defaultCorsOrigins: config.cors.origins } : {}),
+          ...(config.adapter ? { adapter: config.adapter } : {}),
+          ...(config.codec ? { codec: config.codec } : {}),
+          ...(config.replayDelivery ? { replayDelivery: config.replayDelivery } : {}),
+          ...(config.onDiagnostic ? { onDiagnostic: config.onDiagnostic } : {}),
+          ...(config.limits ? { limits: config.limits } : {}),
+          ...(config.exposeHandlerErrors !== undefined ? { exposeHandlerErrors: config.exposeHandlerErrors } : {}),
+        });
+      }),
+    ),
+  ];
+
+  // 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] })
+  class WebSocketModule {}
+
+  return markGlobal(WebSocketModule);
+}