@syncular/client 0.86.0 → 0.90.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.
Files changed (45) hide show
  1. package/README.md +3 -1
  2. package/dist/blob.d.ts +0 -4
  3. package/dist/blob.js +7 -22
  4. package/dist/client.d.ts +12 -1
  5. package/dist/client.js +441 -422
  6. package/dist/diagnostics.d.ts +2 -4
  7. package/dist/diagnostics.js +3 -17
  8. package/dist/encryption.js +2 -21
  9. package/dist/errors.d.ts +2 -0
  10. package/dist/errors.js +4 -0
  11. package/dist/failed-overlay.js +2 -2
  12. package/dist/local-purge.d.ts +1 -0
  13. package/dist/local-purge.js +1 -1
  14. package/dist/local-rebootstrap-receipt.js +2 -2
  15. package/dist/local-rebootstrap.js +1 -1
  16. package/dist/native-bridge.d.ts +6 -2
  17. package/dist/native-bridge.js +24 -11
  18. package/dist/outcomes.d.ts +11 -0
  19. package/dist/outcomes.js +19 -16
  20. package/dist/previous-version.js +23 -35
  21. package/dist/schema.js +14 -13
  22. package/dist/state.d.ts +16 -4
  23. package/dist/state.js +83 -44
  24. package/dist/worker-core.js +7 -8
  25. package/dist/worker-host.d.ts +5 -2
  26. package/dist/worker-host.js +9 -0
  27. package/dist/worker-protocol.d.ts +2 -1
  28. package/package.json +3 -3
  29. package/src/blob.ts +7 -24
  30. package/src/client.ts +615 -501
  31. package/src/diagnostics.ts +3 -19
  32. package/src/encryption.ts +7 -25
  33. package/src/errors.ts +5 -0
  34. package/src/failed-overlay.ts +2 -6
  35. package/src/local-purge.ts +1 -1
  36. package/src/local-rebootstrap-receipt.ts +2 -5
  37. package/src/local-rebootstrap.ts +1 -2
  38. package/src/native-bridge.ts +35 -13
  39. package/src/outcomes.ts +34 -25
  40. package/src/previous-version.ts +31 -40
  41. package/src/schema.ts +13 -13
  42. package/src/state.ts +107 -64
  43. package/src/worker-core.ts +9 -16
  44. package/src/worker-host.ts +17 -1
  45. package/src/worker-protocol.ts +2 -0
package/src/state.ts CHANGED
@@ -9,8 +9,13 @@ export const UNITS_TABLE = '_syncular_units';
9
9
  * contract is keyed on. The replica cursor, the echo digest and the
10
10
  * registration digest the server holds live in meta.
11
11
  */
12
- import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
13
- import { ClientSyncError } from './errors';
12
+ import {
13
+ definedObject,
14
+ type FencedRecord,
15
+ type ScopeMap,
16
+ type UnitScopes,
17
+ } from '@syncular/core';
18
+ import { localStateCorrupt } from './errors';
14
19
  import type { CompiledClientSchema, CompiledClientTable } from './schema';
15
20
  import type { ClientDatabase } from './database';
16
21
  import type { LocalRevision } from './invalidation';
@@ -48,6 +53,13 @@ export interface UnitRecord {
48
53
  /** §5.6 applied-segment record: segment id → rows applied at the unit's
49
54
  * current cursor and token. */
50
55
  readonly applied?: Readonly<Record<string, number>> | undefined;
56
+ /** §7.4.3 restriction: the kept cursor and the tables to bootstrap. */
57
+ readonly restrict?: Restriction | undefined;
58
+ }
59
+
60
+ export interface Restriction {
61
+ readonly cursor: number;
62
+ readonly tables: readonly string[];
51
63
  }
52
64
 
53
65
  /** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
@@ -94,7 +106,8 @@ export function pairScopes(
94
106
  }
95
107
 
96
108
  /** §3.3 row ownership: the pair scopes of every owner of `table` but one.
97
- * A bootstrapping unit owns the tables its current bootstrap seeded. */
109
+ * A bootstrapping unit owns the tables its current bootstrap seeded, and a
110
+ * restricted one the tables outside its restriction. */
98
111
  export function unitOwners(
99
112
  units: readonly UnitRecord[],
100
113
  table: CompiledClientTable,
@@ -106,7 +119,8 @@ export function unitOwners(
106
119
  (owning(unit) ||
107
120
  (unit.status === 'active' &&
108
121
  unit.echo !== undefined &&
109
- unit.seeded.includes(table.name))) &&
122
+ (unit.seeded.includes(table.name) ||
123
+ unit.restrict?.tables.includes(table.name) === false))) &&
110
124
  covers(table, unit.scopes)
