bazis 0.96.1

package/core/websocket/index.ts

@@ -0,0 +1,78 @@
+export {
+  WebSocketGateway,
+  SubscribeMessage,
+  getWebSocketGatewayMetadata,
+  getGatewayMessageHandlers,
+  normalizeNamespace,
+  resolveWebSocketGatewayOptions,
+  type WebSocketGatewayOptions,
+  type SubscribeMessageOptions,
+  type ResolvedGatewayOptions,
+  type MessageHandlerDecl,
+  type WsRateLimit,
+  type WsBodyValidator,
+} from "./decorators";
+export type {
+  ClientPacket,
+  ServerPacket,
+  ReconnectPacketData,
+  ReplayDelivery,
+  ReplayAcknowledgement,
+  SocketUser,
+  SocketContext,
+  AckCallback,
+  SocketBroadcast,
+  BazisSocket,
+  OnGatewayInit,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  OnGatewayShutdown,
+} from "./types";
+export {
+  composeWsUpgradeMiddleware,
+  createOriginCheckMiddleware,
+  createWsAuthMiddleware,
+  extractWebSocketToken,
+  WsUpgradeError,
+  type WsMiddleware,
+  type WsUpgradeContext,
+  type WsAccessTokenAuthenticator,
+  type WsAuthenticationContext,
+} from "./middleware";
+export { WsRateLimiter, type WsRateLimiterOptions, type WsRateLimiterStats } from "./WsRateLimiter";
+export { WebSocketExplorer, type CompiledWsHandler, type RegisteredNamespace } from "./explorer";
+export {
+  WebSocketServer,
+  type WebSocketMemoryLimits,
+  type WebSocketServerOptions,
+  type WebSocketServerStats,
+  type WsConnectionData,
+} from "./ws-server";
+export { websocketModule, type WebSocketModuleConfig } from "./websocketModule";
+export { TopicCache, topicCache, type TopicCacheOptions, type TopicCacheStats } from "./topic-cache";
+export {
+  encodeServerPacket,
+  decodeClientPacket,
+  createAckPacket,
+  createConnectedPacket,
+  createReconnectedPacket,
+  PacketCodecError,
+} from "./packet-codec";
+export { BazisSocketImpl, wrapSocket, restoreRoomSubscriptions, detachRoomSubscriptions, sendPayload } from "./socket-wrapper";
+export {
+  SessionManager,
+  SessionCapacityError,
+  type SessionState,
+  type SessionManagerOptions,
+  type OfflineBroadcastResult,
+} from "./session-manager";
+export type { WebSocketAdapter, WebSocketAdapterHooks } from "./adapter/adapter.interface";
+export { InMemoryWebSocketAdapter, inMemoryWebSocketAdapter, type InMemoryWebSocketAdapterOptions } from "./adapter/in-memory.adapter";
+export { RedisWebSocketAdapter, type RedisWebSocketAdapterOptions } from "./adapter/redis.adapter";
+export type { RedisReliableDeliveryOptions } from "./adapter/redis-delivery-store";
+export { WebSocketDeliveryError } from "./reliable-delivery";
+export type { ReliableBroadcastOptions, ReliableBroadcastReceipt, ReliableRoomPublication, ReliableSessionOwner, ReliableDeliveryBatch, ReliableRoomDelivery, WebSocketDiagnostic } from "./reliable-delivery";
+export { createInstanceId } from "./adapter/adapter.interface";
+export type { PacketCodec } from "./codec/packet-codec.interface";
+export { JsonPacketCodec, jsonPacketCodec } from "./codec/json.codec";
+export { BinaryPacketCodec, binaryPacketCodec } from "./codec/binary.codec";

package/core/websocket/middleware.ts

