@syncular/client 0.85.0 → 0.86.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 +10 -3
- package/dist/apply.d.ts +1 -1
- package/dist/apply.js +25 -26
- package/dist/client.d.ts +19 -9
- package/dist/client.js +62 -45
- package/dist/encryption.js +3 -9
- package/dist/failed-overlay.d.ts +8 -2
- package/dist/failed-overlay.js +31 -20
- package/dist/native-bridge.d.ts +3 -2
- package/dist/native-bridge.js +5 -1
- package/dist/outcomes.d.ts +2 -1
- package/dist/outcomes.js +2 -4
- package/dist/progress.d.ts +4 -0
- package/dist/progress.js +14 -2
- package/dist/realtime-supervisor.d.ts +4 -1
- package/dist/realtime-supervisor.js +2 -2
- package/dist/sync-scheduler.d.ts +8 -2
- package/dist/sync-scheduler.js +11 -3
- package/dist/worker-core.js +7 -2
- package/dist/worker-host.d.ts +5 -0
- package/dist/worker-host.js +6 -0
- package/dist/worker-protocol.d.ts +2 -0
- package/package.json +3 -3
- package/src/apply.ts +34 -47
- package/src/client.ts +85 -53
- package/src/encryption.ts +8 -15
- package/src/failed-overlay.ts +37 -23
- package/src/native-bridge.ts +5 -1
- package/src/outcomes.ts +2 -6
- package/src/progress.ts +18 -2
- package/src/realtime-supervisor.ts +7 -3
- package/src/sync-scheduler.ts +17 -5
- package/src/worker-core.ts +5 -2
- package/src/worker-host.ts +13 -0
- package/src/worker-protocol.ts +2 -0
package/src/client.ts
CHANGED
|
@@ -379,7 +379,7 @@ export interface SyncIdleResult extends SyncSummary {
|
|
|
379
379
|
|
|
380
380
|
export interface SyncIdleOptions {
|
|
381
381
|
/** §7.8: a strict positive round count. Default: 20. */
|
|
382
|
-
readonly maxRounds?: number;
|
|
382
|
+
readonly maxRounds?: number | undefined;
|
|
383
383
|
/**
|
|
384
384
|
* Total budget for one drive, across every round, on the client clock. A
|
|
385
385
|
* drive past it after a completed round resolves with `budgetExhausted`.
|
|
@@ -388,6 +388,12 @@ export interface SyncIdleOptions {
|
|
|
388
388
|
* `Infinity` disables the bound.
|
|
389
389
|
*/
|
|
390
390
|
readonly timeoutMs?: number;
|
|
391
|
+
/**
|
|
392
|
+
* §8.4 host policy: end the drive without a round when the replica has no
|
|
393
|
+
* unit, no outbox commit, and no unit list to clear on the server. The
|
|
394
|
+
* shipped host loops pass it; the native bridge ignores it.
|
|
395
|
+
*/
|
|
396
|
+
readonly skipEmpty?: boolean;
|
|
391
397
|
}
|
|
392
398
|
|
|
393
399
|
export type CurrentBaseProof =
|
|
@@ -438,6 +444,18 @@ export interface SyncClientLimits {
|
|
|
438
444
|
* raises `client.push_request_too_large` and stays queued.
|
|
439
445
|
*/
|
|
440
446
|
readonly maxPushRequestBytes?: number;
|
|
447
|
+
/**
|
|
448
|
+
* §5.4: rows segment downloads one pull response runs at once. Default 4.
|
|
449
|
+
* SQLite images keep their own bound of two (§5.3).
|
|
450
|
+
*/
|
|
451
|
+
readonly segmentPrefetch?: number;
|
|
452
|
+
/**
|
|
453
|
+
* §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
|
|
454
|
+
* exceeds it, unreferenced bodies without pending work are evicted oldest
|
|
455
|
+
* first after each cache write. Referenced bodies stay cached even past the
|
|
456
|
+
* cap. Absent: retain until storage pressure.
|
|
457
|
+
*/
|
|
458
|
+
readonly blobCacheMaxBytes?: number;
|
|
441
459
|
}
|
|
442
460
|
|
|
443
461
|
export interface SyncClientConfig {
|
|
@@ -452,14 +470,6 @@ export interface SyncClientConfig {
|
|
|
452
470
|
readonly segments?: SegmentDownloader;
|
|
453
471
|
/** Blob upload/download (§5.9). Required to use `uploadBlob`/`fetchBlob`. */
|
|
454
472
|
readonly blobs?: BlobTransport;
|
|
455
|
-
/**
|
|
456
|
-
* §5.9.7 B1 blob-cache size cap (bytes). When the sum of cached body sizes
|
|
457
|
-
* exceeds this, unreferenced bodies without pending work are evicted in
|
|
458
|
-
* creation timestamp order after each cache write. Referenced bodies remain cached
|
|
459
|
-
* even when that exceeds the cap. Absent means retain until storage pressure (the shipped
|
|
460
|
-
* default; a referenced body always stays resolvable without a re-download).
|
|
461
|
-
*/
|
|
462
|
-
readonly blobCacheMaxBytes?: number;
|
|
463
473
|
readonly realtime?: RealtimeConnector;
|
|
464
474
|
/**
|
|
465
475
|
* SPEC §8.8: how sync rounds treat the realtime binding. `optional`
|
|
@@ -928,6 +938,15 @@ export type ClientSnapshotReader = {
|
|
|
928
938
|
| Promise<ReturnType<ClientSnapshotMethods[Key]>>;
|
|
929
939
|
};
|
|
930
940
|
|
|
941
|
+
/** Encodes a request in the current wire version. */
|
|
942
|
+
function encodeRequestFrames(frames: RequestFrame[]): Uint8Array {
|
|
943
|
+
return encodeRequest({
|
|
944
|
+
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
945
|
+
msgKind: 'request',
|
|
946
|
+
frames,
|
|
947
|
+
});
|
|
948
|
+
}
|
|
949
|
+
|
|
931
950
|
/** §7.7: progress fields of a payload; no payload is current. */
|
|
932
951
|
const NO_PAYLOAD: Partial<SyncProgress> = {
|
|
933
952
|
table: undefined,
|
|
@@ -1087,6 +1106,7 @@ export class SyncClient {
|
|
|
1087
1106
|
config.limits?.maxPushOperationsPerRequest,
|
|
1088
1107
|
],
|
|
1089
1108
|
['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
|
|
1109
|
+
['segmentPrefetch', config.limits?.segmentPrefetch],
|
|
1090
1110
|
] as const) {
|
|
1091
1111
|
if (
|
|
1092
1112
|
value !== undefined &&
|
|
@@ -1094,7 +1114,7 @@ export class SyncClient {
|
|
|
1094
1114
|
) {
|
|
1095
1115
|
throw new ClientSyncError(
|
|
1096
1116
|
'sync.invalid_request',
|
|
1097
|
-
'
|
|
1117
|
+
'limit must be an integer in 1..=4294967295',
|
|
1098
1118
|
false,
|
|
1099
1119
|
{ limit: name },
|
|
1100
1120
|
);
|
|
@@ -2365,8 +2385,7 @@ export class SyncClient {
|
|
|
2365
2385
|
)
|
|
2366
2386
|
: 0;
|
|
2367
2387
|
const pressure =
|
|
2368
|
-
this.#config.blobCacheMaxBytes
|
|
2369
|
-
blobBytes > this.#config.blobCacheMaxBytes;
|
|
2388
|
+
blobBytes > (this.#config.limits?.blobCacheMaxBytes ?? Infinity);
|
|
2370
2389
|
return {
|
|
2371
2390
|
status: pressure ? 'pressure' : 'healthy',
|
|
2372
2391
|
databaseBytesApprox: Math.max(0, pageCount * pageSize),
|
|
@@ -2647,7 +2666,7 @@ export class SyncClient {
|
|
|
2647
2666
|
|
|
2648
2667
|
/** §5.9.7 B1: trim the blob cache to the configured cap (no-op if unset). */
|
|
2649
2668
|
#enforceBlobCacheCap(): void {
|
|
2650
|
-
const cap = this.#config.blobCacheMaxBytes;
|
|
2669
|
+
const cap = this.#config.limits?.blobCacheMaxBytes;
|
|
2651
2670
|
if (cap === undefined) return;
|
|
2652
2671
|
enforceBlobCacheCap(this.#db, this.#schema, cap);
|
|
2653
2672
|
}
|
|
@@ -4086,13 +4105,7 @@ export class SyncClient {
|
|
|
4086
4105
|
// frames make a valid probe whose encoded size cancels out of the
|
|
4087
4106
|
// per-commit delta measured against the canonical encoder.
|
|
4088
4107
|
const baseBytes =
|
|
4089
|
-
byteCap === undefined
|
|
4090
|
-
? 0
|
|
4091
|
-
: encodeRequest({
|
|
4092
|
-
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
4093
|
-
msgKind: 'request',
|
|
4094
|
-
frames: [header, pull],
|
|
4095
|
-
}).length;
|
|
4108
|
+
byteCap === undefined ? 0 : encodeRequestFrames([header, pull]).length;
|
|
4096
4109
|
const pushFrames: RequestFrame[] = [];
|
|
4097
4110
|
const outbox: OutboxCommit[] = [];
|
|
4098
4111
|
const frameBytes: number[] = [];
|
|
@@ -4189,11 +4202,7 @@ export class SyncClient {
|
|
|
4189
4202
|
const frame =
|
|
4190
4203
|
byteCap === undefined
|
|
4191
4204
|
? 0
|
|
4192
|
-
:
|
|
4193
|
-
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
4194
|
-
msgKind: 'request',
|
|
4195
|
-
frames: [header, pushFrame, pull],
|
|
4196
|
-
}).length - baseBytes;
|
|
4205
|
+
: encodeRequestFrames([header, pushFrame, pull]).length - baseBytes;
|
|
4197
4206
|
// The head is always encoded so the caller can report the full
|
|
4198
4207
|
// projected request size with the final header and subscription bytes;
|
|
4199
4208
|
// a later commit defers once it no longer fits.
|
|
@@ -4621,11 +4630,7 @@ export class SyncClient {
|
|
|
4621
4630
|
// The fixed frames encode as envelope + fixed frames + END; each
|
|
4622
4631
|
// admitted push frame adds its own (5 + payload). Trimming the tail
|
|
4623
4632
|
// re-fits the request to the final registration state.
|
|
4624
|
-
const fixedBytes =
|
|
4625
|
-
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
4626
|
-
msgKind: 'request',
|
|
4627
|
-
frames: fixedFrames,
|
|
4628
|
-
}).length;
|
|
4633
|
+
const fixedBytes = encodeRequestFrames(fixedFrames).length;
|
|
4629
4634
|
if (fixedBytes > byteCap)
|
|
4630
4635
|
throw this.#pushCapacityError('bytes', byteCap, fixedBytes);
|
|
4631
4636
|
let admittedBytes = 0;
|
|
@@ -4651,11 +4656,7 @@ export class SyncClient {
|
|
|
4651
4656
|
...pushFrames,
|
|
4652
4657
|
...fixedFrames.slice(lead.length),
|
|
4653
4658
|
];
|
|
4654
|
-
const requestBytes =
|
|
4655
|
-
wireVersion: PROTOCOL_WIRE_VERSION,
|
|
4656
|
-
msgKind: 'request',
|
|
4657
|
-
frames,
|
|
4658
|
-
});
|
|
4659
|
+
const requestBytes = encodeRequestFrames(frames);
|
|
4659
4660
|
const responseBytes = await this.#roundTrip(requestBytes, signal);
|
|
4660
4661
|
const message = decodeResponse(responseBytes);
|
|
4661
4662
|
// §1.5: a complete, decodable response ends the report obligation.
|
|
@@ -4789,17 +4790,18 @@ export class SyncClient {
|
|
|
4789
4790
|
!(Number.isFinite(timeoutMs) && timeoutMs > 0)
|
|
4790
4791
|
)
|
|
4791
4792
|
throw invalidRequest('timeoutMs must be a positive number or Infinity');
|
|
4792
|
-
const
|
|
4793
|
+
const skipEmpty = typeof options === 'object' && options.skipEmpty === true;
|
|
4794
|
+
const key = `${maxRounds ?? 'default'}:${timeoutMs}:${skipEmpty}`;
|
|
4793
4795
|
const pending = this.#syncIdlePending.get(key);
|
|
4794
4796
|
if (pending !== undefined) return pending;
|
|
4795
4797
|
const previous = this.#syncIdleTail;
|
|
4796
4798
|
let drive: Promise<SyncIdleResult>;
|
|
4797
4799
|
if (previous === undefined) {
|
|
4798
|
-
drive = this.#syncIdleRounds(maxRounds, timeoutMs);
|
|
4800
|
+
drive = this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
|
|
4799
4801
|
} else {
|
|
4800
4802
|
drive = previous.then(() => {
|
|
4801
4803
|
this.#syncIdlePending.delete(key);
|
|
4802
|
-
return this.#syncIdleRounds(maxRounds, timeoutMs);
|
|
4804
|
+
return this.#syncIdleRounds(maxRounds, timeoutMs, skipEmpty);
|
|
4803
4805
|
});
|
|
4804
4806
|
this.#syncIdlePending.set(key, drive);
|
|
4805
4807
|
}
|
|
@@ -4818,6 +4820,7 @@ export class SyncClient {
|
|
|
4818
4820
|
async #syncIdleRounds(
|
|
4819
4821
|
maxRounds: number | undefined,
|
|
4820
4822
|
timeoutMs: number,
|
|
4823
|
+
skipEmpty: boolean,
|
|
4821
4824
|
): Promise<SyncIdleResult> {
|
|
4822
4825
|
const budget = maxRounds ?? 20;
|
|
4823
4826
|
const aggregate = {
|
|
@@ -4835,6 +4838,21 @@ export class SyncClient {
|
|
|
4835
4838
|
budgetExhausted,
|
|
4836
4839
|
};
|
|
4837
4840
|
};
|
|
4841
|
+
// §8.4: a replica without units, outbox work, or a server-side unit list
|
|
4842
|
+
// to clear has nothing to exchange; a host drive ends without a round.
|
|
4843
|
+
this.#requireActive();
|
|
4844
|
+
if (
|
|
4845
|
+
skipEmpty &&
|
|
4846
|
+
this.#schemaFloor === undefined &&
|
|
4847
|
+
!this.#hasStartupWork() &&
|
|
4848
|
+
loadUnits(this.#db).length === 0 &&
|
|
4849
|
+
(getMeta(this.#db, LOG_EPOCH_META_KEY) === undefined ||
|
|
4850
|
+
getMeta(this.#db, REGISTERED_DIGEST_KEY) ===
|
|
4851
|
+
bytesToHex(registrationDigest([])))
|
|
4852
|
+
) {
|
|
4853
|
+
this.#setSyncNeeded(false);
|
|
4854
|
+
return result(false);
|
|
4855
|
+
}
|
|
4838
4856
|
const states = () =>
|
|
4839
4857
|
JSON.stringify(
|
|
4840
4858
|
loadUnits(this.#db).map((unit) => [unit.id, unit.bootstrapState]),
|
|
@@ -5436,11 +5454,12 @@ export class SyncClient {
|
|
|
5436
5454
|
|
|
5437
5455
|
// §5.4/§5.5: queue every segment download of this response, so a paged
|
|
5438
5456
|
// bootstrap overlaps its page fetches instead of paying one blocking round
|
|
5439
|
-
// trip per page.
|
|
5440
|
-
// transport's pool size: enough to overlap
|
|
5441
|
-
// holds
|
|
5442
|
-
//
|
|
5443
|
-
// images (§5.3 client memory)
|
|
5457
|
+
// trip per page. `limits.segmentPrefetch` downloads run at once, by
|
|
5458
|
+
// default four, the Rust native transport's pool size: enough to overlap
|
|
5459
|
+
// round trips, while the client holds that many bodies, the one being
|
|
5460
|
+
// applied and the rest ahead. An image starts only beside at most one
|
|
5461
|
+
// other body, so at most two are images (§5.3 client memory) whatever the
|
|
5462
|
+
// limit; later descriptors wait in order. The
|
|
5444
5463
|
// loop takes each body out of the map before applying it and tops the
|
|
5445
5464
|
// window up at the next descriptor. Eligibility mirrors the loop: a
|
|
5446
5465
|
// descriptor outside an applied section or from an unconfigured
|
|
@@ -5452,7 +5471,7 @@ export class SyncClient {
|
|
|
5452
5471
|
const prefetch = () => {
|
|
5453
5472
|
for (
|
|
5454
5473
|
let next;
|
|
5455
|
-
prefetched.size < 4 &&
|
|
5474
|
+
prefetched.size < (this.#config.limits?.segmentPrefetch ?? 4) &&
|
|
5456
5475
|
!(queued[0]?.[0].mediaType === 'sqlite' && prefetched.size > 1) &&
|
|
5457
5476
|
(next = queued.shift());
|
|
5458
5477
|
) {
|
|
@@ -5593,11 +5612,17 @@ export class SyncClient {
|
|
|
5593
5612
|
skip: false,
|
|
5594
5613
|
}
|
|
5595
5614
|
: undefined;
|
|
5596
|
-
// §7.7: a section boundary ends the previous payload
|
|
5615
|
+
// §7.7: a section boundary ends the previous payload; the same
|
|
5616
|
+
// snapshot takes the section's extent (§4.4).
|
|
5617
|
+
const extent = message.frames[index + 1];
|
|
5618
|
+
const stated =
|
|
5619
|
+
section !== undefined && extent?.type === 'UNIT_EXTENT';
|
|
5597
5620
|
this.#progress.update({
|
|
5598
5621
|
...NO_PAYLOAD,
|
|
5599
5622
|
phase: 'import',
|
|
5600
5623
|
unitId: section?.unit.id,
|
|
5624
|
+
unitRowsTotal: stated ? extent.rowsTotal : undefined,
|
|
5625
|
+
unitRowsProcessed: stated ? extent.rowsDone : undefined,
|
|
5601
5626
|
});
|
|
5602
5627
|
break;
|
|
5603
5628
|
}
|
|
@@ -5625,19 +5650,22 @@ export class SyncClient {
|
|
|
5625
5650
|
// §5.6: rows an earlier attempt at this position applied. A
|
|
5626
5651
|
// partly applied image already ran its table's first-page clear.
|
|
5627
5652
|
appliedRows = section.unit.applied?.[frame.segmentId];
|
|
5628
|
-
if (appliedRows !== undefined)
|
|
5629
|
-
|
|
5630
|
-
if (appliedRows === frame.rowCount) break;
|
|
5631
|
-
}
|
|
5653
|
+
if (appliedRows !== undefined) section.seeded.add(frame.table);
|
|
5654
|
+
const imported = appliedRows === frame.rowCount;
|
|
5632
5655
|
this.#progress.update({
|
|
5633
5656
|
...NO_PAYLOAD,
|
|
5634
|
-
phase: 'download',
|
|
5657
|
+
phase: imported ? 'import' : 'download',
|
|
5635
5658
|
unitId,
|
|
5636
5659
|
table: frame.table,
|
|
5637
5660
|
segmentId: frame.segmentId,
|
|
5638
|
-
bytesTotal: frame.byteLength,
|
|
5661
|
+
bytesTotal: imported ? undefined : frame.byteLength,
|
|
5639
5662
|
rowsTotal: frame.rowCount,
|
|
5640
5663
|
});
|
|
5664
|
+
if (imported) {
|
|
5665
|
+
// §7.7: an earlier attempt imported this payload.
|
|
5666
|
+
this.#progress.update({ rowsProcessed: frame.rowCount });
|
|
5667
|
+
break;
|
|
5668
|
+
}
|
|
5641
5669
|
prefetch();
|
|
5642
5670
|
const pending = prefetched.get(frame);
|
|
5643
5671
|
prefetched.delete(frame);
|
|
@@ -5748,6 +5776,10 @@ export class SyncClient {
|
|
|
5748
5776
|
this.#localResetEpoch === resetEpoch
|
|
5749
5777
|
) {
|
|
5750
5778
|
this.#finishSection(section, frame, summary);
|
|
5779
|
+
// §7.7: a completed bootstrap ends at what it imported.
|
|
5780
|
+
const processed = this.#progress.snapshot()?.unitRowsProcessed;
|
|
5781
|
+
if (frame.bootstrapState === undefined && processed !== undefined)
|
|
5782
|
+
this.#progress.update({ unitRowsTotal: processed });
|
|
5751
5783
|
}
|
|
5752
5784
|
section = undefined;
|
|
5753
5785
|
// The counters stay: `complete` and `failed` report them.
|
|
@@ -6679,7 +6711,7 @@ export class SyncClient {
|
|
|
6679
6711
|
const values = table.columns.map((column) =>
|
|
6680
6712
|
jsonToRowValue(image.values?.[column.name] ?? null),
|
|
6681
6713
|
);
|
|
6682
|
-
upsertLocalRow(this.#db, table, values, image.syncVersion
|
|
6714
|
+
upsertLocalRow(this.#db, table, values, image.syncVersion);
|
|
6683
6715
|
}
|
|
6684
6716
|
|
|
6685
6717
|
#legacyUndoOptimisticRows(
|
|
@@ -6867,7 +6899,7 @@ export class SyncClient {
|
|
|
6867
6899
|
).length
|
|
6868
6900
|
)
|
|
6869
6901
|
continue;
|
|
6870
|
-
upsertLocalRow(this.#db, table, values, version
|
|
6902
|
+
upsertLocalRow(this.#db, table, values, version);
|
|
6871
6903
|
}
|
|
6872
6904
|
}
|
|
6873
6905
|
|
package/src/encryption.ts
CHANGED
|
@@ -116,23 +116,16 @@ function encryptionKeyId(
|
|
|
116
116
|
}
|
|
117
117
|
const selectorColumn = config.keyIdColumns?.[table.name];
|
|
118
118
|
if (selectorColumn === undefined) return table.name;
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
}
|
|
127
|
-
if (table.columns[index]?.encrypted === true) {
|
|
128
|
-
throw new EncryptError(
|
|
129
|
-
`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must not be encrypted`,
|
|
130
|
-
);
|
|
131
|
-
}
|
|
132
|
-
const selected = values[index];
|
|
119
|
+
// The column must exist, stay plaintext, and hold a non-empty string.
|
|
120
|
+
const selected =
|
|
121
|
+
values[
|
|
122
|
+
table.columns.findIndex(
|
|
123
|
+
(column) => column.name === selectorColumn && column.encrypted !== true,
|
|
124
|
+
)
|
|
125
|
+
];
|
|
133
126
|
if (typeof selected !== 'string' || selected.length === 0) {
|
|
134
127
|
throw new EncryptError(
|
|
135
|
-
`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must
|
|
128
|
+
`encryption key-id column ${JSON.stringify(selectorColumn)} on table ${JSON.stringify(table.name)} must be a plaintext column holding a non-empty string`,
|
|
136
129
|
);
|
|
137
130
|
}
|
|
138
131
|
return selected;
|
package/src/failed-overlay.ts
CHANGED
|
@@ -29,7 +29,7 @@ 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
|
|
32
|
+
const SET_UNIQUE_CONFLICTS = `UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE rowid=?`;
|
|
33
33
|
|
|
34
34
|
export function ensureFailedOverlaySchema(db: ClientDatabase): void {
|
|
35
35
|
db.exec(
|
|
@@ -44,24 +44,42 @@ export function ensureFailedOverlaySchema(db: ClientDatabase): void {
|
|
|
44
44
|
);
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
+
/**
|
|
48
|
+
* Server writes, after they are stored: each `written` row replaces the base
|
|
49
|
+
* of its key's retained rows (`undefined`: deleted), and the table's retained
|
|
50
|
+
* intents re-read their unique conflicts with the written keys. A written row
|
|
51
|
+
* without a retained row costs no statement.
|
|
52
|
+
*/
|
|
47
53
|
export function retainedBaseWrite(
|
|
48
54
|
db: ClientDatabase,
|
|
49
55
|
table: CompiledClientTable,
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
56
|
+
written: ReadonlyMap<
|
|
57
|
+
string,
|
|
58
|
+
readonly [readonly RowValue[], number] | undefined
|
|
59
|
+
>,
|
|
53
60
|
): void {
|
|
54
|
-
|
|
55
|
-
values === undefined ? null : JSON.stringify(values),
|
|
56
|
-
version ?? null,
|
|
57
|
-
table.name,
|
|
58
|
-
rowId,
|
|
59
|
-
]);
|
|
60
|
-
if (!hasUniqueIndex(table)) return;
|
|
61
|
+
if (!written.size) return;
|
|
61
62
|
for (const retained of db.query(
|
|
62
|
-
`SELECT
|
|
63
|
+
`SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE tbl=?`,
|
|
63
64
|
[table.name],
|
|
64
65
|
)) {
|
|
66
|
+
const base = written.get(retained.id as string);
|
|
67
|
+
if (written.has(retained.id as string))
|
|
68
|
+
db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE rowid=?`, [
|
|
69
|
+
base
|
|
70
|
+
? JSON.stringify(
|
|
71
|
+
Object.fromEntries(
|
|
72
|
+
table.columns.map((column, index) => [
|
|
73
|
+
column.name,
|
|
74
|
+
rowValueToJson(base[0][index] ?? null),
|
|
75
|
+
]),
|
|
76
|
+
),
|
|
77
|
+
)
|
|
78
|
+
: null,
|
|
79
|
+
base?.[1] ?? null,
|
|
80
|
+
retained.r as number,
|
|
81
|
+
]);
|
|
82
|
+
if (!hasUniqueIndex(table) || retained.commit_seq !== null) continue;
|
|
65
83
|
const prior: readonly (Omit<
|
|
66
84
|
NonNullable<RetainedCommitRow['uniqueConflicts']>[number],
|
|
67
85
|
'serverRow'
|
|
@@ -69,14 +87,14 @@ export function retainedBaseWrite(
|
|
|
69
87
|
retained.unique_conflicts === null
|
|
70
88
|
? []
|
|
71
89
|
: JSON.parse(retained.unique_conflicts as string);
|
|
72
|
-
const conflicts = prior.filter((conflict) => conflict.rowId
|
|
73
|
-
if (
|
|
90
|
+
const conflicts = prior.filter((conflict) => !written.has(conflict.rowId));
|
|
91
|
+
if (retained.intent !== null) {
|
|
74
92
|
const intent: Record<string, JsonRowValue> = JSON.parse(
|
|
75
93
|
retained.intent as string,
|
|
76
94
|
);
|
|
77
95
|
conflicts.push(
|
|
78
96
|
...uniqueConflicts(db, table, mapRowValues(intent, jsonToRowValue))
|
|
79
|
-
.filter((conflict) => conflict.rowId
|
|
97
|
+
.filter((conflict) => written.has(conflict.rowId))
|
|
80
98
|
.map((conflict) => ({
|
|
81
99
|
...conflict,
|
|
82
100
|
serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
|
|
@@ -93,8 +111,7 @@ export function retainedBaseWrite(
|
|
|
93
111
|
),
|
|
94
112
|
)
|
|
95
113
|
: null,
|
|
96
|
-
retained.
|
|
97
|
-
Number(retained.idx),
|
|
114
|
+
retained.r as number,
|
|
98
115
|
]);
|
|
99
116
|
}
|
|
100
117
|
}
|
|
@@ -181,7 +198,7 @@ function retainedRows(
|
|
|
181
198
|
// A scope joins through the (tbl, id) index; a scan per applied commit
|
|
182
199
|
// would make a drained batch quadratic.
|
|
183
200
|
return db.query(
|
|
184
|
-
`SELECT
|
|
201
|
+
`SELECT rowid AS r,* FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
|
|
185
202
|
[scope ? JSON.stringify(scope) : null],
|
|
186
203
|
);
|
|
187
204
|
}
|
|
@@ -190,7 +207,7 @@ export function restoreFailedBases(
|
|
|
190
207
|
db: ClientDatabase,
|
|
191
208
|
schema: CompiledClientSchema,
|
|
192
209
|
scope?: OverlayScope,
|
|
193
|
-
):
|
|
210
|
+
): void {
|
|
194
211
|
const seen = new Set<string>();
|
|
195
212
|
for (const row of retainedRows(db, scope)) {
|
|
196
213
|
const key = JSON.stringify([row.tbl, row.id]);
|
|
@@ -211,11 +228,9 @@ export function restoreFailedBases(
|
|
|
211
228
|
jsonToRowValue(values[column.name] ?? null),
|
|
212
229
|
),
|
|
213
230
|
(row.version ?? -1) as number,
|
|
214
|
-
false,
|
|
215
231
|
);
|
|
216
232
|
}
|
|
217
233
|
}
|
|
218
|
-
return seen.size > 0;
|
|
219
234
|
}
|
|
220
235
|
|
|
221
236
|
export function failedOverlayCommits(
|
|
@@ -278,8 +293,7 @@ export function failedOverlayCommits(
|
|
|
278
293
|
serverRow: mapRowValues(conflict.serverRow, rowValueToJson),
|
|
279
294
|
})),
|
|
280
295
|
),
|
|
281
|
-
row.
|
|
282
|
-
row.idx as number,
|
|
296
|
+
row.r as number,
|
|
283
297
|
]);
|
|
284
298
|
}
|
|
285
299
|
}
|
package/src/native-bridge.ts
CHANGED
|
@@ -25,6 +25,7 @@ import {
|
|
|
25
25
|
type SnapshotReadRequest,
|
|
26
26
|
type SyncClient,
|
|
27
27
|
type SyncClientConfig,
|
|
28
|
+
type SyncIdleOptions,
|
|
28
29
|
type UnitCatchup,
|
|
29
30
|
type WindowState,
|
|
30
31
|
} from './client';
|
|
@@ -1087,10 +1088,13 @@ export abstract class NativeBridgeClient implements PromiseMethods<
|
|
|
1087
1088
|
return this.command('sync', {});
|
|
1088
1089
|
}
|
|
1089
1090
|
|
|
1091
|
+
/** The Rust core has no §8.4 empty-replica gate: `skipEmpty` is not sent. */
|
|
1090
1092
|
async syncUntilIdle(
|
|
1091
|
-
|
|
1093
|
+
options?: number | SyncIdleOptions,
|
|
1092
1094
|
timeoutMs?: number,
|
|
1093
1095
|
): Promise<unknown> {
|
|
1096
|
+
const maxRounds = typeof options === 'object' ? options.maxRounds : options;
|
|
1097
|
+
if (typeof options === 'object') timeoutMs = options.timeoutMs;
|
|
1094
1098
|
return this.command('syncUntilIdle', {
|
|
1095
1099
|
...(maxRounds !== undefined ? { maxRounds } : {}),
|
|
1096
1100
|
...(timeoutMs !== undefined ? { timeoutMs } : {}),
|
package/src/outcomes.ts
CHANGED
|
@@ -488,17 +488,13 @@ export function persistCommitOutcomeResolution(
|
|
|
488
488
|
|
|
489
489
|
/**
|
|
490
490
|
* Bound journal growth without deleting active failures. If active failures
|
|
491
|
-
* alone exceed the cap the journal intentionally remains over-capacity.
|
|
491
|
+
* alone exceed the cap the journal intentionally remains over-capacity. The
|
|
492
|
+
* client constructor validates `maxEntries`.
|
|
492
493
|
*/
|
|
493
494
|
export function pruneCommitOutcomes(
|
|
494
495
|
db: ClientDatabase,
|
|
495
496
|
maxEntries: number,
|
|
496
497
|
): number {
|
|
497
|
-
if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
|
|
498
|
-
throw invalidRequest(
|
|
499
|
-
'outcome retention maxEntries must be a positive safe integer',
|
|
500
|
-
);
|
|
501
|
-
}
|
|
502
498
|
const count = db.query(`SELECT COUNT(*) AS count FROM ${OUTCOMES_TABLE}`)[0]
|
|
503
499
|
?.count as number | undefined;
|
|
504
500
|
const excess = Math.max(0, (count ?? 0) - maxEntries);
|
package/src/progress.ts
CHANGED
|
@@ -14,6 +14,10 @@ export interface SyncProgress {
|
|
|
14
14
|
readonly bytesTotal?: number | undefined;
|
|
15
15
|
readonly rowsProcessed: number;
|
|
16
16
|
readonly rowsTotal?: number | undefined;
|
|
17
|
+
/** The unit's bootstrap rows as the server counted them (SPEC §4.4, §7.7). */
|
|
18
|
+
readonly unitRowsTotal?: number | undefined;
|
|
19
|
+
/** Rows of the unit's bootstrap imported so far, across its sections. */
|
|
20
|
+
readonly unitRowsProcessed?: number | undefined;
|
|
17
21
|
/** Time in this payload's import transactions before COMMIT, in ms. */
|
|
18
22
|
readonly importWriteMs?: number | undefined;
|
|
19
23
|
/** Time committing them and publishing their changes, in ms. */
|
|
@@ -68,7 +72,19 @@ export class ProgressEmitter {
|
|
|
68
72
|
}
|
|
69
73
|
|
|
70
74
|
update(update: Partial<SyncProgress>): void {
|
|
71
|
-
|
|
72
|
-
|
|
75
|
+
const before = this.#snapshot;
|
|
76
|
+
if (before?.state !== 'running') return;
|
|
77
|
+
const next = { ...before, ...update };
|
|
78
|
+
// §7.7: each rise of the payload counter raises the unit's, and the unit
|
|
79
|
+
// total never falls below what was imported.
|
|
80
|
+
if (next.unitRowsProcessed !== undefined) {
|
|
81
|
+
const processed =
|
|
82
|
+
next.unitRowsProcessed +
|
|
83
|
+
Math.max(0, next.rowsProcessed - before.rowsProcessed);
|
|
84
|
+
next.unitRowsProcessed = processed;
|
|
85
|
+
if (next.unitRowsTotal !== undefined)
|
|
86
|
+
next.unitRowsTotal = Math.max(next.unitRowsTotal, processed);
|
|
87
|
+
}
|
|
88
|
+
this.emit(next);
|
|
73
89
|
}
|
|
74
90
|
}
|
|
@@ -11,7 +11,10 @@ type CancelTimer = () => void;
|
|
|
11
11
|
export interface RealtimeSupervisorClient {
|
|
12
12
|
connectRealtime(): Promise<void>;
|
|
13
13
|
disconnectRealtime(): void | Promise<void>;
|
|
14
|
-
|
|
14
|
+
/** Receives `{ skipEmpty: true }` (§8.4); a numeric-budget signature also fits. */
|
|
15
|
+
syncUntilIdle(
|
|
16
|
+
options?: number | { readonly skipEmpty?: boolean },
|
|
17
|
+
): unknown | Promise<unknown>;
|
|
15
18
|
diagnosticsSnapshot():
|
|
16
19
|
| ClientDiagnosticsSnapshot
|
|
17
20
|
| Promise<ClientDiagnosticsSnapshot>;
|
|
@@ -477,7 +480,7 @@ export class RealtimeSupervisor {
|
|
|
477
480
|
return;
|
|
478
481
|
}
|
|
479
482
|
this.#round = Promise.resolve()
|
|
480
|
-
.then(() => this.#client.syncUntilIdle())
|
|
483
|
+
.then(() => this.#client.syncUntilIdle({ skipEmpty: true }))
|
|
481
484
|
.then(
|
|
482
485
|
() => undefined,
|
|
483
486
|
() => undefined,
|
|
@@ -637,7 +640,8 @@ export class RealtimeSupervisor {
|
|
|
637
640
|
});
|
|
638
641
|
this.#transport = true;
|
|
639
642
|
}
|
|
640
|
-
if (generation === this.#generation)
|
|
643
|
+
if (generation === this.#generation)
|
|
644
|
+
await this.#client.syncUntilIdle({ skipEmpty: true });
|
|
641
645
|
caughtUp = generation === this.#generation && this.#transport;
|
|
642
646
|
} catch {
|
|
643
647
|
// A refused socket or a failed catch-up round fails the attempt.
|
package/src/sync-scheduler.ts
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import type { WakeReason } from '@syncular/core';
|
|
2
|
-
import type { SecurityLifecycle } from './client';
|
|
2
|
+
import type { SecurityLifecycle, SyncIdleOptions } from './client';
|
|
3
|
+
import { invalidRequest } from './errors';
|
|
3
4
|
import type { SyncIntent } from './invalidation';
|
|
4
5
|
|
|
5
6
|
export interface SyncSchedulerClient {
|
|
6
7
|
statusSnapshot(): { readonly syncNeeded: boolean };
|
|
7
8
|
securityLifecycle(): SecurityLifecycle;
|
|
8
|
-
syncUntilIdle(
|
|
9
|
+
syncUntilIdle(options: SyncIdleOptions): Promise<unknown>;
|
|
9
10
|
onSyncNeeded(
|
|
10
11
|
listener: (reason: 'startup' | 'hello' | WakeReason) => void,
|
|
11
12
|
): () => void;
|
|
@@ -14,6 +15,12 @@ export interface SyncSchedulerClient {
|
|
|
14
15
|
|
|
15
16
|
export interface SyncSchedulerOptions {
|
|
16
17
|
readonly maxRounds?: number;
|
|
18
|
+
/**
|
|
19
|
+
* §8.4: milliseconds a queued drive waits before it starts, so the claims
|
|
20
|
+
* and writes of one burst ride in one round. Default 0: the drive starts
|
|
21
|
+
* in the next microtask.
|
|
22
|
+
*/
|
|
23
|
+
readonly coalesceMs?: number;
|
|
17
24
|
readonly onError?: (error: unknown) => void;
|
|
18
25
|
readonly now?: () => number;
|
|
19
26
|
readonly queueMicrotask?: (callback: () => void) => void;
|
|
@@ -30,6 +37,9 @@ export function installSyncScheduler(
|
|
|
30
37
|
client: SyncSchedulerClient,
|
|
31
38
|
options: SyncSchedulerOptions = {},
|
|
32
39
|
): SyncScheduler {
|
|
40
|
+
const coalesceMs = options.coalesceMs ?? 0;
|
|
41
|
+
if (!(Number.isFinite(coalesceMs) && coalesceMs >= 0))
|
|
42
|
+
throw invalidRequest('coalesceMs must be a non-negative finite number');
|
|
33
43
|
const now = options.now ?? Date.now;
|
|
34
44
|
const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
|
|
35
45
|
const schedule =
|
|
@@ -71,12 +81,14 @@ export function installSyncScheduler(
|
|
|
71
81
|
immediatePending = true;
|
|
72
82
|
if (stopped || running || immediateQueued) return;
|
|
73
83
|
immediateQueued = true;
|
|
74
|
-
|
|
84
|
+
const start = (): void => {
|
|
75
85
|
immediateQueued = false;
|
|
76
86
|
if (stopped || !immediatePending) return;
|
|
77
87
|
immediatePending = false;
|
|
78
88
|
run();
|
|
79
|
-
}
|
|
89
|
+
};
|
|
90
|
+
if (coalesceMs > 0) schedule(start, coalesceMs);
|
|
91
|
+
else enqueue(start);
|
|
80
92
|
};
|
|
81
93
|
|
|
82
94
|
const run = (): void => {
|
|
@@ -88,7 +100,7 @@ export function installSyncScheduler(
|
|
|
88
100
|
running = true;
|
|
89
101
|
backgroundReady = false;
|
|
90
102
|
void client
|
|
91
|
-
.syncUntilIdle(options.maxRounds)
|
|
103
|
+
.syncUntilIdle({ maxRounds: options.maxRounds, skipEmpty: true })
|
|
92
104
|
.then((result) => {
|
|
93
105
|
retryDelayMs = 250;
|
|
94
106
|
if (
|