@syncular/client 0.64.0 → 0.65.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -214,9 +214,9 @@ export function documentLifecycleSignal(
214
214
  * Supported host policy for Syncular's explicit realtime transport. It owns
215
215
  * exactly one connect attempt, runs an explicit catch-up round before claiming
216
216
  * connected, retries transient loss with bounded exponential jitter, and
217
- * suspends across offline, background, or protected-preflight state. A host
218
- * `online` report also drives `syncUntilIdle` when realtime is unsupported
219
- * or disabled.
217
+ * suspends across offline, background, or protected-preflight state. Each
218
+ * failed attempt, each host `online` report, and each foreground return
219
+ * while no attempt starts at once drives one HTTP round (§1.8).
220
220
  */
221
221
  export class RealtimeSupervisor {
222
222
  readonly #client: RealtimeSupervisorClient;
@@ -285,20 +285,22 @@ export class RealtimeSupervisor {
285
285
  this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) =>
286
286
  this.#observeDiagnostics(snapshot),
287
287
  );
288
- this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => {
289
- // §1.8: the host's connectivity signal re-arms the drive a failed
290
- // round left behind. The drive does not wait for the socket, so a
291
- // socket that cannot connect does not hold back an HTTP round.
292
- if (this.#connectivity?.current() === 'online' && !this.#hostBlock()) {
293
- void Promise.resolve()
294
- .then(() => this.#client.syncUntilIdle())
295
- .catch(() => undefined);
296
- }
288
+ this.#unsubscribeConnectivity = this.#connectivity?.subscribe((state) => {
289
+ if (state === 'online') this.#drive();
297
290
  this.#reconcileHostState();
298
291
  });
299
- this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() =>
300
- this.#reconcileHostState(),
301
- );
292
+ this.#unsubscribeLifecycle = this.#lifecycle?.subscribe((state) => {
293
+ this.#reconcileHostState();
294
+ // An immediate attempt brings its own round; a pending retry or an
295
+ // absent socket does not.
296
+ const phase = this.#snapshot.phase;
297
+ if (
298
+ state === 'active' &&
299
+ (phase === 'retrying' || phase === 'unsupported')
300
+ ) {
301
+ this.#drive();
302
+ }
303
+ });
302
304
  this.#unsubscribeProtection = this.#protection?.subscribe(() =>
303
305
  this.#reconcileHostState(),
304
306
  );
