@syncular/client 0.58.0 → 0.60.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 +34 -34
- package/dist/apply.d.ts +24 -14
- package/dist/apply.js +119 -70
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +15 -0
- package/dist/client.d.ts +83 -75
- package/dist/client.js +982 -910
- package/dist/database.d.ts +5 -0
- 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/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +5 -1
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +6 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +67 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +14 -14
- package/dist/invalidation.js +24 -48
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +226 -0
- package/dist/native-bridge.js +764 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +21 -1
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +20 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +34 -24
- package/dist/query-guard.js +61 -186
- package/dist/reactive-store.js +55 -13
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +19 -23
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +43 -22
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +83 -75
- package/dist/worker-host.d.ts +19 -13
- package/dist/worker-host.js +75 -18
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +15 -10
- package/package.json +11 -3
- package/src/apply.ts +176 -86
- package/src/authority.ts +31 -17
- package/src/blob.ts +28 -15
- package/src/bun-database.ts +24 -0
- package/src/client.ts +1282 -1217
- package/src/database.ts +5 -0
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/encryption.ts +10 -5
- package/src/errors.ts +9 -1
- package/src/failed-overlay.ts +8 -7
- package/src/http.ts +95 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +26 -61
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1153 -0
- package/src/node-database.ts +32 -1
- package/src/outbox.ts +20 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +77 -177
- package/src/reactive-store.ts +52 -12
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +23 -31
- package/src/schema.ts +67 -25
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/window.ts +55 -134
- package/src/worker-core.ts +97 -77
- package/src/worker-host.ts +76 -32
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +14 -10
package/dist/remote.js
CHANGED
|
@@ -2,18 +2,15 @@
|
|
|
2
2
|
* Database-less SSP2 producer (§6.10). It prepares and sends ordinary commits
|
|
3
3
|
* through the existing push path without creating a local replica or outbox.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import { decodeResponse, decodeRemoteOperationResponse, decodeRemoteOperationRealtimeMessage, encodeRequest, encodeRemoteOperationRequest, encodeRemoteOperationRealtimeMessage, encodeSparseRow, normalizeRejectionDetails, PROTOCOL_WIRE_VERSION, registrationDigest, } from '@syncular/core';
|
|
6
6
|
import { encryptRowValues } from './encryption.js';
|
|
7
|
-
import { ClientSyncError } from './errors.js';
|
|
7
|
+
import { ClientSyncError, invalidRequest } from './errors.js';
|
|
8
8
|
import { compileClientSchema, recordToRowValues, normalizeRecordKeys, coerceSqlRepresentation, } from './schema.js';
|
|
9
9
|
export function remoteCommand(id) {
|
|
10
10
|
if (id.length === 0)
|
|
11
|
-
throw
|
|
11
|
+
throw invalidRequest('remote command id must be non-empty');
|
|
12
12
|
return { id };
|
|
13
13
|
}
|
|
14
|
-
function invalid(message) {
|
|
15
|
-
return new ClientSyncError('sync.invalid_request', message);
|
|
16
|
-
}
|
|
17
14
|
function operationResponse(bytes) {
|
|
18
15
|
let response;
|
|
19
16
|
try {
|
|
@@ -86,10 +83,10 @@ export class SyncRemoteClient {
|
|
|
86
83
|
#logEpoch;
|
|
87
84
|
constructor(config) {
|
|
88
85
|
if (config.clientId.length === 0) {
|
|
89
|
-
throw
|
|
86
|
+
throw invalidRequest('SyncRemoteClient clientId must be non-empty');
|
|
90
87
|
}
|
|
91
88
|
if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
|
|
92
|
-
throw
|
|
89
|
+
throw invalidRequest('SyncRemoteClient logEpoch must be non-empty');
|
|
93
90
|
}
|
|
94
91
|
this.#schema =
|
|
95
92
|
config.schema === undefined
|
|
@@ -108,7 +105,7 @@ export class SyncRemoteClient {
|
|
|
108
105
|
throw new ClientSyncError('client.remote_schema_unconfigured', 'SyncRemoteClient needs a schema to prepare ordinary commits');
|
|
109
106
|
}
|
|
110
107
|
if (input.requestId.length === 0) {
|
|
111
|
-
throw
|
|
108
|
+
throw invalidRequest('remote commit requestId must be non-empty');
|
|
112
109
|
}
|
|
113
110
|
if (input.mutations.length === 0) {
|
|
114
111
|
throw new ClientSyncError('sync.empty_commit', 'a remote commit must carry at least one mutation (§6.1)');
|
|
@@ -120,7 +117,7 @@ export class SyncRemoteClient {
|
|
|
120
117
|
if (this.#transport === undefined) {
|
|
121
118
|
throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
|
|
122
119
|
}
|
|
123
|
-
const acquisition =
|
|
120
|
+
const acquisition = decodeResponse(await this.#transport(encodeRequest({
|
|
124
121
|
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
125
122
|
msgKind: 'request',
|
|
126
123
|
frames: [
|
|
@@ -136,13 +133,14 @@ export class SyncRemoteClient {
|
|
|
136
133
|
limitSnapshotRows: 0,
|
|
137
134
|
maxSnapshotPages: 0,
|
|
138
135
|
accept: 0b0011,
|
|
136
|
+
cursor: -1,
|
|
137
|
+
registrationDigest: registrationDigest([]),
|
|
138
|
+
echoDigest: new Uint8Array(),
|
|
139
139
|
},
|
|
140
140
|
],
|
|
141
141
|
})));
|
|
142
142
|
const acquisitionHeader = acquisition.frames[0];
|
|
143
|
-
if (
|
|
144
|
-
acquisitionHeader?.type !== 'RESP_HEADER' ||
|
|
145
|
-
acquisitionHeader.logEpoch === undefined) {
|
|
143
|
+
if (acquisitionHeader?.type !== 'RESP_HEADER') {
|
|
146
144
|
throw new ClientSyncError('client.invalid_host_response', 'remote epoch acquisition returned an invalid response');
|
|
147
145
|
}
|
|
148
146
|
logEpoch = acquisitionHeader.logEpoch;
|
|
@@ -152,11 +150,11 @@ export class SyncRemoteClient {
|
|
|
152
150
|
for (const mutation of input.mutations) {
|
|
153
151
|
const table = schema.tables.get(mutation.table);
|
|
154
152
|
if (table === undefined) {
|
|
155
|
-
throw
|
|
153
|
+
throw invalidRequest('remote commit targets an unknown table');
|
|
156
154
|
}
|
|
157
155
|
if (mutation.op === 'delete') {
|
|
158
156
|
if (mutation.rowId.length === 0) {
|
|
159
|
-
throw
|
|
157
|
+
throw invalidRequest('remote delete rowId must be non-empty');
|
|
160
158
|
}
|
|
161
159
|
operations.push({
|
|
162
160
|
table: mutation.table,
|
|
@@ -182,9 +180,9 @@ export class SyncRemoteClient {
|
|
|
182
180
|
? String(rawRowId)
|
|
183
181
|
: undefined;
|
|
184
182
|
if (rowId === undefined) {
|
|
185
|
-
throw
|
|
183
|
+
throw invalidRequest('remote upsert requires a non-empty primary key');
|
|
186
184
|
}
|
|
187
|
-
if (
|
|
185
|
+
if (table.hasEncryptedColumns) {
|
|
188
186
|
values = await encryptRowValues(this.#encryption, table, rowId, values);
|
|
189
187
|
}
|
|
190
188
|
operations.push({
|
|
@@ -199,7 +197,7 @@ export class SyncRemoteClient {
|
|
|
199
197
|
}
|
|
200
198
|
return {
|
|
201
199
|
requestId: input.requestId,
|
|
202
|
-
bytes:
|
|
200
|
+
bytes: encodeRequest({
|
|
203
201
|
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
204
202
|
msgKind: 'request',
|
|
205
203
|
frames: [
|
|
@@ -212,6 +210,7 @@ export class SyncRemoteClient {
|
|
|
212
210
|
{
|
|
213
211
|
type: 'PUSH_COMMIT',
|
|
214
212
|
clientCommitId: input.requestId,
|
|
213
|
+
clientSeq: 0,
|
|
215
214
|
operations,
|
|
216
215
|
},
|
|
217
216
|
],
|
|
@@ -222,10 +221,7 @@ export class SyncRemoteClient {
|
|
|
222
221
|
if (this.#transport === undefined) {
|
|
223
222
|
throw new ClientSyncError('client.remote_sync_unconfigured', 'SyncRemoteClient has no sync transport for ordinary commits');
|
|
224
223
|
}
|
|
225
|
-
const response =
|
|
226
|
-
if (response.msgKind !== 'response') {
|
|
227
|
-
throw new ClientSyncError('client.invalid_host_response', 'remote commit transport returned a non-response SSP2 message');
|
|
228
|
-
}
|
|
224
|
+
const response = decodeResponse(await this.#transport(prepared.bytes));
|
|
229
225
|
const error = response.frames.find((frame) => frame.type === 'ERROR');
|
|
230
226
|
if (error?.type === 'ERROR') {
|
|
231
227
|
throw new ClientSyncError(error.code, error.message, error.retryable);
|
|
@@ -288,7 +284,7 @@ export class SyncRemoteClient {
|
|
|
288
284
|
throw new ClientSyncError('client.remote_operations_unconfigured', 'SyncRemoteClient has no remote operation transport');
|
|
289
285
|
}
|
|
290
286
|
if (requestId.length === 0) {
|
|
291
|
-
throw
|
|
287
|
+
throw invalidRequest('remote command requestId must be non-empty');
|
|
292
288
|
}
|
|
293
289
|
const response = operationResponse(await this.#operations(encodeRemoteOperationRequest({
|
|
294
290
|
revision: 1,
|
package/dist/schema.d.ts
CHANGED
|
@@ -130,10 +130,10 @@ export declare function ensureLocalSchema(db: ClientDatabase, schema: CompiledCl
|
|
|
130
130
|
* generated schema created — discovered from `sqlite_master`, since a
|
|
131
131
|
* bump may add/remove tables) and recreate the synced tables from the
|
|
132
132
|
* NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
|
|
133
|
-
*
|
|
133
|
+
* units, blob cache) are preserved. RFC 0005's container is not
|
|
134
134
|
* reachable from here: it lives in its own database file, so this reset cannot
|
|
135
135
|
* see or destroy it. Caller owns the surrounding transaction and the
|
|
136
|
-
*
|
|
136
|
+
* unit-state reset (state.ts).
|
|
137
137
|
*/
|
|
138
138
|
export declare function dropAndRecreateSyncedTables(db: ClientDatabase, schema: CompiledClientSchema): void;
|
|
139
139
|
/** RowValue → SQL bind value for the local mirror tables. */
|
|
@@ -165,6 +165,7 @@ export declare function recordToRowValues(table: CompiledClientTable, record: Re
|
|
|
165
165
|
export type JsonRowValue = string | number | boolean | null | {
|
|
166
166
|
readonly $bytes: string;
|
|
167
167
|
};
|
|
168
|
+
export declare function bytesToHex(bytes: Uint8Array): string;
|
|
168
169
|
/**
|
|
169
170
|
* The canonical §7.1 byte envelope: exactly one `$bytes` key holding a string
|
|
170
171
|
* of hexadecimal digit pairs. Uppercase digits are accepted; encoders emit
|
package/dist/schema.js
CHANGED
|
@@ -3,9 +3,9 @@ import { PENDING_EVICTIONS } from './window.js';
|
|
|
3
3
|
import { WINDOWS_TABLE } from './window.js';
|
|
4
4
|
import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox.js';
|
|
5
5
|
import { OUTCOMES_TABLE } from './outcomes.js';
|
|
6
|
-
import {
|
|
6
|
+
import { META_TABLE, resetUnits, UNITS_TABLE } from './state.js';
|
|
7
7
|
import { ensureFailedOverlaySchema } from './failed-overlay.js';
|
|
8
|
-
import { invalidRequest } from './errors.js';
|
|
8
|
+
import { ClientSyncError, invalidRequest } from './errors.js';
|
|
9
9
|
import { snakeToCamel } from './naming.js';
|
|
10
10
|
const PATTERN_RE = /^([^{}]+):\{([^{}:]+)\}$/;
|
|
11
11
|
const ALLOWED_FTS_TOKENIZERS = new Set([
|
|
@@ -65,15 +65,16 @@ export function compileClientSchema(schema) {
|
|
|
65
65
|
const scopePrefixByVariable = new Map();
|
|
66
66
|
for (const spec of table.scopes) {
|
|
67
67
|
const pattern = typeof spec === 'string' ? spec : spec.pattern;
|
|
68
|
-
const
|
|
69
|
-
if (
|
|
68
|
+
const [, prefix, variable] = PATTERN_RE.exec(pattern) ?? [];
|
|
69
|
+
if (!prefix || !variable) {
|
|
70
70
|
invalidSchema(`${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`);
|
|
71
71
|
}
|
|
72
|
-
const prefix = match[1];
|
|
73
|
-
const variable = match[2];
|
|
74
72
|
const column = typeof spec === 'string' ? variable : spec.column;
|
|
75
|
-
|
|
76
|
-
|
|
73
|
+
// §3.1: a scope value is an authorization key; only these two types
|
|
74
|
+
// render identically in every implementation.
|
|
75
|
+
const type = table.columns[columnIndex.get(column) ?? -1]?.type;
|
|
76
|
+
if (type !== 'string' && type !== 'integer') {
|
|
77
|
+
invalidSchema(`${tableLabel}: scope column ${JSON.stringify(column)} must be string or integer (§3.1)`);
|
|
77
78
|
}
|
|
78
79
|
const existing = scopeColumnByVariable.get(variable);
|
|
79
80
|
if (existing !== undefined && existing !== column) {
|
|
@@ -404,12 +405,20 @@ export function ensureLocalBookkeepingSchema(db) {
|
|
|
404
405
|
createTable(BLOB_COMMIT_REFS, 'commit_id TEXT NOT NULL,blob_id TEXT NOT NULL,PRIMARY KEY(commit_id,blob_id)');
|
|
405
406
|
db.exec(`CREATE INDEX IF NOT EXISTS ${BLOB_COMMIT_REFS}_body ON ${BLOB_COMMIT_REFS}(blob_id)`);
|
|
406
407
|
db.exec(`INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`);
|
|
408
|
+
const outboxExisted = db.query(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${OUTBOX_TABLE}'`).length > 0;
|
|
407
409
|
createTable(OUTBOX_TABLE, 'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL');
|
|
410
|
+
// §7.1: `outboxId` names the outbox sequence. A new outbox table starts
|
|
411
|
+
// a new sequence, so it replaces the id in the same transaction.
|
|
412
|
+
db.exec(`INSERT OR ${outboxExisted ? 'IGNORE' : 'REPLACE'} INTO ${META_TABLE}(key,value)VALUES('outboxId',?)`, [crypto.randomUUID()]);
|
|
408
413
|
createTable(OUTBOX_IMAGES, '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)');
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
.some((row) => row.name === '
|
|
412
|
-
|
|
414
|
+
const imageColumns = db.query(`PRAGMA table_info(${OUTBOX_IMAGES})`);
|
|
415
|
+
for (const column of ['delivery_seq INTEGER', 'tbl TEXT', 'row_id TEXT'])
|
|
416
|
+
if (!imageColumns.some((row) => row.name === column.split(' ')[0]))
|
|
417
|
+
db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN ${column}`);
|
|
418
|
+
// Images written before the row key existed take it from their operation.
|
|
419
|
+
if (!imageColumns.some((row) => row.name === 'row_id'))
|
|
420
|
+
db.exec(`UPDATE ${OUTBOX_IMAGES} SET (tbl,row_id)=(SELECT json_extract(operations,'$['||op_index||'].table'),json_extract(operations,'$['||op_index||'].rowId') FROM ${OUTBOX_TABLE} WHERE client_commit_id=${OUTBOX_IMAGES}.client_commit_id)`);
|
|
421
|
+
db.exec(`CREATE INDEX IF NOT EXISTS ${OUTBOX_IMAGES}_row ON ${OUTBOX_IMAGES}(tbl,row_id)`);
|
|
413
422
|
createTable(OUTCOMES_TABLE, "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT");
|
|
414
423
|
// Outcomes created before durable aggregate recovery retain no commit
|
|
415
424
|
// envelope. New failed outcomes store it in the protected client DB.
|
|
@@ -420,14 +429,26 @@ export function ensureLocalBookkeepingSchema(db) {
|
|
|
420
429
|
// column already exists — the CREATE above included it
|
|
421
430
|
}
|
|
422
431
|
db.exec(`CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`);
|
|
423
|
-
createTable(
|
|
424
|
-
// §4.8 window registry:
|
|
425
|
-
//
|
|
426
|
-
// (a unit's omission from the next pull unregisters it, §4.1).
|
|
432
|
+
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");
|
|
433
|
+
// §4.8 window registry: base + value → the unit it holds, the
|
|
434
|
+
// completeness oracle and one of a unit's references (§4.1).
|
|
427
435
|
createTable(WINDOWS_TABLE, 'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)');
|
|
428
|
-
// §4.8 E1: units that left
|
|
429
|
-
// Retried when the outbox drains; cancelled
|
|
430
|
-
createTable(PENDING_EVICTIONS, '
|
|
436
|
+
// §4.8 E1: per-table scopes of units that left with pinned or unevicted
|
|
437
|
+
// rows. Retried when the outbox drains; cancelled when the unit re-enters.
|
|
438
|
+
createTable(PENDING_EVICTIONS, 'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)');
|
|
439
|
+
// §9: a replica written under wire version 3 keeps its outbox, journal,
|
|
440
|
+
// rows and pending evictions and registers its units fresh. Its
|
|
441
|
+
// subscriptions, cursors, echoes, resume tokens and window entries go.
|
|
442
|
+
const legacyEvictions = '_syncular_window_pending_evict';
|
|
443
|
+
if (db.query(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='${legacyEvictions}'`).length > 0) {
|
|
444
|
+
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)
|
|
445
|
+
throw new ClientSyncError('sync.local_corrupt', 'a version 3 pending eviction cannot be upgraded');
|
|
446
|
+
db.exec(`INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`);
|
|
447
|
+
db.exec(`DROP TABLE ${legacyEvictions}`);
|
|
448
|
+
db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
|
|
449
|
+
db.exec(`DELETE FROM ${WINDOWS_TABLE}`);
|
|
450
|
+
resetUnits(db);
|
|
451
|
+
}
|
|
431
452
|
});
|
|
432
453
|
}
|
|
433
454
|
/** Create both application and protected bookkeeping tables. */
|
|
@@ -442,10 +463,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
|
|
|
442
463
|
* generated schema created — discovered from `sqlite_master`, since a
|
|
443
464
|
* bump may add/remove tables) and recreate the synced tables from the
|
|
444
465
|
* NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
|
|
445
|
-
*
|
|
466
|
+
* units, blob cache) are preserved. RFC 0005's container is not
|
|
446
467
|
* reachable from here: it lives in its own database file, so this reset cannot
|
|
447
468
|
* see or destroy it. Caller owns the surrounding transaction and the
|
|
448
|
-
*
|
|
469
|
+
* unit-state reset (state.ts).
|
|
449
470
|
*/
|
|
450
471
|
export function dropAndRecreateSyncedTables(db, schema) {
|
|
451
472
|
// Drop virtual tables first. SQLite then removes their shadow tables as one
|
|
@@ -557,7 +578,7 @@ export function recordToRowValues(table, record) {
|
|
|
557
578
|
return coerceSqlRepresentation(column, value);
|
|
558
579
|
});
|
|
559
580
|
}
|
|
560
|
-
function bytesToHex(bytes) {
|
|
581
|
+
export function bytesToHex(bytes) {
|
|
561
582
|
let out = '';
|
|
562
583
|
for (const byte of bytes)
|
|
563
584
|
out += byte.toString(16).padStart(2, '0');
|
package/dist/state.d.ts
CHANGED
|
@@ -1,50 +1,83 @@
|
|
|
1
1
|
export declare const META_TABLE = "_syncular_meta";
|
|
2
|
-
export declare const
|
|
2
|
+
export declare const UNITS_TABLE = "_syncular_units";
|
|
3
3
|
/**
|
|
4
|
-
* Durable
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
4
|
+
* Durable unit state (SPEC.md §4.1): per unit its scope map, status, live
|
|
5
|
+
* membership, catch-up cursor and opaque resume token (§4.7), the tables its
|
|
6
|
+
* current bootstrap seeded (§5.6) and the last echo (§4.4) the §3.3 purge
|
|
7
|
+
* contract is keyed on. The replica cursor, the echo digest and the
|
|
8
|
+
* registration digest the server holds live in meta.
|
|
8
9
|
*/
|
|
9
|
-
import type { ScopeMap } from '@syncular/core';
|
|
10
|
-
import type { CompiledClientSchema } from './schema.js';
|
|
10
|
+
import type { FencedRecord, ScopeMap, UnitScopes } from '@syncular/core';
|
|
11
|
+
import type { CompiledClientSchema, CompiledClientTable } from './schema.js';
|
|
11
12
|
import type { ClientDatabase } from './database.js';
|
|
12
13
|
import type { LocalRevision } from './invalidation.js';
|
|
13
14
|
export declare const LOCAL_REVISION_KEY = "localRevision";
|
|
14
|
-
|
|
15
|
-
export
|
|
15
|
+
/** §4.5 replica cursor; absent means `-1`. */
|
|
16
|
+
export declare const REPLICA_CURSOR_KEY = "replicaCursor";
|
|
17
|
+
/** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
|
|
18
|
+
export declare const ECHO_DIGEST_KEY = "echoDigest";
|
|
19
|
+
/** Hex of the registration digest of the list the server stores (§4.1). */
|
|
20
|
+
export declare const REGISTERED_DIGEST_KEY = "registrationDigest";
|
|
21
|
+
export type UnitStatus = 'active' | 'revoked' | 'failed';
|
|
22
|
+
export interface UnitRecord {
|
|
23
|
+
/** §4.1: derived from the scope map. */
|
|
16
24
|
readonly id: string;
|
|
17
|
-
readonly
|
|
18
|
-
/**
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
readonly
|
|
22
|
-
/**
|
|
23
|
-
readonly
|
|
25
|
+
readonly scopes: UnitScopes;
|
|
26
|
+
/** An explicit `subscribe` holds the unit; window bases hold it through
|
|
27
|
+
* the window registry (§4.1 references). */
|
|
28
|
+
readonly explicit: boolean;
|
|
29
|
+
readonly status: UnitStatus;
|
|
30
|
+
/** §10 code when not active, or `sync.cursor_expired` after a reset. */
|
|
31
|
+
readonly reasonCode?: string | undefined;
|
|
32
|
+
/** Absent while the unit is live (§4.5); otherwise `-1`, the pin, or the
|
|
33
|
+
* post-bootstrap cursor `P`. */
|
|
34
|
+
readonly cursor?: number | undefined;
|
|
24
35
|
/** Opaque resume token from `SUB_END` (§4.7); present mid-bootstrap. */
|
|
25
|
-
readonly bootstrapState?: string;
|
|
26
|
-
/**
|
|
27
|
-
readonly
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
readonly reasonCode?: string;
|
|
36
|
+
readonly bootstrapState?: string | undefined;
|
|
37
|
+
/** Tables that received a segment in the current bootstrap (§5.6). */
|
|
38
|
+
readonly seeded: readonly string[];
|
|
39
|
+
/** The echo persisted at the last `SUB_END` (§4.4). */
|
|
40
|
+
readonly echo?: readonly FencedRecord[] | undefined;
|
|
31
41
|
}
|
|
32
|
-
|
|
33
|
-
export declare function
|
|
34
|
-
|
|
35
|
-
export declare function
|
|
42
|
+
/** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
|
|
43
|
+
export declare function bootstrapping(unit: UnitRecord): boolean;
|
|
44
|
+
/** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
|
|
45
|
+
export declare function owning(unit: UnitRecord): boolean;
|
|
46
|
+
/** §4.1: the unit covers every table declaring all of its variables. */
|
|
47
|
+
export declare function covers(table: CompiledClientTable, scopes: UnitScopes): boolean;
|
|
36
48
|
/**
|
|
37
|
-
* §
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
* status → active), so the next round fresh-bootstraps exactly the
|
|
41
|
-
* subscriptions the app still wants. Caller owns the transaction.
|
|
49
|
+
* §4.4: the effective scopes of the (unit, table) pair under `echo`: the
|
|
50
|
+
* scope map as one-element lists plus the fenced lists. Undefined when the
|
|
51
|
+
* fence revoked the pair.
|
|
42
52
|
*/
|
|
43
|
-
export declare function
|
|
44
|
-
/**
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
53
|
+
export declare function pairScopes(scopes: UnitScopes, table: string, echo: readonly FencedRecord[] | undefined): ScopeMap | undefined;
|
|
54
|
+
/** §3.3 row ownership: the pair scopes of every owner of `table` but one.
|
|
55
|
+
* A bootstrapping unit owns the tables its current bootstrap seeded. */
|
|
56
|
+
export declare function unitOwners(units: readonly UnitRecord[], table: CompiledClientTable, exceptId: string): ScopeMap[];
|
|
57
|
+
/** Every unit in registration order (§4.1). */
|
|
58
|
+
export declare function loadUnits(db: ClientDatabase): UnitRecord[];
|
|
59
|
+
export declare function getUnit(db: ClientDatabase, id: string): UnitRecord | undefined;
|
|
60
|
+
/** Insert or update in place: an update keeps the registration order. */
|
|
61
|
+
export declare function saveUnit(db: ClientDatabase, record: UnitRecord): void;
|
|
62
|
+
export declare function deleteUnit(db: ClientDatabase, id: string): void;
|
|
63
|
+
/**
|
|
64
|
+
* §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
|
|
65
|
+
* registrations (the app's declared intent) and discard every synced state,
|
|
66
|
+
* so the next round sends the list and fresh-bootstraps every unit. Caller
|
|
67
|
+
* owns the transaction.
|
|
68
|
+
*/
|
|
69
|
+
export declare function resetUnits(db: ClientDatabase): void;
|
|
70
|
+
/** §4.5: the replica cursor, `-1` while no unit is live. */
|
|
71
|
+
export declare function replicaCursor(db: ClientDatabase): number;
|
|
72
|
+
/** §7.4.3 declaration evidence, persisted beside the schema marker. */
|
|
73
|
+
export declare function saveUnitScopeSchema(db: ClientDatabase, schema: CompiledClientSchema): void;
|
|
74
|
+
/**
|
|
75
|
+
* Drop units that cover no table of the running schema, with their window
|
|
76
|
+
* registry rows and pending evictions; never translate scopes. At a bump
|
|
77
|
+
* (§7.4.3) a unit also needs every variable unchanged in prefix and column on
|
|
78
|
+
* every table it covered before.
|
|
79
|
+
*/
|
|
80
|
+
export declare function pruneUnknownUnits(db: ClientDatabase, schema: CompiledClientSchema, bump?: boolean): void;
|
|
48
81
|
export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
|
|
49
82
|
export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
|
|
50
83
|
/** Read the durable client-local observer revision (SPEC §7.5). */
|