|
| 1 | +// Team collaboration client integration. Ties the daemon collab capabilities |
| 2 | +// together for a shared-project session: heartbeat presence, poll the published |
| 3 | +// head version (so a member knows when to pull), and report author-side changes |
| 4 | +// / request a publish. It is the glue the read-only collab view consumes. |
| 5 | +// |
| 6 | +// Polling-based by design (live cursors were cut; content is polled — the spec). |
| 7 | + |
| 8 | +import type { CollabPresenceMember, ProjectSyncState } from '@open-design/contracts'; |
| 9 | + |
| 10 | +// Presence identity is the shared contract DTO; re-export so collab consumers |
| 11 | +// keep importing it from the client module. |
| 12 | +export type { CollabPresenceMember }; |
| 13 | + |
| 14 | +export interface CollabSnapshot { |
| 15 | + present: CollabPresenceMember[]; |
| 16 | + publishedVersion: number | null; |
| 17 | + /** project sync state; null until the first status poll lands. */ |
| 18 | + syncState: ProjectSyncState | null; |
| 19 | + /** The member who shared this project (its single writer); null if unshared. */ |
| 20 | + ownerMemberId: string | null; |
| 21 | +} |
| 22 | + |
| 23 | +export interface CollabClientOptions { |
| 24 | + projectId: string; |
| 25 | + member: CollabPresenceMember; |
| 26 | + /** Injectable for tests; defaults to the global fetch. */ |
| 27 | + fetch?: typeof fetch; |
| 28 | + /** Daemon API base; default '' (same origin). */ |
| 29 | + baseUrl?: string; |
| 30 | + heartbeatMs?: number; |
| 31 | + statusPollMs?: number; |
| 32 | + onUpdate?: (snapshot: CollabSnapshot) => void; |
| 33 | + onError?: (error: unknown) => void; |
| 34 | +} |
| 35 | + |
| 36 | +const DEFAULT_HEARTBEAT_MS = 10_000; |
| 37 | +const DEFAULT_STATUS_POLL_MS = 5_000; |
| 38 | + |
| 39 | +export class CollabClient { |
| 40 | + private readonly projectId: string; |
| 41 | + private readonly member: CollabPresenceMember; |
| 42 | + private readonly fetchImpl: typeof fetch; |
| 43 | + private readonly baseUrl: string; |
| 44 | + private readonly heartbeatMs: number; |
| 45 | + private readonly statusPollMs: number; |
| 46 | + private readonly onUpdate?: CollabClientOptions['onUpdate']; |
| 47 | + private readonly onError?: CollabClientOptions['onError']; |
| 48 | + private readonly timers: ReturnType<typeof setInterval>[] = []; |
| 49 | + private snapshot: CollabSnapshot = { present: [], publishedVersion: null, syncState: null, ownerMemberId: null }; |
| 50 | + private running = false; |
| 51 | + |
| 52 | + constructor(options: CollabClientOptions) { |
| 53 | + this.projectId = options.projectId; |
| 54 | + this.member = options.member; |
| 55 | + this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis); |
| 56 | + this.baseUrl = options.baseUrl ?? ''; |
| 57 | + this.heartbeatMs = Math.max(1_000, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS); |
| 58 | + this.statusPollMs = Math.max(1_000, options.statusPollMs ?? DEFAULT_STATUS_POLL_MS); |
| 59 | + this.onUpdate = options.onUpdate; |
| 60 | + this.onError = options.onError; |
| 61 | + } |
| 62 | + |
| 63 | + getSnapshot(): CollabSnapshot { |
| 64 | + return this.snapshot; |
| 65 | + } |
| 66 | + |
| 67 | + start(): void { |
| 68 | + if (this.running) return; |
| 69 | + this.running = true; |
| 70 | + void this.heartbeat(); |
| 71 | + void this.pollStatus(); |
| 72 | + this.timers.push(setInterval(() => void this.heartbeat(), this.heartbeatMs)); |
| 73 | + this.timers.push(setInterval(() => void this.pollStatus(), this.statusPollMs)); |
| 74 | + } |
| 75 | + |
| 76 | + stop(): void { |
| 77 | + if (!this.running) return; |
| 78 | + this.running = false; |
| 79 | + for (const timer of this.timers) clearInterval(timer); |
| 80 | + this.timers.length = 0; |
| 81 | + void this.leave(); |
| 82 | + } |
| 83 | + |
| 84 | + /** The author edited a file — schedule a coalesced publish. */ |
| 85 | + async reportChange(): Promise<void> { |
| 86 | + await this.post('/collab/changed'); |
| 87 | + } |
| 88 | + |
| 89 | + /** Run boundary — flush the pending publish now. */ |
| 90 | + async requestPublish(): Promise<void> { |
| 91 | + await this.post('/collab/publish'); |
| 92 | + } |
| 93 | + |
| 94 | + async heartbeat(): Promise<void> { |
| 95 | + try { |
| 96 | + const body = await this.post('/presence/heartbeat', this.member); |
| 97 | + if (Array.isArray(body?.present)) this.update({ present: body.present as CollabPresenceMember[] }); |
| 98 | + } catch (error) { |
| 99 | + this.onError?.(error); |
| 100 | + } |
| 101 | + } |
| 102 | + |
| 103 | + async pollStatus(): Promise<void> { |
| 104 | + try { |
| 105 | + const body = await this.get('/collab/status'); |
| 106 | + const version = typeof body?.publishedVersion === 'number' ? body.publishedVersion : null; |
| 107 | + const syncState = (body?.syncState as ProjectSyncState | undefined) ?? null; |
| 108 | + const ownerMemberId = typeof body?.ownerMemberId === 'string' ? body.ownerMemberId : null; |
| 109 | + this.update({ publishedVersion: version, syncState, ownerMemberId }); |
| 110 | + } catch (error) { |
| 111 | + this.onError?.(error); |
| 112 | + } |
| 113 | + } |
| 114 | + |
| 115 | + private async leave(): Promise<void> { |
| 116 | + try { |
| 117 | + await this.post('/presence/leave', { memberId: this.member.memberId }); |
| 118 | + } catch (error) { |
| 119 | + this.onError?.(error); |
| 120 | + } |
| 121 | + } |
| 122 | + |
| 123 | + /** |
| 124 | + * Best-effort leave that survives page unload. A normal fetch is aborted when |
| 125 | + * the tab closes, so a hard close would otherwise leave the member lingering |
| 126 | + * until the daemon's presence TTL sweeps it (~30s). sendBeacon (with a |
| 127 | + * keepalive-fetch fallback) hands the request to the browser to deliver after |
| 128 | + * the page is gone, so the present set drops promptly. |
| 129 | + */ |
| 130 | + leaveBeacon(): void { |
| 131 | + const url = this.url('/presence/leave'); |
| 132 | + const body = JSON.stringify({ memberId: this.member.memberId }); |
| 133 | + try { |
| 134 | + if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') { |
| 135 | + const blob = new Blob([body], { type: 'application/json' }); |
| 136 | + if (navigator.sendBeacon(url, blob)) return; |
| 137 | + } |
| 138 | + } catch { |
| 139 | + // fall through to the keepalive fetch |
| 140 | + } |
| 141 | + void this.fetchImpl(url, { |
| 142 | + method: 'POST', |
| 143 | + headers: { 'content-type': 'application/json' }, |
| 144 | + body, |
| 145 | + keepalive: true, |
| 146 | + }).catch(() => {}); |
| 147 | + } |
| 148 | + |
| 149 | + private update(patch: Partial<CollabSnapshot>): void { |
| 150 | + this.snapshot = { ...this.snapshot, ...patch }; |
| 151 | + this.onUpdate?.(this.snapshot); |
| 152 | + } |
| 153 | + |
| 154 | + private async get(path: string): Promise<Record<string, unknown> | null> { |
| 155 | + const response = await this.fetchImpl(this.url(path)); |
| 156 | + if (!response.ok) throw new Error(`collab GET ${path} failed: ${response.status}`); |
| 157 | + return (await response.json()) as Record<string, unknown>; |
| 158 | + } |
| 159 | + |
| 160 | + private async post(path: string, body?: unknown): Promise<Record<string, unknown> | null> { |
| 161 | + const init: RequestInit = { method: 'POST' }; |
| 162 | + if (body !== undefined) { |
| 163 | + init.headers = { 'content-type': 'application/json' }; |
| 164 | + init.body = JSON.stringify(body); |
| 165 | + } |
| 166 | + const response = await this.fetchImpl(this.url(path), init); |
| 167 | + if (!response.ok) throw new Error(`collab POST ${path} failed: ${response.status}`); |
| 168 | + return (await response.json()) as Record<string, unknown>; |
| 169 | + } |
| 170 | + |
| 171 | + private url(path: string): string { |
| 172 | + return `${this.baseUrl}/api/projects/${encodeURIComponent(this.projectId)}${path}`; |
| 173 | + } |
| 174 | +} |
0 commit comments