111
125
  ? pairScopes(unit.scopes, table.name, unit.echo)
112
126
  : undefined;
@@ -116,18 +130,16 @@ export function unitOwners(
116
130
 
117
131
  /** A unit row; every persisted field must have its stored type and shape,
118
132
  * otherwise the row is `sync.local_corrupt` (§7.5). */
133
+ export const unitStateCorrupt = () =>
134
+ localStateCorrupt('persisted unit state is invalid');
135
+
119
136
  function rowToRecord(row: Record<string, unknown>): UnitRecord {
120
- const corrupt = () =>
121
- new ClientSyncError(
122
- 'sync.local_corrupt',
123
- 'persisted unit state is invalid',
124
- );
125
137
  const json = (raw: unknown): unknown => {
126
- if (typeof raw !== 'string') throw corrupt();
138
+ if (typeof raw !== 'string') throw unitStateCorrupt();
127
139
  try {
128
140
  return JSON.parse(raw);
129
141
  } catch {
130
- throw corrupt();
142
+ throw unitStateCorrupt();
131
143
  }
132
144
  };
133
145
  const isMap = (value: unknown): value is Record<string, unknown> =>
@@ -135,13 +147,14 @@ function rowToRecord(row: Record<string, unknown>): UnitRecord {
135
147
  const isStrings = (value: unknown): value is string[] =>
136
148
  Array.isArray(value) && value.every((item) => typeof item === 'string');
137
149
  const optionalText = (value: unknown) => {
138
- if (value !== null && typeof value !== 'string') throw corrupt();
150
+ if (value !== null && typeof value !== 'string') throw unitStateCorrupt();
139
151
  return value ?? undefined;
140
152
  };
141
153
  const scopes = json(row.scopes);
142
154
  const seeded = json(row.seeded);
143
155
  const echo = row.echo === null ? undefined : json(row.echo);
144
156
  const applied = row.applied === null ? undefined : json(row.applied);
157
+ const restrict = row.restriction === null ? undefined : json(row.restriction);
145
158
  const { id, status, cursor } = row;
146
159
  if (
147
160
  typeof id !== 'string' ||
@@ -164,22 +177,33 @@ function rowToRecord(row: Record<string, unknown>): UnitRecord {
164
177
  )
165
178
  ))
166
179
  )
167
- throw corrupt();
168
- const record: { -readonly [K in keyof UnitRecord]: UnitRecord[K] } = {
180
+ throw unitStateCorrupt();
181
+ let restriction: UnitRecord['restrict'];
182
+ if (restrict !== undefined) {
183
+ if (
184
+ !isMap(restrict) ||
185
+ !Number.isInteger(restrict.cursor) ||
186
+ !isStrings(restrict.tables)
187
+ )
188
+ throw unitStateCorrupt();
189
+ restriction = {
190
+ cursor: restrict.cursor as number,
191
+ tables: restrict.tables,
192
+ };
193
+ }
194
+ return definedObject({
169
195
  id,
170
196
  scopes: scopes as UnitScopes,
171
197
  explicit: row.explicit === 1,
172
198
  status,
173
199
  seeded,
174
- };
175
- const reasonCode = optionalText(row.reason_code);
176
- if (reasonCode !== undefined) record.reasonCode = reasonCode;
177
- if (typeof cursor === 'number') record.cursor = cursor;
178
- const bootstrapState = optionalText(row.bootstrap_state);
179
- if (bootstrapState !== undefined) record.bootstrapState = bootstrapState;
180
- if (echo !== undefined) record.echo = echo as FencedRecord[];
181
- if (applied !== undefined) record.applied = applied as Record<string, number>;
182
- return record;
200
+ reasonCode: optionalText(row.reason_code),
201
+ cursor: typeof cursor === 'number' ? cursor : undefined,
202
+ bootstrapState: optionalText(row.bootstrap_state),
203
+ echo: echo as FencedRecord[] | undefined,
204
+ applied: applied as Record<string, number> | undefined,
205
+ restrict: restriction,
206
+ });
183
207
  }
