Open History to see the last commit
1import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
2import { BrowserCollectionCoordinator } from '../src/browser-coordinator'
3import type { BrowserCollectionCoordinatorOptions } from '../src/browser-coordinator'
4import type { PersistenceAdapter } from '@tanstack/db-sqlite-persistence-core'
5
6// ---------------------------------------------------------------------------
7// BroadcastChannel mock
8// ---------------------------------------------------------------------------
9
10type MessageHandler = (event: { data: unknown }) => void
11const channels: Map<
12 string,
13 Set<{ onmessage: MessageHandler | null }>
14> = new Map()
15
16class MockBroadcastChannel {
17 readonly name: string
18 onmessage: MessageHandler | null = null
19
20 constructor(name: string) {
21 this.name = name
22 if (!channels.has(name)) {
23 channels.set(name, new Set())
24 }
25 channels.get(name)!.add(this)
26 }
27
28 postMessage(data: unknown): void {
29 const peers = channels.get(this.name)
30 if (!peers) return
31 // Deliver to all other instances on same channel (simulating cross-tab)
32 for (const peer of peers) {
33 if (peer !== this && peer.onmessage) {
34 // Use microtask to simulate async delivery
35 const handler = peer.onmessage
36 queueMicrotask(() => handler({ data: structuredClone(data) }))
37 }
38 }
39 }
40
41 close(): void {
42 channels.get(this.name)?.delete(this)
43 }
44}
45
46// ---------------------------------------------------------------------------
47// Web Locks mock
48// ---------------------------------------------------------------------------
49
50type LockGrantedCallback = (lock: { name: string }) => Promise<unknown>
51
52const heldLocks = new Map<string, { release: () => void }>()
53const lockQueues = new Map<
54 string,
55 Array<{
56 callback: LockGrantedCallback
57 signal?: AbortSignal
58 resolve: (v: unknown) => void
59 reject: (e: Error) => void
60 }>
61>()
62
63function tryGrantNextLock(name: string): void {
64 if (heldLocks.has(name)) return
65 const queue = lockQueues.get(name)
66 if (!queue || queue.length === 0) return
67
68 const next = queue.shift()!
69 if (next.signal?.aborted) {
70 // Skip aborted entries and try next
71 tryGrantNextLock(name)
72 return
73 }
74
75 let releaseCallback!: () => void
76 void new Promise<void>((resolve) => {
77 releaseCallback = resolve
78 })
79
80 heldLocks.set(name, { release: releaseCallback })
81
82 const result = next.callback({ name })
83 // When the callback resolves/rejects, release the lock
84 Promise.resolve(result).then(
85 (value) => {
86 heldLocks.delete(name)
87 releaseCallback()
88 next.resolve(value)
89 tryGrantNextLock(name)
90 },
91 (error) => {
92 heldLocks.delete(name)
93 releaseCallback()
94 next.reject(error)
95 tryGrantNextLock(name)
96 },
97 )
98}
99
100const mockNavigatorLocks = {
101 request: (
102 name: string,
103 optionsOrCallback: { signal?: AbortSignal } | LockGrantedCallback,
104 maybeCallback?: LockGrantedCallback,
105 ): Promise<unknown> => {
106 const callback =
107 typeof optionsOrCallback === `function`
108 ? optionsOrCallback
109 : maybeCallback!
110 const signal =
111 typeof optionsOrCallback === `object`
112 ? optionsOrCallback.signal
113 : undefined
114
115 return new Promise((resolve, reject) => {
116 if (signal?.aborted) {
117 reject(new DOMException(`Lock request aborted`, `AbortError`))
118 return
119 }
120
121 const entry = { callback, signal, resolve, reject }
122 if (!lockQueues.has(name)) {
123 lockQueues.set(name, [])
124 }
125 lockQueues.get(name)!.push(entry)
126
127 if (signal) {
128 signal.addEventListener(`abort`, () => {
129 const queue = lockQueues.get(name)
130 if (queue) {
131 const idx = queue.indexOf(entry)
132 if (idx >= 0) {
133 queue.splice(idx, 1)
134 reject(new DOMException(`Lock request aborted`, `AbortError`))
135 }
136 }
137 })
138 }
139
140 tryGrantNextLock(name)
141 })
142 },
143}
144
145// ---------------------------------------------------------------------------
146// Setup / teardown
147// ---------------------------------------------------------------------------
148
149function installGlobals(): void {
150 ;(globalThis as Record<string, unknown>).BroadcastChannel =
151 MockBroadcastChannel as unknown
152 Object.defineProperty(globalThis, `navigator`, {
153 value: {
154 ...(((globalThis as Record<string, unknown>).navigator as
155 | object
156 | undefined) ?? {}),
157 locks: mockNavigatorLocks,
158 },
159 writable: true,
160 configurable: true,
161 })
162}
163
164function cleanupGlobals(): void {
165 channels.clear()
166 heldLocks.clear()
167 lockQueues.clear()
168}
169
170// ---------------------------------------------------------------------------
171// Adapter stub
172// ---------------------------------------------------------------------------
173
174function createStubAdapter(): PersistenceAdapter & {
175 pullSince: (
176 collectionId: string,
177 fromRowVersion: number,
178 ) => Promise<{
179 latestRowVersion: number
180 requiresFullReload: false
181 changedKeys: Array<string | number>
182 deletedKeys: Array<string | number>
183 }>
184 getStreamPosition: (collectionId: string) => Promise<{
185 latestTerm: number
186 latestSeq: number
187 latestRowVersion: number
188 }>
189 appliedTxs: Array<{ collectionId: string; txId: string }>
190} {
191 const appliedTxs: Array<{ collectionId: string; txId: string }> = []
192
193 return {
194 appliedTxs,
195 loadSubset: () => Promise.resolve([]),
196 applyCommittedTx: (collectionId, tx) => {
197 appliedTxs.push({ collectionId, txId: tx.txId })
198 return Promise.resolve()
199 },
200 ensureIndex: () => Promise.resolve(),
201 pullSince: (_collectionId, _fromRowVersion) =>
202 Promise.resolve({
203 latestRowVersion: 0,
204 requiresFullReload: false as const,
205 changedKeys: [],
206 deletedKeys: [],
207 }),
208 getStreamPosition: () =>
209 Promise.resolve({
210 latestTerm: 0,
211 latestSeq: 0,
212 latestRowVersion: 0,
213 }),
214 }
215}
216
217function createCoordinator(
218 adapter?: ReturnType<typeof createStubAdapter>,
219): BrowserCollectionCoordinator {
220 const opts: BrowserCollectionCoordinatorOptions = {
221 dbName: `test-db`,
222 adapter: adapter ?? createStubAdapter(),
223 }
224 return new BrowserCollectionCoordinator(opts)
225}
226
227async function flush(ms: number = 10): Promise<void> {
228 await new Promise((resolve) => setTimeout(resolve, ms))
229}
230
231// ---------------------------------------------------------------------------
232// Tests
233// ---------------------------------------------------------------------------
234
235describe(`BrowserCollectionCoordinator`, () => {
236 beforeEach(() => {
237 installGlobals()
238 })
239
240 afterEach(() => {
241 cleanupGlobals()
242 })
243
244 describe(`leadership`, () => {
245 it(`first coordinator becomes leader for a collection`, async () => {
246 const coord = createCoordinator()
247 coord.subscribe(`todos`, () => {})
248 await flush(50)
249
250 expect(coord.isLeader(`todos`)).toBe(true)
251 coord.dispose()
252 })
253
254 it(`second coordinator waits for leadership`, async () => {
255 const coord1 = createCoordinator()
256 coord1.subscribe(`todos`, () => {})
257 await flush(50)
258 expect(coord1.isLeader(`todos`)).toBe(true)
259
260 const coord2 = createCoordinator()
261 coord2.subscribe(`todos`, () => {})
262 await flush(50)
263 // coord2 should be follower while coord1 holds the lock
264 expect(coord2.isLeader(`todos`)).toBe(false)
265
266 coord1.dispose()
267 coord2.dispose()
268 })
269
270 it(`second coordinator takes over after first disposes`, async () => {
271 const coord1 = createCoordinator()
272 coord1.subscribe(`todos`, () => {})
273 await flush(50)
274 expect(coord1.isLeader(`todos`)).toBe(true)
275
276 const coord2 = createCoordinator()
277 coord2.subscribe(`todos`, () => {})
278 await flush(50)
279 expect(coord2.isLeader(`todos`)).toBe(false)
280
281 coord1.dispose()
282 await flush(50)
283
284 expect(coord2.isLeader(`todos`)).toBe(true)
285 coord2.dispose()
286 })
287
288 it(`different collections have independent leaders`, async () => {
289 const coord1 = createCoordinator()
290 const coord2 = createCoordinator()
291
292 coord1.subscribe(`todos`, () => {})
293 coord2.subscribe(`notes`, () => {})
294 await flush(50)
295
296 expect(coord1.isLeader(`todos`)).toBe(true)
297 expect(coord2.isLeader(`notes`)).toBe(true)
298
299 coord1.dispose()
300 coord2.dispose()
301 })
302
303 it(`returns unique node ids`, () => {
304 const coord1 = createCoordinator()
305 const coord2 = createCoordinator()
306
307 expect(coord1.getNodeId()).not.toBe(coord2.getNodeId())
308
309 coord1.dispose()
310 coord2.dispose()
311 })
312 })
313
314 describe(`message transport`, () => {
315 it(`delivers published messages to remote subscribers`, async () => {
316 const coord1 = createCoordinator()
317 const coord2 = createCoordinator()
318
319 const received: Array<unknown> = []
320 coord2.subscribe(`todos`, (msg) => {
321 received.push(msg.payload)
322 })
323
324 coord1.subscribe(`todos`, () => {})
325 await flush(50)
326
327 coord1.publish(`todos`, {
328 v: 1,
329 dbName: `test-db`,
330 collectionId: `todos`,
331 senderId: coord1.getNodeId(),
332 ts: Date.now(),
333 payload: {
334 type: `tx:committed`,
335 term: 1,
336 seq: 1,
337 txId: `tx-1`,
338 latestRowVersion: 1,
339 requiresFullReload: true,
340 },
341 })
342
343 await flush()
344
345 expect(received.length).toBe(1)
346 expect((received[0] as Record<string, unknown>).type).toBe(`tx:committed`)
347
348 coord1.dispose()
349 coord2.dispose()
350 })
351
352 it(`does not deliver own messages to self via subscriber`, async () => {
353 const coord = createCoordinator()
354 const received: Array<unknown> = []
355 coord.subscribe(`todos`, (msg) => {
356 received.push(msg)
357 })
358 await flush(50)
359
360 coord.publish(`todos`, {
361 v: 1,
362 dbName: `test-db`,
363 collectionId: `todos`,
364 senderId: coord.getNodeId(),
365 ts: Date.now(),
366 payload: {
367 type: `tx:committed`,
368 term: 1,
369 seq: 1,
370 txId: `tx-1`,
371 latestRowVersion: 1,
372 requiresFullReload: true,
373 },
374 })
375
376 await flush()
377
378 expect(received.length).toBe(0)
379 coord.dispose()
380 })
381 })
382
383 describe(`RPC - applyLocalMutations`, () => {
384 it(`leader applies mutations and returns accepted ids`, async () => {
385 const adapter = createStubAdapter()
386 const coord = createCoordinator(adapter)
387
388 coord.subscribe(`todos`, () => {})
389 await flush(50)
390 expect(coord.isLeader(`todos`)).toBe(true)
391
392 const response = await coord.requestApplyLocalMutations(`todos`, [
393 {
394 mutationId: `mut-1`,
395 type: `insert`,
396 key: `1`,
397 value: { id: `1`, title: `Test` },
398 },
399 ])
400
401 expect(response.ok).toBe(true)
402 if (response.ok) {
403 expect(response.acceptedMutationIds).toEqual([`mut-1`])
404 expect(response.term).toBeGreaterThan(0)
405 expect(response.seq).toBeGreaterThan(0)
406 }
407 expect(adapter.appliedTxs.length).toBe(1)
408
409 coord.dispose()
410 })
411
412 it(`follower routes mutations to leader via RPC`, async () => {
413 const adapter = createStubAdapter()
414 const leader = createCoordinator(adapter)
415 const follower = createCoordinator(adapter)
416
417 leader.subscribe(`todos`, () => {})
418 follower.subscribe(`todos`, () => {})
419 await flush(50)
420
421 expect(leader.isLeader(`todos`)).toBe(true)
422 expect(follower.isLeader(`todos`)).toBe(false)
423
424 const response = await follower.requestApplyLocalMutations(`todos`, [
425 {
426 mutationId: `mut-2`,
427 type: `insert`,
428 key: `2`,
429 value: { id: `2`, title: `Follower mutation` },
430 },
431 ])
432
433 expect(response.ok).toBe(true)
434 if (response.ok) {
435 expect(response.acceptedMutationIds).toEqual([`mut-2`])
436 }
437 expect(adapter.appliedTxs.length).toBe(1)
438
439 leader.dispose()
440 follower.dispose()
441 })
442
443 it(`deduplicates envelope ids`, async () => {
444 const adapter = createStubAdapter()
445 const coord = createCoordinator(adapter)
446 coord.subscribe(`todos`, () => {})
447 await flush(50)
448
449 // First call
450 const res1 = await coord.requestApplyLocalMutations(`todos`, [
451 {
452 mutationId: `mut-1`,
453 type: `insert`,
454 key: `1`,
455 value: { id: `1`, title: `Test` },
456 },
457 ])
458 expect(res1.ok).toBe(true)
459 expect(adapter.appliedTxs.length).toBe(1)
460
461 coord.dispose()
462 })
463 })
464
465 describe(`RPC - pullSince`, () => {
466 it(`leader handles pullSince directly`, async () => {
467 const adapter = createStubAdapter()
468 const coord = createCoordinator(adapter)
469 coord.subscribe(`todos`, () => {})
470 await flush(50)
471
472 const response = await coord.pullSince(`todos`, 0)
473
474 expect(response.ok).toBe(true)
475 if (response.ok) {
476 expect(response.requiresFullReload).toBe(false)
477 }
478
479 coord.dispose()
480 })
481
482 it(`follower routes pullSince to leader`, async () => {
483 const adapter = createStubAdapter()
484 adapter.pullSince = vi.fn().mockResolvedValue({
485 latestRowVersion: 5,
486 requiresFullReload: false,
487 changedKeys: [`key-1`],
488 deletedKeys: [],
489 })
490
491 const leader = createCoordinator(adapter)
492 const follower = createCoordinator(adapter)
493
494 leader.subscribe(`todos`, () => {})
495 follower.subscribe(`todos`, () => {})
496 await flush(50)
497
498 const response = await follower.pullSince(`todos`, 0)
499
500 expect(response.ok).toBe(true)
501 if (response.ok && !response.requiresFullReload) {
502 expect(response.changedKeys).toEqual([`key-1`])
503 expect(response.latestRowVersion).toBe(5)
504 }
505
506 leader.dispose()
507 follower.dispose()
508 })
509 })
510
511 describe(`RPC - ensurePersistedIndex`, () => {
512 it(`leader ensures index locally`, async () => {
513 const adapter = createStubAdapter()
514 adapter.ensureIndex = vi.fn().mockResolvedValue(undefined)
515
516 const coord = createCoordinator(adapter)
517 coord.subscribe(`todos`, () => {})
518 await flush(50)
519
520 await coord.requestEnsurePersistedIndex(`todos`, `idx-1`, {
521 expressionSql: [`title`],
522 })
523
524 expect(adapter.ensureIndex).toHaveBeenCalledWith(`todos`, `idx-1`, {
525 expressionSql: [`title`],
526 })
527
528 coord.dispose()
529 })
530
531 it(`follower routes ensurePersistedIndex to leader`, async () => {
532 const adapter = createStubAdapter()
533 adapter.ensureIndex = vi.fn().mockResolvedValue(undefined)
534
535 const leader = createCoordinator(adapter)
536 const follower = createCoordinator(adapter)
537
538 leader.subscribe(`todos`, () => {})
539 follower.subscribe(`todos`, () => {})
540 await flush(50)
541
542 await follower.requestEnsurePersistedIndex(`todos`, `idx-2`, {
543 expressionSql: [`id`],
544 })
545
546 expect(adapter.ensureIndex).toHaveBeenCalled()
547
548 leader.dispose()
549 follower.dispose()
550 })
551 })
552
553 describe(`dispose`, () => {
554 it(`cleans up on dispose`, async () => {
555 const coord = createCoordinator()
556 coord.subscribe(`todos`, () => {})
557 await flush(50)
558
559 coord.dispose()
560
561 // Should not throw after disposal
562 expect(coord.isLeader(`todos`)).toBe(false)
563 })
564 })
565})