@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/src/previous-version.ts
CHANGED
|
@@ -31,9 +31,10 @@
|
|
|
31
31
|
*/
|
|
32
32
|
import type { RowColumn, RowValue } from '@syncular/core';
|
|
33
33
|
import type { ClientDatabase, SqlRow, SqlValue } from './database';
|
|
34
|
-
import { ClientSyncError } from './errors';
|
|
34
|
+
import { ClientSyncError, localStateCorrupt } from './errors';
|
|
35
35
|
import { INVALID_HOST_RESPONSE_CODE } from './local-rebootstrap';
|
|
36
36
|
import {
|
|
37
|
+
bytesToHex,
|
|
37
38
|
type CompiledClientSchema,
|
|
38
39
|
fromSqlValue,
|
|
39
40
|
type JsonRowValue,
|
|
@@ -285,10 +286,7 @@ function hasExactKeys(
|
|
|
285
286
|
}
|
|
286
287
|
|
|
287
288
|
function localCorrupt(what: string): never {
|
|
288
|
-
throw
|
|
289
|
-
'sync.local_corrupt',
|
|
290
|
-
`persisted ${what} is invalid`,
|
|
291
|
-
);
|
|
289
|
+
throw localStateCorrupt(`persisted ${what} is invalid`);
|
|
292
290
|
}
|
|
293
291
|
|
|
294
292
|
// ---------------------------------------------------------------------------
|
|
@@ -649,12 +647,7 @@ export function capturePreviousVersion(
|
|
|
649
647
|
function rowIdText(table: LocalSchemaDescriptorTable, row: SqlRow): string {
|
|
650
648
|
const value = row[table.primaryKey] ?? null;
|
|
651
649
|
if (value === null) return '';
|
|
652
|
-
|
|
653
|
-
return [...value]
|
|
654
|
-
.map((byte) => byte.toString(16).padStart(2, '0'))
|
|
655
|
-
.join('');
|
|
656
|
-
}
|
|
657
|
-
return String(value);
|
|
650
|
+
return value instanceof Uint8Array ? bytesToHex(value) : String(value);
|
|
658
651
|
}
|
|
659
652
|
|
|
660
653
|
function decodePreviousVersionPayload(
|
|
@@ -807,39 +800,37 @@ function firstIncompatibility(
|
|
|
807
800
|
// validation, even against a removed table.
|
|
808
801
|
if (operation.op === 'delete') continue;
|
|
809
802
|
const table = schema.tables.get(operation.table);
|
|
810
|
-
|
|
803
|
+
const column =
|
|
804
|
+
table &&
|
|
805
|
+
Object.keys(operation.values ?? {}).find(
|
|
806
|
+
(key) => !table.columnIndex.has(key),
|
|
807
|
+
);
|
|
808
|
+
// §7.1: an insert-intent operation presents every current column, so a
|
|
809
|
+
// non-nullable column it lacks leaves the commit unencodable.
|
|
810
|
+
const missing =
|
|
811
|
+
operation.insert === true
|
|
812
|
+
? table?.columns.find(
|
|
813
|
+
(entry) =>
|
|
814
|
+
!entry.nullable && operation.values?.[entry.name] === undefined,
|
|
815
|
+
)
|
|
816
|
+
: undefined;
|
|
817
|
+
const refusal =
|
|
818
|
+
table === undefined
|
|
819
|
+
? { reason: 'unknown-table' as const }
|
|
820
|
+
: column !== undefined
|
|
821
|
+
? { reason: 'unknown-column' as const, column }
|
|
822
|
+
: missing !== undefined
|
|
823
|
+
? {
|
|
824
|
+
reason: 'missing-required-column' as const,
|
|
825
|
+
column: missing.name,
|
|
826
|
+
}
|
|
827
|
+
: undefined;
|
|
828
|
+
if (refusal !== undefined)
|
|
811
829
|
return {
|
|
812
830
|
commitId: commit.clientCommitId,
|
|
813
831
|
table: operation.table,
|
|
814
|
-
|
|
832
|
+
...refusal,
|
|
815
833
|
};
|
|
816
|
-
}
|
|
817
|
-
for (const key of Object.keys(operation.values ?? {})) {
|
|
818
|
-
if (!table.columnIndex.has(key)) {
|
|
819
|
-
return {
|
|
820
|
-
commitId: commit.clientCommitId,
|
|
821
|
-
table: operation.table,
|
|
822
|
-
reason: 'unknown-column',
|
|
823
|
-
column: key,
|
|
824
|
-
};
|
|
825
|
-
}
|
|
826
|
-
}
|
|
827
|
-
// §7.1: an insert-intent operation presents every current column, so a
|
|
828
|
-
// non-nullable column it lacks leaves the commit unencodable.
|
|
829
|
-
if (operation.insert === true) {
|
|
830
|
-
const missing = table.columns.find(
|
|
831
|
-
(column) =>
|
|
832
|
-
!column.nullable && operation.values?.[column.name] === undefined,
|
|
833
|
-
);
|
|
834
|
-
if (missing !== undefined) {
|
|
835
|
-
return {
|
|
836
|
-
commitId: commit.clientCommitId,
|
|
837
|
-
table: operation.table,
|
|
838
|
-
reason: 'missing-required-column',
|
|
839
|
-
column: missing.name,
|
|
840
|
-
};
|
|
841
|
-
}
|
|
842
|
-
}
|
|
843
834
|
}
|
|
844
835
|
return undefined;
|
|
845
836
|
}
|
package/src/progress.ts
CHANGED
|
@@ -14,6 +14,10 @@ export interface SyncProgress {
|
|
|
14
14
|
readonly bytesTotal?: number | undefined;
|
|
15
15
|
readonly rowsProcessed: number;
|
|
16
16
|
readonly rowsTotal?: number | undefined;
|
|
17
|
+
/** The unit's bootstrap rows as the server counted them (SPEC §4.4, §7.7). */
|
|
18
|
+
readonly unitRowsTotal?: number | undefined;
|
|
19
|
+
/** Rows of the unit's bootstrap imported so far, across its sections. */
|
|
20
|
+
readonly unitRowsProcessed?: number | undefined;
|
|
17
21
|
/** Time in this payload's import transactions before COMMIT, in ms. */
|
|
18
22
|
readonly importWriteMs?: number | undefined;
|
|
19
23
|
/** Time committing them and publishing their changes, in ms. */
|
|
@@ -68,7 +72,19 @@ export class ProgressEmitter {
|
|
|
68
72
|
}
|
|
69
73
|
|
|
70
74
|
update(update: Partial<SyncProgress>): void {
|
|
71
|
-
|
|
72
|
-
|
|
75
|
+
const before = this.#snapshot;
|
|
76
|
+
if (before?.state !== 'running') return;
|
|
77
|
+
const next = { ...before, ...update };
|
|
78
|
+
// §7.7: each rise of the payload counter raises the unit's, and the unit
|
|
79
|
+
// total never falls below what was imported.
|
|
80
|
+
if (next.unitRowsProcessed !== undefined) {
|
|
81
|
+
const processed =
|
|
82
|
+
next.unitRowsProcessed +
|
|
83
|
+
Math.max(0, next.rowsProcessed - before.rowsProcessed);
|
|
84
|
+
next.unitRowsProcessed = processed;
|
|
85
|
+
if (next.unitRowsTotal !== undefined)
|
|
86
|
+
next.unitRowsTotal = Math.max(next.unitRowsTotal, processed);
|
|
87
|
+
}
|
|
88
|
+
this.emit(next);
|
|
73
89
|
}
|
|
74
90
|
}
|
|
@@ -11,7 +11,10 @@ type CancelTimer = () => void;
|
|
|
11
11
|
export interface RealtimeSupervisorClient {
|
|
12
12
|
connectRealtime(): Promise<void>;
|
|
13
13
|
disconnectRealtime(): void | Promise<void>;
|
|
14
|
-
|
|
14
|
+
/** Receives `{ skipEmpty: true }` (§8.4); a numeric-budget signature also fits. */
|
|
15
|
+
syncUntilIdle(
|
|
16
|
+
options?: number | { readonly skipEmpty?: boolean },
|
|
17
|
+
): unknown | Promise<unknown>;
|
|
15
18
|
diagnosticsSnapshot():
|
|
16
19
|
| ClientDiagnosticsSnapshot
|
|
17
20
|
| Promise<ClientDiagnosticsSnapshot>;
|
|
@@ -477,7 +480,7 @@ export class RealtimeSupervisor {
|
|
|
477
480
|
return;
|
|
478
481
|
}
|
|
479
482
|
this.#round = Promise.resolve()
|
|
480
|
-
.then(() => this.#client.syncUntilIdle())
|
|
483
|
+
.then(() => this.#client.syncUntilIdle({ skipEmpty: true }))
|
|
481
484
|
.then(
|
|
482
485
|
() => undefined,
|
|
483
486
|
() => undefined,
|
|
@@ -637,7 +640,8 @@ export class RealtimeSupervisor {
|
|
|
637
640
|
});
|
|
638
641
|
this.#transport = true;
|
|
639
642
|
}
|
|
640
|
-
if (generation === this.#generation)
|
|
643
|
+
if (generation === this.#generation)
|
|
644
|
+
await this.#client.syncUntilIdle({ skipEmpty: true });
|
|
641
645
|
caughtUp = generation === this.#generation && this.#transport;
|
|
642
646
|
} catch {
|
|
643
647
|
// A refused socket or a failed catch-up round fails the attempt.
|
package/src/schema.ts
CHANGED
|
@@ -18,7 +18,7 @@ import { ensureFailedOverlaySchema, RETAINED_ROWS } from './failed-overlay';
|
|
|
18
18
|
*/
|
|
19
19
|
import type { RowColumn, RowValue } from '@syncular/core';
|
|
20
20
|
import type { ClientDatabase, SqlRow, SqlValue } from './database';
|
|
21
|
-
import {
|
|
21
|
+
import { invalidRequest, localStateCorrupt } from './errors';
|
|
22
22
|
import { snakeToCamel } from './naming';
|
|
23
23
|
|
|
24
24
|
/** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
|
|
@@ -383,11 +383,10 @@ function sqlType(column: RowColumn): string {
|
|
|
383
383
|
case 'blob_ref':
|
|
384
384
|
return 'TEXT';
|
|
385
385
|
case 'integer':
|
|
386
|
+
case 'boolean':
|
|
386
387
|
return 'INTEGER';
|
|
387
388
|
case 'float':
|
|
388
389
|
return 'REAL';
|
|
389
|
-
case 'boolean':
|
|
390
|
-
return 'INTEGER';
|
|
391
390
|
case 'bytes':
|
|
392
391
|
case 'crdt':
|
|
393
392
|
// §5.10: a crdt column stores its opaque bytes locally, exactly like
|
|
@@ -712,12 +711,14 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
|
|
|
712
711
|
UNITS_TABLE,
|
|
713
712
|
"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",
|
|
714
713
|
);
|
|
715
|
-
// §5.6 applied-segment record, added after the
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
714
|
+
// §5.6 applied-segment record and §7.4.3 restriction, added after the
|
|
715
|
+
// table shipped.
|
|
716
|
+
for (const column of ['applied', 'restriction'])
|
|
717
|
+
try {
|
|
718
|
+
db.exec(`ALTER TABLE ${UNITS_TABLE} ADD COLUMN ${column} TEXT`);
|
|
719
|
+
} catch {
|
|
720
|
+
// column already exists
|
|
721
|
+
}
|
|
721
722
|
// §4.8 window registry: base + value → the unit it holds, the
|
|
722
723
|
// completeness oracle and one of a unit's references (§4.1).
|
|
723
724
|
createTable(
|
|
@@ -743,8 +744,7 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
|
|
|
743
744
|
`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'))`,
|
|
744
745
|
).length > 0
|
|
745
746
|
)
|
|
746
|
-
throw
|
|
747
|
-
'sync.local_corrupt',
|
|
747
|
+
throw localStateCorrupt(
|
|
748
748
|
'a version 3 pending eviction cannot be upgraded',
|
|
749
749
|
);
|
|
750
750
|
db.exec(
|
|
@@ -790,7 +790,7 @@ export function resetLocalReplica(
|
|
|
790
790
|
): string[] {
|
|
791
791
|
const kept = bump
|
|
792
792
|
? pruneUnknownUnits(db, schema, true)
|
|
793
|
-
: { tables: new Set<string>(), units: [] };
|
|
793
|
+
: { tables: new Set<string>(), units: [], restricts: undefined };
|
|
794
794
|
const keptNames = [...kept.tables];
|
|
795
795
|
db.exec(
|
|
796
796
|
`DELETE FROM ${RETAINED_ROWS} WHERE commit_seq IS NOT NULL AND tbl NOT IN(${keptNames.map(() => '?')})`,
|
|
@@ -815,7 +815,7 @@ export function resetLocalReplica(
|
|
|
815
815
|
for (const table of schema.tables.values()) createSyncedTable(db, table);
|
|
816
816
|
for (const table of schema.tables.values())
|
|
817
817
|
for (const index of table.ftsIndexes) createFtsProjection(db, table, index);
|
|
818
|
-
resetUnits(db, kept.units);
|
|
818
|
+
resetUnits(db, kept.units, kept.restricts);
|
|
819
819
|
return [...schema.tables.keys()].filter((name) => !kept.tables.has(name));
|
|
820
820
|
}
|
|
821
821
|
|
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
|
|
13
|
-
|
|
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
|
|
138
|
+
if (typeof raw !== 'string') throw unitStateCorrupt();
|
|
127
139
|
try {
|
|
128
140
|
return JSON.parse(raw);
|
|
129
141
|
} catch {
|
|
130
|
-
throw
|
|
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
|
|
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
|
|
168
|
-
|
|
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
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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(
|
|
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.
|
|
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='[]'
|
|
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
|
-
): {
|
|
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
|
|
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
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
)
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
.
|
|
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 (
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
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
|
|
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
|
|
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());
|
package/src/sync-scheduler.ts
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import type { WakeReason } from '@syncular/core';
|
|
2
|
-
import type { SecurityLifecycle } from './client';
|
|
2
|
+
import type { SecurityLifecycle, SyncIdleOptions } from './client';
|
|
3
|
+
import { invalidRequest } from './errors';
|
|
3
4
|
import type { SyncIntent } from './invalidation';
|
|
4
5
|
|
|
5
6
|
export interface SyncSchedulerClient {
|
|
6
7
|
statusSnapshot(): { readonly syncNeeded: boolean };
|
|
7
8
|
securityLifecycle(): SecurityLifecycle;
|
|
8
|
-
syncUntilIdle(
|
|
9
|
+
syncUntilIdle(options: SyncIdleOptions): Promise<unknown>;
|
|
9
10
|
onSyncNeeded(
|
|
10
11
|
listener: (reason: 'startup' | 'hello' | WakeReason) => void,
|
|
11
12
|
): () => void;
|
|
@@ -14,6 +15,12 @@ export interface SyncSchedulerClient {
|
|
|
14
15
|
|
|
15
16
|
export interface SyncSchedulerOptions {
|
|
16
17
|
readonly maxRounds?: number;
|
|
18
|
+
/**
|
|
19
|
+
* §8.4: milliseconds a queued drive waits before it starts, so the claims
|
|
20
|
+
* and writes of one burst ride in one round. Default 0: the drive starts
|
|
21
|
+
* in the next microtask.
|
|
22
|
+
*/
|
|
23
|
+
readonly coalesceMs?: number;
|
|
17
24
|
readonly onError?: (error: unknown) => void;
|
|
18
25
|
readonly now?: () => number;
|
|
19
26
|
readonly queueMicrotask?: (callback: () => void) => void;
|
|
@@ -30,6 +37,9 @@ export function installSyncScheduler(
|
|
|
30
37
|
client: SyncSchedulerClient,
|
|
31
38
|
options: SyncSchedulerOptions = {},
|
|
32
39
|
): SyncScheduler {
|
|
40
|
+
const coalesceMs = options.coalesceMs ?? 0;
|
|
41
|
+
if (!(Number.isFinite(coalesceMs) && coalesceMs >= 0))
|
|
42
|
+
throw invalidRequest('coalesceMs must be a non-negative finite number');
|
|
33
43
|
const now = options.now ?? Date.now;
|
|
34
44
|
const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
|
|
35
45
|
const schedule =
|
|
@@ -71,12 +81,14 @@ export function installSyncScheduler(
|
|
|
71
81
|
immediatePending = true;
|
|
72
82
|
if (stopped || running || immediateQueued) return;
|
|
73
83
|
immediateQueued = true;
|
|
74
|
-
|
|
84
|
+
const start = (): void => {
|
|
75
85
|
immediateQueued = false;
|
|
76
86
|
if (stopped || !immediatePending) return;
|
|
77
87
|
immediatePending = false;
|
|
78
88
|
run();
|
|
79
|
-
}
|
|
89
|
+
};
|
|
90
|
+
if (coalesceMs > 0) schedule(start, coalesceMs);
|
|
91
|
+
else enqueue(start);
|
|
80
92
|
};
|
|
81
93
|
|
|
82
94
|
const run = (): void => {
|
|
@@ -88,7 +100,7 @@ export function installSyncScheduler(
|
|
|
88
100
|
running = true;
|
|
89
101
|
backgroundReady = false;
|
|
90
102
|
void client
|
|
91
|
-
.syncUntilIdle(options.maxRounds)
|
|
103
|
+
.syncUntilIdle({ maxRounds: options.maxRounds, skipEmpty: true })
|
|
92
104
|
.then((result) => {
|
|
93
105
|
retryDelayMs = 250;
|
|
94
106
|
if (
|