184
208
 
185
209
  /** Every unit in registration order (§4.1). */
@@ -201,7 +225,7 @@ export function getUnit(
201
225
  * §5.6 applied-segment record ends when the cursor or the token changes. */
202
226
  export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
203
227
  db.exec(
204
- `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo,applied=iif((cursor,bootstrap_state)IS(excluded.cursor,excluded.bootstrap_state),applied,NULL)`,
228
+ `INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo,restriction)VALUES(?,?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo,restriction=excluded.restriction,applied=iif((cursor,bootstrap_state)IS(excluded.cursor,excluded.bootstrap_state),applied,NULL)`,
205
229
  [
206
230
  record.id,
207
231
  JSON.stringify(record.scopes),
@@ -212,6 +236,7 @@ export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
212
236
  record.bootstrapState ?? null,
213
237
  JSON.stringify(record.seeded),
214
238
  record.echo === undefined ? null : JSON.stringify(record.echo),
239
+ record.restrict === undefined ? null : JSON.stringify(record.restrict),
215
240
  ],
216
241
  );
217
242
  }
@@ -238,17 +263,24 @@ export function deleteUnit(db: ClientDatabase, id: string): void {
238
263
  * §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
239
264
  * registrations (the app's declared intent) and discard the synced state of
240
265
  * every unit outside `keep`, so the next round sends the list and
241
- * fresh-bootstraps those units. The replica cursor survives only while a
266
+ * fresh-bootstraps those units. A bump (`restricts` given) keeps every echo
267
+ * and restricts the units it names. The replica cursor survives only while a
242
268
  * kept unit is live. Caller owns the transaction.
243
269
  */
244
270
  export function resetUnits(
245
271
  db: ClientDatabase,
246
272
  keep: readonly string[] = [],
273
+ restricts?: ReadonlyMap<string, Restriction>,
247
274
  ): void {
248
275
  db.exec(
249
- `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL,applied=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`,
276
+ `UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',${restricts ? '' : 'echo=NULL,'}applied=NULL,restriction=NULL WHERE id NOT IN(${keep.map(() => '?').join(',')})`,
250
277
  [...keep],
251
278
  );
279
+ for (const [id, restrict] of restricts ?? [])
280
+ db.exec(`UPDATE ${UNITS_TABLE} SET restriction=? WHERE id=?`, [
281
+ JSON.stringify(restrict),
282
+ id,
283
+ ]);
252
284
  db.exec(
253
285
  `DELETE FROM ${META_TABLE} WHERE key IN(?,?) OR key=? AND NOT EXISTS(SELECT 1 FROM ${UNITS_TABLE} WHERE cursor IS NULL)`,
254
286
  [ECHO_DIGEST_KEY, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY],
@@ -299,7 +331,11 @@ export function pruneUnknownUnits(
299
331
  db: ClientDatabase,
300
332
  schema: CompiledClientSchema,
301
333
  bump = false,
302
- ): { readonly tables: ReadonlySet<string>; readonly units: string[] } {
334
+ ): {
335
+ readonly tables: ReadonlySet<string>;
336
+ readonly units: string[];
337
+ readonly restricts: Map<string, Restriction>;
338
+ } {
303
339
  const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
304
340
  const previous =
305
341
  stored === undefined
@@ -318,10 +354,7 @@ export function pruneUnknownUnits(
318
354
  Array.isArray(generations) ||
319
355
  Object.values(generations).some((value) => typeof value !== 'string')
320
356
  )
321
- throw new ClientSyncError(
322
- 'sync.local_corrupt',
323
- 'invalid persisted table generations',
324
- );
357
+ throw localStateCorrupt('invalid persisted table generations');
325
358
  const kept = new Set(
326
359
  [...schema.tables.values()]
327
360
  .filter(
@@ -388,22 +421,41 @@ export function pruneUnknownUnits(
388
421
  db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
389
422
  deleteUnit(db, id);
390
423
  }
391
- return {
392
- tables: kept,
393
- units: loadUnits(db)
394
- .filter(
395
- ({ scopes }) =>
396
- Object.entries(previous ?? {}).every(
397
- ([name, old]) =>
398
- kept.has(name) ||
399
- !Object.keys(scopes).every((v) => old[v] !== undefined),
400
- ) &&
401
- [...schema.tables.values()].every(
402
- (table) => kept.has(table.name) || !covers(table, scopes),
403
- ),
404
- )
405
- .map((unit) => unit.id),
406
- };
424
+ const units: string[] = [];
425
+ const restricts = new Map<string, Restriction>();
426
+ for (const unit of loadUnits(db)) {
427
+ const covered = [...schema.tables.values()]
428
+ .filter((table) => covers(table, unit.scopes))
429
+ .map((table) => table.name);
430
+ if (
431
+ Object.entries(previous ?? {}).every(
432
+ ([name, old]) =>
433
+ kept.has(name) ||
434
+ !Object.keys(unit.scopes).every((v) => old[v] !== undefined),
435
+ ) &&
436
+ covered.every((name) => kept.has(name))
437
+ ) {
438
+ units.push(unit.id);
439
+ continue;
440
+ }
441
+ // §7.4.3 restriction: a live, post-bootstrap or restricted unit keeps its
442
+ // rows of kept tables through its kept cursor and bootstraps the rest.
443
+ const tables = covered
444
+ .filter((name) => !kept.has(name) || unit.restrict?.tables.includes(name))
445
+ .sort();
446
+ const cursor =
447
+ unit.restrict?.cursor ??
448
+ (bootstrapping(unit) ? -1 : (unit.cursor ?? replicaCursor(db)));
449
+ if (
450
+ bump &&
451
+ unit.status === 'active' &&
452
+ cursor >= 0 &&
453
+ tables.length > 0 &&
454
+ tables.length < covered.length
455
+ )
456
+ restricts.set(unit.id, { cursor, tables });
457
+ }
458
+ return { tables: kept, units, restricts };
407
459
  }
408
460
 
409
461
  export function getMeta(db: ClientDatabase, key: string): string | undefined {
@@ -422,20 +474,14 @@ export function setMeta(db: ClientDatabase, key: string, value: string): void {
422
474
  export function getLocalRevision(db: ClientDatabase): LocalRevision {
423
475
  const raw = getMeta(db, LOCAL_REVISION_KEY);
424
476
  if (raw === undefined) return 0n;
425
- if (typeof raw !== 'string' || !/^(0|[1-9][0-9]*)$/.test(raw)) {
426
- throw new ClientSyncError(
427
- 'sync.local_corrupt',
428
- 'persisted local revision is invalid',
429
- );
430
- }
431
- const revision = BigInt(raw);
432
- if (revision > MAX_U64) {
433
- throw new ClientSyncError(
434
- 'sync.local_corrupt',
435
- 'persisted local revision is invalid',
436
- );
477
+ if (
478
+ typeof raw !== 'string' ||
479
+ !/^(0|[1-9][0-9]*)$/.test(raw) ||
480
+ BigInt(raw) > MAX_U64
481
+ ) {
482
+ throw localStateCorrupt('persisted local revision is invalid');
437
483
  }
438
- return revision;
484
+ return BigInt(raw);
439
485
  }
440
486
 
441
487
  /**
@@ -445,10 +491,7 @@ export function getLocalRevision(db: ClientDatabase): LocalRevision {
445
491
  export function bumpLocalRevision(db: ClientDatabase): LocalRevision {
446
492
  const current = getLocalRevision(db);
447
493
  if (current === MAX_U64) {
448
- throw new ClientSyncError(
449
- 'sync.local_corrupt',
450
- 'local revision exhausted u64',
451
- );
494
+ throw localStateCorrupt('local revision exhausted u64');
452
495
  }
453
496
  const next = current + 1n;
454
497
  setMeta(db, LOCAL_REVISION_KEY, next.toString());
@@ -549,6 +549,8 @@ export function startSyncWorkerCore(
549
549
  'commitOutcome',
550
550
  'commitOutcomes',
551
551
  'resolveCommitOutcome',
552
+ 'commitDelivery',
553
+ 'replaceCommitOutcome',
552
554
  'pendingCommits',
553
555
  'units',
554
556
  'unit',
@@ -575,11 +577,11 @@ export function startSyncWorkerCore(
575
577
  await requireClient().beginSecurityPreflight();
576
578
  },
577
579
  activateSecurity: async (options = {}) => {
578
- await requireClient().activateSecurity({
579
- ...(options.encryption !== undefined
580
- ? { encryption: encryptionConfigFromKeyring(options.encryption) }
581
- : {}),
582
- });
580
+ await requireClient().activateSecurity(
581
+ options.encryption === undefined
582
+ ? {}
583
+ : { encryption: encryptionConfigFromKeyring(options.encryption) },
584
+ );
583
585
  },
584
586
  setWindow: async (base, units) => {
585
587
  await requireClient().setWindowCommand(base, units);
@@ -590,13 +592,7 @@ export function startSyncWorkerCore(
590
592
  patch: (table, rowId, partial, options) => {
591
593
  // Same §8.4 rule as `mutate`: a local write must push without the app
592
594
  // orchestrating sync, so consume the core's immediate intent.
593
- const result = requireClient().patchCommand(
594
- table,
595
- rowId,
596
- partial,
597
- options,
598
- );
599
- return result.value;
595
+ return requireClient().patchCommand(table, rowId, partial, options).value;
600
596
  },
601
597
  sync: () => {
602
598
  const running = requireClient();
@@ -684,10 +680,7 @@ export function startSyncWorkerCore(
684
680
  void (async () => {
685
681
  try {
686
682
  const value = await fn();
687
- post(
688
- { t: 'result', id, value },
689
- transfer !== undefined ? transfer(value) : undefined,
690
- );
683
+ post({ t: 'result', id, value }, transfer?.(value));
691
684
  } catch (error) {
692
685
  post({ t: 'error', id, error: toErrorShape(error) });
693
686
  }
@@ -3,7 +3,7 @@ import {
3
3
  type SyncProgress,
4
4
  type SyncProgressListener,
5
5
  } from './progress';
6
- import type { PromiseMethods } from './client';
6
+ import type { CommitDelivery, PromiseMethods } from './client';
7
7
  /**
8
8
  * Main-thread side of the worker mode and the
9
9
  * multi-tab topology.
@@ -37,6 +37,7 @@ import type {
37
37
  ConflictRecord,
38
38
  CurrentBaseProof,
39
39
  MutationInput,
40
+ ReplaceCommitOutcomeInput,
40
41
  PresencePeer,
41
42
  QueryReadSpec,
42
43
  QuerySnapshot,
@@ -828,6 +829,21 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
828
829
  return this.#call('resolveCommitOutcome', [input]);
829
830
  }
830
831
 
832
+ commitDelivery(id: string): Promise<CommitDelivery> {
833
+ return this.#call('commitDelivery', [id]);
834
+ }
835
+
836
+ /** §7.2.2: record a decision as a replacement held for a proven base. */
837
+ replaceCommitOutcome({
838
+ clientCommitId,
839
+ sequence,
840
+ replacement,
841
+ }: ReplaceCommitOutcomeInput): Promise<string> {
842
+ return this.#call('replaceCommitOutcome', [
843
+ { clientCommitId, sequence, replacement },
844
+ ]);
845
+ }
846
+
831
847
  /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
832
848
  pendingCommits(): Promise<OutboxCommit[]> {
833
849
  return this.#call('pendingCommits', []);
@@ -23,6 +23,7 @@ import type {
23
23
  ConflictRecord,
24
24
  CurrentBaseProof,
25
25
  ClientSnapshotMethods,
26
+ ReplaceCommitOutcomeInput,
26
27
  MutationInput,
27
28
  PresencePeer,
28
29
  QueryReadSpec,
@@ -223,6 +224,7 @@ export interface WorkerApi extends Omit<
223
224
  outcome: Pick<CommitOutcome, 'clientCommitId' | 'sequence'>,
224
225
  maxRounds?: number,
225
226
  ): Promise<CurrentBaseProof>;
227
+ replaceCommitOutcome(input: ReplaceCommitOutcomeInput): string;
226
228
  resetClientId(): string;
227
229
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
228
230
  authoritySnapshot(): import('./authority').AuthoritySnapshot;