@syncular/client 0.70.1 → 0.70.3
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/dist/client.js +30 -5
- package/dist/outcomes.d.ts +6 -0
- package/dist/outcomes.js +64 -0
- package/package.json +3 -3
- package/src/client.ts +37 -4
- package/src/outcomes.ts +83 -0
package/dist/client.js
CHANGED
|
@@ -27,7 +27,7 @@ import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatch
|
|
|
27
27
|
import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
|
|
28
28
|
import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
|
|
29
29
|
import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
|
|
30
|
-
import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } from './outcomes.js';
|
|
30
|
+
import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, scrubPurgedOutcomes, } from './outcomes.js';
|
|
31
31
|
import { buildPreviousVersionAudit, capturePreviousVersion, clearPreviousVersionAudit, clearPreviousVersionRefusal, dropPreviousVersionContainer, loadLocalSchemaDescriptor, PREVIOUS_VERSION_CONTAINER_NAME, PREVIOUS_VERSION_MAX_LIMIT, readPreviousVersionContainer, readPreviousVersionRows, setLocalSchemaDescriptor, storedPreviousVersionAudit, storedPreviousVersionRefusal, withPreviousVersionContainer, writePreviousVersionAudit, writePreviousVersionRefusal, } from './previous-version.js';
|
|
32
32
|
import { bytesToHex, compileClientSchema, hexToBytes, matchesLocalScopes, dropAndRecreateSyncedTables, ensureLocalBookkeepingSchema, ensureLocalSyncedSchema, fromSqlValue, coerceSqlRepresentation, localColumnType, jsonToRowValue, LOCAL_SCHEMA_VERSION_KEY, normalizeRecordKeys, OPTIMISTIC_VERSION, quoteIdent, recordToRowValues, rowValueToJson, SYNC_VERSION_COLUMN, stripSyncColumns, } from './schema.js';
|
|
33
33
|
import { bootstrapping, bumpLocalRevision, covers, deleteUnit, ECHO_DIGEST_KEY, getLocalRevision, getMeta, getUnit, loadUnits, META_TABLE, owning, pairScopes, pruneUnknownUnits, REGISTERED_DIGEST_KEY, REPLICA_CURSOR_KEY, replicaCursor, resetUnits, saveUnit, saveUnitScopeSchema, setMeta, unitOwners, } from './state.js';
|
|
@@ -2437,6 +2437,8 @@ export class SyncClient {
|
|
|
2437
2437
|
if (appliedPlan !== purge.canonicalPlan) {
|
|
2438
2438
|
throw invalidRequest(`local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`);
|
|
2439
2439
|
}
|
|
2440
|
+
// A retry after a failed rewrite finishes it.
|
|
2441
|
+
this.#erasePurgedPages();
|
|
2440
2442
|
return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
|
|
2441
2443
|
}
|
|
2442
2444
|
// RFC 0005 D7: the container file cannot be a purge target (its name is not
|
|
@@ -2445,8 +2447,9 @@ export class SyncClient {
|
|
|
2445
2447
|
this.#dropPreviousVersion();
|
|
2446
2448
|
const priorRejections = [...this.#rejections];
|
|
2447
2449
|
const priorConflicts = [...this.#conflicts];
|
|
2450
|
+
let result;
|
|
2448
2451
|
try {
|
|
2449
|
-
|
|
2452
|
+
result = this.#applyBatch((batch) => {
|
|
2450
2453
|
const targetsByTable = this.#localPurgeTargetsByTable(purge);
|
|
2451
2454
|
restoreFailedBases(this.#db, this.#schema);
|
|
2452
2455
|
this.#dropRetainedRows(batch, (table, values) => (targetsByTable.get(table) ?? []).some((target) => target.selectors.every((selector) => selector.values.includes(String(values[selector.column])))));
|
|
@@ -2505,16 +2508,21 @@ export class SyncClient {
|
|
|
2505
2508
|
this.#db.exec(`DELETE FROM ${quoteIdent(tableName)} WHERE ${quoteIdent(table.primaryKey)} IN(${chunk.map(() => '?').join(', ')})`, chunk);
|
|
2506
2509
|
}
|
|
2507
2510
|
}
|
|
2511
|
+
if (scrubPurgedOutcomes(this.#db, (table, rowId, values) => (targetsByTable.get(table) ?? []).some((target) => rowIds.get(table)?.has(rowId) === true ||
|
|
2512
|
+
(values !== undefined &&
|
|
2513
|
+
localDataPurgeTargetMatches(target, values)))))
|
|
2514
|
+
batch.outcomes();
|
|
2508
2515
|
if (doomed.length > 0) {
|
|
2516
|
+
// §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
|
|
2517
|
+
// never its operations, so no purged value survives in it.
|
|
2509
2518
|
for (const commit of doomed) {
|
|
2510
|
-
const results = commit.operations.map((
|
|
2519
|
+
const results = commit.operations.map((_operation, opIndex) => {
|
|
2511
2520
|
const rejection = {
|
|
2512
2521
|
clientCommitId: commit.clientCommitId,
|
|
2513
2522
|
opIndex,
|
|
2514
2523
|
code: 'client.local_data_purged',
|
|
2515
2524
|
message: 'the commit was dropped by an application-authorized local data purge',
|
|
2516
2525
|
retryable: false,
|
|
2517
|
-
operation,
|
|
2518
2526
|
};
|
|
2519
2527
|
this.#rejections.push(rejection);
|
|
2520
2528
|
return { status: 'error', rejection };
|
|
@@ -2524,7 +2532,6 @@ export class SyncClient {
|
|
|
2524
2532
|
status: 'rejected',
|
|
2525
2533
|
recordedAtMs: this.#now(),
|
|
2526
2534
|
results,
|
|
2527
|
-
operations: commit.operations,
|
|
2528
2535
|
});
|
|
2529
2536
|
}
|
|
2530
2537
|
pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
|
|
@@ -2549,6 +2556,24 @@ export class SyncClient {
|
|
|
2549
2556
|
this.#conflicts = priorConflicts;
|
|
2550
2557
|
throw error;
|
|
2551
2558
|
}
|
|
2559
|
+
this.#erasePurgedPages();
|
|
2560
|
+
return result;
|
|
2561
|
+
}
|
|
2562
|
+
/**
|
|
2563
|
+
* §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the database
|
|
2564
|
+
* file, and a file replica's WAL keeps the frames written before the
|
|
2565
|
+
* purge, until either is rewritten. VACUUM rebuilds the file from the
|
|
2566
|
+
* remaining rows, and the checkpoint truncates the WAL.
|
|
2567
|
+
*/
|
|
2568
|
+
#erasePurgedPages() {
|
|
2569
|
+
this.#db.exec('PRAGMA secure_delete = ON');
|
|
2570
|
+
try {
|
|
2571
|
+
this.#db.exec('VACUUM');
|
|
2572
|
+
this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
|
|
2573
|
+
}
|
|
2574
|
+
finally {
|
|
2575
|
+
this.#db.exec('PRAGMA secure_delete = OFF');
|
|
2576
|
+
}
|
|
2552
2577
|
}
|
|
2553
2578
|
/**
|
|
2554
2579
|
* Rebuild the server-derived local projection without sacrificing offline
|
package/dist/outcomes.d.ts
CHANGED
|
@@ -118,3 +118,9 @@ export declare function activeFailureRecords(outcomes: readonly CommitOutcome[])
|
|
|
118
118
|
readonly conflicts: ConflictRecord[];
|
|
119
119
|
readonly rejections: RejectionRecord[];
|
|
120
120
|
};
|
|
121
|
+
/**
|
|
122
|
+
* §5.11 purge erasure: every journal entry with an operation, or a conflict
|
|
123
|
+
* row, that `touches` accepts keeps its identity, status, ids and codes only.
|
|
124
|
+
* Returns whether an entry changed.
|
|
125
|
+
*/
|
|
126
|
+
export declare function scrubPurgedOutcomes(db: ClientDatabase, touches: (table: string, rowId: string, values: Readonly<Record<string, unknown>> | undefined) => boolean): boolean;
|
package/dist/outcomes.js
CHANGED
|
@@ -306,3 +306,67 @@ export function activeFailureRecords(outcomes) {
|
|
|
306
306
|
}
|
|
307
307
|
return { conflicts, rejections };
|
|
308
308
|
}
|
|
309
|
+
/**
|
|
310
|
+
* §5.11 purge erasure: every journal entry with an operation, or a conflict
|
|
311
|
+
* row, that `touches` accepts keeps its identity, status, ids and codes only.
|
|
312
|
+
* Returns whether an entry changed.
|
|
313
|
+
*/
|
|
314
|
+
export function scrubPurgedOutcomes(db, touches) {
|
|
315
|
+
let changed = false;
|
|
316
|
+
for (const row of db.query(`SELECT client_commit_id,results,operations FROM ${OUTCOMES_TABLE}`)) {
|
|
317
|
+
const results = JSON.parse(String(row.results));
|
|
318
|
+
const operations = typeof row.operations === 'string'
|
|
319
|
+
? JSON.parse(row.operations)
|
|
320
|
+
: [];
|
|
321
|
+
const named = [
|
|
322
|
+
...operations,
|
|
323
|
+
...results.flatMap((result) => result.status === 'conflict'
|
|
324
|
+
? [
|
|
325
|
+
{
|
|
326
|
+
table: result.conflict.table,
|
|
327
|
+
rowId: result.conflict.rowId,
|
|
328
|
+
values: result.conflict.serverRow,
|
|
329
|
+
},
|
|
330
|
+
...(result.conflict.operation === undefined
|
|
331
|
+
? []
|
|
332
|
+
: [result.conflict.operation]),
|
|
333
|
+
]
|
|
334
|
+
: result.status === 'error' &&
|
|
335
|
+
result.rejection.operation !== undefined
|
|
336
|
+
? [result.rejection.operation]
|
|
337
|
+
: []),
|
|
338
|
+
];
|
|
339
|
+
if (!named.some((op) => touches(op.table, op.rowId, op.values)))
|
|
340
|
+
continue;
|
|
341
|
+
const scrubbed = results.map((result) => {
|
|
342
|
+
if (result.status === 'conflict') {
|
|
343
|
+
const { clientCommitId, opIndex, table, rowId, code, message } = result.conflict;
|
|
344
|
+
return {
|
|
345
|
+
status: 'conflict',
|
|
346
|
+
conflict: {
|
|
347
|
+
clientCommitId,
|
|
348
|
+
opIndex,
|
|
349
|
+
table,
|
|
350
|
+
rowId,
|
|
351
|
+
code,
|
|
352
|
+
message,
|
|
353
|
+
serverVersion: result.conflict.serverVersion,
|
|
354
|
+
serverRow: {},
|
|
355
|
+
conflictColumns: [],
|
|
356
|
+
},
|
|
357
|
+
};
|
|
358
|
+
}
|
|
359
|
+
if (result.status === 'error') {
|
|
360
|
+
const { clientCommitId, opIndex, code, message, retryable } = result.rejection;
|
|
361
|
+
return {
|
|
362
|
+
status: 'error',
|
|
363
|
+
rejection: { clientCommitId, opIndex, code, message, retryable },
|
|
364
|
+
};
|
|
365
|
+
}
|
|
366
|
+
return result;
|
|
367
|
+
});
|
|
368
|
+
db.exec(`UPDATE ${OUTCOMES_TABLE} SET results=?,operations=NULL WHERE client_commit_id=?`, [JSON.stringify(scrubbed), String(row.client_commit_id)]);
|
|
369
|
+
changed = true;
|
|
370
|
+
}
|
|
371
|
+
return changed;
|
|
372
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.70.
|
|
3
|
+
"version": "0.70.3",
|
|
4
4
|
"description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -121,11 +121,11 @@
|
|
|
121
121
|
},
|
|
122
122
|
"dependencies": {
|
|
123
123
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
124
|
-
"@syncular/core": "0.70.
|
|
124
|
+
"@syncular/core": "0.70.3"
|
|
125
125
|
},
|
|
126
126
|
"devDependencies": {
|
|
127
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
128
|
-
"@syncular/server": "0.70.
|
|
128
|
+
"@syncular/server": "0.70.3",
|
|
129
129
|
"playwright": "1.63.0",
|
|
130
130
|
"vite": "8.3.4"
|
|
131
131
|
}
|
package/src/client.ts
CHANGED
|
@@ -191,6 +191,7 @@ import {
|
|
|
191
191
|
type ResolveCommitOutcomeInput,
|
|
192
192
|
commitOutcome as readCommitOutcome,
|
|
193
193
|
recordCommitOutcome,
|
|
194
|
+
scrubPurgedOutcomes,
|
|
194
195
|
} from './outcomes';
|
|
195
196
|
import {
|
|
196
197
|
buildPreviousVersionAudit,
|
|
@@ -3688,6 +3689,8 @@ export class SyncClient {
|
|
|
3688
3689
|
`local purge id ${JSON.stringify(purge.purgeId)} was already used with a different plan`,
|
|
3689
3690
|
);
|
|
3690
3691
|
}
|
|
3692
|
+
// A retry after a failed rewrite finishes it.
|
|
3693
|
+
this.#erasePurgedPages();
|
|
3691
3694
|
return { alreadyApplied: true, purgedRows: 0, droppedCommits: 0 };
|
|
3692
3695
|
}
|
|
3693
3696
|
// RFC 0005 D7: the container file cannot be a purge target (its name is not
|
|
@@ -3697,8 +3700,9 @@ export class SyncClient {
|
|
|
3697
3700
|
|
|
3698
3701
|
const priorRejections = [...this.#rejections];
|
|
3699
3702
|
const priorConflicts = [...this.#conflicts];
|
|
3703
|
+
let result: LocalDataPurgeResult;
|
|
3700
3704
|
try {
|
|
3701
|
-
|
|
3705
|
+
result = this.#applyBatch((batch) => {
|
|
3702
3706
|
const targetsByTable = this.#localPurgeTargetsByTable(purge);
|
|
3703
3707
|
restoreFailedBases(this.#db, this.#schema);
|
|
3704
3708
|
this.#dropRetainedRows(batch, (table, values) =>
|
|
@@ -3778,11 +3782,24 @@ export class SyncClient {
|
|
|
3778
3782
|
);
|
|
3779
3783
|
}
|
|
3780
3784
|
}
|
|
3785
|
+
if (
|
|
3786
|
+
scrubPurgedOutcomes(this.#db, (table, rowId, values) =>
|
|
3787
|
+
(targetsByTable.get(table) ?? []).some(
|
|
3788
|
+
(target) =>
|
|
3789
|
+
rowIds.get(table)?.has(rowId) === true ||
|
|
3790
|
+
(values !== undefined &&
|
|
3791
|
+
localDataPurgeTargetMatches(target, values)),
|
|
3792
|
+
),
|
|
3793
|
+
)
|
|
3794
|
+
)
|
|
3795
|
+
batch.outcomes();
|
|
3781
3796
|
|
|
3782
3797
|
if (doomed.length > 0) {
|
|
3798
|
+
// §5.11 purge erasure: the journal keeps a dropped commit's identity and codes,
|
|
3799
|
+
// never its operations, so no purged value survives in it.
|
|
3783
3800
|
for (const commit of doomed) {
|
|
3784
3801
|
const results: CommitOperationOutcome[] = commit.operations.map(
|
|
3785
|
-
(
|
|
3802
|
+
(_operation, opIndex) => {
|
|
3786
3803
|
const rejection: RejectionRecord = {
|
|
3787
3804
|
clientCommitId: commit.clientCommitId,
|
|
3788
3805
|
opIndex,
|
|
@@ -3790,7 +3807,6 @@ export class SyncClient {
|
|
|
3790
3807
|
message:
|
|
3791
3808
|
'the commit was dropped by an application-authorized local data purge',
|
|
3792
3809
|
retryable: false,
|
|
3793
|
-
operation,
|
|
3794
3810
|
};
|
|
3795
3811
|
this.#rejections.push(rejection);
|
|
3796
3812
|
return { status: 'error', rejection };
|
|
@@ -3801,7 +3817,6 @@ export class SyncClient {
|
|
|
3801
3817
|
status: 'rejected',
|
|
3802
3818
|
recordedAtMs: this.#now(),
|
|
3803
3819
|
results,
|
|
3804
|
-
operations: commit.operations,
|
|
3805
3820
|
});
|
|
3806
3821
|
}
|
|
3807
3822
|
pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
|
|
@@ -3825,6 +3840,24 @@ export class SyncClient {
|
|
|
3825
3840
|
this.#conflicts = priorConflicts;
|
|
3826
3841
|
throw error;
|
|
3827
3842
|
}
|
|
3843
|
+
this.#erasePurgedPages();
|
|
3844
|
+
return result;
|
|
3845
|
+
}
|
|
3846
|
+
|
|
3847
|
+
/**
|
|
3848
|
+
* §5.11 purge erasure: SQLite leaves a deleted value in the freed pages of the database
|
|
3849
|
+
* file, and a file replica's WAL keeps the frames written before the
|
|
3850
|
+
* purge, until either is rewritten. VACUUM rebuilds the file from the
|
|
3851
|
+
* remaining rows, and the checkpoint truncates the WAL.
|
|
3852
|
+
*/
|
|
3853
|
+
#erasePurgedPages(): void {
|
|
3854
|
+
this.#db.exec('PRAGMA secure_delete = ON');
|
|
3855
|
+
try {
|
|
3856
|
+
this.#db.exec('VACUUM');
|
|
3857
|
+
this.#db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
|
|
3858
|
+
} finally {
|
|
3859
|
+
this.#db.exec('PRAGMA secure_delete = OFF');
|
|
3860
|
+
}
|
|
3828
3861
|
}
|
|
3829
3862
|
|
|
3830
3863
|
/**
|
package/src/outcomes.ts
CHANGED
|
@@ -530,3 +530,86 @@ export function activeFailureRecords(outcomes: readonly CommitOutcome[]): {
|
|
|
530
530
|
}
|
|
531
531
|
return { conflicts, rejections };
|
|
532
532
|
}
|
|
533
|
+
|
|
534
|
+
/**
|
|
535
|
+
* §5.11 purge erasure: every journal entry with an operation, or a conflict
|
|
536
|
+
* row, that `touches` accepts keeps its identity, status, ids and codes only.
|
|
537
|
+
* Returns whether an entry changed.
|
|
538
|
+
*/
|
|
539
|
+
export function scrubPurgedOutcomes(
|
|
540
|
+
db: ClientDatabase,
|
|
541
|
+
touches: (
|
|
542
|
+
table: string,
|
|
543
|
+
rowId: string,
|
|
544
|
+
values: Readonly<Record<string, unknown>> | undefined,
|
|
545
|
+
) => boolean,
|
|
546
|
+
): boolean {
|
|
547
|
+
let changed = false;
|
|
548
|
+
for (const row of db.query(
|
|
549
|
+
`SELECT client_commit_id,results,operations FROM ${OUTCOMES_TABLE}`,
|
|
550
|
+
)) {
|
|
551
|
+
const results = JSON.parse(
|
|
552
|
+
String(row.results),
|
|
553
|
+
) as StoredCommitOperationOutcome[];
|
|
554
|
+
const operations =
|
|
555
|
+
typeof row.operations === 'string'
|
|
556
|
+
? (JSON.parse(row.operations) as OutboxOperation[])
|
|
557
|
+
: [];
|
|
558
|
+
const named = [
|
|
559
|
+
...operations,
|
|
560
|
+
...results.flatMap((result) =>
|
|
561
|
+
result.status === 'conflict'
|
|
562
|
+
? [
|
|
563
|
+
{
|
|
564
|
+
table: result.conflict.table,
|
|
565
|
+
rowId: result.conflict.rowId,
|
|
566
|
+
values: result.conflict.serverRow,
|
|
567
|
+
},
|
|
568
|
+
...(result.conflict.operation === undefined
|
|
569
|
+
? []
|
|
570
|
+
: [result.conflict.operation]),
|
|
571
|
+
]
|
|
572
|
+
: result.status === 'error' &&
|
|
573
|
+
result.rejection.operation !== undefined
|
|
574
|
+
? [result.rejection.operation]
|
|
575
|
+
: [],
|
|
576
|
+
),
|
|
577
|
+
];
|
|
578
|
+
if (!named.some((op) => touches(op.table, op.rowId, op.values))) continue;
|
|
579
|
+
const scrubbed: StoredCommitOperationOutcome[] = results.map((result) => {
|
|
580
|
+
if (result.status === 'conflict') {
|
|
581
|
+
const { clientCommitId, opIndex, table, rowId, code, message } =
|
|
582
|
+
result.conflict;
|
|
583
|
+
return {
|
|
584
|
+
status: 'conflict',
|
|
585
|
+
conflict: {
|
|
586
|
+
clientCommitId,
|
|
587
|
+
opIndex,
|
|
588
|
+
table,
|
|
589
|
+
rowId,
|
|
590
|
+
code,
|
|
591
|
+
message,
|
|
592
|
+
serverVersion: result.conflict.serverVersion,
|
|
593
|
+
serverRow: {},
|
|
594
|
+
conflictColumns: [],
|
|
595
|
+
},
|
|
596
|
+
};
|
|
597
|
+
}
|
|
598
|
+
if (result.status === 'error') {
|
|
599
|
+
const { clientCommitId, opIndex, code, message, retryable } =
|
|
600
|
+
result.rejection;
|
|
601
|
+
return {
|
|
602
|
+
status: 'error',
|
|
603
|
+
rejection: { clientCommitId, opIndex, code, message, retryable },
|
|
604
|
+
};
|
|
605
|
+
}
|
|
606
|
+
return result;
|
|
607
|
+
});
|
|
608
|
+
db.exec(
|
|
609
|
+
`UPDATE ${OUTCOMES_TABLE} SET results=?,operations=NULL WHERE client_commit_id=?`,
|
|
610
|
+
[JSON.stringify(scrubbed), String(row.client_commit_id)],
|
|
611
|
+
);
|
|
612
|
+
changed = true;
|
|
613
|
+
}
|
|
614
|
+
return changed;
|
|
615
|
+
}
|