@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.
- package/README.md +32 -0
- package/dist/client.js +18 -3
- package/dist/multi-tab.d.ts +96 -22
- package/dist/multi-tab.js +242 -10
- package/dist/outbox.d.ts +5 -0
- package/dist/outbox.js +11 -3
- package/dist/outcomes.js +6 -2
- package/dist/previous-version.d.ts +3 -1
- package/dist/previous-version.js +24 -5
- package/dist/worker-entry.d.ts +17 -1
- package/dist/worker-entry.js +73 -4
- package/dist/worker-host.d.ts +23 -26
- package/dist/worker-host.js +122 -311
- package/dist/worker-protocol.d.ts +16 -0
- package/dist/worker-protocol.js +2 -0
- package/package.json +3 -3
- package/src/client.ts +26 -3
- package/src/multi-tab.ts +366 -34
- package/src/outbox.ts +16 -2
- package/src/outcomes.ts +6 -2
- package/src/previous-version.ts +32 -5
- package/src/worker-entry.ts +123 -4
- package/src/worker-host.ts +143 -381
- package/src/worker-protocol.ts +18 -0
|
@@ -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
|
/**
|
package/dist/previous-version.js
CHANGED
|
@@ -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
|
-
|
|
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' &&
|
|
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' &&
|
|
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
|
}
|
package/dist/worker-entry.d.ts
CHANGED
|
@@ -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 {
|
|
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
|
package/dist/worker-entry.js
CHANGED
|
@@ -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
|
|
229
|
+
const remote = overrides.createTransport !== undefined
|
|
191
230
|
? overrides.createTransport(config)
|
|
192
231
|
: httpSyncTransport(config.endpoints.syncUrl, http);
|
|
193
|
-
|
|
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
|
-
|
|
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;
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -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
|
|
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,
|
|
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
|
|
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
|
-
|
|
154
|
-
|
|
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
|
-
|
|
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 —
|
|
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
|
-
/**
|
|
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
|
/**
|