sonamu 0.11.16 → 0.12.0

package/src/stream/ws-presence-store.ts

@@ -1,6 +1,10 @@
 import { type WebSocketAudience } from "./ws-audience";
-import { type WebSocketRegistryStats, type WebSocketRoomId, type WebSocketUserId } from "./ws-core";
+import { type MaybePromise, type WebSocketRoomId, type WebSocketUserId } from "./ws-core";
+import { WebSocketPresenceIndex } from "./ws-presence-index";
 
+/**
+ * 세션 presence snapshot. live 객체가 아니므로 값을 바꿔도 registry나 store 상태에 영향을 주지 않는다.
+ */
 export type WebSocketSessionPresence = {
   sessionId: string;
   nodeId: string;
@@ -12,320 +16,96 @@ export type WebSocketSessionPresence = {
   userId?: WebSocketUserId;
 };
 
+export type WebSocketPresenceRegistration = {
+  sessionId: string;
+  nodeId: string;
+  namespace: string;
+  active: boolean;
+  connectedAt: Date;
+};
+
+export type WebSocketRoutingPlan = {
+  localSessionIds: string[];
+  remoteNodeIds: string[];
+};
+
+/**
+ * 클러스터 presence replica 계약. 각 노드의 registry가 자기 세션의 mutation을 세션별 호출 순서대로 전달한다.
+ * 모든 메서드는 값이나 promise를 반환할 수 있고, registry는 동기 throw도 rejection으로 바꿔 처리한다.
+ * userId는 타입까지 일치해야 매칭된다(1과 "1"은 다르다).
+ */
 export interface WebSocketPresenceStore {
-  register(input: {
-    sessionId: string;
-    nodeId: string;
-    namespace: string;
-    active?: boolean;
-  }): WebSocketSessionPresence;
-  activate(sessionId: string): void;
-  unregister(sessionId: string): WebSocketSessionPresence | undefined;
-  touch(sessionId: string): void;
-  setUserId(sessionId: string, userId: WebSocketUserId): void;
-  clearUserId(sessionId: string): void;
-  join(sessionId: string, roomId: WebSocketRoomId): void;
-  leave(sessionId: string, roomId: WebSocketRoomId): void;
-  getConnection(sessionId: string): WebSocketSessionPresence | undefined;
-  getConnectionCount(namespace?: string): number;
-  getRoomMembers(roomId: WebSocketRoomId, namespace?: string): WebSocketSessionPresence[];
-  getStats(): WebSocketRegistryStats;
-  queryAudience(audience: WebSocketAudience): WebSocketSessionPresence[];
+  // 설정하면 runtime nodeId와 같아야 한다. 다르면 runtime 생성이 실패한다
+  readonly nodeId?: string;
+  register(input: WebSocketPresenceRegistration): MaybePromise<void>;
+  activate(sessionId: string): MaybePromise<void>;
+  unregister(sessionId: string): MaybePromise<void>;
+  setUserId(sessionId: string, userId: WebSocketUserId): MaybePromise<void>;
+  clearUserId(sessionId: string): MaybePromise<void>;
+  join(sessionId: string, roomId: WebSocketRoomId): MaybePromise<void>;
+  leave(sessionId: string, roomId: WebSocketRoomId): MaybePromise<void>;
+  // nodeId 관점에서 audience를 로컬 세션 ID와 중복 없는 원격 노드 ID로 나눈다. 비활성 세션은 제외한다
+  resolveRoute(audience: WebSocketAudience, nodeId: string): MaybePromise<WebSocketRoutingPlan>;
+  // 클러스터 전체의 활성 방 인원수
+  getRoomMemberCount(roomId: WebSocketRoomId, namespace?: string): MaybePromise<number>;
+  shutdown?(): MaybePromise<void>;
 }
 
+/**
+ * 프로세스 메모리에 presence를 두는 store. 단일 노드의 기본값이며, 같은 프로세스의 여러 runtime이 공유하면 클러스터 replica로도 동작한다.
+ */
 export class InMemoryWebSocketPresenceStore implements WebSocketPresenceStore {
-  private readonly connections = new Map<string, WebSocketSessionPresence>();
-  private readonly rooms = new Map<string, Set<string>>();
-  private readonly users = new Map<string, Set<string>>();
+  private readonly index = new WebSocketPresenceIndex();
 
-  register(input: {
-    sessionId: string;
-    nodeId: string;
-    namespace: string;
-    active?: boolean;
-  }): WebSocketSessionPresence {
-    const meta: WebSocketSessionPresence = {
-      sessionId: input.sessionId,
-      nodeId: input.nodeId,
-      namespace: input.namespace,
-      active: input.active ?? true,
-      rooms: new Set(),
-      connectedAt: new Date(),
-      lastSeenAt: new Date(),
-    };
-    this.connections.set(input.sessionId, meta);
-    return meta;
+  register(input: WebSocketPresenceRegistration): void {
+    this.index.register(input);
   }
 
   activate(sessionId: string): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return;
-    }
-
-    meta.active = true;
+    this.index.activate(sessionId);
   }
 
-  unregister(sessionId: string): WebSocketSessionPresence | undefined {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return undefined;
-    }
-
-    if (meta.userId !== undefined) {
-      this.removeUserBinding(meta.namespace, meta.userId, sessionId);
-    }
-
-    for (const roomId of meta.rooms) {
-      this.removeRoomBinding(meta.namespace, roomId, sessionId);
-    }
-
-    this.connections.delete(sessionId);
-    return meta;
-  }
-
-  touch(sessionId: string): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return;
-    }
-
-    meta.lastSeenAt = new Date();
+  unregister(sessionId: string): void {
+    this.index.unregister(sessionId);
   }
 
   setUserId(sessionId: string, userId: WebSocketUserId): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return;
