@syncular/client 0.82.3 → 0.84.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 +7 -3
- package/dist/client.d.ts +0 -3
- package/dist/client.js +61 -36
- package/dist/diagnostics.d.ts +5 -0
- package/dist/invalidation.d.ts +0 -1
- package/dist/invalidation.js +0 -3
- package/dist/progress.d.ts +2 -0
- package/package.json +3 -3
- package/src/client.ts +86 -65
- package/src/diagnostics.ts +5 -0
- package/src/invalidation.ts +0 -4
- package/src/progress.ts +2 -0
package/README.md
CHANGED
|
@@ -409,7 +409,9 @@ stop, pending outbox, offline transport, and storage pressure/unreadability.
|
|
|
409
409
|
Failed progress and `lastRound` diagnostics expose an optional bounded
|
|
410
410
|
`causeKind` and HTTP status. Worker leaders and followers receive the same
|
|
411
411
|
evidence. A new progress attempt clears its failure fields; a successful round
|
|
412
|
-
replaces the failed last round. `
|
|
412
|
+
replaces the failed last round. `lastRound.epoch` and `lastRound.attempt`
|
|
413
|
+
identify the round and match its progress events; count rounds by that pair
|
|
414
|
+
instead of `completedAtMs`. `host.connectivity` describes the latest
|
|
413
415
|
endpoint observation and does not prove the device's network state.
|
|
414
416
|
`queryFailures` retains at most 256 failed owned snapshot reads until each query
|
|
415
417
|
reads successfully. An entry contains only its stable PHI-free owner id,
|
|
@@ -836,9 +838,11 @@ const stop = client.onProgress((progress) => {
|
|
|
836
838
|
stop();
|
|
837
839
|
```
|
|
838
840
|
|
|
839
|
-
Each snapshot identifies the round with `attempt`, and the current payload with
|
|
841
|
+
Each snapshot identifies the round with `epoch` and `attempt`, and the current payload with
|
|
840
842
|
`unitId`, `table`, and optional `segmentId`. Counters reset for each
|
|
841
|
-
payload; `syncUntilIdle` starts a new attempt for each round. `
|
|
843
|
+
payload; `syncUntilIdle` starts a new attempt for each round. `epoch` is random per
|
|
844
|
+
client core; a new core (a Worker handover, a reload) counts attempts from 1
|
|
845
|
+
under a new `epoch`. `phase` is `request`,
|
|
842
846
|
`download`, or `import`; `state` is `running`, `complete`, or `failed`. Unknown
|
|
843
847
|
totals remain absent. A new attempt clears prior errors and counters.
|
|
844
848
|
|
package/dist/client.d.ts
CHANGED
|
@@ -564,9 +564,6 @@ export declare class SyncClient {
|
|
|
564
564
|
* dismissed. The transition is one-way and survives restart.
|
|
565
565
|
*/
|
|
566
566
|
resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
|
|
567
|
-
/** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
|
|
568
|
-
* `undefined` if no lease is held. Negative once expired. */
|
|
569
|
-
leaseRemainingMs(now?: number): number | undefined;
|
|
570
567
|
/** True when syncing is stopped pending a client upgrade. */
|
|
571
568
|
get stopped(): boolean;
|
|
572
569
|
/**
|
package/dist/client.js
CHANGED
|
@@ -201,6 +201,8 @@ export class SyncClient {
|
|
|
201
201
|
/** §7.8: restarts the running drive's round bound when rows apply. */
|
|
202
202
|
#roundProgressed;
|
|
203
203
|
#progressAttempt = 0;
|
|
204
|
+
/** §7.6: scopes `#progressAttempt`; a new core gets a new epoch. */
|
|
205
|
+
#epoch = crypto.randomUUID();
|
|
204
206
|
/**
|
|
205
207
|
* True from the synchronous entry of `sync()` until its serialized round
|
|
206
208
|
* settles — the "one loop owns the database" guard that rejects a
|
|
@@ -1905,12 +1907,6 @@ export class SyncClient {
|
|
|
1905
1907
|
throw error;
|
|
1906
1908
|
});
|
|
1907
1909
|
}
|
|
1908
|
-
/** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
|
|
1909
|
-
* `undefined` if no lease is held. Negative once expired. */
|
|
1910
|
-
leaseRemainingMs(now = this.#now()) {
|
|
1911
|
-
const expiresAtMs = this.#leaseState?.expiresAtMs;
|
|
1912
|
-
return expiresAtMs === undefined ? undefined : expiresAtMs - now;
|
|
1913
|
-
}
|
|
1914
1910
|
/** True when syncing is stopped pending a client upgrade. */
|
|
1915
1911
|
get stopped() {
|
|
1916
1912
|
return this.#schemaFloor !== undefined;
|
|
@@ -2261,12 +2257,19 @@ export class SyncClient {
|
|
|
2261
2257
|
readCommitOutcome(this.#db, supplied)))
|
|
2262
2258
|
throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
|
|
2263
2259
|
const clientCommitId = supplied ?? crypto.randomUUID();
|
|
2260
|
+
// §7.1: a patch reads the row as the commit's earlier operations leave
|
|
2261
|
+
// it. Keyed by `table rowId` (a table name holds no space): the JSON
|
|
2262
|
+
// values an earlier upsert wrote, or null after an earlier delete. A
|
|
2263
|
+
// patch changes neither presence nor a scope column, so it records
|
|
2264
|
+
// nothing.
|
|
2265
|
+
const staged = new Map();
|
|
2264
2266
|
const operations = mutations.map((mutation) => {
|
|
2265
2267
|
const table = this.#table(mutation.table);
|
|
2266
2268
|
if (mutation.op === 'delete') {
|
|
2267
2269
|
// §2.4: the server rejects a rowId holding U+0000.
|
|
2268
2270
|
if (mutation.rowId.includes('\u0000'))
|
|
2269
2271
|
throw invalidRequest('rowId holds U+0000');
|
|
2272
|
+
staged.set(`${table.name} ${mutation.rowId}`, null);
|
|
2270
2273
|
return definedObject({
|
|
2271
2274
|
table: mutation.table,
|
|
2272
2275
|
rowId: mutation.rowId,
|
|
@@ -2284,8 +2287,13 @@ export class SyncClient {
|
|
|
2284
2287
|
const scopeColumns = new Set(table.scopeColumnByVariable.values());
|
|
2285
2288
|
const pkColumn = table.columns[table.primaryKeyIndex];
|
|
2286
2289
|
const pkValue = requireRowId(normalized.get(pkColumn.name));
|
|
2287
|
-
|
|
2288
|
-
|
|
2290
|
+
// The base: an earlier operation's JSON values, else the stored row.
|
|
2291
|
+
const key = `${table.name} ${pkValue}`;
|
|
2292
|
+
const base = staged.get(key);
|
|
2293
|
+
const stored = staged.has(key)
|
|
2294
|
+
? undefined
|
|
2295
|
+
: this.#rowById(table, pkValue);
|
|
2296
|
+
if (!base && !stored)
|
|
2289
2297
|
throw new ClientSyncError('sync.row_missing', 'a sparse patch requires a local row');
|
|
2290
2298
|
for (const column of table.columns) {
|
|
2291
2299
|
if (!normalized.has(column.name))
|
|
@@ -2294,7 +2302,8 @@ export class SyncClient {
|
|
|
2294
2302
|
// §3.4 rule 5 / §6.2: scope columns are immutable on update. The
|
|
2295
2303
|
// server accepts a present scope column whose value equals the
|
|
2296
2304
|
// stored row and applies it as a no-op, so a decoded envelope
|
|
2297
|
-
// round-trips. The local row
|
|
2305
|
+
// round-trips. The local row, as the commit's earlier operations
|
|
2306
|
+
// leave it, is the only value the client can
|
|
2298
2307
|
// prove equality against; when the row is absent locally the
|
|
2299
2308
|
// client cannot prove equality against the server's stored row
|
|
2300
2309
|
// and fails closed. A primary key that is also a scope column
|
|
@@ -2302,7 +2311,9 @@ export class SyncClient {
|
|
|
2302
2311
|
// by construction the row id being patched (§6.1), so its value is
|
|
2303
2312
|
// proven equal already.
|
|
2304
2313
|
if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
|
|
2305
|
-
if (!Object.is(
|
|
2314
|
+
if (!Object.is(stored
|
|
2315
|
+
? rowValueToJson(fromSqlValue(column, stored[column.name] ?? null))
|
|
2316
|
+
: base?.[column.name], rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
|
|
2306
2317
|
throw invalidRequest('patch cannot write a scope column (§3.4)', false, at);
|
|
2307
2318
|
}
|
|
2308
2319
|
continue;
|
|
@@ -2337,8 +2348,9 @@ export class SyncClient {
|
|
|
2337
2348
|
});
|
|
2338
2349
|
// §7.1 insert intent: a full-row write of a row the replica does not
|
|
2339
2350
|
// show replays and encodes as a full row under every later schema.
|
|
2340
|
-
|
|
2341
|
-
|
|
2351
|
+
if (mutation.op !== 'patch')
|
|
2352
|
+
staged.set(`${table.name} ${pkValue}`, json);
|
|
2353
|
+
const insert = mutation.op !== 'patch' && !this.#rowById(table, pkValue, '1');
|
|
2342
2354
|
return definedObject({
|
|
2343
2355
|
table: mutation.table,
|
|
2344
2356
|
rowId: pkValue,
|
|
@@ -2354,7 +2366,7 @@ export class SyncClient {
|
|
|
2354
2366
|
const table = this.#table(operation.table);
|
|
2355
2367
|
if (!table.hasEncryptedColumns)
|
|
2356
2368
|
continue;
|
|
2357
|
-
const keyId = this.#
|
|
2369
|
+
const keyId = this.#rowById(table, operation.rowId, `${quoteIdent(SEALED_KEY_COLUMN)} AS k`)?.k;
|
|
2358
2370
|
if (typeof keyId === 'string')
|
|
2359
2371
|
throw new ClientSyncError('client.encryption_key_missing', 'the row is sealed under a key this device does not hold', false, { table: table.name, keyId });
|
|
2360
2372
|
}
|
|
@@ -2781,7 +2793,7 @@ export class SyncClient {
|
|
|
2781
2793
|
const selector = this.#encryption?.keyIdColumns?.[table.name];
|
|
2782
2794
|
if (selector === undefined)
|
|
2783
2795
|
return undefined;
|
|
2784
|
-
const row = this.#
|
|
2796
|
+
const row = this.#rowById(table, rowId, `${quoteIdent(selector)} AS value`);
|
|
2785
2797
|
const value = row?.value;
|
|
2786
2798
|
return typeof value === 'string' && value.length > 0
|
|
2787
2799
|
? value
|
|
@@ -2955,22 +2967,36 @@ export class SyncClient {
|
|
|
2955
2967
|
this.#syncOutstanding = true;
|
|
2956
2968
|
this.#beginDiagnosticsDeferral();
|
|
2957
2969
|
const startedAtMs = this.#now();
|
|
2958
|
-
|
|
2959
|
-
|
|
2970
|
+
// `#syncOutstanding` keeps this the attempt `#runSync` starts (§7.6).
|
|
2971
|
+
const attempt = this.#progressAttempt + 1;
|
|
2972
|
+
const round = () => {
|
|
2960
2973
|
const completedAtMs = this.#now();
|
|
2961
|
-
|
|
2962
|
-
|
|
2974
|
+
return {
|
|
2975
|
+
epoch: this.#epoch,
|
|
2976
|
+
attempt,
|
|
2963
2977
|
startedAtMs,
|
|
2964
2978
|
completedAtMs,
|
|
2965
2979
|
durationMs: Math.max(0, completedAtMs - startedAtMs),
|
|
2980
|
+
};
|
|
2981
|
+
};
|
|
2982
|
+
return this.#serialize(() => this.#runSync(signal))
|
|
2983
|
+
.then((summary) => {
|
|
2984
|
+
this.#lastRound = {
|
|
2985
|
+
status: 'succeeded',
|
|
2986
|
+
...round(),
|
|
2966
2987
|
counters: this.#diagnosticRoundCounters(summary),
|
|
2967
2988
|
};
|
|
2968
2989
|
this.#emitDiagnostics();
|
|
2969
2990
|
return summary;
|
|
2970
2991
|
}, (caught) => {
|
|
2971
2992
|
const error = classifySqliteFailure(caught).error;
|
|
2972
|
-
|
|
2993
|
+
// A gate refusal starts no attempt and records no round.
|
|
2994
|
+
if (this.#progressAttempt !== attempt)
|
|
2995
|
+
throw error;
|
|
2973
2996
|
const code = error.code;
|
|
2997
|
+
const errorCode = typeof code === 'string'
|
|
2998
|
+
? this.#diagnosticCode(code)
|
|
2999
|
+
: 'client.unknown_failure';
|
|
2974
3000
|
const details = typeof error === 'object' && error !== null && 'details' in error
|
|
2975
3001
|
? error.details
|
|
2976
3002
|
: undefined;
|
|
@@ -3012,24 +3038,18 @@ export class SyncClient {
|
|
|
3012
3038
|
: undefined;
|
|
3013
3039
|
this.#progress.update(definedObject({
|
|
3014
3040
|
state: 'failed',
|
|
3015
|
-
errorCode
|
|
3016
|
-
? this.#diagnosticCode(code)
|
|
3017
|
-
: 'client.unknown_failure',
|
|
3041
|
+
errorCode,
|
|
3018
3042
|
retryDelayMs: this.#roundRetryDelayMs,
|
|
3019
3043
|
causeKind,
|
|
3020
3044
|
httpStatus,
|
|
3021
3045
|
}));
|
|
3022
|
-
this.#lastRound = {
|
|
3046
|
+
this.#lastRound = definedObject({
|
|
3023
3047
|
status: 'failed',
|
|
3024
|
-
|
|
3025
|
-
|
|
3026
|
-
|
|
3027
|
-
|
|
3028
|
-
|
|
3029
|
-
: 'client.unknown_failure',
|
|
3030
|
-
...(causeKind !== undefined ? { causeKind } : {}),
|
|
3031
|
-
...(httpStatus !== undefined ? { httpStatus } : {}),
|
|
3032
|
-
};
|
|
3048
|
+
...round(),
|
|
3049
|
+
errorCode,
|
|
3050
|
+
causeKind,
|
|
3051
|
+
httpStatus,
|
|
3052
|
+
});
|
|
3033
3053
|
this.#emitDiagnostics();
|
|
3034
3054
|
throw error;
|
|
3035
3055
|
})
|
|
@@ -3063,6 +3083,7 @@ export class SyncClient {
|
|
|
3063
3083
|
this.#requireTransport();
|
|
3064
3084
|
this.#roundRetryDelayMs = undefined;
|
|
3065
3085
|
this.#progress.emit({
|
|
3086
|
+
epoch: this.#epoch,
|
|
3066
3087
|
attempt: ++this.#progressAttempt,
|
|
3067
3088
|
state: 'running',
|
|
3068
3089
|
phase: 'request',
|
|
@@ -4489,7 +4510,7 @@ export class SyncClient {
|
|
|
4489
4510
|
const mappings = [...table.scopeColumnByVariable].filter(([variable]) => table.scopePrefixByVariable.has(variable));
|
|
4490
4511
|
if (mappings.length === 0)
|
|
4491
4512
|
return false;
|
|
4492
|
-
const row = this.#
|
|
4513
|
+
const row = this.#rowById(table, rowId, mappings.map(([, column]) => quoteIdent(column)).join());
|
|
4493
4514
|
if (row === undefined)
|
|
4494
4515
|
return false;
|
|
4495
4516
|
let recorded = false;
|
|
@@ -4819,7 +4840,7 @@ export class SyncClient {
|
|
|
4819
4840
|
...table.columns.map((column) => quoteIdent(column.name)),
|
|
4820
4841
|
quoteIdent(SYNC_VERSION_COLUMN),
|
|
4821
4842
|
];
|
|
4822
|
-
const row = this.#
|
|
4843
|
+
const row = this.#rowById(table, operation.rowId, columns.join());
|
|
4823
4844
|
if (row === undefined)
|
|
4824
4845
|
return { opIndex, existed: false };
|
|
4825
4846
|
const values = {};
|
|
@@ -4861,7 +4882,7 @@ export class SyncClient {
|
|
|
4861
4882
|
const table = this.#schema.tables.get(operation.table);
|
|
4862
4883
|
if (table === undefined)
|
|
4863
4884
|
continue;
|
|
4864
|
-
const row = this.#
|
|
4885
|
+
const row = this.#rowById(table, operation.rowId, `${quoteIdent(SYNC_VERSION_COLUMN)} AS v`);
|
|
4865
4886
|
if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
|
|
4866
4887
|
batch.table(table.name);
|
|
4867
4888
|
deleteLocalRow(this.#db, table, operation.rowId);
|
|
@@ -4947,7 +4968,7 @@ export class SyncClient {
|
|
|
4947
4968
|
batch.table(op.table);
|
|
4948
4969
|
continue;
|
|
4949
4970
|
}
|
|
4950
|
-
const local = this.#
|
|
4971
|
+
const local = this.#rowById(table, op.rowId);
|
|
4951
4972
|
if (local === undefined && !full) {
|
|
4952
4973
|
if (batch !== undefined && !precise)
|
|
4953
4974
|
batch.table(op.table);
|
|
@@ -5148,6 +5169,10 @@ export class SyncClient {
|
|
|
5148
5169
|
deleteUnreferencedCachedBlobs(this.#db, this.#schema);
|
|
5149
5170
|
}
|
|
5150
5171
|
// -- helpers -----------------------------------------------------------------
|
|
5172
|
+
/** The local row `rowId` of `table`, selecting `columns`. */
|
|
5173
|
+
#rowById(table, rowId, columns = '*') {
|
|
5174
|
+
return this.#db.query(`SELECT ${columns} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`, [pkSqlValue(table, rowId)])[0];
|
|
5175
|
+
}
|
|
5151
5176
|
#table(name) {
|
|
5152
5177
|
const table = this.#schema.tables.get(name);
|
|
5153
5178
|
if (table === undefined) {
|
package/dist/diagnostics.d.ts
CHANGED
|
@@ -56,14 +56,19 @@ export interface DiagnosticRoundCounters {
|
|
|
56
56
|
readonly failed: number;
|
|
57
57
|
readonly deferredCommits: number;
|
|
58
58
|
}
|
|
59
|
+
/** One completed sync round. `(epoch, attempt)` identifies it (SPEC §7.6). */
|
|
59
60
|
export type DiagnosticLastRound = {
|
|
60
61
|
readonly status: 'succeeded';
|
|
62
|
+
readonly epoch: string;
|
|
63
|
+
readonly attempt: number;
|
|
61
64
|
readonly startedAtMs: number;
|
|
62
65
|
readonly completedAtMs: number;
|
|
63
66
|
readonly durationMs: number;
|
|
64
67
|
readonly counters: DiagnosticRoundCounters;
|
|
65
68
|
} | {
|
|
66
69
|
readonly status: 'failed';
|
|
70
|
+
readonly epoch: string;
|
|
71
|
+
readonly attempt: number;
|
|
67
72
|
readonly startedAtMs: number;
|
|
68
73
|
readonly completedAtMs: number;
|
|
69
74
|
readonly durationMs: number;
|
package/dist/invalidation.d.ts
CHANGED
|
@@ -73,7 +73,6 @@ export interface CommandResult<T> {
|
|
|
73
73
|
readonly value: T;
|
|
74
74
|
readonly effects: CommandEffects;
|
|
75
75
|
}
|
|
76
|
-
export declare const NO_COMMAND_EFFECTS: CommandEffects;
|
|
77
76
|
/**
|
|
78
77
|
* Per-observer-transaction accumulator. It contains no revision itself: the
|
|
79
78
|
* transaction wrapper assigns the revision only after all writes succeeded.
|
package/dist/invalidation.js
CHANGED
package/dist/progress.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { TransportCauseKind } from './diagnostics.js';
|
|
2
2
|
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
|
|
3
3
|
export interface SyncProgress {
|
|
4
|
+
/** Random per client core; `(epoch, attempt)` identifies the attempt (SPEC §7.6). */
|
|
5
|
+
readonly epoch: string;
|
|
4
6
|
readonly attempt: number;
|
|
5
7
|
readonly state: 'running' | 'complete' | 'failed';
|
|
6
8
|
readonly phase: 'request' | 'download' | 'import';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.84.0",
|
|
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.
|
|
124
|
+
"@syncular/core": "0.84.0"
|
|
125
125
|
},
|
|
126
126
|
"devDependencies": {
|
|
127
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
128
|
-
"@syncular/server": "0.
|
|
128
|
+
"@syncular/server": "0.84.0",
|
|
129
129
|
"playwright": "1.63.0",
|
|
130
130
|
"vite": "8.3.4"
|
|
131
131
|
}
|
package/src/client.ts
CHANGED
|
@@ -989,6 +989,8 @@ export class SyncClient {
|
|
|
989
989
|
/** §7.8: restarts the running drive's round bound when rows apply. */
|
|
990
990
|
#roundProgressed: (() => void) | undefined;
|
|
991
991
|
#progressAttempt = 0;
|
|
992
|
+
/** §7.6: scopes `#progressAttempt`; a new core gets a new epoch. */
|
|
993
|
+
readonly #epoch = crypto.randomUUID();
|
|
992
994
|
/**
|
|
993
995
|
* True from the synchronous entry of `sync()` until its serialized round
|
|
994
996
|
* settles — the "one loop owns the database" guard that rejects a
|
|
@@ -3031,13 +3033,6 @@ export class SyncClient {
|
|
|
3031
3033
|
);
|
|
3032
3034
|
}
|
|
3033
3035
|
|
|
3034
|
-
/** §7.3.5: remaining lease validity in ms (`expiresAtMs − now`), or
|
|
3035
|
-
* `undefined` if no lease is held. Negative once expired. */
|
|
3036
|
-
leaseRemainingMs(now: number = this.#now()): number | undefined {
|
|
3037
|
-
const expiresAtMs = this.#leaseState?.expiresAtMs;
|
|
3038
|
-
return expiresAtMs === undefined ? undefined : expiresAtMs - now;
|
|
3039
|
-
}
|
|
3040
|
-
|
|
3041
3036
|
/** True when syncing is stopped pending a client upgrade. */
|
|
3042
3037
|
get stopped(): boolean {
|
|
3043
3038
|
return this.#schemaFloor !== undefined;
|
|
@@ -3463,12 +3458,19 @@ export class SyncClient {
|
|
|
3463
3458
|
{ clientCommitId: supplied },
|
|
3464
3459
|
);
|
|
3465
3460
|
const clientCommitId = supplied ?? crypto.randomUUID();
|
|
3461
|
+
// §7.1: a patch reads the row as the commit's earlier operations leave
|
|
3462
|
+
// it. Keyed by `table rowId` (a table name holds no space): the JSON
|
|
3463
|
+
// values an earlier upsert wrote, or null after an earlier delete. A
|
|
3464
|
+
// patch changes neither presence nor a scope column, so it records
|
|
3465
|
+
// nothing.
|
|
3466
|
+
const staged = new Map<string, Record<string, JsonRowValue> | null>();
|
|
3466
3467
|
const operations: OutboxOperation[] = mutations.map((mutation) => {
|
|
3467
3468
|
const table = this.#table(mutation.table);
|
|
3468
3469
|
if (mutation.op === 'delete') {
|
|
3469
3470
|
// §2.4: the server rejects a rowId holding U+0000.
|
|
3470
3471
|
if (mutation.rowId.includes('\u0000'))
|
|
3471
3472
|
throw invalidRequest('rowId holds U+0000');
|
|
3473
|
+
staged.set(`${table.name} ${mutation.rowId}`, null);
|
|
3472
3474
|
return definedObject({
|
|
3473
3475
|
table: mutation.table,
|
|
3474
3476
|
rowId: mutation.rowId,
|
|
@@ -3486,11 +3488,13 @@ export class SyncClient {
|
|
|
3486
3488
|
const scopeColumns = new Set(table.scopeColumnByVariable.values());
|
|
3487
3489
|
const pkColumn = table.columns[table.primaryKeyIndex] as RowColumn;
|
|
3488
3490
|
const pkValue = requireRowId(normalized.get(pkColumn.name));
|
|
3489
|
-
|
|
3490
|
-
|
|
3491
|
-
|
|
3492
|
-
)
|
|
3493
|
-
|
|
3491
|
+
// The base: an earlier operation's JSON values, else the stored row.
|
|
3492
|
+
const key = `${table.name} ${pkValue}`;
|
|
3493
|
+
const base = staged.get(key);
|
|
3494
|
+
const stored = staged.has(key)
|
|
3495
|
+
? undefined
|
|
3496
|
+
: this.#rowById(table, pkValue);
|
|
3497
|
+
if (!base && !stored)
|
|
3494
3498
|
throw new ClientSyncError(
|
|
3495
3499
|
'sync.row_missing',
|
|
3496
3500
|
'a sparse patch requires a local row',
|
|
@@ -3501,7 +3505,8 @@ export class SyncClient {
|
|
|
3501
3505
|
// §3.4 rule 5 / §6.2: scope columns are immutable on update. The
|
|
3502
3506
|
// server accepts a present scope column whose value equals the
|
|
3503
3507
|
// stored row and applies it as a no-op, so a decoded envelope
|
|
3504
|
-
// round-trips. The local row
|
|
3508
|
+
// round-trips. The local row, as the commit's earlier operations
|
|
3509
|
+
// leave it, is the only value the client can
|
|
3505
3510
|
// prove equality against; when the row is absent locally the
|
|
3506
3511
|
// client cannot prove equality against the server's stored row
|
|
3507
3512
|
// and fails closed. A primary key that is also a scope column
|
|
@@ -3511,9 +3516,11 @@ export class SyncClient {
|
|
|
3511
3516
|
if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
|
|
3512
3517
|
if (
|
|
3513
3518
|
!Object.is(
|
|
3514
|
-
|
|
3515
|
-
|
|
3516
|
-
|
|
3519
|
+
stored
|
|
3520
|
+
? rowValueToJson(
|
|
3521
|
+
fromSqlValue(column, stored[column.name] ?? null),
|
|
3522
|
+
)
|
|
3523
|
+
: base?.[column.name],
|
|
3517
3524
|
rowValueToJson(
|
|
3518
3525
|
coerceSqlRepresentation(
|
|
3519
3526
|
column,
|
|
@@ -3570,12 +3577,9 @@ export class SyncClient {
|
|
|
3570
3577
|
);
|
|
3571
3578
|
// §7.1 insert intent: a full-row write of a row the replica does not
|
|
3572
3579
|
// show replays and encodes as a full row under every later schema.
|
|
3580
|
+
if (mutation.op !== 'patch') staged.set(`${table.name} ${pkValue}`, json);
|
|
3573
3581
|
const insert =
|
|
3574
|
-
mutation.op !== 'patch' &&
|
|
3575
|
-
this.#db.query(
|
|
3576
|
-
`SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=? LIMIT 1`,
|
|
3577
|
-
[pkSqlValue(table, pkValue)],
|
|
3578
|
-
).length === 0;
|
|
3582
|
+
mutation.op !== 'patch' && !this.#rowById(table, pkValue, '1');
|
|
3579
3583
|
return definedObject({
|
|
3580
3584
|
table: mutation.table,
|
|
3581
3585
|
rowId: pkValue,
|
|
@@ -3590,10 +3594,11 @@ export class SyncClient {
|
|
|
3590
3594
|
for (const operation of operations) {
|
|
3591
3595
|
const table = this.#table(operation.table);
|
|
3592
3596
|
if (!table.hasEncryptedColumns) continue;
|
|
3593
|
-
const keyId = this.#
|
|
3594
|
-
|
|
3595
|
-
|
|
3596
|
-
|
|
3597
|
+
const keyId = this.#rowById(
|
|
3598
|
+
table,
|
|
3599
|
+
operation.rowId,
|
|
3600
|
+
`${quoteIdent(SEALED_KEY_COLUMN)} AS k`,
|
|
3601
|
+
)?.k;
|
|
3597
3602
|
if (typeof keyId === 'string')
|
|
3598
3603
|
throw new ClientSyncError(
|
|
3599
3604
|
'client.encryption_key_missing',
|
|
@@ -4127,10 +4132,11 @@ export class SyncClient {
|
|
|
4127
4132
|
(table, rowId) => {
|
|
4128
4133
|
const selector = this.#encryption?.keyIdColumns?.[table.name];
|
|
4129
4134
|
if (selector === undefined) return undefined;
|
|
4130
|
-
const row = this.#
|
|
4131
|
-
|
|
4132
|
-
|
|
4133
|
-
|
|
4135
|
+
const row = this.#rowById(
|
|
4136
|
+
table,
|
|
4137
|
+
rowId,
|
|
4138
|
+
`${quoteIdent(selector)} AS value`,
|
|
4139
|
+
);
|
|
4134
4140
|
const value = row?.value;
|
|
4135
4141
|
return typeof value === 'string' && value.length > 0
|
|
4136
4142
|
? value
|
|
@@ -4364,15 +4370,24 @@ export class SyncClient {
|
|
|
4364
4370
|
this.#syncOutstanding = true;
|
|
4365
4371
|
this.#beginDiagnosticsDeferral();
|
|
4366
4372
|
const startedAtMs = this.#now();
|
|
4373
|
+
// `#syncOutstanding` keeps this the attempt `#runSync` starts (§7.6).
|
|
4374
|
+
const attempt = this.#progressAttempt + 1;
|
|
4375
|
+
const round = () => {
|
|
4376
|
+
const completedAtMs = this.#now();
|
|
4377
|
+
return {
|
|
4378
|
+
epoch: this.#epoch,
|
|
4379
|
+
attempt,
|
|
4380
|
+
startedAtMs,
|
|
4381
|
+
completedAtMs,
|
|
4382
|
+
durationMs: Math.max(0, completedAtMs - startedAtMs),
|
|
4383
|
+
};
|
|
4384
|
+
};
|
|
4367
4385
|
return this.#serialize(() => this.#runSync(signal))
|
|
4368
4386
|
.then(
|
|
4369
4387
|
(summary) => {
|
|
4370
|
-
const completedAtMs = this.#now();
|
|
4371
4388
|
this.#lastRound = {
|
|
4372
4389
|
status: 'succeeded',
|
|
4373
|
-
|
|
4374
|
-
completedAtMs,
|
|
4375
|
-
durationMs: Math.max(0, completedAtMs - startedAtMs),
|
|
4390
|
+
...round(),
|
|
4376
4391
|
counters: this.#diagnosticRoundCounters(summary),
|
|
4377
4392
|
};
|
|
4378
4393
|
this.#emitDiagnostics();
|
|
@@ -4380,8 +4395,13 @@ export class SyncClient {
|
|
|
4380
4395
|
},
|
|
4381
4396
|
(caught: unknown) => {
|
|
4382
4397
|
const error = classifySqliteFailure(caught).error;
|
|
4383
|
-
|
|
4398
|
+
// A gate refusal starts no attempt and records no round.
|
|
4399
|
+
if (this.#progressAttempt !== attempt) throw error;
|
|
4384
4400
|
const code = (error as { code?: unknown }).code;
|
|
4401
|
+
const errorCode =
|
|
4402
|
+
typeof code === 'string'
|
|
4403
|
+
? this.#diagnosticCode(code)
|
|
4404
|
+
: 'client.unknown_failure';
|
|
4385
4405
|
const details =
|
|
4386
4406
|
typeof error === 'object' && error !== null && 'details' in error
|
|
4387
4407
|
? error.details
|
|
@@ -4428,27 +4448,19 @@ export class SyncClient {
|
|
|
4428
4448
|
this.#progress.update(
|
|
4429
4449
|
definedObject({
|
|
4430
4450
|
state: 'failed',
|
|
4431
|
-
errorCode
|
|
4432
|
-
typeof code === 'string'
|
|
4433
|
-
? this.#diagnosticCode(code)
|
|
4434
|
-
: 'client.unknown_failure',
|
|
4451
|
+
errorCode,
|
|
4435
4452
|
retryDelayMs: this.#roundRetryDelayMs,
|
|
4436
4453
|
causeKind,
|
|
4437
4454
|
httpStatus,
|
|
4438
4455
|
}),
|
|
4439
4456
|
);
|
|
4440
|
-
this.#lastRound = {
|
|
4457
|
+
this.#lastRound = definedObject({
|
|
4441
4458
|
status: 'failed',
|
|
4442
|
-
|
|
4443
|
-
|
|
4444
|
-
|
|
4445
|
-
|
|
4446
|
-
|
|
4447
|
-
? this.#diagnosticCode(code)
|
|
4448
|
-
: 'client.unknown_failure',
|
|
4449
|
-
...(causeKind !== undefined ? { causeKind } : {}),
|
|
4450
|
-
...(httpStatus !== undefined ? { httpStatus } : {}),
|
|
4451
|
-
};
|
|
4459
|
+
...round(),
|
|
4460
|
+
errorCode,
|
|
4461
|
+
causeKind,
|
|
4462
|
+
httpStatus,
|
|
4463
|
+
});
|
|
4452
4464
|
this.#emitDiagnostics();
|
|
4453
4465
|
throw error;
|
|
4454
4466
|
},
|
|
@@ -4485,6 +4497,7 @@ export class SyncClient {
|
|
|
4485
4497
|
this.#requireTransport();
|
|
4486
4498
|
this.#roundRetryDelayMs = undefined;
|
|
4487
4499
|
this.#progress.emit({
|
|
4500
|
+
epoch: this.#epoch,
|
|
4488
4501
|
attempt: ++this.#progressAttempt,
|
|
4489
4502
|
state: 'running',
|
|
4490
4503
|
phase: 'request',
|
|
@@ -6176,10 +6189,11 @@ export class SyncClient {
|
|
|
6176
6189
|
table.scopePrefixByVariable.has(variable),
|
|
6177
6190
|
);
|
|
6178
6191
|
if (mappings.length === 0) return false;
|
|
6179
|
-
const row = this.#
|
|
6180
|
-
|
|
6181
|
-
|
|
6182
|
-
|
|
6192
|
+
const row = this.#rowById(
|
|
6193
|
+
table,
|
|
6194
|
+
rowId,
|
|
6195
|
+
mappings.map(([, column]) => quoteIdent(column)).join(),
|
|
6196
|
+
);
|
|
6183
6197
|
if (row === undefined) return false;
|
|
6184
6198
|
let recorded = false;
|
|
6185
6199
|
for (const [variable, column] of mappings) {
|
|
@@ -6613,10 +6627,7 @@ export class SyncClient {
|
|
|
6613
6627
|
...table.columns.map((column) => quoteIdent(column.name)),
|
|
6614
6628
|
quoteIdent(SYNC_VERSION_COLUMN),
|
|
6615
6629
|
];
|
|
6616
|
-
const row = this.#
|
|
6617
|
-
`SELECT ${columns.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
|
|
6618
|
-
[pkSqlValue(table, operation.rowId)],
|
|
6619
|
-
)[0];
|
|
6630
|
+
const row = this.#rowById(table, operation.rowId, columns.join());
|
|
6620
6631
|
if (row === undefined) return { opIndex, existed: false };
|
|
6621
6632
|
const values: Record<string, ReturnType<typeof rowValueToJson>> = {};
|
|
6622
6633
|
for (const column of table.columns) {
|
|
@@ -6679,10 +6690,11 @@ export class SyncClient {
|
|
|
6679
6690
|
if (operation.op !== 'upsert') continue;
|
|
6680
6691
|
const table = this.#schema.tables.get(operation.table);
|
|
6681
6692
|
if (table === undefined) continue;
|
|
6682
|
-
const row = this.#
|
|
6683
|
-
|
|
6684
|
-
|
|
6685
|
-
|
|
6693
|
+
const row = this.#rowById(
|
|
6694
|
+
table,
|
|
6695
|
+
operation.rowId,
|
|
6696
|
+
`${quoteIdent(SYNC_VERSION_COLUMN)} AS v`,
|
|
6697
|
+
);
|
|
6686
6698
|
if (row !== undefined && row.v === OPTIMISTIC_VERSION) {
|
|
6687
6699
|
batch.table(table.name);
|
|
6688
6700
|
deleteLocalRow(this.#db, table, operation.rowId);
|
|
@@ -6787,10 +6799,7 @@ export class SyncClient {
|
|
|
6787
6799
|
if (batch !== undefined && !precise) batch.table(op.table);
|
|
6788
6800
|
continue;
|
|
6789
6801
|
}
|
|
6790
|
-
const local = this.#
|
|
6791
|
-
`SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
|
|
6792
|
-
[pkSqlValue(table, op.rowId)],
|
|
6793
|
-
)[0];
|
|
6802
|
+
const local = this.#rowById(table, op.rowId);
|
|
6794
6803
|
if (local === undefined && !full) {
|
|
6795
6804
|
if (batch !== undefined && !precise) batch.table(op.table);
|
|
6796
6805
|
continue;
|
|
@@ -7045,6 +7054,18 @@ export class SyncClient {
|
|
|
7045
7054
|
|
|
7046
7055
|
// -- helpers -----------------------------------------------------------------
|
|
7047
7056
|
|
|
7057
|
+
/** The local row `rowId` of `table`, selecting `columns`. */
|
|
7058
|
+
#rowById(
|
|
7059
|
+
table: CompiledClientTable,
|
|
7060
|
+
rowId: string,
|
|
7061
|
+
columns = '*',
|
|
7062
|
+
): SqlRow | undefined {
|
|
7063
|
+
return this.#db.query(
|
|
7064
|
+
`SELECT ${columns} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
|
|
7065
|
+
[pkSqlValue(table, rowId)],
|
|
7066
|
+
)[0];
|
|
7067
|
+
}
|
|
7068
|
+
|
|
7048
7069
|
#table(name: string): CompiledClientTable {
|
|
7049
7070
|
const table = this.#schema.tables.get(name);
|
|
7050
7071
|
if (table === undefined) {
|
package/src/diagnostics.ts
CHANGED
|
@@ -91,9 +91,12 @@ export interface DiagnosticRoundCounters {
|
|
|
91
91
|
readonly deferredCommits: number;
|
|
92
92
|
}
|
|
93
93
|
|
|
94
|
+
/** One completed sync round. `(epoch, attempt)` identifies it (SPEC §7.6). */
|
|
94
95
|
export type DiagnosticLastRound =
|
|
95
96
|
| {
|
|
96
97
|
readonly status: 'succeeded';
|
|
98
|
+
readonly epoch: string;
|
|
99
|
+
readonly attempt: number;
|
|
97
100
|
readonly startedAtMs: number;
|
|
98
101
|
readonly completedAtMs: number;
|
|
99
102
|
readonly durationMs: number;
|
|
@@ -101,6 +104,8 @@ export type DiagnosticLastRound =
|
|
|
101
104
|
}
|
|
102
105
|
| {
|
|
103
106
|
readonly status: 'failed';
|
|
107
|
+
readonly epoch: string;
|
|
108
|
+
readonly attempt: number;
|
|
104
109
|
readonly startedAtMs: number;
|
|
105
110
|
readonly completedAtMs: number;
|
|
106
111
|
readonly durationMs: number;
|
package/src/invalidation.ts
CHANGED
|
@@ -79,10 +79,6 @@ export interface CommandResult<T> {
|
|
|
79
79
|
readonly effects: CommandEffects;
|
|
80
80
|
}
|
|
81
81
|
|
|
82
|
-
export const NO_COMMAND_EFFECTS: CommandEffects = {
|
|
83
|
-
sync: { kind: 'none' },
|
|
84
|
-
};
|
|
85
|
-
|
|
86
82
|
interface MutableTableChange {
|
|
87
83
|
tableWide: boolean;
|
|
88
84
|
scopeKeys: Set<string> | undefined;
|
package/src/progress.ts
CHANGED
|
@@ -2,6 +2,8 @@ import type { TransportCauseKind } from './diagnostics';
|
|
|
2
2
|
|
|
3
3
|
/** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
|
|
4
4
|
export interface SyncProgress {
|
|
5
|
+
/** Random per client core; `(epoch, attempt)` identifies the attempt (SPEC §7.6). */
|
|
6
|
+
readonly epoch: string;
|
|
5
7
|
readonly attempt: number;
|
|
6
8
|
readonly state: 'running' | 'complete' | 'failed';
|
|
7
9
|
readonly phase: 'request' | 'download' | 'import';
|