@@ -0,0 +1,146 @@
+import type { SocketUser } from "./types";
+
+const MAX_SOCKET_USER_ID_LENGTH = 256;
+
+/** Mutable context for the upgrade pipeline; `data` flows into `ws.data.context`. */
+export interface WsUpgradeContext {
+  readonly request: Request;
+  readonly namespace: string;
+  readonly path: string;
+  /** Aborted when the upgrade is cancelled or exceeds its deadline. */
+  readonly signal: AbortSignal;
+  data: Record<string, unknown>;
+}
+
+/** Upgrade middleware (Koa/ASP.NET-style); throw {@link WsUpgradeError} to reject. */
+export type WsMiddleware = (ctx: WsUpgradeContext, next: () => Promise<void>) => void | Promise<void>;
+
+/** Authenticates a connection at upgrade. Return `null` for anonymous. */
+export interface WsAuthenticationContext {
+  readonly signal: AbortSignal;
+  readonly namespace: string;
+  readonly path?: string;
+  readonly request?: Request;
+}
+
+export type WsAccessTokenAuthenticator = (
+  token: string | null,
+  /** Optional second argument preserves the existing positional token API. */
+  context?: WsAuthenticationContext,
+) => SocketUser | null | Promise<SocketUser | null>;
+
+export interface WebSocketTokenExtractionOptions {
+  /** Accept `?token=` during upgrade. Disabled by default because URLs leak. */
+  readonly allowQueryToken?: boolean;
+}
+
+/** Rejects an upgrade with an HTTP status (the handshake never completes). */
+export class WsUpgradeError extends Error {
+  public constructor(
+    message: string,
+    public readonly status = 403,
+  ) {
+    super(message);
+    this.name = "WsUpgradeError";
+  }
+}
+
+/** Composes upgrade middleware into a single runnable pipeline. */
+export function composeWsUpgradeMiddleware(
+  middlewares: readonly WsMiddleware[],
+  terminal: () => Promise<void>,
+): (ctx: WsUpgradeContext) => Promise<void> {
+  return (ctx) => {
+    let index = -1;
+    const run = (i: number): Promise<void> => {
+      if (i <= index) {
+        return Promise.reject(new Error("next() called multiple times"));
+      }
+      index = i;
+      const middleware = middlewares[i];
+      if (!middleware) {
+        return terminal();
+      }
+      return Promise.resolve(middleware(ctx, () => run(i + 1)));
+    };
+    return run(0);
+  };
+}
+
+/** Rejects upgrades whose `Origin` is not allow-listed (`"*"` allows all). */
+export function createOriginCheckMiddleware(allowed: readonly string[]): WsMiddleware {
+  const allowAll = allowed.includes("*");
+  return (ctx, next) => {
+    const origin = ctx.request.headers.get("origin");
+    if (!allowAll && origin !== null && !allowed.includes(origin)) {
+      throw new WsUpgradeError("Origin not allowed", 403);
+    }
+    return next();
+  };
+}
+
+/**
+ * Extracts a bearer token from `Authorization` or the `Sec-WebSocket-Protocol`
+ * `bearer.<token>` convention. Query-string tokens are disabled by default
+ * because URLs commonly leak into logs, proxies and browser history.
+ */
+export function extractWebSocketToken(
+  request: Request,
+  options: WebSocketTokenExtractionOptions = {},
+): string | null {
+  const authorization = request.headers.get("authorization");
+  if (authorization?.startsWith("Bearer ")) {
+    return authorization.slice("Bearer ".length).trim() || null;
+  }
+  const protocol = request.headers.get("sec-websocket-protocol");
+  if (protocol) {
+    for (const part of protocol.split(",")) {
+      const trimmed = part.trim();
+      if (trimmed.startsWith("bearer.")) {
+        return trimmed.slice("bearer.".length) || null;
+      }
+    }
+  }
+  return options.allowQueryToken === true ? new URL(request.url).searchParams.get("token") : null;
+}
+
+/** Authenticates the upgrade; sets `ctx.data.user`. Closes with 401 when required. */
+export function createWsAuthMiddleware(
+  authenticator: WsAccessTokenAuthenticator,
+  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,
+      },
+    );
+    if (user !== null && !isValidSocketUser(user)) {
+      throw new WsUpgradeError("Unauthorized", 401);
+    }
+    if (user === null) {
+      if (options?.required) {
+        throw new WsUpgradeError("Unauthorized", 401);
+      }
+      return next();
+    }
+    ctx.data.user = user;
+    return next();
+  };
+}
+
+/** Runtime guard for authenticator and custom upgrade-middleware principals. */
+export function isValidSocketUser(value: unknown): value is SocketUser {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const id = (value as { id?: unknown }).id;
+  return typeof id === "string"
+    && id.trim().length > 0
+    && id.length <= MAX_SOCKET_USER_ID_LENGTH
+    && !id.includes("\0");
+}

package/core/websocket/packet-codec.ts