-    }
-
-    if (meta.userId !== undefined) {
-      this.removeUserBinding(meta.namespace, meta.userId, sessionId);
-    }
-
-    meta.userId = userId;
-    const key = getBindingKey(meta.namespace, String(userId));
-    const bound = this.users.get(key) ?? new Set<string>();
-    bound.add(sessionId);
-    this.users.set(key, bound);
+    this.index.setUserId(sessionId, userId);
   }
 
   clearUserId(sessionId: string): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta || meta.userId === undefined) {
-      return;
-    }
-
-    this.removeUserBinding(meta.namespace, meta.userId, sessionId);
-    delete meta.userId;
+    this.index.clearUserId(sessionId);
   }
 
   join(sessionId: string, roomId: WebSocketRoomId): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return;
-    }
-
-    meta.rooms.add(roomId);
-    const key = getBindingKey(meta.namespace, roomId);
-    const members = this.rooms.get(key) ?? new Set<string>();
-    members.add(sessionId);
-    this.rooms.set(key, members);
+    this.index.join(sessionId, roomId);
   }
 
   leave(sessionId: string, roomId: WebSocketRoomId): void {
-    const meta = this.connections.get(sessionId);
-    if (!meta) {
-      return;
-    }
-
-    meta.rooms.delete(roomId);
-    this.removeRoomBinding(meta.namespace, roomId, sessionId);
-  }
-
-  getConnection(sessionId: string): WebSocketSessionPresence | undefined {
-    return this.connections.get(sessionId);
-  }
-
-  getConnectionCount(namespace?: string): number {
-    let count = 0;
-
-    for (const meta of this.connections.values()) {
-      if (!meta.active || (namespace && meta.namespace !== namespace)) {
-        continue;
-      }
-
-      count += 1;
-    }
-
-    return count;
-  }
-
-  getRoomMembers(roomId: WebSocketRoomId, namespace?: string): WebSocketSessionPresence[] {
-    return this.getBoundConnections(this.rooms, roomId, namespace);
-  }
-
-  getStats(): WebSocketRegistryStats {
-    const byNamespace: Record<string, number> = {};
-
-    for (const meta of this.connections.values()) {
-      if (!meta.active) {
-        continue;
-      }
-      byNamespace[meta.namespace] = (byNamespace[meta.namespace] ?? 0) + 1;
-    }
-
-    return {
-      totalConnections: Object.values(byNamespace).reduce((sum, count) => sum + count, 0),
-      totalRooms: this.rooms.size,
-      byNamespace,
-    };
-  }
-
-  queryAudience(audience: WebSocketAudience): WebSocketSessionPresence[] {
-    switch (audience.type) {
-      case "all":
-        return this.getActiveConnections(audience.namespace);
-      case "room":
-        return this.getBoundConnections(this.rooms, audience.roomId, audience.namespace);
-      case "user":
-        return this.getBoundConnections(this.users, String(audience.userId), audience.namespace);
-      case "connections": {
-        const metas: WebSocketSessionPresence[] = [];
-
-        for (const connectionId of audience.connectionIds) {
-          const meta = this.connections.get(connectionId);
-          if (!meta?.active) {
-            continue;
-          }
-          if (audience.namespace && meta.namespace !== audience.namespace) {
-            continue;
-          }
-          metas.push(meta);
-        }
-
-        return metas;
-      }
-      case "union": {
-        const seen = new Set<string>();
-        const metas: WebSocketSessionPresence[] = [];
-
-        for (const item of audience.audiences) {
-          for (const meta of this.queryAudience(item)) {
-            if (seen.has(meta.sessionId)) {
-              continue;
-            }
-
-            seen.add(meta.sessionId);
-            metas.push(meta);
-          }
-        }
-
-        return metas;
-      }
-    }
-  }
-
-  private getActiveConnections(namespace?: string): WebSocketSessionPresence[] {
-    const metas: WebSocketSessionPresence[] = [];
-
-    for (const meta of this.connections.values()) {
-      if (!meta.active || (namespace && meta.namespace !== namespace)) {
-        continue;
-      }
-
-      metas.push(meta);
-    }
-
-    return metas;
+    this.index.leave(sessionId, roomId);
   }
 
