@syncular/client 0.85.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.
- package/README.md +13 -4
- package/dist/apply.d.ts +1 -1
- package/dist/apply.js +25 -26
- package/dist/blob.d.ts +0 -4
- package/dist/blob.js +7 -22
- package/dist/client.d.ts +31 -10
- package/dist/client.js +501 -465
- package/dist/diagnostics.d.ts +2 -4
- package/dist/diagnostics.js +3 -17
- package/dist/encryption.js +5 -30
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +4 -0
- package/dist/failed-overlay.d.ts +8 -2
- package/dist/failed-overlay.js +33 -22
- package/dist/local-purge.d.ts +1 -0
- package/dist/local-purge.js +1 -1
- package/dist/local-rebootstrap-receipt.js +2 -2
- package/dist/local-rebootstrap.js +1 -1
- package/dist/native-bridge.d.ts +8 -3
- package/dist/native-bridge.js +29 -12
- package/dist/outcomes.d.ts +13 -1
- package/dist/outcomes.js +21 -20
- package/dist/previous-version.js +23 -35
- package/dist/progress.d.ts +4 -0
- package/dist/progress.js +14 -2
- package/dist/realtime-supervisor.d.ts +4 -1
- package/dist/realtime-supervisor.js +2 -2
- package/dist/schema.js +14 -13
- package/dist/state.d.ts +16 -4
- package/dist/state.js +83 -44
- package/dist/sync-scheduler.d.ts +8 -2
- package/dist/sync-scheduler.js +11 -3
- package/dist/worker-core.js +14 -10
- package/dist/worker-host.d.ts +10 -2
- package/dist/worker-host.js +15 -0
- package/dist/worker-protocol.d.ts +4 -1
- package/package.json +3 -3
- package/src/apply.ts +34 -47
- package/src/blob.ts +7 -24
- package/src/client.ts +699 -553
- package/src/diagnostics.ts +3 -19
- package/src/encryption.ts +15 -40
- package/src/errors.ts +5 -0
- package/src/failed-overlay.ts +39 -29
- package/src/local-purge.ts +1 -1
- package/src/local-rebootstrap-receipt.ts +2 -5
- package/src/local-rebootstrap.ts +1 -2
- package/src/native-bridge.ts +40 -14
- package/src/outcomes.ts +36 -31
- package/src/previous-version.ts +31 -40
- package/src/progress.ts +18 -2
- package/src/realtime-supervisor.ts +7 -3
- package/src/schema.ts +13 -13
- package/src/state.ts +107 -64
- package/src/sync-scheduler.ts +17 -5
- package/src/worker-core.ts +14 -18
- package/src/worker-host.ts +30 -1
- package/src/worker-protocol.ts +4 -0
package/dist/previous-version.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { ClientSyncError } from './errors.js';
|
|
1
|
+
import { ClientSyncError, localStateCorrupt } from './errors.js';
|
|
2
2
|
import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap.js';
|
|
3
|
-
import { fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, tableExists, } from './schema.js';
|
|
3
|
+
import { bytesToHex, fromSqlValue, jsonToRowValue, localColumnType, quoteIdent, rowValueToJson, tableExists, } from './schema.js';
|
|
4
4
|
import { getMeta, setMeta, META_TABLE } from './state.js';
|
|
5
5
|
/** `_syncular_meta` key holding the persisted {@link LocalSchemaDescriptor}. */
|
|
6
6
|
const LOCAL_SCHEMA_DESCRIPTOR_KEY = 'localSchemaDescriptor';
|
|
@@ -94,7 +94,7 @@ function hasExactKeys(record, expected) {
|
|
|
94
94
|
expected.every((key) => Object.hasOwn(record, key)));
|
|
95
95
|
}
|
|
96
96
|
function localCorrupt(what) {
|
|
97
|
-
throw
|
|
97
|
+
throw localStateCorrupt(`persisted ${what} is invalid`);
|
|
98
98
|
}
|
|
99
99
|
// ---------------------------------------------------------------------------
|
|
100
100
|
// Descriptor (D1)
|
|
@@ -382,12 +382,7 @@ function rowIdText(table, row) {
|
|
|
382
382
|
const value = row[table.primaryKey] ?? null;
|
|
383
383
|
if (value === null)
|
|
384
384
|
return '';
|
|
385
|
-
|
|
386
|
-
return [...value]
|
|
387
|
-
.map((byte) => byte.toString(16).padStart(2, '0'))
|
|
388
|
-
.join('');
|
|
389
|
-
}
|
|
390
|
-
return String(value);
|
|
385
|
+
return value instanceof Uint8Array ? bytesToHex(value) : String(value);
|
|
391
386
|
}
|
|
392
387
|
function decodePreviousVersionPayload(table, payload) {
|
|
393
388
|
const record = parseJsonObject(payload);
|
|
@@ -490,36 +485,29 @@ function firstIncompatibility(schema, commit) {
|
|
|
490
485
|
if (operation.op === 'delete')
|
|
491
486
|
continue;
|
|
492
487
|
const table = schema.tables.get(operation.table);
|
|
493
|
-
|
|
488
|
+
const column = table &&
|
|
489
|
+
Object.keys(operation.values ?? {}).find((key) => !table.columnIndex.has(key));
|
|
490
|
+
// §7.1: an insert-intent operation presents every current column, so a
|
|
491
|
+
// non-nullable column it lacks leaves the commit unencodable.
|
|
492
|
+
const missing = operation.insert === true
|
|
493
|
+
? table?.columns.find((entry) => !entry.nullable && operation.values?.[entry.name] === undefined)
|
|
494
|
+
: undefined;
|
|
495
|
+
const refusal = table === undefined
|
|
496
|
+
? { reason: 'unknown-table' }
|
|
497
|
+
: column !== undefined
|
|
498
|
+
? { reason: 'unknown-column', column }
|
|
499
|
+
: missing !== undefined
|
|
500
|
+
? {
|
|
501
|
+
reason: 'missing-required-column',
|
|
502
|
+
column: missing.name,
|
|
503
|
+
}
|
|
504
|
+
: undefined;
|
|
505
|
+
if (refusal !== undefined)
|
|
494
506
|
return {
|
|
495
507
|
commitId: commit.clientCommitId,
|
|
496
508
|
table: operation.table,
|
|
497
|
-
|
|
509
|
+
...refusal,
|
|
498
510
|
};
|
|
499
|
-
}
|
|
500
|
-
for (const key of Object.keys(operation.values ?? {})) {
|
|
501
|
-
if (!table.columnIndex.has(key)) {
|
|
502
|
-
return {
|
|
503
|
-
commitId: commit.clientCommitId,
|
|
504
|
-
table: operation.table,
|
|
505
|
-
reason: 'unknown-column',
|
|
506
|
-
column: key,
|
|
507
|
-
};
|
|
508
|
-
}
|
|
509
|
-
}
|
|
510
|
-
// §7.1: an insert-intent operation presents every current column, so a
|
|
511
|
-
// non-nullable column it lacks leaves the commit unencodable.
|
|
512
|
-
if (operation.insert === true) {
|
|
513
|
-
const missing = table.columns.find((column) => !column.nullable && operation.values?.[column.name] === undefined);
|
|
514
|
-
if (missing !== undefined) {
|
|
515
|
-
return {
|
|
516
|
-
commitId: commit.clientCommitId,
|
|
517
|
-
table: operation.table,
|
|
518
|
-
reason: 'missing-required-column',
|
|
519
|
-
column: missing.name,
|
|
520
|
-
};
|
|
521
|
-
}
|
|
522
|
-
}
|
|
523
511
|
}
|
|
524
512
|
return undefined;
|
|
525
513
|
}
|
package/dist/progress.d.ts
CHANGED
|
@@ -13,6 +13,10 @@ export interface SyncProgress {
|
|
|
13
13
|
readonly bytesTotal?: number | undefined;
|
|
14
14
|
readonly rowsProcessed: number;
|
|
15
15
|
readonly rowsTotal?: number | undefined;
|
|
16
|
+
/** The unit's bootstrap rows as the server counted them (SPEC §4.4, §7.7). */
|
|
17
|
+
readonly unitRowsTotal?: number | undefined;
|
|
18
|
+
/** Rows of the unit's bootstrap imported so far, across its sections. */
|
|
19
|
+
readonly unitRowsProcessed?: number | undefined;
|
|
16
20
|
/** Time in this payload's import transactions before COMMIT, in ms. */
|
|
17
21
|
readonly importWriteMs?: number | undefined;
|
|
18
22
|
/** Time committing them and publishing their changes, in ms. */
|
package/dist/progress.js
CHANGED
|
@@ -36,7 +36,19 @@ export class ProgressEmitter {
|
|
|
36
36
|
}
|
|
37
37
|
}
|
|
38
38
|
update(update) {
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
const before = this.#snapshot;
|
|
40
|
+
if (before?.state !== 'running')
|
|
41
|
+
return;
|
|
42
|
+
const next = { ...before, ...update };
|
|
43
|
+
// §7.7: each rise of the payload counter raises the unit's, and the unit
|
|
44
|
+
// total never falls below what was imported.
|
|
45
|
+
if (next.unitRowsProcessed !== undefined) {
|
|
46
|
+
const processed = next.unitRowsProcessed +
|
|
47
|
+
Math.max(0, next.rowsProcessed - before.rowsProcessed);
|
|
48
|
+
next.unitRowsProcessed = processed;
|
|
49
|
+
if (next.unitRowsTotal !== undefined)
|
|
50
|
+
next.unitRowsTotal = Math.max(next.unitRowsTotal, processed);
|
|
51
|
+
}
|
|
52
|
+
this.emit(next);
|
|
41
53
|
}
|
|
42
54
|
}
|
|
@@ -5,7 +5,10 @@ type CancelTimer = () => void;
|
|
|
5
5
|
export interface RealtimeSupervisorClient {
|
|
6
6
|
connectRealtime(): Promise<void>;
|
|
7
7
|
disconnectRealtime(): void | Promise<void>;
|
|
8
|
-
|
|
8
|
+
/** Receives `{ skipEmpty: true }` (§8.4); a numeric-budget signature also fits. */
|
|
9
|
+
syncUntilIdle(options?: number | {
|
|
10
|
+
readonly skipEmpty?: boolean;
|
|
11
|
+
}): unknown | Promise<unknown>;
|
|
9
12
|
diagnosticsSnapshot(): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
|
|
10
13
|
onDiagnostics(listener: ClientDiagnosticsListener): () => void;
|
|
11
14
|
close(): void | Promise<void>;
|
|
@@ -326,7 +326,7 @@ export class RealtimeSupervisor {
|
|
|
326
326
|
return;
|
|
327
327
|
}
|
|
328
328
|
this.#round = Promise.resolve()
|
|
329
|
-
.then(() => this.#client.syncUntilIdle())
|
|
329
|
+
.then(() => this.#client.syncUntilIdle({ skipEmpty: true }))
|
|
330
330
|
.then(() => undefined, () => undefined)
|
|
331
331
|
.finally(() => {
|
|
332
332
|
this.#round = undefined;
|
|
@@ -479,7 +479,7 @@ export class RealtimeSupervisor {
|
|
|
479
479
|
this.#transport = true;
|
|
480
480
|
}
|
|
481
481
|
if (generation === this.#generation)
|
|
482
|
-
await this.#client.syncUntilIdle();
|
|
482
|
+
await this.#client.syncUntilIdle({ skipEmpty: true });
|
|
483
483
|
caughtUp = generation === this.#generation && this.#transport;
|
|
484
484
|
}
|
|
485
485
|
catch {
|
package/dist/schema.js
CHANGED
|
@@ -5,7 +5,7 @@ import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox.js';
|
|
|
5
5
|
import { OUTCOMES_TABLE } from './outcomes.js';
|
|
6
6
|
import { META_TABLE, pruneUnknownUnits, resetUnits, UNITS_TABLE, } from './state.js';
|
|
7
7
|
import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay.js';
|
|
8
|
-
import {
|
|
8
|
+
import { invalidRequest, localStateCorrupt } from './errors.js';
|
|
9
9
|
import { snakeToCamel } from './naming.js';
|
|
10
10
|
const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
|
|
11
11
|
const ALLOWED_FTS_TOKENIZERS = new Set([
|
|
@@ -239,11 +239,10 @@ function sqlType(column) {
|
|
|
239
239
|
case 'blob_ref':
|
|
240
240
|
return 'TEXT';
|
|
241
241
|
case 'integer':
|
|
242
|
+
case 'boolean':
|
|
242
243
|
return 'INTEGER';
|
|
243
244
|
case 'float':
|
|
244
245
|
return 'REAL';
|
|
245
|
-
case 'boolean':
|
|
246
|
-
return 'INTEGER';
|
|
247
246
|
case 'bytes':
|
|
248
247
|
case 'crdt':
|
|
249
248
|
// §5.10: a crdt column stores its opaque bytes locally, exactly like
|
|
@@ -478,13 +477,15 @@ export function ensureLocalBookkeepingSchema(db) {
|
|
|
478
477
|
}
|
|
479
478
|
db.exec(`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`);
|
|
480
479
|
createTable(UNITS_TABLE, "id TEXT PRIMARY KEY,scopes TEXT NOT NULL,explicit INTEGER NOT NULL DEFAULT 0,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT,cursor INTEGER DEFAULT -1,bootstrap_state TEXT,seeded TEXT NOT NULL DEFAULT '[]',echo TEXT");
|
|
481
|
-
// §5.6 applied-segment record, added after the
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
480
|
+
// §5.6 applied-segment record and §7.4.3 restriction, added after the
|
|
481
|
+
// table shipped.
|
|
482
|
+
for (const column of ['applied', 'restriction'])
|
|
483
|
+
try {
|
|
484
|
+
db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN ${column} TEXT`);
|
|
485
|
+
}
|
|
486
|
+
catch {
|
|
487
|
+
// column already exists
|
|
488
|
+
}
|
|
488
489
|
// §4.8 window registry: base + value → the unit it holds, the
|
|
489
490
|
// completeness oracle and one of a unit's references (§4.1).
|
|
490
491
|
createTable(WINDOWS_TABLE, 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
|
|
@@ -498,7 +499,7 @@ export function ensureLocalBookkeepingSchema(db) {
|
|
|
498
499
|
const legacyEvictions = '_syncular_window_pending_evict';
|
|
499
500
|
if (tableExists(db, legacyEvictions)) {
|
|
500
501
|
if (db.query(`SELECT 1 FROM ${legacyEvictions} WHERE NOT json_valid(effective_scopes) OR json_type(effective_scopes)<>'object' OR EXISTS(SELECT 1 FROM json_each(effective_scopes) WHERE json_type(value)<>'array' OR EXISTS(SELECT 1 FROM json_each(value) v WHERE v.type<>'text'))`).length > 0)
|
|
501
|
-
throw
|
|
502
|
+
throw localStateCorrupt('a version 3 pending eviction cannot be upgraded');
|
|
502
503
|
db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`);
|
|
503
504
|
db.exec(`DROP TABLE ${legacyEvictions}`);
|
|
504
505
|
db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
|
|
@@ -530,7 +531,7 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
|
|
|
530
531
|
export function resetLocalReplica(db, schema, bump = false) {
|
|
531
532
|
const kept = bump
|
|
532
533
|
? pruneUnknownUnits(db, schema, true)
|
|
533
|
-
: { tables: new Set(), units: [] };
|
|
534
|
+
: { tables: new Set(), units: [], restricts: undefined };
|
|
534
535
|
const keptNames = [...kept.tables];
|
|
535
536
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`, keptNames);
|
|
536
537
|
// Drop virtual tables first. SQLite then removes their shadow tables as one
|
|
@@ -550,7 +551,7 @@ export function resetLocalReplica(db, schema, bump = false) {
|
|
|
550
551
|
for (const table of schema.tables.values())
|
|
551
552
|
for (const index of table.ftsIndexes)
|
|
552
553
|
createFtsProjection(db, table, index);
|
|
553
|
-
resetUnits(db, kept.units);
|
|
554
|
+
resetUnits(db, kept.units, kept.restricts);
|
|
554
555
|
return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
|
|
555
556
|
}
|
|
556
557
|
// ---------------------------------------------------------------------------
|
package/dist/state.d.ts
CHANGED
|
@@ -7,7 +7,7 @@ export declare const UNITS_TABLE = "_syncular_units";
|
|
|
7
7
|
* contract is keyed on. The replica cursor, the echo digest and the
|
|
8
8
|
* registration digest the server holds live in meta.
|
|
9
9
|
*/
|
|
10
|
-
import type
|
|
10
|
+
import { type FencedRecord, type ScopeMap, type UnitScopes } from '@syncular/core';
|
|
11
11
|
import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
|
|
12
12
|
import type { ClientDatabase } from './database.js';
|
|
13
13
|
import type { LocalRevision } from './invalidation.js';
|
|
@@ -41,6 +41,12 @@ export interface UnitRecord {
|
|
|
41
41
|
/** §5.6 applied-segment record: segment id → rows applied at the unit's
|
|
42
42
|
* current cursor and token. */
|
|
43
43
|
readonly applied?: Readonly<Record<string, number>> | undefined;
|
|
44
|
+
/** §7.4.3 restriction: the kept cursor and the tables to bootstrap. */
|
|
45
|
+
readonly restrict?: Restriction | undefined;
|
|
46
|
+
}
|
|
47
|
+
export interface Restriction {
|
|
48
|
+
readonly cursor: number;
|
|
49
|
+
readonly tables: readonly string[];
|
|
44
50
|
}
|
|
45
51
|
/** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
|
|
46
52
|
export declare function bootstrapping(unit: UnitRecord): boolean;
|
|
@@ -55,8 +61,12 @@ export declare function covers(table: CompiledClientTable, scopes: UnitScopes):
|
|
|
55
61
|
*/
|
|
56
62
|
export declare function pairScopes(scopes: UnitScopes, table: string, echo: readonly FencedRecord[] | undefined): ScopeMap | undefined;
|
|
57
63
|
/** §3.3 row ownership: the pair scopes of every owner of `table` but one.
|
|
58
|
-
* A bootstrapping unit owns the tables its current bootstrap seeded
|
|
64
|
+
* A bootstrapping unit owns the tables its current bootstrap seeded, and a
|
|
65
|
+
* restricted one the tables outside its restriction. */
|
|
59
66
|
export declare function unitOwners(units: readonly UnitRecord[], table: CompiledClientTable, exceptId: string): ScopeMap[];
|
|
67
|
+
/** A unit row; every persisted field must have its stored type and shape,
|
|
68
|
+
* otherwise the row is `sync.local_corrupt` (§7.5). */
|
|
69
|
+
export declare const unitStateCorrupt: () => import("./errors.js").ClientSyncError;
|
|
60
70
|
/** Every unit in registration order (§4.1). */
|
|
61
71
|
export declare function loadUnits(db: ClientDatabase): UnitRecord[];
|
|
62
72
|
export declare function getUnit(db: ClientDatabase, id: string): UnitRecord | undefined;
|
|
@@ -71,10 +81,11 @@ export declare function deleteUnit(db: ClientDatabase, id: string): void;
|
|
|
71
81
|
* §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
|
|
72
82
|
* registrations (the app's declared intent) and discard the synced state of
|
|
73
83
|
* every unit outside `keep`, so the next round sends the list and
|
|
74
|
-
* fresh-bootstraps those units.
|
|
84
|
+
* fresh-bootstraps those units. A bump (`restricts` given) keeps every echo
|
|
85
|
+
* and restricts the units it names. The replica cursor survives only while a
|
|
75
86
|
* kept unit is live. Caller owns the transaction.
|
|
76
87
|
*/
|
|
77
|
-
export declare function resetUnits(db: ClientDatabase, keep?: readonly string[]): void;
|
|
88
|
+
export declare function resetUnits(db: ClientDatabase, keep?: readonly string[], restricts?: ReadonlyMap<string, Restriction>): void;
|
|
78
89
|
/** §4.5: the replica cursor, `-1` while no unit is live. */
|
|
79
90
|
export declare function replicaCursor(db: ClientDatabase): number;
|
|
80
91
|
/** §7.4.3 declaration evidence and table generations, persisted beside the
|
|
@@ -91,6 +102,7 @@ export declare function saveUnitScopeSchema(db: ClientDatabase, schema: Compiled
|
|
|
91
102
|
export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): {
|
|
92
103
|
readonly tables: ReadonlySet<string>;
|
|
93
104
|
readonly units: string[];
|
|
105
|
+
readonly restricts: Map<string, Restriction>;
|
|
94
106
|
};
|
|
95
107
|
export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
|
|
96
108
|
export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
|
package/dist/state.js
CHANGED
|
@@ -2,7 +2,15 @@ export const META_TABLE = '_syncular_meta';
|
|
|
2
2
|
import { PENDING_EVICTIONS } from './window.js';
|
|
3
3
|
import { WINDOWS_TABLE } from './window.js';
|
|
4
4
|
export const UNITS_TABLE = '_syncular_units';
|
|
5
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Durable unit state (SPEC.md §4.1): per unit its scope map, status, live
|
|
7
|
+
* membership, catch-up cursor and opaque resume token (§4.7), the tables its
|
|
8
|
+
* current bootstrap seeded (§5.6) and the last echo (§4.4) the §3.3 purge
|
|
9
|
+
* contract is keyed on. The replica cursor, the echo digest and the
|
|
10
|
+
* registration digest the server holds live in meta.
|
|
11
|
+
*/
|
|
12
|
+
import { definedObject, } from '@syncular/core';
|
|
13
|
+
import { localStateCorrupt } from './errors.js';
|
|
6
14
|
export const LOCAL_REVISION_KEY = 'localRevision';
|
|
7
15
|
/** §4.5 replica cursor; absent means `-1`. */
|
|
8
16
|
export const REPLICA_CURSOR_KEY = 'replicaCursor';
|
|
@@ -39,14 +47,16 @@ export function pairScopes(scopes, table, echo) {
|
|
|
39
47
|
return effective;
|
|
40
48
|
}
|
|
41
49
|
/** §3.3 row ownership: the pair scopes of every owner of `table` but one.
|
|
42
|
-
* A bootstrapping unit owns the tables its current bootstrap seeded
|
|
50
|
+
* A bootstrapping unit owns the tables its current bootstrap seeded, and a
|
|
51
|
+
* restricted one the tables outside its restriction. */
|
|
43
52
|
export function unitOwners(units, table, exceptId) {
|
|
44
53
|
return units.flatMap((unit) => {
|
|
45
54
|
const scopes = unit.id !== exceptId &&
|
|
46
55
|
(owning(unit) ||
|
|
47
56
|
(unit.status === 'active' &&
|
|
48
57
|
unit.echo !== undefined &&
|
|
49
|
-
unit.seeded.includes(table.name)
|
|
58
|
+
(unit.seeded.includes(table.name) ||
|
|
59
|
+
unit.restrict?.tables.includes(table.name) === false))) &&
|
|
50
60
|
covers(table, unit.scopes)
|
|
51
61
|
? pairScopes(unit.scopes, table.name, unit.echo)
|
|
52
62
|
: undefined;
|
|
@@ -55,29 +65,30 @@ export function unitOwners(units, table, exceptId) {
|
|
|
55
65
|
}
|
|
56
66
|
/** A unit row; every persisted field must have its stored type and shape,
|
|
57
67
|
* otherwise the row is `sync.local_corrupt` (§7.5). */
|
|
68
|
+
export const unitStateCorrupt = () => localStateCorrupt('persisted unit state is invalid');
|
|
58
69
|
function rowToRecord(row) {
|
|
59
|
-
const corrupt = () => new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
|
|
60
70
|
const json = (raw) => {
|
|
61
71
|
if (typeof raw !== 'string')
|
|
62
|
-
throw
|
|
72
|
+
throw unitStateCorrupt();
|
|
63
73
|
try {
|
|
64
74
|
return JSON.parse(raw);
|
|
65
75
|
}
|
|
66
76
|
catch {
|
|
67
|
-
throw
|
|
77
|
+
throw unitStateCorrupt();
|
|
68
78
|
}
|
|
69
79
|
};
|
|
70
80
|
const isMap = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
71
81
|
const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
|
|
72
82
|
const optionalText = (value) => {
|
|
73
83
|
if (value !== null && typeof value !== 'string')
|
|
74
|
-
throw
|
|
84
|
+
throw unitStateCorrupt();
|
|
75
85
|
return value ?? undefined;
|
|
76
86
|
};
|
|
77
87
|
const scopes = json(row.scopes);
|
|
78
88
|
const seeded = json(row.seeded);
|
|
79
89
|
const echo = row.echo === null ? undefined : json(row.echo);
|
|
80
90
|
const applied = row.applied === null ? undefined : json(row.applied);
|
|
91
|
+
const restrict = row.restriction === null ? undefined : json(row.restriction);
|
|
81
92
|
const { id, status, cursor } = row;
|
|
82
93
|
if (typeof id !== 'string' ||
|
|
83
94
|
!isMap(scopes) ||
|
|
@@ -93,27 +104,31 @@ function rowToRecord(row) {
|
|
|
93
104
|
(record.status === 'active' || record.status === 'revoked') &&
|
|
94
105
|
isMap(record.scopes) &&
|
|
95
106
|
Object.values(record.scopes).every(isStrings)))))
|
|
96
|
-
throw
|
|
97
|
-
|
|
107
|
+
throw unitStateCorrupt();
|
|
108
|
+
let restriction;
|
|
109
|
+
if (restrict !== undefined) {
|
|
110
|
+
if (!isMap(restrict) ||
|
|
111
|
+
!Number.isInteger(restrict.cursor) ||
|
|
112
|
+
!isStrings(restrict.tables))
|
|
113
|
+
throw unitStateCorrupt();
|
|
114
|
+
restriction = {
|
|
115
|
+
cursor: restrict.cursor,
|
|
116
|
+
tables: restrict.tables,
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
return definedObject({
|
|
98
120
|
id,
|
|
99
121
|
scopes: scopes,
|
|
100
122
|
explicit: row.explicit === 1,
|
|
101
123
|
status,
|
|
102
124
|
seeded,
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
if (bootstrapState !== undefined)
|
|
111
|
-
record.bootstrapState = bootstrapState;
|
|
112
|
-
if (echo !== undefined)
|
|
113
|
-
record.echo = echo;
|
|
114
|
-
if (applied !== undefined)
|
|
115
|
-
record.applied = applied;
|
|
116
|
-
return record;
|
|
125
|
+
reasonCode: optionalText(row.reason_code),
|
|
126
|
+
cursor: typeof cursor === 'number' ? cursor : undefined,
|
|
127
|
+
bootstrapState: optionalText(row.bootstrap_state),
|
|
128
|
+
echo: echo,
|
|
129
|
+
applied: applied,
|
|
130
|
+
restrict: restriction,
|
|
131
|
+
});
|
|
117
132
|
}
|
|
118
133
|
/** Every unit in registration order (§4.1). */
|
|
119
134
|
export function loadUnits(db) {
|
|
@@ -128,7 +143,7 @@ export function getUnit(db, id) {
|
|
|
128
143
|
/** Insert or update in place: an update keeps the registration order. The
|
|
129
144
|
* §5.6 applied-segment record ends when the cursor or the token changes. */
|
|
130
145
|
export function saveUnit(db, record) {
|
|
131
|
-
db.exec(`INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(
|
|
146
|
+
db.exec(`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)`, [
|
|
132
147
|
record.id,
|
|
133
148
|
JSON.stringify(record.scopes),
|
|
134
149
|
record.explicit ? 1 : 0,
|
|
@@ -138,6 +153,7 @@ export function saveUnit(db, record) {
|
|
|
138
153
|
record.bootstrapState ?? null,
|
|
139
154
|
JSON.stringify(record.seeded),
|
|
140
155
|
record.echo === undefined ? null : JSON.stringify(record.echo),
|
|
156
|
+
record.restrict === undefined ? null : JSON.stringify(record.restrict),
|
|
141
157
|
]);
|
|
142
158
|
}
|
|
143
159
|
/** §5.6: `rows` rows of `segmentId` applied at the unit's position. Runs
|
|
@@ -152,11 +168,17 @@ export function deleteUnit(db, id) {
|
|
|
152
168
|
* §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
|
|
153
169
|
* registrations (the app's declared intent) and discard the synced state of
|
|
154
170
|
* every unit outside `keep`, so the next round sends the list and
|
|
155
|
-
* fresh-bootstraps those units.
|
|
171
|
+
* fresh-bootstraps those units. A bump (`restricts` given) keeps every echo
|
|
172
|
+
* and restricts the units it names. The replica cursor survives only while a
|
|
156
173
|
* kept unit is live. Caller owns the transaction.
|
|
157
174
|
*/
|
|
158
|
-
export function resetUnits(db, keep = []) {
|
|
159
|
-
db.exec(`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]'
|
|
175
|
+
export function resetUnits(db, keep = [], restricts) {
|
|
176
|
+
db.exec(`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(',')})`, [...keep]);
|
|
177
|
+
for (const [id, restrict] of restricts ?? [])
|
|
178
|
+
db.exec(`UPDATE ${UNITS_TABLE} SET restriction=? WHERE id=?`, [
|
|
179
|
+
JSON.stringify(restrict),
|
|
180
|
+
id,
|
|
181
|
+
]);
|
|
160
182
|
db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?) OR key=? AND NOT EXISTS(SELECT 1 FROM ${UNITS_TABLE} WHERE cursor IS NULL)`, [ECHO_DIGEST_KEY, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY]);
|
|
161
183
|
}
|
|
162
184
|
/** §4.5: the replica cursor, `-1` while no unit is live. */
|
|
@@ -204,7 +226,7 @@ export function pruneUnknownUnits(db, schema, bump = false) {
|
|
|
204
226
|
generations === null ||
|
|
205
227
|
Array.isArray(generations) ||
|
|
206
228
|
Object.values(generations).some((value) => typeof value !== 'string'))
|
|
207
|
-
throw
|
|
229
|
+
throw localStateCorrupt('invalid persisted table generations');
|
|
208
230
|
const kept = new Set([...schema.tables.values()]
|
|
209
231
|
.filter((table) => table.generation !== undefined &&
|
|
210
232
|
generations[table.name] ===
|
|
@@ -251,14 +273,33 @@ export function pruneUnknownUnits(db, schema, bump = false) {
|
|
|
251
273
|
db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
|
|
252
274
|
deleteUnit(db, id);
|
|
253
275
|
}
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
276
|
+
const units = [];
|
|
277
|
+
const restricts = new Map();
|
|
278
|
+
for (const unit of loadUnits(db)) {
|
|
279
|
+
const covered = [...schema.tables.values()]
|
|
280
|
+
.filter((table) => covers(table, unit.scopes))
|
|
281
|
+
.map((table) => table.name);
|
|
282
|
+
if (Object.entries(previous ?? {}).every(([name, old]) => kept.has(name) ||
|
|
283
|
+
!Object.keys(unit.scopes).every((v) => old[v] !== undefined)) &&
|
|
284
|
+
covered.every((name) => kept.has(name))) {
|
|
285
|
+
units.push(unit.id);
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
// §7.4.3 restriction: a live, post-bootstrap or restricted unit keeps its
|
|
289
|
+
// rows of kept tables through its kept cursor and bootstraps the rest.
|
|
290
|
+
const tables = covered
|
|
291
|
+
.filter((name) => !kept.has(name) || unit.restrict?.tables.includes(name))
|
|
292
|
+
.sort();
|
|
293
|
+
const cursor = unit.restrict?.cursor ??
|
|
294
|
+
(bootstrapping(unit) ? -1 : (unit.cursor ?? replicaCursor(db)));
|
|
295
|
+
if (bump &&
|
|
296
|
+
unit.status === 'active' &&
|
|
297
|
+
cursor >= 0 &&
|
|
298
|
+
tables.length > 0 &&
|
|
299
|
+
tables.length < covered.length)
|
|
300
|
+
restricts.set(unit.id, { cursor, tables });
|
|
301
|
+
}
|
|
302
|
+
return { tables: kept, units, restricts };
|
|
262
303
|
}
|
|
263
304
|
export function getMeta(db, key) {
|
|
264
305
|
const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
|
|
@@ -275,14 +316,12 @@ export function getLocalRevision(db) {
|
|
|
275
316
|
const raw = getMeta(db, LOCAL_REVISION_KEY);
|
|
276
317
|
if (raw === undefined)
|
|
277
318
|
return 0n;
|
|
278
|
-
if (typeof raw !== 'string' ||
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
if (revision > MAX_U64) {
|
|
283
|
-
throw new ClientSyncError('sync.local_corrupt', 'persisted local revision is invalid');
|
|
319
|
+
if (typeof raw !== 'string' ||
|
|
320
|
+
!/^(0|[1-9][0-9]*)$/.test(raw) ||
|
|
321
|
+
BigInt(raw) > MAX_U64) {
|
|
322
|
+
throw localStateCorrupt('persisted local revision is invalid');
|
|
284
323
|
}
|
|
285
|
-
return
|
|
324
|
+
return BigInt(raw);
|
|
286
325
|
}
|
|
287
326
|
/**
|
|
288
327
|
* Increment the durable revision. The caller MUST own the same transaction as
|
|
@@ -291,7 +330,7 @@ export function getLocalRevision(db) {
|
|
|
291
330
|
export function bumpLocalRevision(db) {
|
|
292
331
|
const current = getLocalRevision(db);
|
|
293
332
|
if (current === MAX_U64) {
|
|
294
|
-
throw
|
|
333
|
+
throw localStateCorrupt('local revision exhausted u64');
|
|
295
334
|
}
|
|
296
335
|
const next = current + 1n;
|
|
297
336
|
setMeta(db, LOCAL_REVISION_KEY, next.toString());
|
package/dist/sync-scheduler.d.ts
CHANGED
|
@@ -1,17 +1,23 @@
|
|
|
1
1
|
import type { WakeReason } from '@syncular/core';
|
|
2
|
-
import type { SecurityLifecycle } from './client.js';
|
|
2
|
+
import type { SecurityLifecycle, SyncIdleOptions } from './client.js';
|
|
3
3
|
import type { SyncIntent } from './invalidation.js';
|
|
4
4
|
export interface SyncSchedulerClient {
|
|
5
5
|
statusSnapshot(): {
|
|
6
6
|
readonly syncNeeded: boolean;
|
|
7
7
|
};
|
|
8
8
|
securityLifecycle(): SecurityLifecycle;
|
|
9
|
-
syncUntilIdle(
|
|
9
|
+
syncUntilIdle(options: SyncIdleOptions): Promise<unknown>;
|
|
10
10
|
onSyncNeeded(listener: (reason: 'startup' | 'hello' | WakeReason) => void): () => void;
|
|
11
11
|
onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
|
|
12
12
|
}
|
|
13
13
|
export interface SyncSchedulerOptions {
|
|
14
14
|
readonly maxRounds?: number;
|
|
15
|
+
/**
|
|
16
|
+
* §8.4: milliseconds a queued drive waits before it starts, so the claims
|
|
17
|
+
* and writes of one burst ride in one round. Default 0: the drive starts
|
|
18
|
+
* in the next microtask.
|
|
19
|
+
*/
|
|
20
|
+
readonly coalesceMs?: number;
|
|
15
21
|
readonly onError?: (error: unknown) => void;
|
|
16
22
|
readonly now?: () => number;
|
|
17
23
|
readonly queueMicrotask?: (callback: () => void) => void;
|
package/dist/sync-scheduler.js
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
|
+
import { invalidRequest } from './errors.js';
|
|
1
2
|
/** Install the event-driven single-flight host loop for a direct client. */
|
|
2
3
|
export function installSyncScheduler(client, options = {}) {
|
|
4
|
+
const coalesceMs = options.coalesceMs ?? 0;
|
|
5
|
+
if (!(Number.isFinite(coalesceMs) && coalesceMs >= 0))
|
|
6
|
+
throw invalidRequest('coalesceMs must be a non-negative finite number');
|
|
3
7
|
const now = options.now ?? Date.now;
|
|
4
8
|
const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
|
|
5
9
|
const schedule = options.schedule ??
|
|
@@ -38,13 +42,17 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
38
42
|
if (stopped || running || immediateQueued)
|
|
39
43
|
return;
|
|
40
44
|
immediateQueued = true;
|
|
41
|
-
|
|
45
|
+
const start = () => {
|
|
42
46
|
immediateQueued = false;
|
|
43
47
|
if (stopped || !immediatePending)
|
|
44
48
|
return;
|
|
45
49
|
immediatePending = false;
|
|
46
50
|
run();
|
|
47
|
-
}
|
|
51
|
+
};
|
|
52
|
+
if (coalesceMs > 0)
|
|
53
|
+
schedule(start, coalesceMs);
|
|
54
|
+
else
|
|
55
|
+
enqueue(start);
|
|
48
56
|
};
|
|
49
57
|
const run = () => {
|
|
50
58
|
if (stopped || running)
|
|
@@ -56,7 +64,7 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
56
64
|
running = true;
|
|
57
65
|
backgroundReady = false;
|
|
58
66
|
void client
|
|
59
|
-
.syncUntilIdle(options.maxRounds)
|
|
67
|
+
.syncUntilIdle({ maxRounds: options.maxRounds, skipEmpty: true })
|
|
60
68
|
.then((result) => {
|
|
61
69
|
retryDelayMs = 250;
|
|
62
70
|
if (result !== null &&
|