@syncular/client 0.48.0 → 0.49.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.
@@ -167,7 +167,10 @@ type PreviousVersionCaptureOutcome =
167
167
  interface PreviousVersionAuditEntry {
168
168
  readonly commitId: string;
169
169
  readonly table: string;
170
- readonly reason: 'unknown-table' | 'unknown-column';
170
+ readonly reason:
171
+ | 'unknown-table'
172
+ | 'unknown-column'
173
+ | 'missing-required-column';
171
174
  /** The offending column; present for every reason except `unknown-table`. */
172
175
  readonly column?: string;
173
176
  }
@@ -761,7 +764,9 @@ interface PendingCommitLike {
761
764
  readonly clientCommitId: string;
762
765
  readonly operations: readonly {
763
766
  readonly table: string;
767
+ readonly op: 'upsert' | 'delete';
764
768
  readonly values?: Readonly<Record<string, JsonRowValue>>;
769
+ readonly insert?: true;
765
770
  }[];
766
771
  }
767
772
 
@@ -807,6 +812,9 @@ function firstIncompatibility(
807
812
  commit: PendingCommitLike,
808
813
  ): PreviousVersionAuditEntry | undefined {
809
814
  for (const operation of commit.operations) {
815
+ // §7.4.4: a value-free delete stays encodable and takes ordinary server
816
+ // validation, even against a removed table.
817
+ if (operation.op === 'delete') continue;
810
818
  const table = schema.tables.get(operation.table);
811
819
  if (table === undefined) {
812
820
  return {
@@ -815,8 +823,7 @@ function firstIncompatibility(
815
823
  reason: 'unknown-table',
816
824
  };
817
825
  }
818
- if (operation.values === undefined) continue;
819
- for (const key of Object.keys(operation.values)) {
826
+ for (const key of Object.keys(operation.values ?? {})) {
820
827
  if (!table.columnIndex.has(key)) {
821
828
  return {
822
829
  commitId: commit.clientCommitId,
@@ -826,6 +833,22 @@ function firstIncompatibility(
826
833
  };
827
834
  }
828
835
  }
836
+ // §7.1: an insert-intent operation presents every current column, so a
837
+ // non-nullable column it lacks leaves the commit unencodable.
838
+ if (operation.insert === true) {
839
+ const missing = table.columns.find(
840
+ (column) =>
841
+ !column.nullable && operation.values?.[column.name] === undefined,
842
+ );
843
+ if (missing !== undefined) {
844
+ return {
845
+ commitId: commit.clientCommitId,
846
+ table: operation.table,
847
+ reason: 'missing-required-column',
848
+ column: missing.name,
849
+ };
850
+ }
851
+ }
829
852
  }
830
853
  return undefined;
831
854
  }
@@ -859,7 +882,9 @@ export function storedPreviousVersionAudit(
859
882
  if (
860
883
  typeof item.commitId !== 'string' ||
861
884
  typeof item.table !== 'string' ||
862
- (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
885
+ (item.reason !== 'unknown-table' &&
886
+ item.reason !== 'unknown-column' &&
887
+ item.reason !== 'missing-required-column') ||
863
888
  (item.column !== undefined && typeof item.column !== 'string')
864
889
  ) {
865
890
  return undefined;
@@ -1009,7 +1034,9 @@ export function decodePreviousVersionAuditResult(
1009
1034
  ) ||
1010
1035
  typeof item.commitId !== 'string' ||
1011
1036
  typeof item.table !== 'string' ||
1012
- (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
1037
+ (item.reason !== 'unknown-table' &&
1038
+ item.reason !== 'unknown-column' &&
1039
+ item.reason !== 'missing-required-column') ||
1013
1040
  (item.column !== undefined && typeof item.column !== 'string')
1014
1041
  ) {
1015
1042
  return invalidHostResponse(method);
@@ -15,7 +15,7 @@
15
15
  */
16
16
  import type { defineAuthorityReads } from './authority';
17
17
  import { SyncClient } from './client';
18
- import type { ClientDatabase } from './database';
18
+ import type { ClientDatabase, SiblingDatabase } from './database';
19
19
  import {
20
20
  type ClientDiagnosticsSnapshot,
21
21
  withClientDiagnosticsHost,
@@ -38,8 +38,11 @@ import type {
38
38
  SegmentDownloader,
39
39
  SyncTransport,
40
40
  } from './transport';
41
+ import type { ClientSchema } from './schema';
41
42
  import { openPersistentWasmDatabase } from './wasm-database';
42
43
  import {
44
+ LOCAL_AUTHORITY_UNCONFIGURED_CODE,
45
+ type LocalAuthorityState,
43
46
  type MainToWorkerMessage,
44
47
  WORKER_FAILED_CODE,
45
48
  type WorkerApi,
@@ -73,8 +76,30 @@ export interface SyncWorkerOverrides {
73
76
  clientId: string,
74
77
  headers: () => Readonly<Record<string, string>>,
75
78
  ) => RealtimeConnector | undefined;
79
+ /**
80
+ * SPEC §12 local authority, required by init's `localAuthority: true`:
81
+ * `(database, schema) => openLocalAuthority({ database:
82
+ * clientSqliteDatabase(database), schema })` from `@syncular/server`. Only
83
+ * a worker entry that passes it bundles the server code.
84
+ */
85
+ readonly openLocalAuthority?: (
86
+ database: ClientDatabase,
87
+ schema: ClientSchema,
88
+ ) => Promise<WorkerLocalAuthority>;
89
+ }
90
+
91
+ /** The `LocalAuthority` surface of `@syncular/server` the worker drives (§12). */
92
+ export interface WorkerLocalAuthority {
93
+ readonly state: LocalAuthorityState;
94
+ readonly sync: SyncTransport;
95
+ readonly downloadSegment: SegmentDownloader;
96
+ readonly attach: (transport: SyncTransport) => Promise<void>;
97
+ readonly abandonAttach: (transport?: SyncTransport) => Promise<void>;
76
98
  }
77
99
 
100
+ /** §12: the worker's sibling file for the local authority. */
101
+ const LOCAL_AUTHORITY_SIBLING = 'local-authority';
102
+
78
103
  /** Minimal structural view of the dedicated-worker global scope. */
79
104
  interface WorkerScope {
80
105
  postMessage(message: unknown, transfer?: Transferable[]): void;
@@ -142,6 +167,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
142
167
 
143
168
  let client: SyncClient | undefined;
144
169
  let database: ClientDatabase | undefined;
170
+ let authority: WorkerLocalAuthority | undefined;
171
+ let authoritySibling: SiblingDatabase | undefined;
172
+ let remoteTransport: SyncTransport | undefined;
145
173
  let offline = false;
146
174
  let headers: Readonly<Record<string, string>> = {};
147
175
  let closed = false;
@@ -237,6 +265,51 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
237
265
  queueMicrotask(runAutoSync);
238
266
  }
239
267
 
268
+ /**
269
+ * §12.3: attach or abandon with the client's rounds held, so no round
270
+ * reaches the authority while it uploads or rolls back.
271
+ */
272
+ async function driveLocalAuthority(
273
+ run: (local: WorkerLocalAuthority, remote: SyncTransport) => Promise<void>,
274
+ ): Promise<void> {
275
+ const running = requireClient();
276
+ const local = authority;
277
+ const remote = remoteTransport;
278
+ if (local === undefined || remote === undefined) {
279
+ throw new ClientSyncError(
280
+ LOCAL_AUTHORITY_UNCONFIGURED_CODE,
281
+ 'init did not enable the local authority',
282
+ );
283
+ }
284
+ running.setTransportEnabled(false);
285
+ try {
286
+ await serializedSync(() => run(local, remote));
287
+ } catch (error) {
288
+ // `sync.attach_rejected` keeps its code and details across the RPC.
289
+ if (
290
+ error instanceof Error &&
291
+ !(error instanceof ClientSyncError) &&
292
+ 'code' in error &&
293
+ typeof error.code === 'string'
294
+ ) {
295
+ throw new ClientSyncError(
296
+ error.code,
297
+ error.message,
298
+ false,
299
+ 'details' in error &&
300
+ typeof error.details === 'object' &&
301
+ error.details !== null
302
+ ? { ...error.details }
303
+ : undefined,
304
+ );
305
+ }
306
+ throw error;
307
+ } finally {
308
+ running.setTransportEnabled(!offline);
309
+ }
310
+ consumeSyncIntent({ kind: 'interactive' });
311
+ }
312
+
240
313
  function requireClient(): SyncClient {
241
314
  if (client === undefined) {
242
315
  throw new ClientSyncError(
@@ -290,16 +363,55 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
290
363
  }
291
364
  }
292
365
  }
293
- const transport =
366
+ const remote =
294
367
  overrides.createTransport !== undefined
295
368
  ? overrides.createTransport(config)
296
369
  : httpSyncTransport(config.endpoints.syncUrl, http);
297
- const segments =
370
+ remoteTransport = remote;
371
+ const remoteSegments =
298
372
  overrides.createSegments !== undefined
299
373
  ? overrides.createSegments(config)
300
374
  : config.endpoints.segmentsUrl !== undefined
301
375
  ? httpSegmentDownloader(config.endpoints.segmentsUrl, http)
302
376
  : undefined;
377
+ if (config.localAuthority === true) {
378
+ if (overrides.openLocalAuthority === undefined) {
379
+ throw new ClientSyncError(
380
+ LOCAL_AUTHORITY_UNCONFIGURED_CODE,
381
+ 'localAuthority requires startSyncWorker({ openLocalAuthority })',
382
+ );
383
+ }
384
+ authoritySibling = database.openSibling?.(LOCAL_AUTHORITY_SIBLING);
385
+ if (authoritySibling === undefined) {
386
+ throw new ClientSyncError(
387
+ LOCAL_AUTHORITY_UNCONFIGURED_CODE,
388
+ 'localAuthority requires a database with sibling files',
389
+ );
390
+ }
391
+ authority = await overrides.openLocalAuthority(
392
+ authoritySibling.database,
393
+ config.schema,
394
+ );
395
+ }
396
+ // §12.4: rounds reach the local authority until attach completes, then
397
+ // the remote server; the replica rebinds through the §2.1 epoch reset.
398
+ const localActive = () =>
399
+ authority !== undefined && authority.state !== 'attached';
400
+ const transport: SyncTransport = (request) =>
401
+ localActive() ? authority!.sync(request) : remote(request);
402
+ const segments: SegmentDownloader | undefined =
403
+ authority === undefined
404
+ ? remoteSegments
405
+ : (request) => {
406
+ if (localActive()) return authority!.downloadSegment(request);
407
+ if (remoteSegments === undefined) {
408
+ throw new ClientSyncError(
409
+ 'sync.invalid_request',
410
+ 'no segment endpoint configured',
411
+ );
412
+ }
413
+ return remoteSegments(request);
414
+ };
303
415
  // §5.9 blob transport: only when a blobs URL is configured.
304
416
  const blobs =
305
417
  config.endpoints.blobsUrl !== undefined
@@ -319,7 +431,8 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
319
431
  ...(segments !== undefined ? { segments } : {}),
320
432
  ...(blobs !== undefined ? { blobs } : {}),
321
433
  realtime: (handlers) => {
322
- if (realtimeConnector === undefined) {
434
+ // §12.2: a local authority has no realtime channel.
435
+ if (realtimeConnector === undefined || localActive()) {
323
436
  throw new ClientSyncError(
324
437
  'sync.invalid_request',
325
438
  'no realtime connector configured',
@@ -529,10 +642,16 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
529
642
  });
530
643
  }
531
644
  },
645
+ localAuthorityState: () => authority?.state,
646
+ attachLocalAuthority: () =>
647
+ driveLocalAuthority((local, remote) => local.attach(remote)),
648
+ abandonLocalAuthorityAttach: () =>
649
+ driveLocalAuthority((local, remote) => local.abandonAttach(remote)),
532
650
  close: async () => {
533
651
  closed = true;
534
652
  if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
535
653
  await client?.close();
654
+ authoritySibling?.close();
536
655
  database?.close();
537
656
  client = undefined;
538
657
  database = undefined;