-  private getBoundConnections(
-    bindings: Map<string, Set<string>>,
-    id: string,
-    namespace?: string,
-  ): WebSocketSessionPresence[] {
-    const metas: WebSocketSessionPresence[] = [];
-    const seen = new Set<string>();
+  resolveRoute(audience: WebSocketAudience, nodeId: string): WebSocketRoutingPlan {
+    const localSessionIds: string[] = [];
+    const remoteNodeIds = new Set<string>();
 
-    for (const members of this.getScopedBindings(bindings, id, namespace)) {
-      for (const connectionId of members) {
-        if (seen.has(connectionId)) {
-          continue;
-        }
-        seen.add(connectionId);
-
-        const meta = this.connections.get(connectionId);
-        if (meta?.active) {
-          metas.push(meta);
-        }
+    for (const session of this.index.queryAudience(audience)) {
+      if (session.nodeId === nodeId) {
+        localSessionIds.push(session.sessionId);
+      } else {
+        remoteNodeIds.add(session.nodeId);
       }
     }
 
-    return metas;
+    return { localSessionIds, remoteNodeIds: [...remoteNodeIds] };
   }
 
-  private getScopedBindings(
-    bindings: Map<string, Set<string>>,
-    id: string,
-    namespace?: string,
-  ): Set<string>[] {
-    if (namespace) {
-      const exact = bindings.get(getBindingKey(namespace, id));
-      return exact ? [exact] : [];
-    }
-
-    const matches: Set<string>[] = [];
-    for (const [key, members] of bindings) {
-      const parsed = parseBindingKey(key);
-      if (parsed.id === id) {
-        matches.push(members);
-      }
-    }
-
-    return matches;
-  }
-
-  private removeRoomBinding(namespace: string, roomId: WebSocketRoomId, sessionId: string): void {
-    const key = getBindingKey(namespace, roomId);
-    const members = this.rooms.get(key);
-    if (!members) {
-      return;
-    }
-
-    members.delete(sessionId);
-    if (members.size === 0) {
-      this.rooms.delete(key);
-    }
+  getRoomMemberCount(roomId: WebSocketRoomId, namespace?: string): number {
+    return this.index.getRoomMemberCount(roomId, namespace);
   }
 
-  private removeUserBinding(namespace: string, userId: WebSocketUserId, sessionId: string): void {
-    const key = getBindingKey(namespace, String(userId));
-    const members = this.users.get(key);
-    if (!members) {
-      return;
-    }
-
-    members.delete(sessionId);
-    if (members.size === 0) {
-      this.users.delete(key);
-    }
+  // 복사본을 반환하므로 호출자가 값을 바꿔도 store 상태는 그대로다
+  getConnection(sessionId: string): WebSocketSessionPresence | undefined {
+    return this.index.getConnection(sessionId);
   }
 }
-
-function getBindingKey(namespace: string, id: string): string {
-  return `${namespace}::${id}`;
-}
-
-interface PresenceBinding {
-  namespace: string;
-  id: string;
-}
-
-function parseBindingKey(key: string): PresenceBinding {
-  const [namespace, ...rest] = key.split("::");
-  return {
-    namespace,
-    id: rest.join("::"),
-  };
-}