@syncular/client 0.58.0 → 0.60.0
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.
- package/README.md +34 -34
- package/dist/apply.d.ts +24 -14
- package/dist/apply.js +119 -70
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +15 -0
- package/dist/client.d.ts +83 -75
- package/dist/client.js +982 -910
- package/dist/database.d.ts +5 -0
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +5 -1
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +6 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +67 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +14 -14
- package/dist/invalidation.js +24 -48
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +226 -0
- package/dist/native-bridge.js +764 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +21 -1
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +20 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +34 -24
- package/dist/query-guard.js +61 -186
- package/dist/reactive-store.js +55 -13
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +19 -23
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +43 -22
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +83 -75
- package/dist/worker-host.d.ts +19 -13
- package/dist/worker-host.js +75 -18
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +15 -10
- package/package.json +11 -3
- package/src/apply.ts +176 -86
- package/src/authority.ts +31 -17
- package/src/blob.ts +28 -15
- package/src/bun-database.ts +24 -0
- package/src/client.ts +1282 -1217
- package/src/database.ts +5 -0
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/encryption.ts +10 -5
- package/src/errors.ts +9 -1
- package/src/failed-overlay.ts +8 -7
- package/src/http.ts +95 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +26 -61
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1153 -0
- package/src/node-database.ts +32 -1
- package/src/outbox.ts +20 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +77 -177
- package/src/reactive-store.ts +52 -12
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +23 -31
- package/src/schema.ts +67 -25
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/window.ts +55 -134
- package/src/worker-core.ts +97 -77
- package/src/worker-host.ts +76 -32
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +14 -10
package/src/worker-core.ts
CHANGED
|
@@ -24,6 +24,7 @@ import { encryptionConfigFromKeyring } from './encryption';
|
|
|
24
24
|
import {
|
|
25
25
|
classifySqliteFailure,
|
|
26
26
|
ClientSyncError,
|
|
27
|
+
invalidRequest,
|
|
27
28
|
STORAGE_BUSY_CODE,
|
|
28
29
|
} from './errors';
|
|
29
30
|
import {
|
|
@@ -64,6 +65,14 @@ export interface SyncWorkerOverrides {
|
|
|
64
65
|
) => Promise<ClientDatabase> | ClientDatabase;
|
|
65
66
|
/** Retry deadline indirection for deterministic worker-host tests. */
|
|
66
67
|
readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
|
|
68
|
+
/**
|
|
69
|
+
* Timer indirection for deterministic worker-host tests: background-intent
|
|
70
|
+
* deadlines and the client's §8.5 heartbeat watchdog.
|
|
71
|
+
*/
|
|
72
|
+
readonly scheduleBackground?: (
|
|
73
|
+
callback: () => void,
|
|
74
|
+
delayMs: number,
|
|
75
|
+
) => () => void;
|
|
67
76
|
readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
|
|
68
77
|
readonly createSegments?: (
|
|
69
78
|
config: WorkerInitConfig,
|
|
@@ -201,6 +210,7 @@ export function startSyncWorkerCore(
|
|
|
201
210
|
let offline = false;
|
|
202
211
|
let headers: Readonly<Record<string, string>> = {};
|
|
203
212
|
let closed = false;
|
|
213
|
+
let pushingDiagnostics = false;
|
|
204
214
|
|
|
205
215
|
// -- one sync loop: RPC-driven and auto-driven rounds serialize ----------
|
|
206
216
|
let syncChain: Promise<unknown> = Promise.resolve();
|
|
@@ -216,8 +226,32 @@ export function startSyncWorkerCore(
|
|
|
216
226
|
// -- SPEC §7.5 host loop: event-driven intents, no interactive polling --
|
|
217
227
|
let autoSync = true;
|
|
218
228
|
let autoSyncScheduled = false;
|
|
219
|
-
let
|
|
229
|
+
let cancelBackground: (() => void) | undefined;
|
|
220
230
|
let backgroundDue = Number.POSITIVE_INFINITY;
|
|
231
|
+
// §7.7 backoff for drives that end without a client retry intent.
|
|
232
|
+
let retryDelayMs = 250;
|
|
233
|
+
const scheduleBackground =
|
|
234
|
+
overrides.scheduleBackground ??
|
|
235
|
+
((callback: () => void, delayMs: number): (() => void) => {
|
|
236
|
+
const timer = setTimeout(callback, delayMs);
|
|
237
|
+
return () => clearTimeout(timer);
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
const workerDiagnostics = (snapshot: ClientDiagnosticsSnapshot) =>
|
|
241
|
+
withClientDiagnosticsHost(snapshot, {
|
|
242
|
+
kind: 'worker',
|
|
243
|
+
role: 'leader',
|
|
244
|
+
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
245
|
+
realtime: snapshot.host.realtime,
|
|
246
|
+
});
|
|
247
|
+
const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
|
|
248
|
+
if (!closed) {
|
|
249
|
+
post({
|
|
250
|
+
t: 'event',
|
|
251
|
+
event: { kind: 'diagnostics', snapshot: workerDiagnostics(snapshot) },
|
|
252
|
+
});
|
|
253
|
+
}
|
|
254
|
+
};
|
|
221
255
|
|
|
222
256
|
function runAutoSync(): void {
|
|
223
257
|
if (
|
|
@@ -238,19 +272,44 @@ export function startSyncWorkerCore(
|
|
|
238
272
|
return running.syncUntilIdle();
|
|
239
273
|
})
|
|
240
274
|
.then((summary) => {
|
|
275
|
+
retryDelayMs = 250;
|
|
241
276
|
if (!closed) post({ t: 'event', event: { kind: 'synced', summary } });
|
|
242
277
|
if (summary.budgetExhausted) consumeSyncIntent({ kind: 'interactive' });
|
|
243
278
|
})
|
|
244
279
|
.catch((error: unknown) => {
|
|
245
|
-
if (
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
280
|
+
if (closed) return;
|
|
281
|
+
post({
|
|
282
|
+
t: 'event',
|
|
283
|
+
event: { kind: 'synced', error: toErrorShape(error) },
|
|
284
|
+
});
|
|
285
|
+
// §7.8: a retryable drive rejection owes another drive. A retryable
|
|
286
|
+
// round failure already handed this loop its background intent; the
|
|
287
|
+
// drive deadline did not. An unreachable endpoint waits for the
|
|
288
|
+
// host's connectivity resume (§1.8).
|
|
289
|
+
const causeKind =
|
|
290
|
+
error instanceof ClientSyncError
|
|
291
|
+
? error.details?.['causeKind']
|
|
292
|
+
: undefined;
|
|
293
|
+
if (
|
|
294
|
+
error instanceof ClientSyncError &&
|
|
295
|
+
error.retryable &&
|
|
296
|
+
causeKind !== 'network' &&
|
|
297
|
+
causeKind !== 'connect' &&
|
|
298
|
+
cancelBackground === undefined &&
|
|
299
|
+
!autoSyncScheduled
|
|
300
|
+
) {
|
|
301
|
+
consumeSyncIntent({ kind: 'background', delayMs: retryDelayMs });
|
|
302
|
+
retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
|
|
250
303
|
}
|
|
251
304
|
});
|
|
252
305
|
}
|
|
253
306
|
|
|
307
|
+
function stopBackground(): void {
|
|
308
|
+
cancelBackground?.();
|
|
309
|
+
cancelBackground = undefined;
|
|
310
|
+
backgroundDue = Number.POSITIVE_INFINITY;
|
|
311
|
+
}
|
|
312
|
+
|
|
254
313
|
function consumeSyncIntent(intent: SyncIntent): void {
|
|
255
314
|
if (
|
|
256
315
|
!autoSync ||
|
|
@@ -265,12 +324,12 @@ export function startSyncWorkerCore(
|
|
|
265
324
|
if (intent.kind === 'background') {
|
|
266
325
|
if (autoSyncScheduled) return;
|
|
267
326
|
const due = Date.now() + Math.max(0, intent.delayMs);
|
|
268
|
-
if (
|
|
269
|
-
|
|
327
|
+
if (cancelBackground !== undefined && due >= backgroundDue) return;
|
|
328
|
+
cancelBackground?.();
|
|
270
329
|
backgroundDue = due;
|
|
271
|
-
|
|
330
|
+
cancelBackground = scheduleBackground(
|
|
272
331
|
() => {
|
|
273
|
-
|
|
332
|
+
cancelBackground = undefined;
|
|
274
333
|
backgroundDue = Number.POSITIVE_INFINITY;
|
|
275
334
|
if (!autoSyncScheduled) {
|
|
276
335
|
autoSyncScheduled = true;
|
|
@@ -281,11 +340,7 @@ export function startSyncWorkerCore(
|
|
|
281
340
|
);
|
|
282
341
|
return;
|
|
283
342
|
}
|
|
284
|
-
|
|
285
|
-
clearTimeout(backgroundTimer);
|
|
286
|
-
backgroundTimer = undefined;
|
|
287
|
-
backgroundDue = Number.POSITIVE_INFINITY;
|
|
288
|
-
}
|
|
343
|
+
stopBackground();
|
|
289
344
|
if (!autoSync || autoSyncScheduled || closed || client === undefined) {
|
|
290
345
|
return;
|
|
291
346
|
}
|
|
@@ -393,15 +448,12 @@ export function startSyncWorkerCore(
|
|
|
393
448
|
? { segments: bindings.segments }
|
|
394
449
|
: {}),
|
|
395
450
|
...(blobs !== undefined ? { blobs } : {}),
|
|
396
|
-
realtime: (handlers) => {
|
|
451
|
+
realtime: (handlers, clientId) => {
|
|
397
452
|
// §12.2: a local authority has no realtime channel.
|
|
398
453
|
if (realtimeConnector === undefined || local?.active()) {
|
|
399
|
-
throw
|
|
400
|
-
'sync.invalid_request',
|
|
401
|
-
'no realtime connector configured',
|
|
402
|
-
);
|
|
454
|
+
throw invalidRequest('no realtime connector configured');
|
|
403
455
|
}
|
|
404
|
-
return realtimeConnector(handlers);
|
|
456
|
+
return realtimeConnector(handlers, clientId);
|
|
405
457
|
},
|
|
406
458
|
...(config.clientId !== undefined ? { clientId: config.clientId } : {}),
|
|
407
459
|
...(config.limits !== undefined ? { limits: config.limits } : {}),
|
|
@@ -411,6 +463,10 @@ export function startSyncWorkerCore(
|
|
|
411
463
|
...(config.realtimePolicy !== undefined
|
|
412
464
|
? { realtimePolicy: config.realtimePolicy }
|
|
413
465
|
: {}),
|
|
466
|
+
...(config.realtimeHeartbeatMs !== undefined
|
|
467
|
+
? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
|
|
468
|
+
: {}),
|
|
469
|
+
schedule: scheduleBackground,
|
|
414
470
|
...(config.encryption !== undefined
|
|
415
471
|
? { encryption: encryptionConfigFromKeyring(config.encryption) }
|
|
416
472
|
: {}),
|
|
@@ -439,9 +495,9 @@ export function startSyncWorkerCore(
|
|
|
439
495
|
// §7.4.5: surface the schema-bump reset + completion to the UI thread.
|
|
440
496
|
post({ t: 'event', event: { kind: 'upgrading', upgrading } });
|
|
441
497
|
},
|
|
442
|
-
onPresence: (scopeKey) => {
|
|
443
|
-
// §8.6: surface a presence change to the UI thread.
|
|
444
|
-
post({ t: 'event', event: { kind: 'presence', scopeKey } });
|
|
498
|
+
onPresence: (scopeKey, error) => {
|
|
499
|
+
// §8.6: surface a presence change or rejection to the UI thread.
|
|
500
|
+
post({ t: 'event', event: { kind: 'presence', scopeKey, error } });
|
|
445
501
|
},
|
|
446
502
|
});
|
|
447
503
|
started.onProgress((progress) => {
|
|
@@ -450,33 +506,12 @@ export function startSyncWorkerCore(
|
|
|
450
506
|
started.onChange((batch) => {
|
|
451
507
|
if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
|
|
452
508
|
});
|
|
453
|
-
const postDiagnostics = (snapshot: ClientDiagnosticsSnapshot): void => {
|
|
454
|
-
if (closed) return;
|
|
455
|
-
post({
|
|
456
|
-
t: 'event',
|
|
457
|
-
event: {
|
|
458
|
-
kind: 'diagnostics',
|
|
459
|
-
snapshot: withClientDiagnosticsHost(snapshot, {
|
|
460
|
-
kind: 'worker',
|
|
461
|
-
role: 'leader',
|
|
462
|
-
connectivity: offline ? 'offline' : snapshot.host.connectivity,
|
|
463
|
-
realtime: snapshot.host.realtime,
|
|
464
|
-
}),
|
|
465
|
-
},
|
|
466
|
-
});
|
|
467
|
-
};
|
|
468
|
-
started.onDiagnostics(postDiagnostics);
|
|
469
509
|
await started.start();
|
|
470
510
|
realtimeConnector =
|
|
471
511
|
overrides.createRealtime !== undefined
|
|
472
512
|
? overrides.createRealtime(config, started.clientId, http.headers)
|
|
473
513
|
: config.endpoints.realtimeUrl !== undefined
|
|
474
|
-
? webSocketRealtimeConnector(
|
|
475
|
-
config.endpoints.realtimeUrl.replace(
|
|
476
|
-
'{clientId}',
|
|
477
|
-
encodeURIComponent(started.clientId),
|
|
478
|
-
),
|
|
479
|
-
)
|
|
514
|
+
? webSocketRealtimeConnector(config.endpoints.realtimeUrl)
|
|
480
515
|
: undefined;
|
|
481
516
|
client = started;
|
|
482
517
|
// `start()` may discover persisted subscriptions/outbox work. Its callback
|
|
@@ -510,8 +545,8 @@ export function startSyncWorkerCore(
|
|
|
510
545
|
'commitOutcomes',
|
|
511
546
|
'resolveCommitOutcome',
|
|
512
547
|
'pendingCommits',
|
|
513
|
-
'
|
|
514
|
-
'
|
|
548
|
+
'units',
|
|
549
|
+
'unit',
|
|
515
550
|
'connectRealtime',
|
|
516
551
|
'disconnectRealtime',
|
|
517
552
|
'setPresence',
|
|
@@ -530,9 +565,7 @@ export function startSyncWorkerCore(
|
|
|
530
565
|
]),
|
|
531
566
|
) as Pick<WorkerApi, (typeof coreMethods)[number]>),
|
|
532
567
|
beginSecurityPreflight: async () => {
|
|
533
|
-
|
|
534
|
-
backgroundTimer = undefined;
|
|
535
|
-
backgroundDue = Number.POSITIVE_INFINITY;
|
|
568
|
+
stopBackground();
|
|
536
569
|
autoSyncScheduled = false;
|
|
537
570
|
await requireClient().beginSecurityPreflight();
|
|
538
571
|
},
|
|
@@ -574,14 +607,15 @@ export function startSyncWorkerCore(
|
|
|
574
607
|
},
|
|
575
608
|
resetClientId: () => requireClient().resetClientId(),
|
|
576
609
|
localRevision: () => requireClient().localRevision,
|
|
577
|
-
diagnosticsSnapshot: (
|
|
578
|
-
const
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
}
|
|
610
|
+
diagnosticsSnapshot: () => {
|
|
611
|
+
const running = requireClient();
|
|
612
|
+
// The first pull makes the worker a push source: no tab has asked for
|
|
613
|
+
// diagnostics before it, so no snapshot is built per revision until then.
|
|
614
|
+
if (!pushingDiagnostics) {
|
|
615
|
+
pushingDiagnostics = true;
|
|
616
|
+
running.onDiagnostics(postDiagnostics);
|
|
617
|
+
}
|
|
618
|
+
return workerDiagnostics(running.diagnosticsSnapshot());
|
|
585
619
|
},
|
|
586
620
|
setHeaders: (next) => {
|
|
587
621
|
headers = next;
|
|
@@ -590,29 +624,15 @@ export function startSyncWorkerCore(
|
|
|
590
624
|
offline = value;
|
|
591
625
|
requireClient().setTransportEnabled(!value);
|
|
592
626
|
if (offline) {
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
} else if (client !== undefined) {
|
|
597
|
-
const snapshot = client.diagnosticsSnapshot();
|
|
598
|
-
post({
|
|
599
|
-
t: 'event',
|
|
600
|
-
event: {
|
|
601
|
-
kind: 'diagnostics',
|
|
602
|
-
snapshot: withClientDiagnosticsHost(snapshot, {
|
|
603
|
-
kind: 'worker',
|
|
604
|
-
role: 'leader',
|
|
605
|
-
connectivity: snapshot.host.connectivity,
|
|
606
|
-
realtime: snapshot.host.realtime,
|
|
607
|
-
}),
|
|
608
|
-
},
|
|
609
|
-
});
|
|
627
|
+
stopBackground();
|
|
628
|
+
} else if (client !== undefined && pushingDiagnostics) {
|
|
629
|
+
postDiagnostics(client.diagnosticsSnapshot());
|
|
610
630
|
}
|
|
611
631
|
},
|
|
612
632
|
...local?.methods,
|
|
613
633
|
close: async () => {
|
|
614
634
|
closed = true;
|
|
615
|
-
|
|
635
|
+
cancelBackground?.();
|
|
616
636
|
await client?.close();
|
|
617
637
|
local?.close();
|
|
618
638
|
database?.close();
|
package/src/worker-host.ts
CHANGED
|
@@ -27,7 +27,11 @@ import type { PromiseMethods } from './client';
|
|
|
27
27
|
* With `multiTab: false`, the loser is an `isLeader === false` handle whose
|
|
28
28
|
* calls reject with `client.not_leader` (the single-tab contract).
|
|
29
29
|
*/
|
|
30
|
-
import
|
|
30
|
+
import {
|
|
31
|
+
type PresenceErrorCode,
|
|
32
|
+
serializeBlobRef,
|
|
33
|
+
type WakeReason,
|
|
34
|
+
} from '@syncular/core';
|
|
31
35
|
import type { BlobRef, CachedBlob } from './blob';
|
|
32
36
|
import type {
|
|
33
37
|
ConflictRecord,
|
|
@@ -40,7 +44,6 @@ import type {
|
|
|
40
44
|
SecurityLifecycle,
|
|
41
45
|
SnapshotRead,
|
|
42
46
|
SnapshotReadRequest,
|
|
43
|
-
SubscribeInput,
|
|
44
47
|
SyncClientConfig,
|
|
45
48
|
SyncClientLimits,
|
|
46
49
|
SyncSummary,
|
|
@@ -53,13 +56,12 @@ import type { DevtoolsRegistrar } from './devtools';
|
|
|
53
56
|
import {
|
|
54
57
|
ClientDiagnosticsEmitter,
|
|
55
58
|
type ClientDiagnosticsListener,
|
|
56
|
-
type ClientDiagnosticsRequest,
|
|
57
59
|
type ClientDiagnosticsSnapshot,
|
|
58
60
|
type RealtimePolicy,
|
|
59
61
|
withClientDiagnosticsHost,
|
|
60
62
|
} from './diagnostics';
|
|
61
63
|
import type { EncryptionKeyringConfig } from './encryption';
|
|
62
|
-
import { ClientSyncError } from './errors';
|
|
64
|
+
import { ClientSyncError, invalidRequest } from './errors';
|
|
63
65
|
import {
|
|
64
66
|
ChangeEmitter,
|
|
65
67
|
type ClientChangeListener,
|
|
@@ -106,7 +108,8 @@ import {
|
|
|
106
108
|
type PreviousVersionSnapshot,
|
|
107
109
|
} from './previous-version';
|
|
108
110
|
import type { ClientSchema } from './schema';
|
|
109
|
-
import type {
|
|
111
|
+
import type { UnitScopes } from '@syncular/core';
|
|
112
|
+
import type { UnitRecord } from './state';
|
|
110
113
|
import type { WindowBase } from './window';
|
|
111
114
|
import {
|
|
112
115
|
type LocalAuthorityState,
|
|
@@ -161,8 +164,7 @@ export function isolatedReplicaNames(options: {
|
|
|
161
164
|
readonly replicaId: string;
|
|
162
165
|
}): IsolatedReplicaNames {
|
|
163
166
|
if (!/^[A-Za-z0-9._-]+$/.test(options.replicaId)) {
|
|
164
|
-
throw
|
|
165
|
-
'sync.invalid_request',
|
|
167
|
+
throw invalidRequest(
|
|
166
168
|
'an isolated replica id must contain only letters, numbers, dot, underscore, or dash',
|
|
167
169
|
);
|
|
168
170
|
}
|
|
@@ -213,6 +215,8 @@ export interface SyncClientHandleConfig {
|
|
|
213
215
|
* `WorkerInitConfig`. Absent ⇒ `optional`.
|
|
214
216
|
*/
|
|
215
217
|
readonly realtimePolicy?: RealtimePolicy;
|
|
218
|
+
/** SPEC §8.5 heartbeat interval, forwarded into `WorkerInitConfig`. */
|
|
219
|
+
readonly realtimeHeartbeatMs?: number;
|
|
216
220
|
/**
|
|
217
221
|
* RFC 0005 previous-version context, forwarded into the worker's
|
|
218
222
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -263,8 +267,9 @@ export interface SyncClientHandleConfig {
|
|
|
263
267
|
}) => void;
|
|
264
268
|
/** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
|
|
265
269
|
readonly onUpgrading?: (upgrading: boolean) => void;
|
|
266
|
-
/** §8.6: presence on a scope key changed
|
|
267
|
-
|
|
270
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
271
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
272
|
+
readonly onPresence?: (scopeKey: string, error?: PresenceErrorCode) => void;
|
|
268
273
|
/** Atomic privacy-safe diagnostics changed. */
|
|
269
274
|
readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
|
|
270
275
|
}
|
|
@@ -334,7 +339,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
334
339
|
readonly #invalidation: InvalidationEmitter;
|
|
335
340
|
readonly #progress = new ProgressEmitter();
|
|
336
341
|
readonly #changes: ChangeEmitter;
|
|
337
|
-
readonly #presence: Set<
|
|
342
|
+
readonly #presence: Set<
|
|
343
|
+
(scopeKey: string, error?: PresenceErrorCode) => void
|
|
344
|
+
>;
|
|
338
345
|
readonly #diagnostics: ClientDiagnosticsEmitter;
|
|
339
346
|
readonly #roleListeners: Set<(role: HandleRole) => void>;
|
|
340
347
|
readonly #leadershipListeners: Set<(state: LeadershipState) => void>;
|
|
@@ -352,7 +359,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
352
359
|
tabs?: TabCoordinator;
|
|
353
360
|
invalidation: InvalidationEmitter;
|
|
354
361
|
changes: ChangeEmitter;
|
|
355
|
-
presence: Set<(scopeKey: string) => void>;
|
|
362
|
+
presence: Set<(scopeKey: string, error?: PresenceErrorCode) => void>;
|
|
356
363
|
diagnostics: ClientDiagnosticsEmitter;
|
|
357
364
|
roleListeners?: Set<(role: HandleRole) => void>;
|
|
358
365
|
leadershipListeners?: Set<(state: LeadershipState) => void>;
|
|
@@ -390,7 +397,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
390
397
|
clientId: () => this.#clientId,
|
|
391
398
|
role: () => this.#role,
|
|
392
399
|
outbox: async () => (await this.statusSnapshot()).outbox,
|
|
393
|
-
|
|
400
|
+
units: () => this.units(),
|
|
394
401
|
conflicts: async () => (await this.conflicts()).length,
|
|
395
402
|
rejections: async () => (await this.rejections()).length,
|
|
396
403
|
syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
|
|
@@ -407,6 +414,13 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
407
414
|
this.#leadership = state;
|
|
408
415
|
if (state.state === 'leader') this.#clientId = state.clientId;
|
|
409
416
|
if (state.state === 'follower') this.#clientId = state.leaderClientId;
|
|
417
|
+
// A new leader starts a fresh core that no tab has pulled from yet.
|
|
418
|
+
if (
|
|
419
|
+
this.#diagnostics.observed &&
|
|
420
|
+
(state.state === 'leader' || state.state === 'follower')
|
|
421
|
+
) {
|
|
422
|
+
this.#pullDiagnostics();
|
|
423
|
+
}
|
|
410
424
|
for (const listener of this.#leadershipListeners) {
|
|
411
425
|
try {
|
|
412
426
|
listener(state);
|
|
@@ -433,7 +447,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
433
447
|
} else if (event.kind === 'presence') {
|
|
434
448
|
for (const listener of this.#presence) {
|
|
435
449
|
try {
|
|
436
|
-
listener(event.scopeKey);
|
|
450
|
+
listener(event.scopeKey, event.error);
|
|
437
451
|
} catch {
|
|
438
452
|
/* a UI listener must never break event dispatch */
|
|
439
453
|
}
|
|
@@ -475,14 +489,27 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
475
489
|
}
|
|
476
490
|
|
|
477
491
|
onDiagnostics(listener: ClientDiagnosticsListener): () => void {
|
|
478
|
-
|
|
492
|
+
const off = this.#diagnostics.on(listener);
|
|
493
|
+
this.#pullDiagnostics();
|
|
494
|
+
return off;
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* The worker pushes diagnostics only after a consumer pulled once. A handle
|
|
499
|
+
* that cannot reach a core has nothing to observe, so a failed pull is
|
|
500
|
+
* dropped.
|
|
501
|
+
*/
|
|
502
|
+
#pullDiagnostics(): void {
|
|
503
|
+
void this.diagnosticsSnapshot().catch(() => undefined);
|
|
479
504
|
}
|
|
480
505
|
|
|
481
506
|
/**
|
|
482
507
|
* §8.6: subscribe to presence changes — the identical surface as
|
|
483
508
|
* `SyncClient.onPresence`. Returns an unsubscribe function.
|
|
484
509
|
*/
|
|
485
|
-
onPresence(
|
|
510
|
+
onPresence(
|
|
511
|
+
listener: (scopeKey: string, error?: PresenceErrorCode) => void,
|
|
512
|
+
): () => void {
|
|
486
513
|
this.#presence.add(listener);
|
|
487
514
|
return () => {
|
|
488
515
|
this.#presence.delete(listener);
|
|
@@ -571,12 +598,12 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
571
598
|
>;
|
|
572
599
|
}
|
|
573
600
|
|
|
574
|
-
subscribe(
|
|
575
|
-
return this.#call('subscribe', [
|
|
601
|
+
subscribe(scopes: UnitScopes): Promise<string> {
|
|
602
|
+
return this.#call('subscribe', [scopes]);
|
|
576
603
|
}
|
|
577
604
|
|
|
578
|
-
subscribeMany(
|
|
579
|
-
return this.#call('subscribeMany', [
|
|
605
|
+
subscribeMany(units: readonly UnitScopes[]): Promise<string[]> {
|
|
606
|
+
return this.#call('subscribeMany', [units]);
|
|
580
607
|
}
|
|
581
608
|
|
|
582
609
|
securityLifecycle(): Promise<SecurityLifecycle> {
|
|
@@ -714,10 +741,8 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
714
741
|
return this.#call('statusSnapshot', []);
|
|
715
742
|
}
|
|
716
743
|
|
|
717
|
-
async diagnosticsSnapshot(
|
|
718
|
-
|
|
719
|
-
): Promise<ClientDiagnosticsSnapshot> {
|
|
720
|
-
const snapshot = await this.#call('diagnosticsSnapshot', [request]);
|
|
744
|
+
async diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot> {
|
|
745
|
+
const snapshot = await this.#call('diagnosticsSnapshot', []);
|
|
721
746
|
return withClientDiagnosticsHost(snapshot, {
|
|
722
747
|
...snapshot.host,
|
|
723
748
|
kind: 'worker',
|
|
@@ -754,12 +779,12 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
754
779
|
return this.#call('pendingCommits', []);
|
|
755
780
|
}
|
|
756
781
|
|
|
757
|
-
|
|
758
|
-
return this.#call('
|
|
782
|
+
units(): Promise<UnitRecord[]> {
|
|
783
|
+
return this.#call('units', []);
|
|
759
784
|
}
|
|
760
785
|
|
|
761
|
-
|
|
762
|
-
return this.#call('
|
|
786
|
+
unit(id: string): Promise<UnitRecord | undefined> {
|
|
787
|
+
return this.#call('unit', [id]);
|
|
763
788
|
}
|
|
764
789
|
|
|
765
790
|
connectRealtime(): Promise<void> {
|
|
@@ -790,6 +815,11 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
790
815
|
return this.#call('uploadBlob', [bytes, options]);
|
|
791
816
|
}
|
|
792
817
|
|
|
818
|
+
/** Serialize a BlobRef to the canonical string a `blob_ref` column holds. */
|
|
819
|
+
blobRefString(ref: BlobRef): string {
|
|
820
|
+
return serializeBlobRef(ref);
|
|
821
|
+
}
|
|
822
|
+
|
|
793
823
|
fetchBlob(blobIdOrRef: string): Promise<CachedBlob> {
|
|
794
824
|
return this.#call('fetchBlob', [blobIdOrRef]);
|
|
795
825
|
}
|
|
@@ -862,7 +892,14 @@ async function startWorkerCore(options: {
|
|
|
862
892
|
dispatchEvent: (event: SyncWorkerEvent) => void;
|
|
863
893
|
}): Promise<LeaderCore> {
|
|
864
894
|
const { config, initConfig, lease } = options;
|
|
865
|
-
|
|
895
|
+
let worker: Worker;
|
|
896
|
+
try {
|
|
897
|
+
worker = config.worker();
|
|
898
|
+
} catch (error) {
|
|
899
|
+
// No worker exists to terminate; the lease is the only thing held.
|
|
900
|
+
await lease.release();
|
|
901
|
+
throw error;
|
|
902
|
+
}
|
|
866
903
|
const pending = new Map<number, Pending>();
|
|
867
904
|
const nextId = { value: 1 };
|
|
868
905
|
let terminated = false;
|
|
@@ -961,6 +998,9 @@ async function startWorkerCore(options: {
|
|
|
961
998
|
} as MainToWorkerMessage);
|
|
962
999
|
},
|
|
963
1000
|
);
|
|
1001
|
+
// A config callback is a consumer from the first round.
|
|
1002
|
+
if (config.onDiagnostics !== undefined)
|
|
1003
|
+
await invoke('diagnosticsSnapshot', []);
|
|
964
1004
|
return {
|
|
965
1005
|
clientId: initResult.clientId,
|
|
966
1006
|
invoke,
|
|
@@ -1012,6 +1052,9 @@ function buildInitConfig(
|
|
|
1012
1052
|
...(config.realtimePolicy !== undefined
|
|
1013
1053
|
? { realtimePolicy: config.realtimePolicy }
|
|
1014
1054
|
: {}),
|
|
1055
|
+
...(config.realtimeHeartbeatMs !== undefined
|
|
1056
|
+
? { realtimeHeartbeatMs: config.realtimeHeartbeatMs }
|
|
1057
|
+
: {}),
|
|
1015
1058
|
...(config.previousVersionContext !== undefined
|
|
1016
1059
|
? { previousVersionContext: config.previousVersionContext }
|
|
1017
1060
|
: {}),
|
|
@@ -1031,7 +1074,7 @@ function fireConfigCallbacks(
|
|
|
1031
1074
|
} else if (event.kind === 'upgrading') {
|
|
1032
1075
|
config.onUpgrading?.(event.upgrading);
|
|
1033
1076
|
} else if (event.kind === 'presence') {
|
|
1034
|
-
config.onPresence?.(event.scopeKey);
|
|
1077
|
+
config.onPresence?.(event.scopeKey, event.error);
|
|
1035
1078
|
} else if (event.kind === 'synced') {
|
|
1036
1079
|
config.onSynced?.({
|
|
1037
1080
|
...(event.summary !== undefined ? { summary: event.summary } : {}),
|
|
@@ -1057,7 +1100,9 @@ export async function createSyncClientHandle(
|
|
|
1057
1100
|
const lockName = resolvedConfig.lockName ?? 'syncular-leader';
|
|
1058
1101
|
const invalidation = new InvalidationEmitter();
|
|
1059
1102
|
const changes = new ChangeEmitter();
|
|
1060
|
-
const presence = new Set<
|
|
1103
|
+
const presence = new Set<
|
|
1104
|
+
(scopeKey: string, error?: PresenceErrorCode) => void
|
|
1105
|
+
>();
|
|
1061
1106
|
const diagnostics = new ClientDiagnosticsEmitter();
|
|
1062
1107
|
const roleListeners = new Set<(role: HandleRole) => void>();
|
|
1063
1108
|
if (resolvedConfig.onRoleChange !== undefined)
|
|
@@ -1213,8 +1258,7 @@ function resolveReplicaConfig(
|
|
|
1213
1258
|
): SyncClientHandleConfig {
|
|
1214
1259
|
if (config.replica?.mode !== 'isolated') return config;
|
|
1215
1260
|
if (config.database.mode !== 'persistent') {
|
|
1216
|
-
throw
|
|
1217
|
-
'sync.invalid_request',
|
|
1261
|
+
throw invalidRequest(
|
|
1218
1262
|
'isolated browser replicas require a named persistent database',
|
|
1219
1263
|
);
|
|
1220
1264
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { SiblingDatabase } from './database';
|
|
2
|
-
import { ClientSyncError } from './errors';
|
|
2
|
+
import { ClientSyncError, invalidRequest } from './errors';
|
|
3
3
|
import type { SyncTransport } from './transport';
|
|
4
4
|
import type {
|
|
5
5
|
WorkerLocalAuthority,
|
|
@@ -91,10 +91,7 @@ export const createWorkerLocalAuthority: WorkerLocalAuthorityFactory = (
|
|
|
91
91
|
segments: (request) => {
|
|
92
92
|
if (active()) return local.downloadSegment(request);
|
|
93
93
|
if (segments === undefined) {
|
|
94
|
-
throw
|
|
95
|
-
'sync.invalid_request',
|
|
96
|
-
'no segment endpoint configured',
|
|
97
|
-
);
|
|
94
|
+
throw invalidRequest('no segment endpoint configured');
|
|
98
95
|
}
|
|
99
96
|
return segments(request);
|
|
100
97
|
},
|
package/src/worker-protocol.ts
CHANGED
|
@@ -17,7 +17,7 @@ import type { SyncProgress } from './progress';
|
|
|
17
17
|
* so the UI thread never has to react to keep data flowing. Events are
|
|
18
18
|
* still forwarded to the handle for visibility.
|
|
19
19
|
*/
|
|
20
|
-
import type { WakeReason } from '@syncular/core';
|
|
20
|
+
import type { PresenceErrorCode, WakeReason } from '@syncular/core';
|
|
21
21
|
import type { BlobRef, CachedBlob } from './blob';
|
|
22
22
|
import type {
|
|
23
23
|
ConflictRecord,
|
|
@@ -28,7 +28,6 @@ import type {
|
|
|
28
28
|
QueryReadSpec,
|
|
29
29
|
QuerySnapshot,
|
|
30
30
|
SecurityLifecycle,
|
|
31
|
-
SubscribeInput,
|
|
32
31
|
SyncClientConfig,
|
|
33
32
|
SyncClientLimits,
|
|
34
33
|
SyncSummary,
|
|
@@ -53,7 +52,8 @@ import type {
|
|
|
53
52
|
PreviousVersionSnapshot,
|
|
54
53
|
} from './previous-version';
|
|
55
54
|
import type { ClientSchema } from './schema';
|
|
56
|
-
import type {
|
|
55
|
+
import type { UnitScopes } from '@syncular/core';
|
|
56
|
+
import type { UnitRecord } from './state';
|
|
57
57
|
import type { WindowBase } from './window';
|
|
58
58
|
|
|
59
59
|
// ---------------------------------------------------------------------------
|
|
@@ -147,6 +147,8 @@ export interface WorkerInitConfig {
|
|
|
147
147
|
* Absent ⇒ `optional` (a connected socket, otherwise `POST /sync`).
|
|
148
148
|
*/
|
|
149
149
|
readonly realtimePolicy?: RealtimePolicy;
|
|
150
|
+
/** SPEC §8.5 heartbeat interval for the worker-owned core; forwarded verbatim. */
|
|
151
|
+
readonly realtimeHeartbeatMs?: number;
|
|
150
152
|
/**
|
|
151
153
|
* RFC 0005 previous-version context, forwarded verbatim into the worker's
|
|
152
154
|
* `SyncClientConfig`. Absent ⇒ the feature stays off (default-off).
|
|
@@ -181,12 +183,12 @@ export interface WorkerApi extends Omit<
|
|
|
181
183
|
securityLifecycle(): SecurityLifecycle;
|
|
182
184
|
beginSecurityPreflight(): Promise<void>;
|
|
183
185
|
activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
|
|
184
|
-
subscribe(
|
|
185
|
-
subscribeMany(
|
|
186
|
+
subscribe(scopes: UnitScopes): string;
|
|
187
|
+
subscribeMany(units: readonly UnitScopes[]): string[];
|
|
186
188
|
unsubscribe(id: string): void;
|
|
187
|
-
/** §4.8
|
|
189
|
+
/** §4.8 windows: set the windowed-in values of a base. */
|
|
188
190
|
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
189
|
-
/** §4.8 completeness oracle
|
|
191
|
+
/** §4.8 completeness oracle: the windowed-in values of a base. */
|
|
190
192
|
windowState(base: WindowBase): WindowState;
|
|
191
193
|
mutate(mutations: readonly MutationInput[]): string;
|
|
192
194
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
|
@@ -222,8 +224,8 @@ export interface WorkerApi extends Omit<
|
|
|
222
224
|
querySnapshot(spec: QueryReadSpec): QuerySnapshot;
|
|
223
225
|
localRevision(): LocalRevision;
|
|
224
226
|
pendingCommits(): OutboxCommit[];
|
|
225
|
-
|
|
226
|
-
|
|
227
|
+
units(): UnitRecord[];
|
|
228
|
+
unit(id: string): UnitRecord | undefined;
|
|
227
229
|
connectRealtime(): Promise<void>;
|
|
228
230
|
disconnectRealtime(): void;
|
|
229
231
|
/** §8.6 presence: publish/clear a scope-keyed presence document. */
|
|
@@ -299,9 +301,11 @@ export type SyncWorkerEvent =
|
|
|
299
301
|
readonly upgrading: boolean;
|
|
300
302
|
}
|
|
301
303
|
| {
|
|
302
|
-
/** §8.6: presence on a scope key changed
|
|
304
|
+
/** §8.6: presence on a scope key changed, or the server refused this
|
|
305
|
+
* client's publish on it (`error`, §8.6.2). */
|
|
303
306
|
readonly kind: 'presence';
|
|
304
307
|
readonly scopeKey: string;
|
|
308
|
+
readonly error?: PresenceErrorCode | undefined;
|
|
305
309
|
}
|
|
306
310
|
| {
|
|
307
311
|
/** Exact revisioned core transaction; Sets and bigint clone directly. */
|