presence.ts · Source

presence.tsapps/realtime/src/presence.tsraw ← src6,946 B← Back to the app
1/**
2 * Presence tracking (TASK-0093, doc §5) — the server's room-scoped peer
3 * state + broadcast shaping.
4 *
5 * One {@link PresenceTracker} per server process. Peers are keyed by
6 * `(roomKey, userId)`: a user with two tabs in the same room shows ONE
7 * avatar (the second tab's state wins — both tabs are the same person);
8 * tabs in DIFFERENT rooms are separate entries (different pageIds).
9 *
10 * Identity is server-stamped: the entry's `user` is built from the
11 * socket's authenticated handshake id + the name resolved by the
12 * handshake's meta seam (the display name — never an email) + the shared
13 * `presenceColor(userId)` hash (the server and every client agree on the
14 * color without negotiating; the client-supplied presence frame carries
15 * ONLY `cursor`/`viewing` — impersonation is impossible).
16 *
17 * The > 50 peer cap (doc §5.1 / `REALTIME_LIMITS.awarenessPeerCap`): a
18 * broadcast for a room over the cap is shaped to AVATARS-ONLY — `cursor`
19 * and `viewing` are stripped, `user` + `lastSeen` stay. The strip is
20 * applied per-broadcast by {@link PresenceTracker.broadcastFor} (the
21 * stored state is never mutated — a room that drops back to ≤ 50 peers
22 * carries full cursors again on the next update).
23 *
24 * Prune: a peer silent for longer than `pruneAfterMs` (90 s — the doc
25 * §5.1 awareness timeout, wired from `REALTIME_LIMITS.awarenessPruneMs`)
26 * is dropped; the server's heartbeat loop calls {@link PresenceTracker.prune}
27 * and broadcasts the pruned set (the clients drop peers not re-asserted
28 * by a later roster/`presence` frame — best-effort, doc §5.2).
29 */
30 
31import { presenceColor } from "@factory/shared/presence";
32import {
33  REALTIME_LIMITS,
34  type PresenceBroadcast,
35  type PresenceCursor,
36} from "@factory/shared/realtime/frames";
37 
38/** One peer's server-side presence state (roomKey + userId → entry). */
39export interface PresenceEntry {
40  /** Server-stamped identity (never client-supplied). */
41  readonly userId: string;
42  readonly name: string;
43  readonly color: string;
44  /** The cursor (null = cleared / hidden — tab blurred, or never set). */
45  cursor: PresenceCursor | null;
46  /** False when the peer's tab is hidden (the cursor hides, the avatar stays). */
47  viewing: boolean;
48  /** The epoch ms of the last `presence` frame from this peer (prune basis). */
49  lastSeen: number;
50}
51 
52/** What a client sent in a `presence` frame (state only — no identity). */
53export interface PresenceUpdate {
54  cursor?: PresenceCursor | null;
55  viewing?: boolean;
56}
57 
58export interface PresenceTrackerOpts {
59  /** Injectable clock (deterministic prune tests; rule 25). */
60  readonly now?: () => number;
61  /** Silence before a peer is pruned (default 90 s, doc §5.1). */
62  readonly pruneAfterMs?: number;
63  /** The fan-out cap (default 50 — doc §5.1 avatars-only beyond it). */
64  readonly peerCap?: number;
65}
66 
67export class PresenceTracker {
68  private readonly now: () => number;
69  private readonly pruneAfterMs: number;
70  private readonly peerCap: number;
71  /** roomKey → userId → entry. */
72  private readonly rooms = new Map<string, Map<string, PresenceEntry>>();
73 
74  constructor(opts: PresenceTrackerOpts = {}) {
75    this.now = opts.now ?? (() => Date.now());
76    this.pruneAfterMs = opts.pruneAfterMs ?? REALTIME_LIMITS.awarenessPruneMs;
77    this.peerCap = opts.peerCap ?? REALTIME_LIMITS.awarenessPeerCap;
78  }
79 
80  /**
81   * Upsert a peer's state (a `presence` frame or a join). `user` is the
82   * server-stamped identity (id from the handshake, name from the meta
83   * seam, color from the shared hash). Returns the (new or updated)
84   * entry — the caller broadcasts `broadcastFor(entry)`.
85   */
86  upsert(
87    roomKey: string,
88    user: { id: string; name?: string },
89    update: PresenceUpdate,
90  ): PresenceEntry {
91    let room = this.rooms.get(roomKey);
92    if (room === undefined) {
93      room = new Map<string, PresenceEntry>();
94      this.rooms.set(roomKey, room);
95    }
96    const t = this.now();
97    const existing = room.get(user.id);
98    const entry: PresenceEntry = {
99      userId: user.id,
100      name: user.name ?? existing?.name ?? "Guest (shared)",
101      color: presenceColor(user.id),
102      cursor: update.cursor === undefined ? (existing?.cursor ?? null) : update.cursor,
103      viewing: update.viewing ?? existing?.viewing ?? true,
104      lastSeen: t,
105    };
106    room.set(user.id, entry);
107    return entry;
108  }
109 
110  /** Remove a peer (explicit `presence-leave` or a socket close). */
111  remove(roomKey: string, userId: string): void {
112    const room = this.rooms.get(roomKey);
113    if (room === undefined) return;
114    room.delete(userId);
115    if (room.size === 0) this.rooms.delete(roomKey);
116  }
117 
118  /** The room's live peer count (the cap's basis — users, not sockets). */
119  count(roomKey: string): number {
120    return this.rooms.get(roomKey)?.size ?? 0;
121  }
122 
123  /** The room's current entries (a copy — safe to iterate). */
124  peers(roomKey: string): readonly PresenceEntry[] {
125    const room = this.rooms.get(roomKey);
126    if (room === undefined) return [];
127    return [...room.values()];
128  }
129 
130  /**
131   * Shape one peer's state into the wire broadcast for a room. The cap
132   * rule (doc §5.1): a room with MORE than `peerCap` peers broadcasts
133   * avatars-only — `cursor` and `viewing` are stripped, `user` +
134   * `lastSeen` stay. At ≤ `peerCap` the full state (cursor included)
135   * is carried.
136   */
137  broadcastFor(roomKey: string, entry: PresenceEntry): PresenceBroadcast {
138    const avatarsOnly = this.count(roomKey) > this.peerCap;
139    return {
140      type: "presence",
141      pageId: roomKey,
142      user: { id: entry.userId, name: entry.name, color: entry.color },
143      cursor: avatarsOnly ? null : (entry.cursor ?? null),
144      viewing: avatarsOnly ? undefined : entry.viewing,
145      lastSeen: entry.lastSeen,
146    };
147  }
148 
149  /**
150   * Drop peers silent for longer than `pruneAfterMs`. Returns
151   * `roomKey → pruned entries` (the caller broadcasts each pruned peer's
152   * removal; a client that never re-hears a peer before its own prune
153   * window drops it locally — doc §5.2 best-effort).
154   */
155  prune(): Map<string, readonly PresenceEntry[]> {
156    const t = this.now();
157    const pruned = new Map<string, PresenceEntry[]>();
158    for (const [roomKey, room] of this.rooms) {
159      const dropped: PresenceEntry[] = [];
160      for (const [userId, entry] of room) {
161        if (t - entry.lastSeen > this.pruneAfterMs) {
162          room.delete(userId);
163          dropped.push(entry);
164        }
165      }
166      if (dropped.length > 0) pruned.set(roomKey, dropped);
167      if (room.size === 0) this.rooms.delete(roomKey);
168    }
169    return pruned;
170  }
171 
172  /** Drop every entry for a room (room GC / drain). */
173  removeRoom(roomKey: string): void {
174    this.rooms.delete(roomKey);
175  }
176 
177  /** Total live entries across rooms (metrics / tests). */
178  get size(): number {
179    let n = 0;
180    for (const room of this.rooms.values()) n += room.size;
181    return n;
182  }
183}
184