@@ -0,0 +1,75 @@
+import type { ClientPacket, ServerPacket } from "./types";
+
+const decoder = new TextDecoder();
+
+export function encodeServerPacket(packet: Omit<ServerPacket, "v"> & { v?: 1 }): string {
+  return JSON.stringify({ v: 1 as const, ...packet });
+}
+
+export function encodeClientPacket(packet: Omit<ClientPacket, "v"> & { v?: 1 }): string {
+  return JSON.stringify({ v: 1 as const, ...packet });
+}
+
+export function decodeClientPacket(raw: string | Buffer): ClientPacket {
+  const text = typeof raw === "string" ? raw : decoder.decode(raw);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new PacketCodecError("Invalid JSON packet");
+  }
+
+  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;
+}
+
+export class PacketCodecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PacketCodecError";
+  }
+}
+
+export function createAckPacket(id: string, data?: unknown): string {
+  return encodeServerPacket({
+    type: "ack",
+    id,
+    data,
+  });
+}
+
+export function createConnectedPacket(sid: string, namespace: string, data?: unknown): string {
+  return encodeServerPacket({
+    type: "connected",
+    sid,
+    namespace,
+    data,
+  });
+}
+
+export function createReconnectedPacket(
+  sid: string,
+  namespace: string,
+  missed: ServerPacket[] = [],
+  data?: unknown,
+): string {
+  return encodeServerPacket({
+    type: "reconnected",
+    sid,
+    namespace,
+    missed,
+    data,
+  });
+}

package/core/websocket/reliable-delivery.ts

@@ -0,0 +1,56 @@
+import type { ServerPacket } from "./types";
+
+export interface ReliableBroadcastOptions {
+  /** UUID v4, reused unchanged when retrying an indeterminate publication. */
+  readonly messageId: string;
+  /** Acceptance deadline (Unix ms), reused on retry; at most 60s ahead. */
+  readonly expiresAt: number;
+}
+
+export interface ReliableBroadcastReceipt {
+  readonly messageId: string;
+  readonly recipients: number;
+  readonly duplicate: boolean;
+}
+
+export interface ReliableRoomPublication extends ReliableBroadcastOptions {
+  readonly namespace: string;
+  readonly room: string;
+  readonly excludeSid: string;
+  readonly packet: ServerPacket;
+}
+
+export interface ReliableSessionOwner {
+  readonly sid: string;
+  readonly connId: string;
+  readonly ownerInstanceId: string;
+  /** Read-only cursor: skip already issued, unacknowledged frames on this connection. */
+  readonly issuedIds?: readonly string[];
+}
+
+export interface ReliableDeliveryBatch {
+  readonly sid: string;
+  readonly packets: readonly ServerPacket[];
+}
+
+/** Optional adapter capability; queue updates do not change session revisions. */
+export interface ReliableRoomDelivery {
+  publish(request: ReliableRoomPublication): Promise<ReliableBroadcastReceipt>;
+  readPending(owners: readonly ReliableSessionOwner[]): Promise<readonly ReliableDeliveryBatch[]>;
+  acknowledge(owner: ReliableSessionOwner, deliveryIds: readonly string[]): Promise<number>;
+}
+
+export class WebSocketDeliveryError extends Error {
+  constructor(readonly code: string, message = `WebSocket delivery rejected: ${code}.`) {
+    super(message);
+    this.name = "WebSocketDeliveryError";
+  }
+}
+
+export interface WebSocketDiagnostic {
+  readonly type: "queue-rejected" | "adapter-error" | "lease-lost" | "reliable-published" | "reliable-rejected" | "reliable-acked" | "poll-error";
+  readonly timestamp: number;
+  readonly count: number;
+}
+
+export const deliveryUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

package/core/websocket/session-creation.ts

@@ -0,0 +1,16 @@
+// In-memory storage can compact deletion history without confusing a fresh
+// session with an old snapshot, including many creations in the same millisecond.
+// This token is internal metadata; distributed adapters use their own CAS/TTL.
+const incarnation = `${crypto.randomUUID()}:`;
+let sequence = 0;
+
+export function issueSessionCreationToken(): string {
+  if (!Number.isSafeInteger(++sequence)) throw new Error("WebSocket creation sequence exhausted.");
+  return `${incarnation}${sequence}`;
+}
+
+export function localSessionCreationOrder(token: string | undefined): number | undefined {
+  if (typeof token !== "string" || !token.startsWith(incarnation)) return undefined;
+  const order = Number(token.slice(incarnation.length));
+  return Number.isSafeInteger(order) && order > 0 && order <= sequence ? order : undefined;
+}