@@ -310,21 +312,12 @@ export class RealtimeSupervisor {
310
312
  stop(): void {
311
313
  if (this.#stopped) return;
312
314
  this.#stopped = true;
313
- this.#generation += 1;
314
- const disconnect =
315
- this.#connected || this.#transportConnected || this.#connecting;
316
- this.#connected = false;
317
- this.#transportConnected = false;
318
- this.#connecting = false;
319
- this.#attempt = 0;
320
- this.#clearRetry();
315
+ this.#suspend('stopped');
321
316
  this.#unsubscribeDiagnostics?.();
322
317
  this.#unsubscribeConnectivity?.();
323
318
  this.#unsubscribeLifecycle?.();
324
319
  this.#unsubscribeProtection?.();
325
- this.#publish({ phase: 'stopped', attempt: 0 });
326
320
  this.#listeners.clear();
327
- if (disconnect) this.#disconnect();
328
321
  }
329
322
 
330
323
  async #initialize(generation: number): Promise<void> {
@@ -361,6 +354,18 @@ export class RealtimeSupervisor {
361
354
  return undefined;
362
355
  }
363
356
 
357
+ /**
358
+ * §1.8: one HTTP round that re-arms the drive a refused fetch left behind.
359
+ * It does not wait for the socket, so a socket that cannot connect does not
360
+ * hold back the round.
361
+ */
362
+ #drive(): void {
363
+ if (this.#hostBlock()) return;
364
+ void Promise.resolve()
365
+ .then(() => this.#client.syncUntilIdle())
366
+ .catch(() => undefined);
367
+ }
368
+
364
369
  #canConnect(): boolean {
365
370
  return (
366
371
  this.#initialized &&
@@ -393,17 +398,31 @@ export class RealtimeSupervisor {
393
398
  this.#cancelRetry = undefined;
394
399
  }
395
400
 
396
- #schedule(delayMs: number): void {
397
- if (
398
- !this.#canConnect() ||
399
- this.#connected ||
400
- this.#connecting ||
401
- this.#cancelRetry
402
- ) {
403
- return;
401
+ /** A retry counts one attempt and backs off with bounded jitter. */
402
+ #schedule(retry: boolean): void {
403
+ if (!this.#canConnect()) return this.#reconcileHostState();
404
+ // Count an attempt only when this call actually schedules one. Repeated
405
+ // 'disconnected' diagnostics beside a pending retry keep the backoff and
406
+ // the worker-mode reconnect nudge intact.
407
+ if (this.#connected || this.#connecting || this.#cancelRetry) return;
408
+ let delayMs = 0;
409
+ if (retry) {
410
+ const exponential = Math.min(
411
+ this.#maximumDelayMs,
412
+ this.#initialDelayMs * 2 ** this.#attempt,
413
+ );
414
+ const random = this.#random();
415
+ const boundedRandom = Number.isFinite(random)
416
+ ? Math.max(0, Math.min(1, random))
417
+ : 0;
418
+ delayMs = Math.min(
419
+ this.#maximumDelayMs,
420
+ exponential + Math.floor(exponential * 0.25 * boundedRandom),
421
+ );
422
+ this.#attempt = Math.min(32, this.#attempt + 1);
404
423
  }
405
424
  this.#publish(
406
- delayMs > 0
425
+ retry
407
426
  ? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
408
427
  : { phase: 'connecting', attempt: this.#attempt },
409
428
  );
@@ -413,39 +432,6 @@ export class RealtimeSupervisor {
413
432
  }, delayMs);
414
433
  }
415
434
 
416
- #retryDelay(): number {
417
- const exponential = Math.min(
418
- this.#maximumDelayMs,
419
- this.#initialDelayMs * 2 ** this.#attempt,
420
- );
421
- const random = this.#random();
422
- const boundedRandom = Number.isFinite(random)
423
- ? Math.max(0, Math.min(1, random))
424
- : 0;
425
- const jitter = Math.floor(exponential * 0.25 * boundedRandom);
426
- return Math.min(this.#maximumDelayMs, exponential + jitter);
427
- }
428
-
429
- #scheduleRetry(): void {
430
- if (!this.#canConnect()) {
431
- this.#reconcileHostState();
432
- return;
433
- }
434
- // Count an attempt only when this call actually schedules one. Repeated
435
- // 'disconnected' diagnostics beside a pending retry keep the backoff and
436
- // the worker-mode reconnect nudge intact.
437
- if (
438
- this.#connected ||
439
- this.#connecting ||
440
- this.#cancelRetry !== undefined
441
- ) {
442
- return;
443
- }
444
- const delay = this.#retryDelay();
445
- this.#attempt = Math.min(32, this.#attempt + 1);
446
- this.#schedule(delay);
447
- }
448
-
449
435
  /**
450
436
  * A superseded attempt observed a generation bump mid-flight. Whenever a
451
437
  * newer generation is mid-connect or holds the transport, that generation
@@ -496,7 +482,10 @@ export class RealtimeSupervisor {
496
482
  // A superseded attempt leaves the successor's in-flight state alone.
497
483
  if (generation === this.#generation) this.#connecting = false;
498
484
  }
499
- if (failed && generation === this.#generation) this.#scheduleRetry();
485
+ if (failed && generation === this.#generation) {
486
+ this.#schedule(true);
487
+ this.#drive();
488
+ }
500
489
  }
501
490
 
502
491
  async #catchUpConnectedTransport(generation: number): Promise<void> {
@@ -538,7 +527,7 @@ export class RealtimeSupervisor {
538
527
  // A superseded adoption leaves the successor's in-flight state alone.
539
528
  if (generation === this.#generation) this.#connecting = false;
540
529
  }
541
- if (failed && generation === this.#generation) this.#scheduleRetry();
530
+ if (failed && generation === this.#generation) this.#schedule(true);
542
531
  }
543
532
 
544
533
  #observeDiagnostics(
@@ -551,16 +540,8 @@ export class RealtimeSupervisor {
551
540
  snapshot.host.realtime === 'unsupported' ||
552
541
  snapshot.host.realtime === 'disabled'
553
542
  ) {
554
- const disconnect =
555
- this.#connected || this.#transportConnected || this.#connecting;
556
543
  this.#realtimeSupported = false;
557
- this.#generation += 1;
558
- this.#connected = false;
559
- this.#transportConnected = false;
560
- this.#attempt = 0;
561
- this.#clearRetry();
562
- this.#publish({ phase: 'unsupported', attempt: 0 });
563
- if (disconnect) this.#disconnect();
544
+ this.#suspend('unsupported');
564
545
  return;
565
546
  }
566
547
  if (!this.#realtimeSupported) {
@@ -606,7 +587,7 @@ export class RealtimeSupervisor {
606
587
  this.#transportConnected = false;
607
588
  this.#connected = false;
608
589
  if (this.#connecting) return;
609
- if (this.#initialized && !initial) this.#scheduleRetry();
590
+ if (this.#initialized && !initial) this.#schedule(true);
610
591
  return;
611
592
  }
612
593
  this.#reconcileHostState();
@@ -631,15 +612,16 @@ export class RealtimeSupervisor {
631
612
  this.#publish({ phase: 'connected', attempt: 0 });
632
613
  return;
633
614
  }
634
- this.#schedule(0);
615
+ this.#schedule(false);
635
616
  }
636
617
 
637
- #suspend(phase: RealtimeSuspendedPhase): void {
618
+ /** Cancel every attempt and release the socket, then publish `phase`. */
619
+ #suspend(phase: RealtimeSupervisorPhase): void {
638
620
  const disconnect =
639
621
  this.#connected || this.#transportConnected || this.#connecting;
640
- const hadScheduledWork = this.#cancelRetry !== undefined;
641
- const phaseChanged = this.#snapshot.phase !== phase;
642
- if (!disconnect && !hadScheduledWork && !phaseChanged) return;
622
+ if (!disconnect && !this.#cancelRetry && this.#snapshot.phase === phase) {
623
+ return;
624
+ }
643
625
  this.#generation += 1;
644
626
  this.#connected = false;
645
627
  this.#transportConnected = false;
@@ -72,7 +72,11 @@ export interface SyncWorkerOverrides {
72
72
  callback: () => void,
73
73
  delayMs: number,
74
74
  ) => () => void;
75
- readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
75
+ /** `http` reads the current host auth set, as the default transport does. */
76
+ readonly createTransport?: (
77
+ config: WorkerInitConfig,
78
+ http: { readonly headers: () => Readonly<Record<string, string>> },
79
+ ) => SyncTransport;
76
80
  readonly createSegments?: (
77
81
  config: WorkerInitConfig,
78
82
  ) => SegmentDownloader | undefined;
@@ -398,7 +402,7 @@ export function startSyncWorkerCore(
398
402
  }
399
403
  const remote =
400
404
  overrides.createTransport !== undefined
401
- ? overrides.createTransport(config)
405
+ ? overrides.createTransport(config, http)
402
406
  : httpSyncTransport(config.endpoints.syncUrl, http);
403
407
  const remoteSegments =
404
408
  overrides.createSegments !== undefined
@@ -702,8 +706,7 @@ async function defaultOpenDatabase(
702
706
  if (config.database.mode !== 'persistent') {
703
707
  throw new ClientSyncError(
704
708
  WORKER_FAILED_CODE,
705
- "database mode 'custom' requires an openDatabase override in the " +
706
- 'worker bootstrap (startSyncWorker({ openDatabase }))',
709
+ "database mode 'custom' requires startSyncWorker({ openDatabase })",
707
710
  );
708
711
  }
709
712
  return openPersistentWasmDatabase(config.database.name, {