@syncular/client 0.47.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.
@@ -103,7 +103,7 @@ type PreviousVersionCaptureOutcome = {
103
103
  interface PreviousVersionAuditEntry {
104
104
  readonly commitId: string;
105
105
  readonly table: string;
106
- readonly reason: 'unknown-table' | 'unknown-column';
106
+ readonly reason: 'unknown-table' | 'unknown-column' | 'missing-required-column';
107
107
  /** The offending column; present for every reason except `unknown-table`. */
108
108
  readonly column?: string;
109
109
  }
@@ -177,7 +177,9 @@ interface PendingCommitLike {
177
177
  readonly clientCommitId: string;
178
178
  readonly operations: readonly {
179
179
  readonly table: string;
180
+ readonly op: 'upsert' | 'delete';
180
181
  readonly values?: Readonly<Record<string, JsonRowValue>>;
182
+ readonly insert?: true;
181
183
  }[];
182
184
  }
183
185
  /**
@@ -499,6 +499,10 @@ export function buildPreviousVersionAudit(schema, pending, fromVersion, toVersio
499
499
  }
500
500
  function firstIncompatibility(schema, commit) {
501
501
  for (const operation of commit.operations) {
502
+ // §7.4.4: a value-free delete stays encodable and takes ordinary server
503
+ // validation, even against a removed table.
504
+ if (operation.op === 'delete')
505
+ continue;
502
506
  const table = schema.tables.get(operation.table);
503
507
  if (table === undefined) {
504
508
  return {
@@ -507,9 +511,7 @@ function firstIncompatibility(schema, commit) {
507
511
  reason: 'unknown-table',
508
512
  };
509
513
  }
510
- if (operation.values === undefined)
511
- continue;
512
- for (const key of Object.keys(operation.values)) {
514
+ for (const key of Object.keys(operation.values ?? {})) {
513
515
  if (!table.columnIndex.has(key)) {
514
516
  return {
515
517
  commitId: commit.clientCommitId,
@@ -519,6 +521,19 @@ function firstIncompatibility(schema, commit) {
519
521
  };
520
522
  }
521
523
  }
524
+ // §7.1: an insert-intent operation presents every current column, so a
525
+ // non-nullable column it lacks leaves the commit unencodable.
526
+ if (operation.insert === true) {
527
+ const missing = table.columns.find((column) => !column.nullable && operation.values?.[column.name] === undefined);
528
+ if (missing !== undefined) {
529
+ return {
530
+ commitId: commit.clientCommitId,
531
+ table: operation.table,
532
+ reason: 'missing-required-column',
533
+ column: missing.name,
534
+ };
535
+ }
536
+ }
522
537
  }
523
538
  return undefined;
524
539
  }
@@ -548,7 +563,9 @@ export function storedPreviousVersionAudit(db) {
548
563
  const item = entry;
549
564
  if (typeof item.commitId !== 'string' ||
550
565
  typeof item.table !== 'string' ||
551
- (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
566
+ (item.reason !== 'unknown-table' &&
567
+ item.reason !== 'unknown-column' &&
568
+ item.reason !== 'missing-required-column') ||
552
569
  (item.column !== undefined && typeof item.column !== 'string')) {
553
570
  return undefined;
554
571
  }
@@ -678,7 +695,9 @@ export function decodePreviousVersionAuditResult(value) {
678
695
  if (!Object.keys(item).every((key) => AUDIT_ENTRY_KEYS.includes(key)) ||
679
696
  typeof item.commitId !== 'string' ||
680
697
  typeof item.table !== 'string' ||
681
- (item.reason !== 'unknown-table' && item.reason !== 'unknown-column') ||
698
+ (item.reason !== 'unknown-table' &&
699
+ item.reason !== 'unknown-column' &&
700
+ item.reason !== 'missing-required-column') ||
682
701
  (item.column !== undefined && typeof item.column !== 'string')) {
683
702
  return invalidHostResponse(method);
684
703
  }
@@ -16,7 +16,8 @@
16
16
  import type { defineAuthorityReads } from './authority.js';
17
17
  import type { ClientDatabase } from './database.js';
18
18
  import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
19
- import { type WorkerInitConfig } from './worker-protocol.js';
19
+ import type { ClientSchema } from './schema.js';
20
+ import { type LocalAuthorityState, type WorkerInitConfig } from './worker-protocol.js';
20
21
  export interface SyncWorkerOverrides {
21
22
  /** Explicit authority reader factory. Required when init declares authorityReads. */
22
23
  readonly createAuthorityReads?: typeof defineAuthorityReads;
@@ -31,6 +32,21 @@ export interface SyncWorkerOverrides {
31
32
  * connection attempt. `headers` reads the current host auth set.
32
33
  */
33
34
  readonly createRealtime?: (config: WorkerInitConfig, clientId: string, headers: () => Readonly<Record<string, string>>) => RealtimeConnector | undefined;
35
+ /**
36
+ * SPEC §12 local authority, required by init's `localAuthority: true`:
37
+ * `(database, schema) => openLocalAuthority({ database:
38
+ * clientSqliteDatabase(database), schema })` from `@syncular/server`. Only
39
+ * a worker entry that passes it bundles the server code.
40
+ */
41
+ readonly openLocalAuthority?: (database: ClientDatabase, schema: ClientSchema) => Promise<WorkerLocalAuthority>;
42
+ }
43
+ /** The `LocalAuthority` surface of `@syncular/server` the worker drives (§12). */
44
+ export interface WorkerLocalAuthority {
45
+ readonly state: LocalAuthorityState;
46
+ readonly sync: SyncTransport;
47
+ readonly downloadSegment: SegmentDownloader;
48
+ readonly attach: (transport: SyncTransport) => Promise<void>;
49
+ readonly abandonAttach: (transport?: SyncTransport) => Promise<void>;
34
50
  }
35
51
  /**
36
52
  * Register the RPC server on the current worker scope. Call this once
@@ -4,7 +4,9 @@ import { encryptionConfigFromKeyring } from './encryption.js';
4
4
  import { classifySqliteFailure, ClientSyncError, STORAGE_BUSY_CODE, } from './errors.js';
5
5
  import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
6
6
  import { openPersistentWasmDatabase } from './wasm-database.js';
7
- import { WORKER_FAILED_CODE, } from './worker-protocol.js';
7
+ import { LOCAL_AUTHORITY_UNCONFIGURED_CODE, WORKER_FAILED_CODE, } from './worker-protocol.js';
8
+ /** §12: the worker's sibling file for the local authority. */
9
+ const LOCAL_AUTHORITY_SIBLING = 'local-authority';
8
10
  function toErrorShape(caught) {
9
11
  const error = classifySqliteFailure(caught).error;
10
12
  if (error instanceof ClientSyncError) {
@@ -60,6 +62,9 @@ export function startSyncWorker(overrides = {}) {
60
62
  };
61
63
  let client;
62
64
  let database;
65
+ let authority;
66
+ let authoritySibling;
67
+ let remoteTransport;
63
68
  let offline = false;
64
69
  let headers = {};
65
70
  let closed = false;
@@ -145,6 +150,40 @@ export function startSyncWorker(overrides = {}) {
145
150
  autoSyncScheduled = true;
146
151
  queueMicrotask(runAutoSync);
147
152
  }
153
+ /**
154
+ * §12.3: attach or abandon with the client's rounds held, so no round
155
+ * reaches the authority while it uploads or rolls back.
156
+ */
157
+ async function driveLocalAuthority(run) {
158
+ const running = requireClient();
159
+ const local = authority;
160
+ const remote = remoteTransport;
161
+ if (local === undefined || remote === undefined) {
162
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'init did not enable the local authority');
163
+ }
164
+ running.setTransportEnabled(false);
165
+ try {
166
+ await serializedSync(() => run(local, remote));
167
+ }
168
+ catch (error) {
169
+ // `sync.attach_rejected` keeps its code and details across the RPC.
170
+ if (error instanceof Error &&
171
+ !(error instanceof ClientSyncError) &&
172
+ 'code' in error &&
173
+ typeof error.code === 'string') {
174
+ throw new ClientSyncError(error.code, error.message, false, 'details' in error &&
175
+ typeof error.details === 'object' &&
176
+ error.details !== null
177
+ ? { ...error.details }
178
+ : undefined);
179
+ }
180
+ throw error;
181
+ }
182
+ finally {
183
+ running.setTransportEnabled(!offline);
184
+ }
185
+ consumeSyncIntent({ kind: 'interactive' });
186
+ }
148
187
  function requireClient() {
149
188
  if (client === undefined) {
150
189
  throw new ClientSyncError(WORKER_FAILED_CODE, 'the worker received a call before init completed');
@@ -187,14 +226,39 @@ export function startSyncWorker(overrides = {}) {
187
226
  }
188
227
  }
189
228
  }
190
- const transport = overrides.createTransport !== undefined
229
+ const remote = overrides.createTransport !== undefined
191
230
  ? overrides.createTransport(config)
192
231
  : httpSyncTransport(config.endpoints.syncUrl, http);
193
- const segments = overrides.createSegments !== undefined
232
+ remoteTransport = remote;
233
+ const remoteSegments = overrides.createSegments !== undefined
194
234
  ? overrides.createSegments(config)
195
235
  : config.endpoints.segmentsUrl !== undefined
196
236
  ? httpSegmentDownloader(config.endpoints.segmentsUrl, http)
197
237
  : undefined;
238
+ if (config.localAuthority === true) {
239
+ if (overrides.openLocalAuthority === undefined) {
240
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires startSyncWorker({ openLocalAuthority })');
241
+ }
242
+ authoritySibling = database.openSibling?.(LOCAL_AUTHORITY_SIBLING);
243
+ if (authoritySibling === undefined) {
244
+ throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires a database with sibling files');
245
+ }
246
+ authority = await overrides.openLocalAuthority(authoritySibling.database, config.schema);
247
+ }
248
+ // §12.4: rounds reach the local authority until attach completes, then
249
+ // the remote server; the replica rebinds through the §2.1 epoch reset.
250
+ const localActive = () => authority !== undefined && authority.state !== 'attached';
251
+ const transport = (request) => localActive() ? authority.sync(request) : remote(request);
252
+ const segments = authority === undefined
253
+ ? remoteSegments
254
+ : (request) => {
255
+ if (localActive())
256
+ return authority.downloadSegment(request);
257
+ if (remoteSegments === undefined) {
258
+ throw new ClientSyncError('sync.invalid_request', 'no segment endpoint configured');
259
+ }
260
+ return remoteSegments(request);
261
+ };
198
262
  // §5.9 blob transport: only when a blobs URL is configured.
199
263
  const blobs = config.endpoints.blobsUrl !== undefined
200
264
  ? httpBlobTransport(config.endpoints.blobsUrl, http)
@@ -212,7 +276,8 @@ export function startSyncWorker(overrides = {}) {
212
276
  ...(segments !== undefined ? { segments } : {}),
213
277
  ...(blobs !== undefined ? { blobs } : {}),
214
278
  realtime: (handlers) => {
215
- if (realtimeConnector === undefined) {
279
+ // §12.2: a local authority has no realtime channel.
280
+ if (realtimeConnector === undefined || localActive()) {
216
281
  throw new ClientSyncError('sync.invalid_request', 'no realtime connector configured');
217
282
  }
218
283
  return realtimeConnector(handlers);
@@ -410,11 +475,15 @@ export function startSyncWorker(overrides = {}) {
410
475
  });
411
476
  }
412
477
  },
478
+ localAuthorityState: () => authority?.state,
479
+ attachLocalAuthority: () => driveLocalAuthority((local, remote) => local.attach(remote)),
480
+ abandonLocalAuthorityAttach: () => driveLocalAuthority((local, remote) => local.abandonAttach(remote)),
413
481
  close: async () => {
414
482
  closed = true;
415
483
  if (backgroundTimer !== undefined)
416
484
  clearTimeout(backgroundTimer);
417
485
  await client?.close();
486
+ authoritySibling?.close();
418
487
  database?.close();
419
488
  client = undefined;
420
489
  database = undefined;
@@ -31,17 +31,17 @@ import { ClientDiagnosticsEmitter, type ClientDiagnosticsListener, type ClientDi
31
31
  import type { EncryptionKeyringConfig } from './encryption.js';
32
32
  import { ClientSyncError } from './errors.js';
33
33
  import { ChangeEmitter, type ClientChangeListener, InvalidationEmitter, type InvalidationListener, type LocalRevision, type SyncStatusSnapshot } from './invalidation.js';
34
- import { type LeaderLease, type LeaderLock } from './leader-lock.js';
34
+ import { type LeaderLock } from './leader-lock.js';
35
35
  import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
36
36
  import { type LocalDataRebootstrapInput, type LocalDataRebootstrapResult } from './local-rebootstrap.js';
37
- import { type CrossTabChannel, FollowerLink, LeaderBridge, type LeadershipState } from './multi-tab.js';
37
+ import { type CrossTabChannel, type LeadershipState, type TabCoordinator } from './multi-tab.js';
38
38
  import type { OutboxCommit } from './outbox.js';
39
39
  import type { CommitOutcome, CommitOutcomeQuery, ResolveCommitOutcomeInput } from './outcomes.js';
40
40
  import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
41
41
  import type { ClientSchema } from './schema.js';
42
42
  import type { SubscriptionRecord } from './state.js';
43
43
  import type { WindowBase } from './window.js';
44
- import { type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
44
+ import { type LocalAuthorityState, type SyncWorkerEvent, type WorkerApi, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape, type WorkerSecurityActivation } from './worker-protocol.js';
45
45
  /** Classify startup without echoing a chunk URL or bundler text to UI/logs. */
46
46
  export declare function workerStartupError(message: unknown): ClientSyncError;
47
47
  export type HandleRole = 'leader' | 'follower';
@@ -88,6 +88,8 @@ export interface SyncClientHandleConfig {
88
88
  /** Open the worker-owned replica behind the fail-closed security gate. */
89
89
  readonly securityPreflight?: boolean;
90
90
  readonly transportEnabled?: boolean;
91
+ /** SPEC §12: start against the worker's local authority (`WorkerInitConfig`). */
92
+ readonly localAuthority?: boolean;
91
93
  readonly clientId?: string;
92
94
  readonly limits?: SyncClientLimits;
93
95
  readonly retainFailedCommits?: boolean;
@@ -143,16 +145,14 @@ export interface SyncClientHandleConfig {
143
145
  readonly onDiagnostics?: (snapshot: ClientDiagnosticsSnapshot) => void;
144
146
  }
145
147
  /**
146
- * A running worker core owned by THIS tab (the leader). Wraps the worker,
147
- * the RPC pending map, and (in multi-tab mode) the `LeaderBridge` relaying
148
- * follower requests. Torn down on `close()` or on a graceful demotion.
148
+ * A running worker core owned by THIS tab (the leader). Wraps the worker and
149
+ * the RPC pending map. Torn down on `close()` or on a graceful demotion.
149
150
  */
150
151
  interface LeaderCore {
151
152
  readonly clientId: string;
152
153
  readonly invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
153
- readonly bridge: LeaderBridge | undefined;
154
- readonly lease: LeaderLease;
155
- close(terminate: boolean): Promise<void>;
154
+ /** Close the core, terminate the worker, and release the lease. */
155
+ close(): Promise<void>;
156
156
  }
157
157
  /**
158
158
  * The main-thread proxy: the same logical API as `SyncClient`, every method a
@@ -175,7 +175,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
175
175
  clientId: string;
176
176
  currentSchemaVersion: number;
177
177
  core?: LeaderCore;
178
- follower?: FollowerLink;
178
+ tabs?: TabCoordinator;
179
179
  invalidation: InvalidationEmitter;
180
180
  changes: ChangeEmitter;
181
181
  presence: Set<(scopeKey: string) => void>;
@@ -185,22 +185,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
185
185
  leadership?: LeadershipState;
186
186
  });
187
187
  /**
188
- * @internal — whether `close()` has run.
189
- *
190
- * A follower keeps a blocking `acquire` outstanding for the whole time it is a
191
- * follower, so its promotion can fire long after the application has discarded
192
- * the handle. The promotion path consults this before opening anything.
193
- */
194
- get __isClosed(): boolean;
195
- /** @internal — swap this handle from follower to leader (promotion). */
196
- __becomeLeader(core: LeaderCore): void;
197
- /**
198
- * @internal — a newer tab asked for the database: close the core and
199
- * release the lock so that tab promotes. This tab stays blocked until it
200
- * reloads with the newer build.
188
+ * @internal — apply a leadership snapshot in place: a promotion flips the
189
+ * role to `'leader'`, stepping down for a newer tab flips it back.
201
190
  */
202
- __yieldToNewerTab(): void;
203
- /** @internal — apply a follower reachability snapshot in place. */
204
191
  __setLeadership(state: LeadershipState): void;
205
192
  /** @internal — dispatch a worker/relayed event to handle-local listeners. */
206
193
  __dispatchEvent(event: SyncWorkerEvent): void;
@@ -289,7 +276,17 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
289
276
  __headers: Readonly<Record<string, string>> | undefined;
290
277
  /** Sever/restore transport + realtime inside the worker (demos). */
291
278
  setOffline(offline: boolean): Promise<void>;
292
- /** Close the core (leader) or unbind the link (follower), release leadership. */
279
+ /** SPEC §12.3 local-authority state; `undefined` without `localAuthority`. */
280
+ localAuthorityState(): Promise<LocalAuthorityState | undefined>;
281
+ /**
282
+ * SPEC §12.3: upload the local authority's rows to `endpoints.syncUrl`,
283
+ * then sync with that server. Rejects with `sync.attach_rejected` when the
284
+ * server refuses an upload commit.
285
+ */
286
+ attachLocalAuthority(): Promise<void>;
287
+ /** SPEC §12.3: delete the rows a stopped attach uploaded, then sync locally. */
288
+ abandonLocalAuthorityAttach(): Promise<void>;
289
+ /** Close the core (leader) or the link (follower), release leadership. */
293
290
  close(): Promise<void>;
294
291
  }
295
292
  /**