@syncular/client 0.68.0 → 0.70.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/dist/apply.js +13 -1
- package/dist/client.d.ts +8 -3
- package/dist/client.js +30 -28
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +2 -2
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +3 -2
- package/dist/http.js +17 -21
- package/dist/native-bridge.d.ts +3 -1
- package/dist/native-bridge.js +4 -1
- package/dist/outbox.d.ts +6 -1
- package/dist/outbox.js +26 -15
- package/dist/outcomes.js +6 -5
- package/dist/worker-core.js +2 -2
- package/dist/worker-host.d.ts +3 -1
- package/dist/worker-host.js +2 -2
- package/dist/worker-protocol.d.ts +3 -1
- package/package.json +3 -3
- package/src/apply.ts +27 -1
- package/src/client.ts +58 -40
- package/src/errors.ts +7 -1
- package/src/failed-overlay.ts +25 -29
- package/src/http.ts +20 -25
- package/src/native-bridge.ts +7 -1
- package/src/outbox.ts +49 -29
- package/src/outcomes.ts +8 -6
- package/src/worker-core.ts +2 -2
- package/src/worker-host.ts +5 -2
- package/src/worker-protocol.ts +4 -1
package/dist/apply.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { hasUniqueIndex } from './schema.js';
|
|
2
|
-
import {
|
|
2
|
+
import { chainsOn, countOutbox, listOutbox, OUTBOX_IMAGES, OUTBOX_TABLE, } from './outbox.js';
|
|
3
3
|
import { RETAINED_ROWS } from './failed-overlay.js';
|
|
4
4
|
import { retainedBaseWrite, restoreFailedBases } from './failed-overlay.js';
|
|
5
5
|
/**
|
|
@@ -108,6 +108,18 @@ export async function applyCommitFrame(db, schema, frame, encryption, transactio
|
|
|
108
108
|
const { rowId, rowVersion } = frame.changes[index];
|
|
109
109
|
const land = lands(db, change.table, rowId, rowVersion, kept, skipped);
|
|
110
110
|
db.exec(`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`, [frame.commitSeq, change.table.name, rowId]);
|
|
111
|
+
// §7.1 chained base: this change names the version an acknowledged own
|
|
112
|
+
// commit wrote; pending upserts chained on it move to that version.
|
|
113
|
+
for (const { op } of db.query(`SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`, [change.table.name, rowId, frame.commitSeq])) {
|
|
114
|
+
const earlier = JSON.parse(op);
|
|
115
|
+
for (const commit of listOutbox(db, scope))
|
|
116
|
+
db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
|
|
117
|
+
JSON.stringify(commit.operations.map((operation) => chainsOn(earlier, operation)
|
|
118
|
+
? { ...operation, baseVersion: rowVersion }
|
|
119
|
+
: operation)),
|
|
120
|
+
commit.seq,
|
|
121
|
+
]);
|
|
122
|
+
}
|
|
111
123
|
db.exec(`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`, [change.table.name, rowId, frame.commitSeq]);
|
|
112
124
|
if (!land)
|
|
113
125
|
continue;
|
package/dist/client.d.ts
CHANGED
|
@@ -630,11 +630,16 @@ export declare class SyncClient {
|
|
|
630
630
|
/**
|
|
631
631
|
* Record one atomic local commit (§7.1): appended to the outbox in
|
|
632
632
|
* schema-agnostic form and applied optimistically to the local mirror.
|
|
633
|
-
* Returns the generated `clientCommitId
|
|
633
|
+
* Returns the generated `clientCommitId`, or the caller's unused one
|
|
634
|
+
* (`client.commit_id_reused` when this replica holds it).
|
|
634
635
|
*/
|
|
635
|
-
mutate(mutations: readonly MutationInput[]
|
|
636
|
+
mutate(mutations: readonly MutationInput[], options?: {
|
|
637
|
+
readonly clientCommitId?: string;
|
|
638
|
+
}): string;
|
|
636
639
|
/** Host-facing mutation result with explicit network work intent (§7.5). */
|
|
637
|
-
mutateCommand(mutations: readonly MutationInput[]
|
|
640
|
+
mutateCommand(mutations: readonly MutationInput[], options?: {
|
|
641
|
+
readonly clientCommitId?: string;
|
|
642
|
+
}): CommandResult<string>;
|
|
638
643
|
/**
|
|
639
644
|
* Partial update over the §6.1 sparse wire: record one upsert whose
|
|
640
645
|
* presence set is the primary key plus the supplied non-scope columns.
|
package/dist/client.js
CHANGED
|
@@ -14,7 +14,7 @@ import { ProgressEmitter, } from './progress.js';
|
|
|
14
14
|
* ownership behind `LeaderLock`. One combined push+pull request per
|
|
15
15
|
* `sync()` round (§7.2); local reads go straight to the database.
|
|
16
16
|
*/
|
|
17
|
-
import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, } from '@syncular/core';
|
|
17
|
+
import { canonicalScopeJson, decodeResponse, DecodeError, decodeRow, decodeRowsSegment, encodeRequest, encodeRow, encodeSparseRow, encodePresencePublish, isRoundFailureCode, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseJsonDocument, parseRealtimeServerEvent, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, registrationDigest, unitId, definedObject, } from '@syncular/core';
|
|
18
18
|
import { EncryptError } from '@syncular/core';
|
|
19
19
|
import { EncodeError } from '@syncular/core';
|
|
20
20
|
import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
|
|
@@ -26,7 +26,7 @@ import { singleOwnerLock, } from './leader-lock.js';
|
|
|
26
26
|
import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
|
|
27
27
|
import { compileLocalDataRebootstrap, localDataRebootstrapMetaKey, } from './local-rebootstrap.js';
|
|
28
28
|
import { decodeLocalDataRebootstrapReceipt, encodeLocalDataRebootstrapReceipt, } from './local-rebootstrap-receipt.js';
|
|
29
|
-
import { appendOutboxCommit, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
|
|
29
|
+
import { appendOutboxCommit, chainsOn, deleteOutboxCommit, encodeOutboxCommit, listOutbox, iterateOutbox, countOutbox, listOutboxBeforeImages, OutboxEncodeError, replaceOutboxBeforeImages, } from './outbox.js';
|
|
30
30
|
import { activeFailureRecords, isStoredOperation, listCommitOutcomes, persistCommitOutcomeResolution, persistedCommitOutcome, pruneCommitOutcomes, commitOutcome as readCommitOutcome, recordCommitOutcome, } 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';
|
|
@@ -941,8 +941,7 @@ export class SyncClient {
|
|
|
941
941
|
});
|
|
942
942
|
};
|
|
943
943
|
const deliveryOf = (id) => {
|
|
944
|
-
|
|
945
|
-
if (pending)
|
|
944
|
+
if (this.#outboxCommitExists(id))
|
|
946
945
|
return { status: 'pending', clientCommitId: id };
|
|
947
946
|
const outcome = persistedCommitOutcome(this.#db, id);
|
|
948
947
|
return outcome === undefined
|
|
@@ -2222,14 +2221,22 @@ export class SyncClient {
|
|
|
2222
2221
|
/**
|
|
2223
2222
|
* Record one atomic local commit (§7.1): appended to the outbox in
|
|
2224
2223
|
* schema-agnostic form and applied optimistically to the local mirror.
|
|
2225
|
-
* Returns the generated `clientCommitId
|
|
2224
|
+
* Returns the generated `clientCommitId`, or the caller's unused one
|
|
2225
|
+
* (`client.commit_id_reused` when this replica holds it).
|
|
2226
2226
|
*/
|
|
2227
|
-
mutate(mutations) {
|
|
2228
|
-
return this.#recordMutations(mutations);
|
|
2227
|
+
mutate(mutations, options) {
|
|
2228
|
+
return this.#recordMutations(mutations, options?.clientCommitId);
|
|
2229
2229
|
}
|
|
2230
|
-
#recordMutations(mutations) {
|
|
2230
|
+
#recordMutations(mutations, supplied) {
|
|
2231
2231
|
this.#requireActive();
|
|
2232
|
-
|
|
2232
|
+
// §7.1: a supplied ID is non-empty (§6.1) and unknown to this replica.
|
|
2233
|
+
if (supplied === '')
|
|
2234
|
+
throw invalidRequest('clientCommitId is empty');
|
|
2235
|
+
if (supplied !== undefined &&
|
|
2236
|
+
(this.#outboxCommitExists(supplied) ||
|
|
2237
|
+
readCommitOutcome(this.#db, supplied)))
|
|
2238
|
+
throw new ClientSyncError('client.commit_id_reused', 'clientCommitId is held', false, { clientCommitId: supplied });
|
|
2239
|
+
const clientCommitId = supplied ?? crypto.randomUUID();
|
|
2233
2240
|
const operations = mutations.map((mutation) => {
|
|
2234
2241
|
const table = this.#table(mutation.table);
|
|
2235
2242
|
if (mutation.op === 'delete') {
|
|
@@ -2259,6 +2266,7 @@ export class SyncClient {
|
|
|
2259
2266
|
for (const column of table.columns) {
|
|
2260
2267
|
if (!normalized.has(column.name))
|
|
2261
2268
|
continue;
|
|
2269
|
+
const at = { table: table.name, column: column.name };
|
|
2262
2270
|
// §3.4 rule 5 / §6.2: scope columns are immutable on update. The
|
|
2263
2271
|
// server accepts a present scope column whose value equals the
|
|
2264
2272
|
// stored row and applies it as a no-op, so a decoded envelope
|
|
@@ -2271,14 +2279,14 @@ export class SyncClient {
|
|
|
2271
2279
|
// proven equal already.
|
|
2272
2280
|
if (scopeColumns.has(column.name) && column.name !== pkColumn.name) {
|
|
2273
2281
|
if (!Object.is(rowValueToJson(fromSqlValue(column, local[column.name] ?? null)), rowValueToJson(coerceSqlRepresentation(column, normalized.get(column.name))))) {
|
|
2274
|
-
throw invalidRequest(
|
|
2282
|
+
throw invalidRequest('patch cannot write a scope column (§3.4)', false, at);
|
|
2275
2283
|
}
|
|
2276
2284
|
continue;
|
|
2277
2285
|
}
|
|
2278
2286
|
const value = normalized.get(column.name);
|
|
2279
2287
|
if (value === undefined || value === null) {
|
|
2280
2288
|
if (!column.nullable) {
|
|
2281
|
-
throw invalidRequest(
|
|
2289
|
+
throw invalidRequest('a non-nullable column is null (§6.1)', false, at);
|
|
2282
2290
|
}
|
|
2283
2291
|
json[column.name] = null;
|
|
2284
2292
|
continue;
|
|
@@ -2363,9 +2371,9 @@ export class SyncClient {
|
|
|
2363
2371
|
return clientCommitId;
|
|
2364
2372
|
}
|
|
2365
2373
|
/** Host-facing mutation result with explicit network work intent (§7.5). */
|
|
2366
|
-
mutateCommand(mutations) {
|
|
2374
|
+
mutateCommand(mutations, options) {
|
|
2367
2375
|
return {
|
|
2368
|
-
value: this.mutate(mutations),
|
|
2376
|
+
value: this.mutate(mutations, options),
|
|
2369
2377
|
effects: {
|
|
2370
2378
|
sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
|
|
2371
2379
|
},
|
|
@@ -2386,7 +2394,9 @@ export class SyncClient {
|
|
|
2386
2394
|
const normalized = normalizeRecordKeys(compiled, partial);
|
|
2387
2395
|
const pkOverride = normalized.get(pkColumn.name);
|
|
2388
2396
|
if (pkOverride !== undefined && String(pkOverride) !== rowId) {
|
|
2389
|
-
throw invalidRequest(
|
|
2397
|
+
throw invalidRequest('patch cannot change the primary key', false, {
|
|
2398
|
+
table,
|
|
2399
|
+
});
|
|
2390
2400
|
}
|
|
2391
2401
|
const pkType = localColumnType(pkColumn);
|
|
2392
2402
|
const typedPk = pkType === 'integer' &&
|
|
@@ -2697,7 +2707,10 @@ export class SyncClient {
|
|
|
2697
2707
|
// §6.1/§7.1: the commit-count and operation caps are hard. A first
|
|
2698
2708
|
// commit that alone exceeds the operation cap is a typed capacity error
|
|
2699
2709
|
// and stays queued; a later one defers with the complete suffix.
|
|
2700
|
-
|
|
2710
|
+
// §7.1 chained base: a commit chained on an earlier commit of this
|
|
2711
|
+
// request waits for that commit's change, which supplies its version.
|
|
2712
|
+
if ((maxCommits !== undefined && pushFrames.length >= maxCommits) ||
|
|
2713
|
+
outbox.some((earlier) => earlier.operations.some((prior) => commit.operations.some((operation) => chainsOn(prior, operation))))) {
|
|
2701
2714
|
deferred = pendingCount - processed;
|
|
2702
2715
|
break;
|
|
2703
2716
|
}
|
|
@@ -2721,12 +2734,8 @@ export class SyncClient {
|
|
|
2721
2734
|
});
|
|
2722
2735
|
}
|
|
2723
2736
|
catch (error) {
|
|
2724
|
-
if (error instanceof OutboxEncodeError
|
|
2725
|
-
|
|
2726
|
-
processed += 1;
|
|
2727
|
-
continue;
|
|
2728
|
-
}
|
|
2729
|
-
if (error instanceof EncryptError) {
|
|
2737
|
+
if (error instanceof OutboxEncodeError ||
|
|
2738
|
+
error instanceof EncryptError) {
|
|
2730
2739
|
this.#dropIncompatibleCommit(commit, error.message, error.code);
|
|
2731
2740
|
processed += 1;
|
|
2732
2741
|
continue;
|
|
@@ -5036,13 +5045,6 @@ export class SyncClient {
|
|
|
5036
5045
|
}
|
|
5037
5046
|
}
|
|
5038
5047
|
}
|
|
5039
|
-
function definedObject(record) {
|
|
5040
|
-
for (const key of Object.keys(record)) {
|
|
5041
|
-
if (record[key] === undefined)
|
|
5042
|
-
delete record[key];
|
|
5043
|
-
}
|
|
5044
|
-
return record;
|
|
5045
|
-
}
|
|
5046
5048
|
function requireRowId(value) {
|
|
5047
5049
|
if (typeof value === 'string' && value.length > 0)
|
|
5048
5050
|
return value;
|
package/dist/errors.d.ts
CHANGED
|
@@ -34,7 +34,7 @@ export declare class ClientSyncError extends Error {
|
|
|
34
34
|
constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>, recommendedAction?: string);
|
|
35
35
|
}
|
|
36
36
|
/** Shared invalid-request construction for client validators and transport guards. */
|
|
37
|
-
export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
|
|
37
|
+
export declare function invalidRequest(message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>): ClientSyncError;
|
|
38
38
|
/** Shared retryable `sync.transport_failed` construction for client transports. */
|
|
39
39
|
export declare function transportFailed(message: string, details?: Readonly<Record<string, unknown>>): ClientSyncError;
|
|
40
40
|
/**
|
package/dist/errors.js
CHANGED
|
@@ -40,8 +40,8 @@ export class ClientSyncError extends Error {
|
|
|
40
40
|
}
|
|
41
41
|
}
|
|
42
42
|
/** Shared invalid-request construction for client validators and transport guards. */
|
|
43
|
-
export function invalidRequest(message, retryable = false) {
|
|
44
|
-
return new ClientSyncError('sync.invalid_request', message, retryable);
|
|
43
|
+
export function invalidRequest(message, retryable = false, details) {
|
|
44
|
+
return new ClientSyncError('sync.invalid_request', message, retryable, details);
|
|
45
45
|
}
|
|
46
46
|
/** Shared retryable `sync.transport_failed` construction for client transports. */
|
|
47
47
|
export function transportFailed(message, details) {
|
package/dist/failed-overlay.d.ts
CHANGED
|
@@ -4,7 +4,6 @@ import type { CompiledClientSchema, CompiledClientTable, JsonRowValue } from './
|
|
|
4
4
|
import type { RowValue } from '@syncular/core';
|
|
5
5
|
import type { RetainedCommitRow } from './outcomes.js';
|
|
6
6
|
import type { OutboxCommit, OutboxBeforeImage } from './outbox.js';
|
|
7
|
-
/** Protected failure state. The server base advances independently of intent. */
|
|
8
7
|
export declare function ensureFailedOverlaySchema(db: ClientDatabase): void;
|
|
9
8
|
export declare function retainedBaseWrite(db: ClientDatabase, table: CompiledClientTable, rowId: string, values?: Readonly<Record<string, JsonRowValue>>, version?: number): void;
|
|
10
9
|
export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommit, images: readonly OutboxBeforeImage[], commitSeq?: number): void;
|
package/dist/failed-overlay.js
CHANGED
|
@@ -6,6 +6,7 @@ import { ClientSyncError } from './errors.js';
|
|
|
6
6
|
import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
|
|
7
7
|
import { deleteLocalRow, upsertLocalRow } from './apply.js';
|
|
8
8
|
/** Protected failure state. The server base advances independently of intent. */
|
|
9
|
+
const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
|
|
9
10
|
export function ensureFailedOverlaySchema(db) {
|
|
10
11
|
db.exec(`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`);
|
|
11
12
|
const columns = db.query(`PRAGMA table_info(${RETAINED_ROWS})`);
|
|
@@ -37,7 +38,7 @@ export function retainedBaseWrite(db, table, rowId, values, version) {
|
|
|
37
38
|
serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
|
|
38
39
|
})));
|
|
39
40
|
}
|
|
40
|
-
db.exec(
|
|
41
|
+
db.exec(SET_UNIQUE_CONFLICTS, [
|
|
41
42
|
conflicts.length
|
|
42
43
|
? JSON.stringify(conflicts.sort((a, b) => table.indexes.findIndex((index) => index.name === a.index) -
|
|
43
44
|
table.indexes.findIndex((index) => index.name === b.index)))
|
|
@@ -143,7 +144,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
|
|
|
143
144
|
const authorized = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue)).filter((conflict) => conflict.serverVersion >= 0 &&
|
|
144
145
|
!db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
|
|
145
146
|
if (authorized.length)
|
|
146
|
-
db.exec(
|
|
147
|
+
db.exec(SET_UNIQUE_CONFLICTS, [
|
|
147
148
|
JSON.stringify(authorized.map((conflict) => ({
|
|
148
149
|
...conflict,
|
|
149
150
|
serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
|
package/dist/http.js
CHANGED
|
@@ -264,15 +264,9 @@ export function httpBlobTransport(blobsBaseUrl, options) {
|
|
|
264
264
|
catch {
|
|
265
265
|
// Not JSON: inline bytes.
|
|
266
266
|
}
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
url: envelope.url,
|
|
271
|
-
...(typeof envelope.urlExpiresAtMs === 'number'
|
|
272
|
-
? { urlExpiresAtMs: envelope.urlExpiresAtMs }
|
|
273
|
-
: {}),
|
|
274
|
-
};
|
|
275
|
-
}
|
|
267
|
+
const grant = envelope && urlGrant(envelope);
|
|
268
|
+
if (grant)
|
|
269
|
+
return grant;
|
|
276
270
|
}
|
|
277
271
|
return { kind: 'bytes', bytes };
|
|
278
272
|
},
|
|
@@ -304,18 +298,8 @@ export function httpBlobTransport(blobsBaseUrl, options) {
|
|
|
304
298
|
if (!response.ok)
|
|
305
299
|
await throwHttpError(response);
|
|
306
300
|
const body = (await transfer('blob grant read failed', () => response.json(), response.status));
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
kind: 'url',
|
|
310
|
-
url: body.url,
|
|
311
|
-
...(typeof body.urlExpiresAtMs === 'number'
|
|
312
|
-
? { urlExpiresAtMs: body.urlExpiresAtMs }
|
|
313
|
-
: {}),
|
|
314
|
-
};
|
|
315
|
-
}
|
|
316
|
-
if (body.present === true)
|
|
317
|
-
return { kind: 'present' };
|
|
318
|
-
return { kind: 'none' };
|
|
301
|
+
return (urlGrant(body) ??
|
|
302
|
+
(body.present === true ? { kind: 'present' } : { kind: 'none' }));
|
|
319
303
|
},
|
|
320
304
|
// §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
|
|
321
305
|
uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
|
|
@@ -392,3 +376,15 @@ export function webSocketRealtimeConnector(realtimeUrl) {
|
|
|
392
376
|
};
|
|
393
377
|
});
|
|
394
378
|
}
|
|
379
|
+
/** §5.9.3, §5.9.5: a JSON body with a string `url` is a presigned grant. */
|
|
380
|
+
function urlGrant(body) {
|
|
381
|
+
return typeof body.url === 'string'
|
|
382
|
+
? {
|
|
383
|
+
kind: 'url',
|
|
384
|
+
url: body.url,
|
|
385
|
+
...(typeof body.urlExpiresAtMs === 'number'
|
|
386
|
+
? { urlExpiresAtMs: body.urlExpiresAtMs }
|
|
387
|
+
: {}),
|
|
388
|
+
}
|
|
389
|
+
: undefined;
|
|
390
|
+
}
|
package/dist/native-bridge.d.ts
CHANGED
|
@@ -149,7 +149,9 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
|
|
|
149
149
|
localRevision(): Promise<bigint>;
|
|
150
150
|
statusSnapshot(): Promise<SyncStatusSnapshot>;
|
|
151
151
|
diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
|
|
152
|
-
mutate(mutations: readonly MutationInput[]
|
|
152
|
+
mutate(mutations: readonly MutationInput[], options?: {
|
|
153
|
+
readonly clientCommitId?: string;
|
|
154
|
+
}): Promise<string>;
|
|
153
155
|
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
154
156
|
readonly baseVersion?: number;
|
|
155
157
|
}): Promise<string>;
|
package/dist/native-bridge.js
CHANGED
|
@@ -533,9 +533,12 @@ export class NativeBridgeClient {
|
|
|
533
533
|
role: 'single',
|
|
534
534
|
});
|
|
535
535
|
}
|
|
536
|
-
async mutate(mutations) {
|
|
536
|
+
async mutate(mutations, options) {
|
|
537
537
|
const result = (await this.command('mutate', {
|
|
538
538
|
mutations: encodeValue(mutations),
|
|
539
|
+
...(options?.clientCommitId === undefined
|
|
540
|
+
? {}
|
|
541
|
+
: { clientCommitId: options.clientCommitId }),
|
|
539
542
|
}));
|
|
540
543
|
return result.clientCommitId;
|
|
541
544
|
}
|
package/dist/outbox.d.ts
CHANGED
|
@@ -38,6 +38,11 @@ export interface OutboxCommit {
|
|
|
38
38
|
readonly createdAtMs: number;
|
|
39
39
|
readonly operations: readonly OutboxOperation[];
|
|
40
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
|
|
43
|
+
* and presents only columns `earlier` presents.
|
|
44
|
+
*/
|
|
45
|
+
export declare function chainsOn(earlier: OutboxOperation, later: OutboxOperation): boolean;
|
|
41
46
|
/** Protected local rollback image; never encoded or exposed in outcomes. */
|
|
42
47
|
export interface OutboxBeforeImage {
|
|
43
48
|
readonly opIndex: number;
|
|
@@ -68,7 +73,7 @@ export declare function replaceOutboxBeforeImages(db: ClientDatabase, commit: Pi
|
|
|
68
73
|
* so the caller can drop the commit through the rejection channel.
|
|
69
74
|
*/
|
|
70
75
|
export declare class OutboxEncodeError extends ClientSyncError {
|
|
71
|
-
constructor(
|
|
76
|
+
constructor();
|
|
72
77
|
}
|
|
73
78
|
/**
|
|
74
79
|
* Encode one outbox commit as a `PUSH_COMMIT` frame with the current
|
package/dist/outbox.js
CHANGED
|
@@ -8,9 +8,22 @@ export const OUTBOX_IMAGES = '_syncular_outbox_before_images';
|
|
|
8
8
|
* request is built — a commit recorded under schema N replays after an
|
|
9
9
|
* upgrade to N+1 by re-encoding.
|
|
10
10
|
*/
|
|
11
|
-
import { encodeSparseRow, } from '@syncular/core';
|
|
11
|
+
import { definedObject, encodeSparseRow, } from '@syncular/core';
|
|
12
12
|
import { ClientSyncError, invalidRequest } from './errors.js';
|
|
13
13
|
import { jsonToRowValue, } from './schema.js';
|
|
14
|
+
/**
|
|
15
|
+
* §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
|
|
16
|
+
* and presents only columns `earlier` presents.
|
|
17
|
+
*/
|
|
18
|
+
export function chainsOn(earlier, later) {
|
|
19
|
+
// Only an upsert carries values, and it always carries its primary key.
|
|
20
|
+
return (later.op === 'upsert' &&
|
|
21
|
+
earlier.rowId === later.rowId &&
|
|
22
|
+
earlier.table === later.table &&
|
|
23
|
+
later.baseVersion > 0 &&
|
|
24
|
+
earlier.baseVersion === later.baseVersion &&
|
|
25
|
+
Object.keys(later.values ?? {}).every((column) => earlier.values?.[column] !== undefined));
|
|
26
|
+
}
|
|
14
27
|
export function appendOutboxCommit(db, clientCommitId, operations, nowMs, beforeImages = []) {
|
|
15
28
|
if (operations.length === 0) {
|
|
16
29
|
throw new ClientSyncError('sync.empty_commit', 'a local commit must carry at least one operation (§6.1)');
|
|
@@ -110,8 +123,8 @@ export function replaceOutboxBeforeImages(db, commit, replacements) {
|
|
|
110
123
|
* so the caller can drop the commit through the rejection channel.
|
|
111
124
|
*/
|
|
112
125
|
export class OutboxEncodeError extends ClientSyncError {
|
|
113
|
-
constructor(
|
|
114
|
-
super('sync.outbox_incompatible',
|
|
126
|
+
constructor() {
|
|
127
|
+
super('sync.outbox_incompatible', 'the persisted commit cannot encode under the current schema', false);
|
|
115
128
|
}
|
|
116
129
|
}
|
|
117
130
|
function sparseValues(table, values, insert) {
|
|
@@ -119,7 +132,7 @@ function sparseValues(table, values, insert) {
|
|
|
119
132
|
// bump removed (or renamed) it — the commit cannot be expressed now.
|
|
120
133
|
for (const key of Object.keys(values)) {
|
|
121
134
|
if (!table.columnIndex.has(key)) {
|
|
122
|
-
throw new OutboxEncodeError(
|
|
135
|
+
throw new OutboxEncodeError();
|
|
123
136
|
}
|
|
124
137
|
}
|
|
125
138
|
return table.columns.map((column) => {
|
|
@@ -130,7 +143,7 @@ function sparseValues(table, values, insert) {
|
|
|
130
143
|
return undefined;
|
|
131
144
|
// §7.1: an insert-intent operation presents every current column.
|
|
132
145
|
if (!column.nullable) {
|
|
133
|
-
throw new OutboxEncodeError(
|
|
146
|
+
throw new OutboxEncodeError();
|
|
134
147
|
}
|
|
135
148
|
return null;
|
|
136
149
|
});
|
|
@@ -147,23 +160,21 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
|
|
|
147
160
|
const operations = [];
|
|
148
161
|
for (const op of commit.operations) {
|
|
149
162
|
if (op.op === 'delete') {
|
|
150
|
-
operations.push({
|
|
163
|
+
operations.push(definedObject({
|
|
151
164
|
table: op.table,
|
|
152
165
|
rowId: op.rowId,
|
|
153
166
|
op: 'delete',
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
: {}),
|
|
157
|
-
});
|
|
167
|
+
baseVersion: op.baseVersion,
|
|
168
|
+
}));
|
|
158
169
|
continue;
|
|
159
170
|
}
|
|
160
171
|
const table = schema.tables.get(op.table);
|
|
161
172
|
if (table === undefined) {
|
|
162
173
|
// §7.4.4: the bump removed this table — the commit cannot be encoded.
|
|
163
|
-
throw new OutboxEncodeError(
|
|
174
|
+
throw new OutboxEncodeError();
|
|
164
175
|
}
|
|
165
176
|
if (op.values === undefined) {
|
|
166
|
-
throw invalidRequest(
|
|
177
|
+
throw invalidRequest('an outbox upsert has no values');
|
|
167
178
|
}
|
|
168
179
|
let values = sparseValues(table, op.values, op.insert === true);
|
|
169
180
|
if (table.hasEncryptedColumns) {
|
|
@@ -171,13 +182,13 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
|
|
|
171
182
|
const { encryptRowValues } = await import('./encryption.js');
|
|
172
183
|
values = await encryptRowValues(encryption, table, op.rowId, values, storedKeyIdFor?.(table, op.rowId));
|
|
173
184
|
}
|
|
174
|
-
operations.push({
|
|
185
|
+
operations.push(definedObject({
|
|
175
186
|
table: op.table,
|
|
176
187
|
rowId: op.rowId,
|
|
177
188
|
op: 'upsert',
|
|
178
|
-
|
|
189
|
+
baseVersion: op.baseVersion,
|
|
179
190
|
payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
|
|
180
|
-
});
|
|
191
|
+
}));
|
|
181
192
|
}
|
|
182
193
|
return {
|
|
183
194
|
type: 'PUSH_COMMIT',
|
package/dist/outcomes.js
CHANGED
|
@@ -187,10 +187,13 @@ export function recordCommitOutcome(db, outcome) {
|
|
|
187
187
|
]);
|
|
188
188
|
return commitOutcome(db, outcome.clientCommitId);
|
|
189
189
|
}
|
|
190
|
-
|
|
191
|
-
|
|
190
|
+
function outcomeRow(db, clientCommitId) {
|
|
191
|
+
return db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
|
|
192
192
|
clientCommitId,
|
|
193
193
|
])[0];
|
|
194
|
+
}
|
|
195
|
+
export function commitOutcome(db, clientCommitId) {
|
|
196
|
+
const row = outcomeRow(db, clientCommitId);
|
|
194
197
|
return row === undefined ? undefined : parseOutcome(db, row);
|
|
195
198
|
}
|
|
196
199
|
/**
|
|
@@ -200,9 +203,7 @@ export function commitOutcome(db, clientCommitId) {
|
|
|
200
203
|
* native sidecar reports, never a raw `SyntaxError`.
|
|
201
204
|
*/
|
|
202
205
|
export function persistedCommitOutcome(db, clientCommitId) {
|
|
203
|
-
const row = db
|
|
204
|
-
clientCommitId,
|
|
205
|
-
])[0];
|
|
206
|
+
const row = outcomeRow(db, clientCommitId);
|
|
206
207
|
if (row === undefined)
|
|
207
208
|
return undefined;
|
|
208
209
|
function corrupt() {
|
package/dist/worker-core.js
CHANGED
|
@@ -377,8 +377,8 @@ export function startSyncWorkerCore(overrides, createLocalAuthority) {
|
|
|
377
377
|
setWindow: async (base, units) => {
|
|
378
378
|
await requireClient().setWindowCommand(base, units);
|
|
379
379
|
},
|
|
380
|
-
mutate: (mutations) => {
|
|
381
|
-
return requireClient().mutateCommand(mutations).value;
|
|
380
|
+
mutate: (mutations, options) => {
|
|
381
|
+
return requireClient().mutateCommand(mutations, options).value;
|
|
382
382
|
},
|
|
383
383
|
patch: (table, rowId, partial, options) => {
|
|
384
384
|
// Same §8.4 rule as `mutate`: a local write must push without the app
|
package/dist/worker-host.d.ts
CHANGED
|
@@ -264,7 +264,9 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
264
264
|
unsubscribe(id: string): Promise<void>;
|
|
265
265
|
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
266
266
|
windowState(base: WindowBase): Promise<WindowState>;
|
|
267
|
-
mutate(mutations: readonly MutationInput[]
|
|
267
|
+
mutate(mutations: readonly MutationInput[], options?: {
|
|
268
|
+
readonly clientCommitId?: string;
|
|
269
|
+
}): Promise<string>;
|
|
268
270
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
|
269
271
|
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
270
272
|
readonly baseVersion?: number;
|
package/dist/worker-host.js
CHANGED
|
@@ -351,8 +351,8 @@ export class SyncClientHandle {
|
|
|
351
351
|
windowState(base) {
|
|
352
352
|
return this.#call('windowState', [base]);
|
|
353
353
|
}
|
|
354
|
-
mutate(mutations) {
|
|
355
|
-
return this.#call('mutate', [mutations]);
|
|
354
|
+
mutate(mutations, options) {
|
|
355
|
+
return this.#call('mutate', [mutations, options]);
|
|
356
356
|
}
|
|
357
357
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
|
358
358
|
patch(table, rowId, partial, options) {
|
|
@@ -141,7 +141,9 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
|
|
|
141
141
|
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
142
142
|
/** §4.8 completeness oracle: the windowed-in values of a base. */
|
|
143
143
|
windowState(base: WindowBase): WindowState;
|
|
144
|
-
mutate(mutations: readonly MutationInput[]
|
|
144
|
+
mutate(mutations: readonly MutationInput[], options?: {
|
|
145
|
+
readonly clientCommitId?: string;
|
|
146
|
+
}): string;
|
|
145
147
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
|
146
148
|
patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
|
|
147
149
|
readonly baseVersion?: number;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.70.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.70.0"
|
|
125
125
|
},
|
|
126
126
|
"devDependencies": {
|
|
127
127
|
"@electric-sql/pglite": "^0.5.4",
|
|
128
|
-
"@syncular/server": "0.
|
|
128
|
+
"@syncular/server": "0.70.0",
|
|
129
129
|
"playwright": "1.63.0",
|
|
130
130
|
"vite": "8.3.4"
|
|
131
131
|
}
|
package/src/apply.ts
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
import { hasUniqueIndex } from './schema';
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
chainsOn,
|
|
4
|
+
countOutbox,
|
|
5
|
+
listOutbox,
|
|
6
|
+
OUTBOX_IMAGES,
|
|
7
|
+
OUTBOX_TABLE,
|
|
8
|
+
type OutboxOperation,
|
|
9
|
+
} from './outbox';
|
|
3
10
|
import { RETAINED_ROWS, type OverlayScope } from './failed-overlay';
|
|
4
11
|
import { retainedBaseWrite, restoreFailedBases } from './failed-overlay';
|
|
5
12
|
/**
|
|
@@ -186,6 +193,25 @@ export async function applyCommitFrame(
|
|
|
186
193
|
`UPDATE ${OUTBOX_IMAGES} SET delivery_seq=MAX(COALESCE(delivery_seq,0),?) WHERE tbl=? AND row_id=?`,
|
|
187
194
|
[frame.commitSeq, change.table.name, rowId],
|
|
188
195
|
);
|
|
196
|
+
// §7.1 chained base: this change names the version an acknowledged own
|
|
197
|
+
// commit wrote; pending upserts chained on it move to that version.
|
|
198
|
+
for (const { op } of db.query(
|
|
199
|
+
`SELECT op FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq=?`,
|
|
200
|
+
[change.table.name, rowId, frame.commitSeq],
|
|
201
|
+
)) {
|
|
202
|
+
const earlier: OutboxOperation = JSON.parse(op as string);
|
|
203
|
+
for (const commit of listOutbox(db, scope))
|
|
204
|
+
db.exec(`UPDATE ${OUTBOX_TABLE} SET operations=? WHERE seq=?`, [
|
|
205
|
+
JSON.stringify(
|
|
206
|
+
commit.operations.map((operation) =>
|
|
207
|
+
chainsOn(earlier, operation)
|
|
208
|
+
? { ...operation, baseVersion: rowVersion }
|
|
209
|
+
: operation,
|
|
210
|
+
),
|
|
211
|
+
),
|
|
212
|
+
commit.seq,
|
|
213
|
+
]);
|
|
214
|
+
}
|
|
189
215
|
db.exec(
|
|
190
216
|
`DELETE FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? AND commit_seq<=?`,
|
|
191
217
|
[change.table.name, rowId, frame.commitSeq],
|
package/src/client.ts
CHANGED
|
@@ -62,6 +62,7 @@ import {
|
|
|
62
62
|
unitId,
|
|
63
63
|
type UnitScopes,
|
|
64
64
|
type WakeReason,
|
|
65
|
+
definedObject,
|
|
65
66
|
} from '@syncular/core';
|
|
66
67
|
import { EncryptError } from '@syncular/core';
|
|
67
68
|
import { EncodeError } from '@syncular/core';
|
|
@@ -161,6 +162,7 @@ import {
|
|
|
161
162
|
} from './local-rebootstrap-receipt';
|
|
162
163
|
import {
|
|
163
164
|
appendOutboxCommit,
|
|
165
|
+
chainsOn,
|
|
164
166
|
deleteOutboxCommit,
|
|
165
167
|
encodeOutboxCommit,
|
|
166
168
|
listOutbox,
|
|
@@ -1852,12 +1854,8 @@ export class SyncClient {
|
|
|
1852
1854
|
});
|
|
1853
1855
|
};
|
|
1854
1856
|
const deliveryOf = (id: string): CommitDelivery => {
|
|
1855
|
-
|
|
1856
|
-
|
|
1857
|
-
`SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`,
|
|
1858
|
-
[id],
|
|
1859
|
-
).length > 0;
|
|
1860
|
-
if (pending) return { status: 'pending', clientCommitId: id };
|
|
1857
|
+
if (this.#outboxCommitExists(id))
|
|
1858
|
+
return { status: 'pending', clientCommitId: id };
|
|
1861
1859
|
const outcome = persistedCommitOutcome(this.#db, id);
|
|
1862
1860
|
return outcome === undefined
|
|
1863
1861
|
? { status: 'unknown', clientCommitId: id }
|
|
@@ -3404,15 +3402,35 @@ export class SyncClient {
|
|
|
3404
3402
|
/**
|
|
3405
3403
|
* Record one atomic local commit (§7.1): appended to the outbox in
|
|
3406
3404
|
* schema-agnostic form and applied optimistically to the local mirror.
|
|
3407
|
-
* Returns the generated `clientCommitId
|
|
3405
|
+
* Returns the generated `clientCommitId`, or the caller's unused one
|
|
3406
|
+
* (`client.commit_id_reused` when this replica holds it).
|
|
3408
3407
|
*/
|
|
3409
|
-
mutate(
|
|
3410
|
-
|
|
3408
|
+
mutate(
|
|
3409
|
+
mutations: readonly MutationInput[],
|
|
3410
|
+
options?: { readonly clientCommitId?: string },
|
|
3411
|
+
): string {
|
|
3412
|
+
return this.#recordMutations(mutations, options?.clientCommitId);
|
|
3411
3413
|
}
|
|
3412
3414
|
|
|
3413
|
-
#recordMutations(
|
|
3415
|
+
#recordMutations(
|
|
3416
|
+
mutations: readonly MutationInput[],
|
|
3417
|
+
supplied?: string,
|
|
3418
|
+
): string {
|
|
3414
3419
|
this.#requireActive();
|
|
3415
|
-
|
|
3420
|
+
// §7.1: a supplied ID is non-empty (§6.1) and unknown to this replica.
|
|
3421
|
+
if (supplied === '') throw invalidRequest('clientCommitId is empty');
|
|
3422
|
+
if (
|
|
3423
|
+
supplied !== undefined &&
|
|
3424
|
+
(this.#outboxCommitExists(supplied) ||
|
|
3425
|
+
readCommitOutcome(this.#db, supplied))
|
|
3426
|
+
)
|
|
3427
|
+
throw new ClientSyncError(
|
|
3428
|
+
'client.commit_id_reused',
|
|
3429
|
+
'clientCommitId is held',
|
|
3430
|
+
false,
|
|
3431
|
+
{ clientCommitId: supplied },
|
|
3432
|
+
);
|
|
3433
|
+
const clientCommitId = supplied ?? crypto.randomUUID();
|
|
3416
3434
|
const operations: OutboxOperation[] = mutations.map((mutation) => {
|
|
3417
3435
|
const table = this.#table(mutation.table);
|
|
3418
3436
|
if (mutation.op === 'delete') {
|
|
@@ -3447,6 +3465,7 @@ export class SyncClient {
|
|
|
3447
3465
|
);
|
|
3448
3466
|
for (const column of table.columns) {
|
|
3449
3467
|
if (!normalized.has(column.name)) continue;
|
|
3468
|
+
const at = { table: table.name, column: column.name };
|
|
3450
3469
|
// §3.4 rule 5 / §6.2: scope columns are immutable on update. The
|
|
3451
3470
|
// server accepts a present scope column whose value equals the
|
|
3452
3471
|
// stored row and applies it as a no-op, so a decoded envelope
|
|
@@ -3472,7 +3491,9 @@ export class SyncClient {
|
|
|
3472
3491
|
)
|
|
3473
3492
|
) {
|
|
3474
3493
|
throw invalidRequest(
|
|
3475
|
-
|
|
3494
|
+
'patch cannot write a scope column (§3.4)',
|
|
3495
|
+
false,
|
|
3496
|
+
at,
|
|
3476
3497
|
);
|
|
3477
3498
|
}
|
|
3478
3499
|
continue;
|
|
@@ -3481,7 +3502,9 @@ export class SyncClient {
|
|
|
3481
3502
|
if (value === undefined || value === null) {
|
|
3482
3503
|
if (!column.nullable) {
|
|
3483
3504
|
throw invalidRequest(
|
|
3484
|
-
|
|
3505
|
+
'a non-nullable column is null (§6.1)',
|
|
3506
|
+
false,
|
|
3507
|
+
at,
|
|
3485
3508
|
);
|
|
3486
3509
|
}
|
|
3487
3510
|
json[column.name] = null;
|
|
@@ -3586,9 +3609,12 @@ export class SyncClient {
|
|
|
3586
3609
|
}
|
|
3587
3610
|
|
|
3588
3611
|
/** Host-facing mutation result with explicit network work intent (§7.5). */
|
|
3589
|
-
mutateCommand(
|
|
3612
|
+
mutateCommand(
|
|
3613
|
+
mutations: readonly MutationInput[],
|
|
3614
|
+
options?: { readonly clientCommitId?: string },
|
|
3615
|
+
): CommandResult<string> {
|
|
3590
3616
|
return {
|
|
3591
|
-
value: this.mutate(mutations),
|
|
3617
|
+
value: this.mutate(mutations, options),
|
|
3592
3618
|
effects: {
|
|
3593
3619
|
sync: { kind: this.#transportEnabled ? 'interactive' : 'none' },
|
|
3594
3620
|
},
|
|
@@ -3615,9 +3641,9 @@ export class SyncClient {
|
|
|
3615
3641
|
const normalized = normalizeRecordKeys(compiled, partial);
|
|
3616
3642
|
const pkOverride = normalized.get(pkColumn.name);
|
|
3617
3643
|
if (pkOverride !== undefined && String(pkOverride) !== rowId) {
|
|
3618
|
-
throw invalidRequest(
|
|
3619
|
-
|
|
3620
|
-
);
|
|
3644
|
+
throw invalidRequest('patch cannot change the primary key', false, {
|
|
3645
|
+
table,
|
|
3646
|
+
});
|
|
3621
3647
|
}
|
|
3622
3648
|
const pkType = localColumnType(pkColumn);
|
|
3623
3649
|
const typedPk =
|
|
@@ -3996,7 +4022,16 @@ export class SyncClient {
|
|
|
3996
4022
|
// §6.1/§7.1: the commit-count and operation caps are hard. A first
|
|
3997
4023
|
// commit that alone exceeds the operation cap is a typed capacity error
|
|
3998
4024
|
// and stays queued; a later one defers with the complete suffix.
|
|
3999
|
-
|
|
4025
|
+
// §7.1 chained base: a commit chained on an earlier commit of this
|
|
4026
|
+
// request waits for that commit's change, which supplies its version.
|
|
4027
|
+
if (
|
|
4028
|
+
(maxCommits !== undefined && pushFrames.length >= maxCommits) ||
|
|
4029
|
+
outbox.some((earlier) =>
|
|
4030
|
+
earlier.operations.some((prior) =>
|
|
4031
|
+
commit.operations.some((operation) => chainsOn(prior, operation)),
|
|
4032
|
+
),
|
|
4033
|
+
)
|
|
4034
|
+
) {
|
|
4000
4035
|
deferred = pendingCount - processed;
|
|
4001
4036
|
break;
|
|
4002
4037
|
}
|
|
@@ -4026,12 +4061,10 @@ export class SyncClient {
|
|
|
4026
4061
|
},
|
|
4027
4062
|
);
|
|
4028
4063
|
} catch (error) {
|
|
4029
|
-
if (
|
|
4030
|
-
|
|
4031
|
-
|
|
4032
|
-
|
|
4033
|
-
}
|
|
4034
|
-
if (error instanceof EncryptError) {
|
|
4064
|
+
if (
|
|
4065
|
+
error instanceof OutboxEncodeError ||
|
|
4066
|
+
error instanceof EncryptError
|
|
4067
|
+
) {
|
|
4035
4068
|
this.#dropIncompatibleCommit(commit, error.message, error.code);
|
|
4036
4069
|
processed += 1;
|
|
4037
4070
|
continue;
|
|
@@ -6880,21 +6913,6 @@ export class SyncClient {
|
|
|
6880
6913
|
}
|
|
6881
6914
|
}
|
|
6882
6915
|
|
|
6883
|
-
type DefinedObject<T> = {
|
|
6884
|
-
[K in keyof T as undefined extends T[K] ? never : K]: T[K];
|
|
6885
|
-
} & {
|
|
6886
|
-
[K in keyof T as undefined extends T[K] ? K : never]?: Exclude<
|
|
6887
|
-
T[K],
|
|
6888
|
-
undefined
|
|
6889
|
-
>;
|
|
6890
|
-
};
|
|
6891
|
-
function definedObject<const T extends object>(record: T): DefinedObject<T> {
|
|
6892
|
-
for (const key of Object.keys(record) as (keyof T)[]) {
|
|
6893
|
-
if (record[key] === undefined) delete record[key];
|
|
6894
|
-
}
|
|
6895
|
-
return record as DefinedObject<T>;
|
|
6896
|
-
}
|
|
6897
|
-
|
|
6898
6916
|
function requireRowId(value: unknown): string {
|
|
6899
6917
|
if (typeof value === 'string' && value.length > 0) return value;
|
|
6900
6918
|
if (typeof value === 'number' && Number.isSafeInteger(value)) {
|
package/src/errors.ts
CHANGED
|
@@ -61,8 +61,14 @@ export class ClientSyncError extends Error {
|
|
|
61
61
|
export function invalidRequest(
|
|
62
62
|
message: string,
|
|
63
63
|
retryable = false,
|
|
64
|
+
details?: Readonly<Record<string, unknown>>,
|
|
64
65
|
): ClientSyncError {
|
|
65
|
-
return new ClientSyncError(
|
|
66
|
+
return new ClientSyncError(
|
|
67
|
+
'sync.invalid_request',
|
|
68
|
+
message,
|
|
69
|
+
retryable,
|
|
70
|
+
details,
|
|
71
|
+
);
|
|
66
72
|
}
|
|
67
73
|
|
|
68
74
|
/** Shared retryable `sync.transport_failed` construction for client transports. */
|
package/src/failed-overlay.ts
CHANGED
|
@@ -29,6 +29,8 @@ import type {
|
|
|
29
29
|
import { deleteLocalRow, upsertLocalRow } from './apply';
|
|
30
30
|
|
|
31
31
|
/** Protected failure state. The server base advances independently of intent. */
|
|
32
|
+
const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`;
|
|
33
|
+
|
|
32
34
|
export function ensureFailedOverlaySchema(db: ClientDatabase): void {
|
|
33
35
|
db.exec(
|
|
34
36
|
`CREATE TABLE IF NOT EXISTS ${RETAINED_ROWS}(commit_id TEXT NOT NULL,idx INTEGER NOT NULL,tbl TEXT NOT NULL,id TEXT NOT NULL,at INTEGER NOT NULL,op TEXT NOT NULL,intent TEXT,base TEXT,version INTEGER,unique_conflicts TEXT,commit_seq INTEGER,PRIMARY KEY(commit_id,idx))`,
|
|
@@ -81,22 +83,19 @@ export function retainedBaseWrite(
|
|
|
81
83
|
})),
|
|
82
84
|
);
|
|
83
85
|
}
|
|
84
|
-
db.exec(
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
(
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
Number(retained.idx),
|
|
98
|
-
],
|
|
99
|
-
);
|
|
86
|
+
db.exec(SET_UNIQUE_CONFLICTS, [
|
|
87
|
+
conflicts.length
|
|
88
|
+
? JSON.stringify(
|
|
89
|
+
conflicts.sort(
|
|
90
|
+
(a, b) =>
|
|
91
|
+
table.indexes.findIndex((index) => index.name === a.index) -
|
|
92
|
+
table.indexes.findIndex((index) => index.name === b.index),
|
|
93
|
+
),
|
|
94
|
+
)
|
|
95
|
+
: null,
|
|
96
|
+
retained.commit_id as string,
|
|
97
|
+
Number(retained.idx),
|
|
98
|
+
]);
|
|
100
99
|
}
|
|
101
100
|
}
|
|
102
101
|
|
|
@@ -272,19 +271,16 @@ export function failedOverlayCommits(
|
|
|
272
271
|
).length,
|
|
273
272
|
);
|
|
274
273
|
if (authorized.length)
|
|
275
|
-
db.exec(
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
row.idx as number,
|
|
286
|
-
],
|
|
287
|
-
);
|
|
274
|
+
db.exec(SET_UNIQUE_CONFLICTS, [
|
|
275
|
+
JSON.stringify(
|
|
276
|
+
authorized.map((conflict) => ({
|
|
277
|
+
...conflict,
|
|
278
|
+
serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
|
|
279
|
+
})),
|
|
280
|
+
),
|
|
281
|
+
row.commit_id as string,
|
|
282
|
+
row.idx as number,
|
|
283
|
+
]);
|
|
288
284
|
}
|
|
289
285
|
}
|
|
290
286
|
const prior = commits.get(id);
|
package/src/http.ts
CHANGED
|
@@ -411,15 +411,8 @@ export function httpBlobTransport(
|
|
|
411
411
|
} catch {
|
|
412
412
|
// Not JSON: inline bytes.
|
|
413
413
|
}
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
kind: 'url',
|
|
417
|
-
url: envelope.url,
|
|
418
|
-
...(typeof envelope.urlExpiresAtMs === 'number'
|
|
419
|
-
? { urlExpiresAtMs: envelope.urlExpiresAtMs }
|
|
420
|
-
: {}),
|
|
421
|
-
};
|
|
422
|
-
}
|
|
414
|
+
const grant = envelope && urlGrant(envelope);
|
|
415
|
+
if (grant) return grant;
|
|
423
416
|
}
|
|
424
417
|
return { kind: 'bytes', bytes };
|
|
425
418
|
},
|
|
@@ -461,22 +454,11 @@ export function httpBlobTransport(
|
|
|
461
454
|
'blob grant read failed',
|
|
462
455
|
() => response.json(),
|
|
463
456
|
response.status,
|
|
464
|
-
)) as {
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
present
|
|
468
|
-
|
|
469
|
-
if (typeof body.url === 'string') {
|
|
470
|
-
return {
|
|
471
|
-
kind: 'url',
|
|
472
|
-
url: body.url,
|
|
473
|
-
...(typeof body.urlExpiresAtMs === 'number'
|
|
474
|
-
? { urlExpiresAtMs: body.urlExpiresAtMs }
|
|
475
|
-
: {}),
|
|
476
|
-
};
|
|
477
|
-
}
|
|
478
|
-
if (body.present === true) return { kind: 'present' };
|
|
479
|
-
return { kind: 'none' };
|
|
457
|
+
)) as { url?: unknown; urlExpiresAtMs?: unknown; present?: boolean };
|
|
458
|
+
return (
|
|
459
|
+
urlGrant(body) ??
|
|
460
|
+
(body.present === true ? { kind: 'present' } : { kind: 'none' })
|
|
461
|
+
);
|
|
480
462
|
},
|
|
481
463
|
// §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
|
|
482
464
|
uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
|
|
@@ -569,3 +551,16 @@ export function webSocketRealtimeConnector(
|
|
|
569
551
|
};
|
|
570
552
|
});
|
|
571
553
|
}
|
|
554
|
+
|
|
555
|
+
/** §5.9.3, §5.9.5: a JSON body with a string `url` is a presigned grant. */
|
|
556
|
+
function urlGrant(body: { url?: unknown; urlExpiresAtMs?: unknown }) {
|
|
557
|
+
return typeof body.url === 'string'
|
|
558
|
+
? {
|
|
559
|
+
kind: 'url' as const,
|
|
560
|
+
url: body.url,
|
|
561
|
+
...(typeof body.urlExpiresAtMs === 'number'
|
|
562
|
+
? { urlExpiresAtMs: body.urlExpiresAtMs }
|
|
563
|
+
: {}),
|
|
564
|
+
}
|
|
565
|
+
: undefined;
|
|
566
|
+
}
|
package/src/native-bridge.ts
CHANGED
|
@@ -800,9 +800,15 @@ export abstract class NativeBridgeClient implements PromiseMethods<
|
|
|
800
800
|
});
|
|
801
801
|
}
|
|
802
802
|
|
|
803
|
-
async mutate(
|
|
803
|
+
async mutate(
|
|
804
|
+
mutations: readonly MutationInput[],
|
|
805
|
+
options?: { readonly clientCommitId?: string },
|
|
806
|
+
): Promise<string> {
|
|
804
807
|
const result = (await this.command('mutate', {
|
|
805
808
|
mutations: encodeValue(mutations),
|
|
809
|
+
...(options?.clientCommitId === undefined
|
|
810
|
+
? {}
|
|
811
|
+
: { clientCommitId: options.clientCommitId }),
|
|
806
812
|
})) as { clientCommitId: string };
|
|
807
813
|
return result.clientCommitId;
|
|
808
814
|
}
|
package/src/outbox.ts
CHANGED
|
@@ -10,6 +10,7 @@ import type { OverlayScope } from './failed-overlay';
|
|
|
10
10
|
* upgrade to N+1 by re-encoding.
|
|
11
11
|
*/
|
|
12
12
|
import {
|
|
13
|
+
definedObject,
|
|
13
14
|
encodeSparseRow,
|
|
14
15
|
type PushCommitFrame,
|
|
15
16
|
type PushOperation,
|
|
@@ -52,6 +53,27 @@ export interface OutboxCommit {
|
|
|
52
53
|
readonly operations: readonly OutboxOperation[];
|
|
53
54
|
}
|
|
54
55
|
|
|
56
|
+
/**
|
|
57
|
+
* §7.1 chained base: `later` repeats `earlier`'s positive base on the same row
|
|
58
|
+
* and presents only columns `earlier` presents.
|
|
59
|
+
*/
|
|
60
|
+
export function chainsOn(
|
|
61
|
+
earlier: OutboxOperation,
|
|
62
|
+
later: OutboxOperation,
|
|
63
|
+
): boolean {
|
|
64
|
+
// Only an upsert carries values, and it always carries its primary key.
|
|
65
|
+
return (
|
|
66
|
+
later.op === 'upsert' &&
|
|
67
|
+
earlier.rowId === later.rowId &&
|
|
68
|
+
earlier.table === later.table &&
|
|
69
|
+
later.baseVersion! > 0 &&
|
|
70
|
+
earlier.baseVersion === later.baseVersion &&
|
|
71
|
+
Object.keys(later.values ?? {}).every(
|
|
72
|
+
(column) => earlier.values?.[column] !== undefined,
|
|
73
|
+
)
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
|
|
55
77
|
/** Protected local rollback image; never encoded or exposed in outcomes. */
|
|
56
78
|
export interface OutboxBeforeImage {
|
|
57
79
|
readonly opIndex: number;
|
|
@@ -209,8 +231,12 @@ export function replaceOutboxBeforeImages(
|
|
|
209
231
|
* so the caller can drop the commit through the rejection channel.
|
|
210
232
|
*/
|
|
211
233
|
export class OutboxEncodeError extends ClientSyncError {
|
|
212
|
-
constructor(
|
|
213
|
-
super(
|
|
234
|
+
constructor() {
|
|
235
|
+
super(
|
|
236
|
+
'sync.outbox_incompatible',
|
|
237
|
+
'the persisted commit cannot encode under the current schema',
|
|
238
|
+
false,
|
|
239
|
+
);
|
|
214
240
|
}
|
|
215
241
|
}
|
|
216
242
|
|
|
@@ -223,9 +249,7 @@ function sparseValues(
|
|
|
223
249
|
// bump removed (or renamed) it — the commit cannot be expressed now.
|
|
224
250
|
for (const key of Object.keys(values)) {
|
|
225
251
|
if (!table.columnIndex.has(key)) {
|
|
226
|
-
throw new OutboxEncodeError(
|
|
227
|
-
`outbox column ${JSON.stringify(key)} is absent from table ${JSON.stringify(table.name)} (§7.4.4)`,
|
|
228
|
-
);
|
|
252
|
+
throw new OutboxEncodeError();
|
|
229
253
|
}
|
|
230
254
|
}
|
|
231
255
|
return table.columns.map((column) => {
|
|
@@ -234,9 +258,7 @@ function sparseValues(
|
|
|
234
258
|
if (!insert) return undefined;
|
|
235
259
|
// §7.1: an insert-intent operation presents every current column.
|
|
236
260
|
if (!column.nullable) {
|
|
237
|
-
throw new OutboxEncodeError(
|
|
238
|
-
'an outbox insert lacks a non-nullable column (§7.4.4)',
|
|
239
|
-
);
|
|
261
|
+
throw new OutboxEncodeError();
|
|
240
262
|
}
|
|
241
263
|
return null;
|
|
242
264
|
});
|
|
@@ -262,27 +284,23 @@ export async function encodeOutboxCommit(
|
|
|
262
284
|
const operations: PushOperation[] = [];
|
|
263
285
|
for (const op of commit.operations) {
|
|
264
286
|
if (op.op === 'delete') {
|
|
265
|
-
operations.push(
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
287
|
+
operations.push(
|
|
288
|
+
definedObject({
|
|
289
|
+
table: op.table,
|
|
290
|
+
rowId: op.rowId,
|
|
291
|
+
op: 'delete',
|
|
292
|
+
baseVersion: op.baseVersion,
|
|
293
|
+
}),
|
|
294
|
+
);
|
|
273
295
|
continue;
|
|
274
296
|
}
|
|
275
297
|
const table = schema.tables.get(op.table);
|
|
276
298
|
if (table === undefined) {
|
|
277
299
|
// §7.4.4: the bump removed this table — the commit cannot be encoded.
|
|
278
|
-
throw new OutboxEncodeError(
|
|
279
|
-
`outbox table ${JSON.stringify(op.table)} is absent from the current schema (§7.4.4)`,
|
|
280
|
-
);
|
|
300
|
+
throw new OutboxEncodeError();
|
|
281
301
|
}
|
|
282
302
|
if (op.values === undefined) {
|
|
283
|
-
throw invalidRequest(
|
|
284
|
-
`outbox upsert on ${op.table}/${op.rowId} has no values`,
|
|
285
|
-
);
|
|
303
|
+
throw invalidRequest('an outbox upsert has no values');
|
|
286
304
|
}
|
|
287
305
|
let values = sparseValues(table, op.values, op.insert === true);
|
|
288
306
|
if (table.hasEncryptedColumns) {
|
|
@@ -296,13 +314,15 @@ export async function encodeOutboxCommit(
|
|
|
296
314
|
storedKeyIdFor?.(table, op.rowId),
|
|
297
315
|
);
|
|
298
316
|
}
|
|
299
|
-
operations.push(
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
317
|
+
operations.push(
|
|
318
|
+
definedObject({
|
|
319
|
+
table: op.table,
|
|
320
|
+
rowId: op.rowId,
|
|
321
|
+
op: 'upsert',
|
|
322
|
+
baseVersion: op.baseVersion,
|
|
323
|
+
payload: encodeSparseRow(table.columns, table.primaryKeyIndex, values),
|
|
324
|
+
}),
|
|
325
|
+
);
|
|
306
326
|
}
|
|
307
327
|
return {
|
|
308
328
|
type: 'PUSH_COMMIT',
|
package/src/outcomes.ts
CHANGED
|
@@ -365,13 +365,17 @@ export function recordCommitOutcome(
|
|
|
365
365
|
return commitOutcome(db, outcome.clientCommitId) as CommitOutcome;
|
|
366
366
|
}
|
|
367
367
|
|
|
368
|
+
function outcomeRow(db: ClientDatabase, clientCommitId: string) {
|
|
369
|
+
return db.query(`${SELECT_OUTCOME} WHERE client_commit_id=?`, [
|
|
370
|
+
clientCommitId,
|
|
371
|
+
])[0];
|
|
372
|
+
}
|
|
373
|
+
|
|
368
374
|
export function commitOutcome(
|
|
369
375
|
db: ClientDatabase,
|
|
370
376
|
clientCommitId: string,
|
|
371
377
|
): CommitOutcome | undefined {
|
|
372
|
-
const row = db
|
|
373
|
-
clientCommitId,
|
|
374
|
-
])[0];
|
|
378
|
+
const row = outcomeRow(db, clientCommitId);
|
|
375
379
|
return row === undefined ? undefined : parseOutcome(db, row);
|
|
376
380
|
}
|
|
377
381
|
|
|
@@ -385,9 +389,7 @@ export function persistedCommitOutcome(
|
|
|
385
389
|
db: ClientDatabase,
|
|
386
390
|
clientCommitId: string,
|
|
387
391
|
): CommitOutcome | undefined {
|
|
388
|
-
const row = db
|
|
389
|
-
clientCommitId,
|
|
390
|
-
])[0];
|
|
392
|
+
const row = outcomeRow(db, clientCommitId);
|
|
391
393
|
if (row === undefined) return undefined;
|
|
392
394
|
function corrupt(): never {
|
|
393
395
|
throw new ClientSyncError(
|
package/src/worker-core.ts
CHANGED
|
@@ -578,8 +578,8 @@ export function startSyncWorkerCore(
|
|
|
578
578
|
setWindow: async (base, units) => {
|
|
579
579
|
await requireClient().setWindowCommand(base, units);
|
|
580
580
|
},
|
|
581
|
-
mutate: (mutations) => {
|
|
582
|
-
return requireClient().mutateCommand(mutations).value;
|
|
581
|
+
mutate: (mutations, options) => {
|
|
582
|
+
return requireClient().mutateCommand(mutations, options).value;
|
|
583
583
|
},
|
|
584
584
|
patch: (table, rowId, partial, options) => {
|
|
585
585
|
// Same §8.4 rule as `mutate`: a local write must push without the app
|
package/src/worker-host.ts
CHANGED
|
@@ -664,8 +664,11 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
|
|
|
664
664
|
return this.#call('windowState', [base]);
|
|
665
665
|
}
|
|
666
666
|
|
|
667
|
-
mutate(
|
|
668
|
-
|
|
667
|
+
mutate(
|
|
668
|
+
mutations: readonly MutationInput[],
|
|
669
|
+
options?: { readonly clientCommitId?: string },
|
|
670
|
+
): Promise<string> {
|
|
671
|
+
return this.#call('mutate', [mutations, options]);
|
|
669
672
|
}
|
|
670
673
|
|
|
671
674
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
package/src/worker-protocol.ts
CHANGED
|
@@ -190,7 +190,10 @@ export interface WorkerApi extends Omit<
|
|
|
190
190
|
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
191
191
|
/** §4.8 completeness oracle: the windowed-in values of a base. */
|
|
192
192
|
windowState(base: WindowBase): WindowState;
|
|
193
|
-
mutate(
|
|
193
|
+
mutate(
|
|
194
|
+
mutations: readonly MutationInput[],
|
|
195
|
+
options?: { readonly clientCommitId?: string },
|
|
196
|
+
): string;
|
|
194
197
|
/** Partial-update convenience: read-merge-write one full-row upsert. */
|
|
195
198
|
patch(
|
|
196
199
|
table: string,
|