@syncular/client 0.59.0 → 0.60.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 +27 -27
- package/dist/apply.d.ts +6 -5
- package/dist/apply.js +52 -25
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +4 -4
- package/dist/bun-database.js +3 -16
- package/dist/client.d.ts +57 -66
- package/dist/client.js +701 -796
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +1 -1
- package/dist/failed-overlay.js +4 -1
- package/dist/http.js +19 -5
- package/dist/invalidation.d.ts +3 -4
- package/dist/invalidation.js +9 -22
- package/dist/native-bridge.d.ts +7 -16
- package/dist/native-bridge.js +16 -41
- package/dist/node-database.js +16 -25
- package/dist/outbox.js +1 -0
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +15 -6
- package/dist/query-guard.js +38 -6
- package/dist/reactive-store.js +2 -2
- package/dist/remote.js +9 -9
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +28 -12
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +2 -2
- package/dist/transport.d.ts +2 -2
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.js +6 -6
- package/dist/worker-host.d.ts +9 -8
- package/dist/worker-host.js +23 -14
- package/dist/worker-protocol.d.ts +9 -8
- package/package.json +3 -3
- package/src/apply.ts +87 -33
- package/src/authority.ts +31 -17
- package/src/blob.ts +4 -3
- package/src/bun-database.ts +9 -14
- package/src/client.ts +886 -1037
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/errors.ts +1 -1
- package/src/failed-overlay.ts +6 -1
- package/src/http.ts +22 -9
- package/src/invalidation.ts +9 -29
- package/src/native-bridge.ts +22 -58
- package/src/node-database.ts +26 -27
- package/src/outbox.ts +1 -0
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +45 -8
- package/src/reactive-store.ts +2 -2
- package/src/remote.ts +12 -16
- package/src/schema.ts +48 -13
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +2 -2
- package/src/transport.ts +2 -2
- package/src/window.ts +55 -134
- package/src/worker-core.ts +6 -6
- package/src/worker-host.ts +27 -19
- package/src/worker-protocol.ts +8 -8
package/src/remote.ts
CHANGED
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
* through the existing push path without creating a local replica or outbox.
|
|
4
4
|
*/
|
|
5
5
|
import {
|
|
6
|
-
|
|
6
|
+
decodeResponse,
|
|
7
7
|
decodeRemoteOperationResponse,
|
|
8
8
|
decodeRemoteOperationRealtimeMessage,
|
|
9
|
-
|
|
9
|
+
encodeRequest,
|
|
10
10
|
encodeRemoteOperationRequest,
|
|
11
11
|
encodeRemoteOperationRealtimeMessage,
|
|
12
12
|
encodeSparseRow,
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
type PushResultFrame,
|
|
19
19
|
type RowValue,
|
|
20
20
|
type RemoteOperationResponse,
|
|
21
|
+
registrationDigest,
|
|
21
22
|
} from '@syncular/core';
|
|
22
23
|
import type { MutationInput } from './client';
|
|
23
24
|
import type { EncryptionConfig } from './encryption';
|
|
@@ -280,9 +281,9 @@ export class SyncRemoteClient {
|
|
|
280
281
|
'SyncRemoteClient has no sync transport for ordinary commits',
|
|
281
282
|
);
|
|
282
283
|
}
|
|
283
|
-
const acquisition =
|
|
284
|
+
const acquisition = decodeResponse(
|
|
284
285
|
await this.#transport(
|
|
285
|
-
|
|
286
|
+
encodeRequest({
|
|
286
287
|
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
287
288
|
msgKind: 'request',
|
|
288
289
|
frames: [
|
|
@@ -298,16 +299,16 @@ export class SyncRemoteClient {
|
|
|
298
299
|
limitSnapshotRows: 0,
|
|
299
300
|
maxSnapshotPages: 0,
|
|
300
301
|
accept: 0b0011,
|
|
302
|
+
cursor: -1,
|
|
303
|
+
registrationDigest: registrationDigest([]),
|
|
304
|
+
echoDigest: new Uint8Array(),
|
|
301
305
|
},
|
|
302
306
|
],
|
|
303
307
|
}),
|
|
304
308
|
),
|
|
305
309
|
);
|
|
306
310
|
const acquisitionHeader = acquisition.frames[0];
|
|
307
|
-
if (
|
|
308
|
-
acquisition.msgKind !== 'response' ||
|
|
309
|
-
acquisitionHeader?.type !== 'RESP_HEADER'
|
|
310
|
-
) {
|
|
311
|
+
if (acquisitionHeader?.type !== 'RESP_HEADER') {
|
|
311
312
|
throw new ClientSyncError(
|
|
312
313
|
'client.invalid_host_response',
|
|
313
314
|
'remote epoch acquisition returned an invalid response',
|
|
@@ -374,7 +375,7 @@ export class SyncRemoteClient {
|
|
|
374
375
|
}
|
|
375
376
|
return {
|
|
376
377
|
requestId: input.requestId,
|
|
377
|
-
bytes:
|
|
378
|
+
bytes: encodeRequest({
|
|
378
379
|
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
379
380
|
msgKind: 'request',
|
|
380
381
|
frames: [
|
|
@@ -387,6 +388,7 @@ export class SyncRemoteClient {
|
|
|
387
388
|
{
|
|
388
389
|
type: 'PUSH_COMMIT',
|
|
389
390
|
clientCommitId: input.requestId,
|
|
391
|
+
clientSeq: 0,
|
|
390
392
|
operations,
|
|
391
393
|
},
|
|
392
394
|
],
|
|
@@ -403,13 +405,7 @@ export class SyncRemoteClient {
|
|
|
403
405
|
'SyncRemoteClient has no sync transport for ordinary commits',
|
|
404
406
|
);
|
|
405
407
|
}
|
|
406
|
-
const response =
|
|
407
|
-
if (response.msgKind !== 'response') {
|
|
408
|
-
throw new ClientSyncError(
|
|
409
|
-
'client.invalid_host_response',
|
|
410
|
-
'remote commit transport returned a non-response SSP2 message',
|
|
411
|
-
);
|
|
412
|
-
}
|
|
408
|
+
const response = decodeResponse(await this.#transport(prepared.bytes));
|
|
413
409
|
const error = response.frames.find((frame) => frame.type === 'ERROR');
|
|
414
410
|
if (error?.type === 'ERROR') {
|
|
415
411
|
throw new ClientSyncError(error.code, error.message, error.retryable);
|
package/src/schema.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { PENDING_EVICTIONS } from './window';
|
|
|
3
3
|
import { WINDOWS_TABLE } from './window';
|
|
4
4
|
import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox';
|
|
5
5
|
import { OUTCOMES_TABLE } from './outcomes';
|
|
6
|
-
import {
|
|
6
|
+
import { META_TABLE, resetUnits, UNITS_TABLE } from './state';
|
|
7
7
|
import { ensureFailedOverlaySchema } from './failed-overlay';
|
|
8
8
|
/**
|
|
9
9
|
* Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
|
|
@@ -13,7 +13,7 @@ import { ensureFailedOverlaySchema } from './failed-overlay';
|
|
|
13
13
|
*/
|
|
14
14
|
import type { RowColumn, RowValue } from '@syncular/core';
|
|
15
15
|
import type { ClientDatabase, SqlRow, SqlValue } from './database';
|
|
16
|
-
import { invalidRequest } from './errors';
|
|
16
|
+
import { ClientSyncError, invalidRequest } from './errors';
|
|
17
17
|
import { snakeToCamel } from './naming';
|
|
18
18
|
|
|
19
19
|
/** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
|
|
@@ -592,10 +592,20 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
|
|
|
592
592
|
db.exec(
|
|
593
593
|
`INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`,
|
|
594
594
|
);
|
|
595
|
+
const outboxExisted =
|
|
596
|
+
db.query(
|
|
597
|
+
`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${OUTBOX_TABLE}'`,
|
|
598
|
+
).length > 0;
|
|
595
599
|
createTable(
|
|
596
600
|
OUTBOX_TABLE,
|
|
597
601
|
'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL',
|
|
598
602
|
);
|
|
603
|
+
// §7.1: `outboxId` names the outbox sequence. A new outbox table starts
|
|
604
|
+
// a new sequence, so it replaces the id in the same transaction.
|
|
605
|
+
db.exec(
|
|
606
|
+
`INSERT OR ${outboxExisted ? 'IGNORE' : 'REPLACE'} INTO ${META_TABLE}(key,value)VALUES('outboxId',?)`,
|
|
607
|
+
[crypto.randomUUID()],
|
|
608
|
+
);
|
|
599
609
|
createTable(
|
|
600
610
|
OUTBOX_IMAGES,
|
|
601
611
|
'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)',
|
|
@@ -627,22 +637,47 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
|
|
|
627
637
|
`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`,
|
|
628
638
|
);
|
|
629
639
|
createTable(
|
|
630
|
-
|
|
631
|
-
"id TEXT PRIMARY KEY,
|
|
640
|
+
UNITS_TABLE,
|
|
641
|
+
"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",
|
|
632
642
|
);
|
|
633
|
-
// §4.8 window registry:
|
|
634
|
-
//
|
|
635
|
-
// (a unit's omission from the next pull unregisters it, §4.1).
|
|
643
|
+
// §4.8 window registry: base + value → the unit it holds, the
|
|
644
|
+
// completeness oracle and one of a unit's references (§4.1).
|
|
636
645
|
createTable(
|
|
637
646
|
WINDOWS_TABLE,
|
|
638
647
|
'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
|
|
639
648
|
);
|
|
640
|
-
// §4.8 E1: units that left
|
|
641
|
-
// Retried when the outbox drains; cancelled
|
|
649
|
+
// §4.8 E1: per-table scopes of units that left with pinned or unevicted
|
|
650
|
+
// rows. Retried when the outbox drains; cancelled when the unit re-enters.
|
|
642
651
|
createTable(
|
|
643
652
|
PENDING_EVICTIONS,
|
|
644
|
-
'
|
|
653
|
+
'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)',
|
|
645
654
|
);
|
|
655
|
+
// §9: a replica written under wire version 3 keeps its outbox, journal,
|
|
656
|
+
// rows and pending evictions and registers its units fresh. Its
|
|
657
|
+
// subscriptions, cursors, echoes, resume tokens and window entries go.
|
|
658
|
+
const legacyEvictions = '_syncular_window_pending_evict';
|
|
659
|
+
if (
|
|
660
|
+
db.query(
|
|
661
|
+
`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${legacyEvictions}'`,
|
|
662
|
+
).length > 0
|
|
663
|
+
) {
|
|
664
|
+
if (
|
|
665
|
+
db.query(
|
|
666
|
+
`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'))`,
|
|
667
|
+
).length > 0
|
|
668
|
+
)
|
|
669
|
+
throw new ClientSyncError(
|
|
670
|
+
'sync.local_corrupt',
|
|
671
|
+
'a version 3 pending eviction cannot be upgraded',
|
|
672
|
+
);
|
|
673
|
+
db.exec(
|
|
674
|
+
`INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`,
|
|
675
|
+
);
|
|
676
|
+
db.exec(`DROP TABLE ${legacyEvictions}`);
|
|
677
|
+
db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
|
|
678
|
+
db.exec(`DELETE FROM ${WINDOWS_TABLE}`);
|
|
679
|
+
resetUnits(db);
|
|
680
|
+
}
|
|
646
681
|
});
|
|
647
682
|
}
|
|
648
683
|
|
|
@@ -663,10 +698,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
|
|
|
663
698
|
* generated schema created — discovered from `sqlite_master`, since a
|
|
664
699
|
* bump may add/remove tables) and recreate the synced tables from the
|
|
665
700
|
* NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
|
|
666
|
-
*
|
|
701
|
+
* units, blob cache) are preserved. RFC 0005's container is not
|
|
667
702
|
* reachable from here: it lives in its own database file, so this reset cannot
|
|
668
703
|
* see or destroy it. Caller owns the surrounding transaction and the
|
|
669
|
-
*
|
|
704
|
+
* unit-state reset (state.ts).
|
|
670
705
|
*/
|
|
671
706
|
export function dropAndRecreateSyncedTables(
|
|
672
707
|
db: ClientDatabase,
|
|
@@ -821,7 +856,7 @@ export type JsonRowValue =
|
|
|
821
856
|
| null
|
|
822
857
|
| { readonly $bytes: string };
|
|
823
858
|
|
|
824
|
-
function bytesToHex(bytes: Uint8Array): string {
|
|
859
|
+
export function bytesToHex(bytes: Uint8Array): string {
|
|
825
860
|
let out = '';
|
|
826
861
|
for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
|
|
827
862
|
return out;
|
package/src/state.ts
CHANGED
|
@@ -1,119 +1,238 @@
|
|
|
1
1
|
export const META_TABLE = '_syncular_meta';
|
|
2
2
|
import { PENDING_EVICTIONS } from './window';
|
|
3
3
|
import { WINDOWS_TABLE } from './window';
|
|
4
|
-
export const
|
|
4
|
+
export const UNITS_TABLE = '_syncular_units';
|
|
5
5
|
/**
|
|
6
|
-
* Durable
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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.
|
|
10
11
|
*/
|
|
11
|
-
import type { ScopeMap } from '@syncular/core';
|
|
12
|
+
import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
|
|
12
13
|
import { ClientSyncError } from './errors';
|
|
13
|
-
import type { CompiledClientSchema } from './schema';
|
|
14
|
+
import type { CompiledClientSchema, CompiledClientTable } from './schema';
|
|
14
15
|
import type { ClientDatabase } from './database';
|
|
15
16
|
import type { LocalRevision } from './invalidation';
|
|
16
17
|
|
|
17
18
|
export const LOCAL_REVISION_KEY = 'localRevision';
|
|
19
|
+
/** §4.5 replica cursor; absent means `-1`. */
|
|
20
|
+
export const REPLICA_CURSOR_KEY = 'replicaCursor';
|
|
21
|
+
/** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
|
|
22
|
+
export const ECHO_DIGEST_KEY = 'echoDigest';
|
|
23
|
+
/** Hex of the registration digest of the list the server stores (§4.1). */
|
|
24
|
+
export const REGISTERED_DIGEST_KEY = 'registrationDigest';
|
|
18
25
|
const MAX_U64 = 18_446_744_073_709_551_615n;
|
|
19
26
|
|
|
20
|
-
export type
|
|
27
|
+
export type UnitStatus = 'active' | 'revoked' | 'failed';
|
|
21
28
|
|
|
22
|
-
export interface
|
|
29
|
+
export interface UnitRecord {
|
|
30
|
+
/** §4.1: derived from the scope map. */
|
|
23
31
|
readonly id: string;
|
|
24
|
-
readonly
|
|
25
|
-
/**
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
readonly
|
|
29
|
-
/**
|
|
30
|
-
readonly
|
|
32
|
+
readonly scopes: UnitScopes;
|
|
33
|
+
/** An explicit `subscribe` holds the unit; window bases hold it through
|
|
34
|
+
* the window registry (§4.1 references). */
|
|
35
|
+
readonly explicit: boolean;
|
|
36
|
+
readonly status: UnitStatus;
|
|
37
|
+
/** §10 code when not active, or `sync.cursor_expired` after a reset. */
|
|
38
|
+
readonly reasonCode?: string | undefined;
|
|
39
|
+
/** Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
|
|
40
|
+
* post-bootstrap cursor `P`. */
|
|
41
|
+
readonly cursor?: number | undefined;
|
|
31
42
|
/** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
|
|
32
|
-
readonly bootstrapState?: string;
|
|
33
|
-
/**
|
|
34
|
-
readonly
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
readonly reasonCode?: string;
|
|
43
|
+
readonly bootstrapState?: string | undefined;
|
|
44
|
+
/** Tables that received a segment in the current bootstrap (§5.6). */
|
|
45
|
+
readonly seeded: readonly string[];
|
|
46
|
+
/** The echo persisted at the last `SUB_END` (§4.4). */
|
|
47
|
+
readonly echo?: readonly FencedRecord[] | undefined;
|
|
38
48
|
}
|
|
39
49
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
50
|
+
/** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
|
|
51
|
+
export function bootstrapping(unit: UnitRecord): boolean {
|
|
52
|
+
return (
|
|
53
|
+
unit.cursor !== undefined &&
|
|
54
|
+
(unit.cursor < 0 || unit.bootstrapState !== undefined)
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
|
|
59
|
+
export function owning(unit: UnitRecord): boolean {
|
|
60
|
+
return (
|
|
61
|
+
unit.status === 'active' && unit.echo !== undefined && !bootstrapping(unit)
|
|
62
|
+
);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** §4.1: the unit covers every table declaring all of its variables. */
|
|
66
|
+
export function covers(
|
|
67
|
+
table: CompiledClientTable,
|
|
68
|
+
scopes: UnitScopes,
|
|
69
|
+
): boolean {
|
|
70
|
+
return Object.keys(scopes).every((variable) =>
|
|
71
|
+
table.scopeColumnByVariable.has(variable),
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* §4.4: the effective scopes of the (unit, table) pair under `echo`: the
|
|
77
|
+
* scope map as one-element lists plus the fenced lists. Undefined when the
|
|
78
|
+
* fence revoked the pair.
|
|
79
|
+
*/
|
|
80
|
+
export function pairScopes(
|
|
81
|
+
scopes: UnitScopes,
|
|
82
|
+
table: string,
|
|
83
|
+
echo: readonly FencedRecord[] | undefined,
|
|
84
|
+
): ScopeMap | undefined {
|
|
85
|
+
const fenced = echo?.find((record) => record.table === table);
|
|
86
|
+
if (fenced?.status === 'revoked') return undefined;
|
|
87
|
+
const effective: ScopeMap = { ...fenced?.scopes };
|
|
88
|
+
for (const [variable, value] of Object.entries(scopes))
|
|
89
|
+
effective[variable] = [value];
|
|
90
|
+
return effective;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** §3.3 row ownership: the pair scopes of every owner of `table` but one.
|
|
94
|
+
* A bootstrapping unit owns the tables its current bootstrap seeded. */
|
|
95
|
+
export function unitOwners(
|
|
96
|
+
units: readonly UnitRecord[],
|
|
97
|
+
table: CompiledClientTable,
|
|
98
|
+
exceptId: string,
|
|
99
|
+
): ScopeMap[] {
|
|
100
|
+
return units.flatMap((unit) => {
|
|
101
|
+
const scopes =
|
|
102
|
+
unit.id !== exceptId &&
|
|
103
|
+
(owning(unit) ||
|
|
104
|
+
(unit.status === 'active' &&
|
|
105
|
+
unit.echo !== undefined &&
|
|
106
|
+
unit.seeded.includes(table.name))) &&
|
|
107
|
+
covers(table, unit.scopes)
|
|
108
|
+
? pairScopes(unit.scopes, table.name, unit.echo)
|
|
109
|
+
: undefined;
|
|
110
|
+
return scopes === undefined ? [] : [scopes];
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** A unit row; every persisted field must have its stored type and shape,
|
|
115
|
+
* otherwise the row is `sync.local_corrupt` (§7.5). */
|
|
116
|
+
function rowToRecord(row: Record<string, unknown>): UnitRecord {
|
|
117
|
+
const corrupt = () =>
|
|
118
|
+
new ClientSyncError(
|
|
119
|
+
'sync.local_corrupt',
|
|
120
|
+
'persisted unit state is invalid',
|
|
121
|
+
);
|
|
122
|
+
const json = (raw: unknown): unknown => {
|
|
123
|
+
if (typeof raw !== 'string') throw corrupt();
|
|
124
|
+
try {
|
|
125
|
+
return JSON.parse(raw);
|
|
126
|
+
} catch {
|
|
127
|
+
throw corrupt();
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
const isMap = (value: unknown): value is Record<string, unknown> =>
|
|
131
|
+
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
132
|
+
const isStrings = (value: unknown): value is string[] =>
|
|
133
|
+
Array.isArray(value) && value.every((item) => typeof item === 'string');
|
|
134
|
+
const optionalText = (value: unknown) => {
|
|
135
|
+
if (value !== null && typeof value !== 'string') throw corrupt();
|
|
136
|
+
return value ?? undefined;
|
|
61
137
|
};
|
|
138
|
+
const scopes = json(row.scopes);
|
|
139
|
+
const seeded = json(row.seeded);
|
|
140
|
+
const echo = row.echo === null ? undefined : json(row.echo);
|
|
141
|
+
const { id, status, cursor } = row;
|
|
142
|
+
if (
|
|
143
|
+
typeof id !== 'string' ||
|
|
144
|
+
!isMap(scopes) ||
|
|
145
|
+
!Object.values(scopes).every((value) => typeof value === 'string') ||
|
|
146
|
+
(status !== 'active' && status !== 'revoked' && status !== 'failed') ||
|
|
147
|
+
(cursor !== null && !Number.isInteger(cursor)) ||
|
|
148
|
+
!isStrings(seeded) ||
|
|
149
|
+
(echo !== undefined &&
|
|
150
|
+
!(
|
|
151
|
+
Array.isArray(echo) &&
|
|
152
|
+
echo.every(
|
|
153
|
+
(record) =>
|
|
154
|
+
isMap(record) &&
|
|
155
|
+
typeof record.table === 'string' &&
|
|
156
|
+
(record.status === 'active' || record.status === 'revoked') &&
|
|
157
|
+
isMap(record.scopes) &&
|
|
158
|
+
Object.values(record.scopes).every(isStrings),
|
|
159
|
+
)
|
|
160
|
+
))
|
|
161
|
+
)
|
|
162
|
+
throw corrupt();
|
|
163
|
+
const record: { -readonly [K in keyof UnitRecord]: UnitRecord[K] } = {
|
|
164
|
+
id,
|
|
165
|
+
scopes: scopes as UnitScopes,
|
|
166
|
+
explicit: row.explicit === 1,
|
|
167
|
+
status,
|
|
168
|
+
seeded,
|
|
169
|
+
};
|
|
170
|
+
const reasonCode = optionalText(row.reason_code);
|
|
171
|
+
if (reasonCode !== undefined) record.reasonCode = reasonCode;
|
|
172
|
+
if (typeof cursor === 'number') record.cursor = cursor;
|
|
173
|
+
const bootstrapState = optionalText(row.bootstrap_state);
|
|
174
|
+
if (bootstrapState !== undefined) record.bootstrapState = bootstrapState;
|
|
175
|
+
if (echo !== undefined) record.echo = echo as FencedRecord[];
|
|
176
|
+
return record;
|
|
62
177
|
}
|
|
63
178
|
|
|
64
|
-
|
|
179
|
+
/** Every unit in registration order (§4.1). */
|
|
180
|
+
export function loadUnits(db: ClientDatabase): UnitRecord[] {
|
|
65
181
|
return db
|
|
66
|
-
.query(`SELECT * FROM ${
|
|
182
|
+
.query(`SELECT * FROM ${UNITS_TABLE} ORDER BY rowid ASC`)
|
|
67
183
|
.map(rowToRecord);
|
|
68
184
|
}
|
|
69
185
|
|
|
70
|
-
export function
|
|
186
|
+
export function getUnit(
|
|
71
187
|
db: ClientDatabase,
|
|
72
188
|
id: string,
|
|
73
|
-
):
|
|
74
|
-
const row = db.query(`SELECT * FROM ${
|
|
75
|
-
id,
|
|
76
|
-
])[0];
|
|
189
|
+
): UnitRecord | undefined {
|
|
190
|
+
const row = db.query(`SELECT * FROM ${UNITS_TABLE} WHERE id=?`, [id])[0];
|
|
77
191
|
return row === undefined ? undefined : rowToRecord(row);
|
|
78
192
|
}
|
|
79
193
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
record: SubscriptionRecord,
|
|
83
|
-
): void {
|
|
194
|
+
/** Insert or update in place: an update keeps the registration order. */
|
|
195
|
+
export function saveUnit(db: ClientDatabase, record: UnitRecord): void {
|
|
84
196
|
db.exec(
|
|
85
|
-
`INSERT
|
|
197
|
+
`INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)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`,
|
|
86
198
|
[
|
|
87
199
|
record.id,
|
|
88
|
-
record.table,
|
|
89
200
|
JSON.stringify(record.scopes),
|
|
90
|
-
record.
|
|
91
|
-
record.cursor,
|
|
92
|
-
record.bootstrapState ?? null,
|
|
93
|
-
record.effectiveScopes === undefined
|
|
94
|
-
? null
|
|
95
|
-
: JSON.stringify(record.effectiveScopes),
|
|
201
|
+
record.explicit ? 1 : 0,
|
|
96
202
|
record.status,
|
|
97
203
|
record.reasonCode ?? null,
|
|
204
|
+
record.cursor ?? null,
|
|
205
|
+
record.bootstrapState ?? null,
|
|
206
|
+
JSON.stringify(record.seeded),
|
|
207
|
+
record.echo === undefined ? null : JSON.stringify(record.echo),
|
|
98
208
|
],
|
|
99
209
|
);
|
|
100
210
|
}
|
|
101
211
|
|
|
102
|
-
export function
|
|
103
|
-
db.exec(`DELETE FROM ${
|
|
212
|
+
export function deleteUnit(db: ClientDatabase, id: string): void {
|
|
213
|
+
db.exec(`DELETE FROM ${UNITS_TABLE} WHERE id=?`, [id]);
|
|
104
214
|
}
|
|
105
215
|
|
|
106
216
|
/**
|
|
107
|
-
* §7.4.3 reset
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
* subscriptions the app still wants. Caller owns the transaction.
|
|
217
|
+
* §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
|
|
218
|
+
* registrations (the app's declared intent) and discard every synced state,
|
|
219
|
+
* so the next round sends the list and fresh-bootstraps every unit. Caller
|
|
220
|
+
* owns the transaction.
|
|
112
221
|
*/
|
|
113
|
-
export function
|
|
222
|
+
export function resetUnits(db: ClientDatabase): void {
|
|
114
223
|
db.exec(
|
|
115
|
-
`UPDATE ${
|
|
224
|
+
`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`,
|
|
116
225
|
);
|
|
226
|
+
db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
|
|
227
|
+
REPLICA_CURSOR_KEY,
|
|
228
|
+
ECHO_DIGEST_KEY,
|
|
229
|
+
REGISTERED_DIGEST_KEY,
|
|
230
|
+
]);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** §4.5: the replica cursor, `-1` while no unit is live. */
|
|
234
|
+
export function replicaCursor(db: ClientDatabase): number {
|
|
235
|
+
return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
|
|
117
236
|
}
|
|
118
237
|
|
|
119
238
|
type ScopeDeclarations = Record<
|
|
@@ -121,8 +240,8 @@ type ScopeDeclarations = Record<
|
|
|
121
240
|
Record<string, readonly [string, string]>
|
|
122
241
|
>;
|
|
123
242
|
|
|
124
|
-
/**
|
|
125
|
-
export function
|
|
243
|
+
/** §7.4.3 declaration evidence, persisted beside the schema marker. */
|
|
244
|
+
export function saveUnitScopeSchema(
|
|
126
245
|
db: ClientDatabase,
|
|
127
246
|
schema: CompiledClientSchema,
|
|
128
247
|
): void {
|
|
@@ -138,76 +257,78 @@ export function saveSubscriptionScopeSchema(
|
|
|
138
257
|
setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
|
|
139
258
|
}
|
|
140
259
|
|
|
141
|
-
/**
|
|
142
|
-
|
|
260
|
+
/**
|
|
261
|
+
* Drop units that cover no table of the running schema, with their window
|
|
262
|
+
* registry rows and pending evictions; never translate scopes. At a bump
|
|
263
|
+
* (§7.4.3) a unit also needs every variable unchanged in prefix and column on
|
|
264
|
+
* every table it covered before.
|
|
265
|
+
*/
|
|
266
|
+
export function pruneUnknownUnits(
|
|
143
267
|
db: ClientDatabase,
|
|
144
|
-
subscriptions: readonly SubscriptionRecord[],
|
|
145
268
|
schema: CompiledClientSchema,
|
|
146
269
|
bump = false,
|
|
147
|
-
):
|
|
270
|
+
): void {
|
|
148
271
|
const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
|
|
149
272
|
const previous =
|
|
150
273
|
stored === undefined
|
|
151
274
|
? undefined
|
|
152
275
|
: (JSON.parse(stored) as ScopeDeclarations);
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
const
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
276
|
+
// A table keeps the variables' meaning when each has the same prefix and
|
|
277
|
+
// column as before. An old binary stored no declaration evidence; matching
|
|
278
|
+
// names cannot prove unchanged meaning, so the app registers again.
|
|
279
|
+
const unchanged = (name: string, variables: readonly string[]): boolean => {
|
|
280
|
+
const old = previous?.[name];
|
|
281
|
+
const table = schema.tables.get(name);
|
|
282
|
+
return (
|
|
283
|
+
old !== undefined &&
|
|
284
|
+
table !== undefined &&
|
|
285
|
+
variables.every(
|
|
286
|
+
(variable) =>
|
|
287
|
+
old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
|
|
288
|
+
old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
|
|
289
|
+
)
|
|
290
|
+
);
|
|
291
|
+
};
|
|
292
|
+
const compatible = (scopes: UnitScopes): boolean => {
|
|
293
|
+
const variables = Object.keys(scopes);
|
|
294
|
+
if (![...schema.tables.values()].some((table) => covers(table, scopes)))
|
|
162
295
|
return false;
|
|
163
296
|
if (!bump) return true;
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
variables.length === 0
|
|
170
|
-
? [
|
|
171
|
-
...new Set([
|
|
172
|
-
...Object.keys(old),
|
|
173
|
-
...table.scopeColumnByVariable.keys(),
|
|
174
|
-
]),
|
|
175
|
-
]
|
|
176
|
-
: variables;
|
|
177
|
-
return compared.every(
|
|
178
|
-
(variable) =>
|
|
179
|
-
old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
|
|
180
|
-
old[variable]?.[1] === table.scopeColumnByVariable.get(variable),
|
|
297
|
+
if (previous === undefined) return false;
|
|
298
|
+
return Object.entries(previous).every(
|
|
299
|
+
([name, old]) =>
|
|
300
|
+
!variables.every((variable) => old[variable] !== undefined) ||
|
|
301
|
+
unchanged(name, variables),
|
|
181
302
|
);
|
|
182
303
|
};
|
|
183
|
-
const
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
.
|
|
187
|
-
.map((record) => record.id),
|
|
304
|
+
const stale = new Set(
|
|
305
|
+
loadUnits(db)
|
|
306
|
+
.filter((unit) => !compatible(unit.scopes))
|
|
307
|
+
.map((unit) => unit.id),
|
|
188
308
|
);
|
|
189
|
-
//
|
|
190
|
-
//
|
|
309
|
+
// A shrunk window's deferred eviction outlives its unit row and keeps its
|
|
310
|
+
// per-table scopes. A table the schema no longer has cannot be evicted, and
|
|
311
|
+
// at a bump a table whose scope declarations changed must not be evicted by
|
|
312
|
+
// the outdated rule.
|
|
191
313
|
for (const row of db.query(
|
|
192
|
-
`SELECT
|
|
314
|
+
`SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`,
|
|
193
315
|
)) {
|
|
316
|
+
const table = String(row.tbl);
|
|
194
317
|
if (
|
|
195
|
-
!
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
318
|
+
!schema.tables.has(table) ||
|
|
319
|
+
(bump &&
|
|
320
|
+
!unchanged(
|
|
321
|
+
table,
|
|
322
|
+
Object.keys(JSON.parse(String(row.effective_scopes)) as ScopeMap),
|
|
323
|
+
))
|
|
199
324
|
)
|
|
200
|
-
|
|
325
|
+
stale.add(String(row.unit_id));
|
|
326
|
+
}
|
|
327
|
+
for (const id of stale) {
|
|
328
|
+
db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
|
|
329
|
+
db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
|
|
330
|
+
deleteUnit(db, id);
|
|
201
331
|
}
|
|
202
|
-
if (staleIds.size === 0) return retained;
|
|
203
|
-
db.transaction(() => {
|
|
204
|
-
for (const id of staleIds) {
|
|
205
|
-
db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
|
|
206
|
-
db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
|
|
207
|
-
db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
|
|
208
|
-
}
|
|
209
|
-
});
|
|
210
|
-
return retained;
|
|
211
332
|
}
|
|
212
333
|
|
|
213
334
|
export function getMeta(db: ClientDatabase, key: string): string | undefined {
|