@crowi/api 2.0.0-alpha.0

package/dist/service/presence.d.ts

@@ -0,0 +1,219 @@
+import type { PresenceViewer } from '@crowi/api-contract';
+import type Crowi from '../crowi';
+/**
+ * RFC-0005 — page-presence service.
+ *
+ * Tracks which users are currently *viewing* a page (the live-presence
+ * row above the page title). Editor-side presence (peer cursors,
+ * typing badges) is RFC-0003's concern and lives in `@crowi/collab`.
+ *
+ * Replaces the RFC-0003 Phase 5 `markEditing` no-op stub that
+ * previously occupied this file — the swap point the stub's comment
+ * promised. The collab package still calls into presence through a
+ * dependency-injected adapter (`createPresenceCollabDeps` below) so
+ * `@crowi/collab` never imports `@crowi/api`.
+ *
+ * Wire-level design:
+ *
+ *   - Viewer hash: `crowi:presence:viewers:<pageId>` — a Redis hash,
+ *     one field per viewing `userId`, value a JSON blob with the
+ *     viewer's denormalised identity + `joinedAt` + `lastHeartbeatAt`.
+ *   - TTL: the hash carries a *key-level* `EXPIRE` (re-applied on every
+ *     write) so an idle page's hash evaporates. Per-*field* TTL would
+ *     need `HEXPIRE` (Redis 7.4 / node-redis v5) which this codebase's
+ *     node-redis v4.7 does not expose — instead each field stores
+ *     `lastHeartbeatAt` and `listViewers` filters out entries whose
+ *     last heartbeat is older than `VIEWER_TTL_MS`, sweeping the stale
+ *     fields from the hash as a side effect.
+ *   - Pub/sub: `crowi:presence:updates` carries `<pageId>` strings.
+ *     When a viewer joins / leaves on api instance A, A publishes the
+ *     pageId; every instance (including A) re-broadcasts the fresh
+ *     viewer list to its locally-connected clients. Same
+ *     Redis-as-shared-state pattern as RFC-0003.
+ *   - `isEditing`: NOT stored in the viewer hash. It is derived at
+ *     `listViewers` time from a dedicated, short-lived *editing hash*
+ *     `crowi:presence:editing:<pageId>` — one field per editor
+ *     connection (`<userId>:<socketId>`), value `lastSeenAt`
+ *     (epoch-ms). The collab process refreshes its own fields every
+ *     `EDITING_REFRESH_MS`; a field older than `EDITING_TTL_MS` is
+ *     considered stale and swept. This replaces the earlier design
+ *     that joined the RFC-0003 editor-cap Set: that Set is a *soft
+ *     concurrency-limit counter* with a 24h key TTL whose members are
+ *     only SREM'd on a clean `onDisconnect`, so an api crash / restart
+ *     could leave stale members for up to 24h and paint the `✏️` badge
+ *     on plain viewers. The editing hash self-heals: when the editing
+ *     process dies it stops refreshing, and every field ages out
+ *     within `EDITING_TTL_MS`.
+ *
+ * Fail-soft posture: when `crowi.redis` is null (REDIS_URL unset,
+ * single-instance dev) presence degrades to an in-process-only store
+ * with no cross-instance fan-out. The `/presence` WebSocket still works
+ * for viewers connected to the same process.
+ */
+/** Redis key prefix for the per-page viewer hash. */
+declare const VIEWER_HASH_PREFIX = "crowi:presence:viewers:";
+/** Redis pub/sub channel for cross-instance viewer-list invalidation. */
+declare const PRESENCE_UPDATES_CHANNEL = "crowi:presence:updates";
+/**
+ * Redis key prefix for the per-page *editing hash* — the presence-owned
+ * short-lived editing signal that drives the `✏️` badge. One field per
+ * editor connection (`<userId>:<socketId>`), value `lastSeenAt`.
+ */
+declare const EDITING_HASH_PREFIX = "crowi:presence:editing:";
+/**
+ * A viewer entry is considered live for 30s after its last heartbeat.
+ * The browser heartbeats every 15s, so a viewer normally refreshes
+ * twice within the window; a single dropped heartbeat does not evict.
+ */
+declare const VIEWER_TTL_MS = 30000;
+/**
+ * An editing-hash field is considered live for 30s after its last
+ * refresh. The collab process refreshes every `EDITING_REFRESH_MS`
+ * (10s) so a healthy editor field stays comfortably fresh; once the
+ * editing process dies and stops refreshing, the field ages out within
+ * this window and the badge disappears.
+ */
+declare const EDITING_TTL_MS = 30000;
+/**
+ * Interval at which the collab→presence adapter refreshes the
+ * `lastSeenAt` of every live editor connection it owns. Well under
+ * `EDITING_TTL_MS` so a single missed tick does not age a field out.
+ */
+declare const EDITING_REFRESH_MS = 10000;
+/** Identity fields a caller supplies when a viewer joins. */
+export interface ViewerIdentity {
+    userId: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string | null;
+}
+/**
+ * Minimum node-redis v4 surface the presence service leans on. Keeps
+ * the test-mock surface narrow and documents exactly which commands a
+ * fake must implement.
+ */
+export interface PresenceRedisClient {
+    hSet(key: string, field: string, value: string): Promise<number>;
+    hGet(key: string, field: string): Promise<string | null | undefined>;
+    hGetAll(key: string): Promise<Record<string, string>>;
+    hDel(key: string, field: string | string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean | number>;
+    publish(channel: string, message: string): Promise<number>;
+    duplicate(): PresenceRedisClient;
+    connect(): Promise<unknown>;
+    disconnect(): Promise<unknown>;
+    subscribe(channel: string, listener: (message: string) => void): Promise<void>;
+    isOpen?: boolean;
+}
+/**
+ * Public surface of the presence service. The `/presence` WebSocket
+ * handler holds one process-shared instance (see `getPresenceService`);
+ * `@crowi/collab` is wired to `markEditing` / `unmarkEditing` via
+ * dependency injection so the collab package never imports `@crowi/api`.
+ */
+export interface PresenceService {
+    /**
+     * Register (or refresh) a viewer for a page. Idempotent — re-calling
+     * for the same `userId` updates `lastHeartbeatAt` and dedupes
+     * multiple tabs to a single hash field. Publishes a viewer-list
+     * change so every instance re-broadcasts.
+     */
+    join(pageId: string, viewer: ViewerIdentity): Promise<void>;
+    /**
+     * Refresh a viewer's `lastHeartbeatAt` (and the hash key TTL). Called
+     * on every client heartbeat. Returns `false` when the viewer was not
+     * present (e.g. swept while the socket was briefly idle) so the
+     * handler can re-`join`.
+     */
+    heartbeat(pageId: string, userId: string): Promise<boolean>;
+    /**
+     * Remove a viewer from a page. Idempotent. Publishes a viewer-list
+     * change. The handler calls this on WebSocket close.
+     */
+    leave(pageId: string, userId: string): Promise<void>;
+    /**
+     * Current live viewer list for a page, with `isEditing` derived from
+     * the short-lived editing hash. Stale entries (heartbeat older than
+     * `VIEWER_TTL_MS`) are filtered out and swept from the hash.
+     */
+    listViewers(pageId: string): Promise<PresenceViewer[]>;
+    /**
+     * Collab `onAuthenticate` integration point — a user opened the
+     * editor for this page on connection `socketId`. Records an editing
+     * signal in the editing hash and publishes a viewer-list change so
+     * the editor immediately picks up an `✏️` badge.
+     */
+    markEditing(pageId: string, userId: string, socketId: string): Promise<void>;
+    /**
+     * Keep-alive for a live editor connection — refreshes the editing
+     * hash field's `lastSeenAt` so it does not age past `EDITING_TTL_MS`.
+     * Unlike `markEditing` this does NOT publish a viewer-list change
+     * (the editing set did not change), so periodic refreshes do not
+     * trigger redundant broadcasts.
+     */
+    refreshEditing(pageId: string, userId: string, socketId: string): Promise<void>;
+    /**
+     * Collab `onDisconnect` integration point — a user closed the editor
+     * on connection `socketId`. Removes the editing-hash field and
+     * publishes a viewer-list change so the `✏️` badge clears on the next
+     * broadcast.
+     */
+    unmarkEditing(pageId: string, userId: string, socketId: string): Promise<void>;
+    /**
+     * Subscribe to viewer-list change notifications. The listener is
+     * invoked with a `pageId` whenever that page's viewer list may have
+     * changed (local or cross-instance). Returns an unsubscribe fn.
+     */
+    onViewersChanged(listener: (pageId: string) => void): () => void;
+    /** Tear down the dedicated pub/sub subscriber client. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Build a presence service.
+ *
+ *   - `redis` present  → cross-instance mode: viewer state in Redis,
+ *     change notifications fan out via pub/sub.
+ *   - `redis` null     → single-instance mode: viewer state in a
+ *     process-local Map, change notifications are emitted directly.
+ *
+ * The two modes share the same `PresenceService` surface so the
+ * `/presence` handler never branches on Redis availability.
+ */
+export declare function createPresenceService(redis: PresenceRedisClient | null): Promise<PresenceService>;
+export declare function getPresenceService(crowi: Crowi): Promise<PresenceService>;
+/**
+ * Collab → presence wiring. `@crowi/collab` is crowi-agnostic, so the
+ * api hands it this adapter via `createCollabServer`'s `presence`
+ * option. Each call resolves the process-shared presence service
+ * lazily and forwards; errors are swallowed because presence is
+ * advisory and must never block a collab connection.
+ *
+ * The adapter also owns a periodic *refresher*: it tracks every live
+ * editor connection of *this* process in an in-process Map and, on a
+ * `setInterval`, calls `service.refreshEditing` for each so the Redis
+ * editing hash field never ages past `EDITING_TTL_MS` while the editor
+ * is connected. This is the self-heal mechanism — when the process
+ * dies the Map and interval die with it, nothing refreshes the editing
+ * hash, and every field ages out within `EDITING_TTL_MS` so the `✏️`
+ * badge disappears on plain viewers. A clean disconnect removes the
+ * field immediately via `unmarkEditing`. In a multi-instance
+ * deployment each instance refreshes only its own connections, so the
+ * scheme stays correct under load balancing.
+ */
+export interface PresenceCollabDeps {
+    markEditing(pageId: string, userId: string, socketId: string): Promise<void>;
+    unmarkEditing(pageId: string, userId: string, socketId: string): Promise<void>;
+    /**
+     * Stop the periodic editing-hash refresher. Called from the collab
+     * `shutdown()` so a graceful api teardown does not leak a timer.
+     */
+    shutdown(): void;
+}
+export declare function createPresenceCollabDeps(crowi: Crowi): PresenceCollabDeps;
+/**
+ * Test helper — inject a pre-built service or reset to lazy. Pass a
+ * fake to exercise the `/presence` handler / collab wiring without
+ * Redis; pass `null` to clear the cache.
+ */
+export declare const _setPresenceServiceForTesting: (service: PresenceService | null) => void;
+export { PRESENCE_UPDATES_CHANNEL, VIEWER_HASH_PREFIX, VIEWER_TTL_MS, EDITING_HASH_PREFIX, EDITING_TTL_MS, EDITING_REFRESH_MS };