@syncular/server 0.58.0 → 0.60.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -36
- package/dist/admin.d.ts +32 -20
- package/dist/admin.js +46 -40
- package/dist/blob-handlers.d.ts +25 -31
- package/dist/blob-handlers.js +63 -41
- package/dist/blob-store.d.ts +42 -24
- package/dist/blob-store.js +0 -0
- package/dist/bucket-blob-store.d.ts +12 -8
- package/dist/bucket-blob-store.js +54 -45
- package/dist/bucket-segment-store.js +18 -16
- package/dist/content-encoding.d.ts +5 -2
- package/dist/content-encoding.js +42 -13
- package/dist/context.d.ts +19 -5
- package/dist/context.js +19 -1
- package/dist/d1-storage.d.ts +14 -98
- package/dist/d1-storage.js +249 -1119
- package/dist/errors.js +16 -0
- package/dist/events.d.ts +36 -18
- package/dist/frame-bytes.js +24 -6
- package/dist/handler.js +503 -208
- package/dist/local-authority.d.ts +2 -0
- package/dist/local-authority.js +24 -12
- package/dist/object-bucket.d.ts +2 -0
- package/dist/operations-realtime.js +69 -50
- package/dist/operations.d.ts +5 -2
- package/dist/operations.js +20 -29
- package/dist/pg-executor-pglite.d.ts +5 -6
- package/dist/pg-executor-pglite.js +22 -14
- package/dist/pg-executor.d.ts +4 -1
- package/dist/postgres-storage.d.ts +24 -19
- package/dist/postgres-storage.js +420 -262
- package/dist/pull.d.ts +70 -47
- package/dist/pull.js +270 -301
- package/dist/push.d.ts +12 -3
- package/dist/push.js +361 -173
- package/dist/realtime.d.ts +85 -39
- package/dist/realtime.js +355 -219
- package/dist/relational-rows.d.ts +21 -66
- package/dist/relational-rows.js +28 -109
- package/dist/s3-blob-store.d.ts +11 -12
- package/dist/s3-blob-store.js +20 -13
- package/dist/s3-object-bucket.d.ts +8 -1
- package/dist/s3-object-bucket.js +16 -3
- package/dist/schema.d.ts +14 -0
- package/dist/schema.js +23 -0
- package/dist/scopes.d.ts +6 -2
- package/dist/scopes.js +22 -4
- package/dist/seed.js +10 -16
- package/dist/segment-download.d.ts +4 -1
- package/dist/segment-download.js +22 -6
- package/dist/signed-url.d.ts +2 -2
- package/dist/signed-url.js +9 -2
- package/dist/sigv4.d.ts +8 -2
- package/dist/sigv4.js +8 -4
- package/dist/sqlite-blob-store.d.ts +1 -1
- package/dist/sqlite-blob-store.js +23 -22
- package/dist/sqlite-dialect.d.ts +164 -84
- package/dist/sqlite-dialect.js +1145 -150
- package/dist/sqlite-lease-store.js +13 -18
- package/dist/sqlite-storage.d.ts +9 -62
- package/dist/sqlite-storage.js +303 -1123
- package/dist/storage-query.d.ts +30 -1
- package/dist/storage-query.js +68 -0
- package/dist/storage.d.ts +185 -63
- package/dist/storage.js +15 -0
- package/package.json +2 -2
- package/src/admin.ts +99 -57
- package/src/blob-handlers.ts +91 -72
- package/src/blob-store.ts +0 -0
- package/src/bucket-blob-store.ts +75 -48
- package/src/bucket-segment-store.ts +20 -15
- package/src/content-encoding.ts +48 -16
- package/src/context.ts +33 -6
- package/src/d1-storage.ts +350 -1700
- package/src/errors.ts +16 -0
- package/src/events.ts +37 -18
- package/src/frame-bytes.ts +26 -6
- package/src/handler.ts +654 -261
- package/src/local-authority.ts +27 -14
- package/src/object-bucket.ts +2 -0
- package/src/operations-realtime.ts +85 -61
- package/src/operations.ts +44 -42
- package/src/pg-executor-pglite.ts +27 -23
- package/src/pg-executor.ts +5 -1
- package/src/postgres-storage.ts +557 -354
- package/src/pull.ts +406 -440
- package/src/push.ts +466 -220
- package/src/realtime.ts +447 -290
- package/src/relational-rows.ts +43 -121
- package/src/s3-blob-store.ts +23 -13
- package/src/s3-object-bucket.ts +20 -2
- package/src/schema.ts +31 -0
- package/src/scopes.ts +23 -3
- package/src/seed.ts +13 -20
- package/src/segment-download.ts +33 -7
- package/src/signed-url.ts +10 -4
- package/src/sigv4.ts +17 -4
- package/src/sqlite-blob-store.ts +27 -26
- package/src/sqlite-dialect.ts +1851 -199
- package/src/sqlite-lease-store.ts +12 -23
- package/src/sqlite-storage.ts +390 -1821
- package/src/storage-query.ts +102 -0
- package/src/storage.ts +215 -67
package/dist/storage-query.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { CompiledTable, IndexSchema } from './schema.js';
|
|
2
|
-
import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, IndexRowScanQuery, RowScanQuery, StorageTransaction } from './storage.js';
|
|
2
|
+
import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, RowScanQuery, StorageTransaction, StoredChange } from './storage.js';
|
|
3
3
|
/**
|
|
4
4
|
* Fail loudly instead of making an unsupported unscoped scan look empty.
|
|
5
5
|
* Returns the first scope variable in sorted order — the one every adapter
|
|
@@ -15,3 +15,32 @@ export declare function resolveIndexRowScan(table: CompiledTable, query: IndexRo
|
|
|
15
15
|
* which reads outside the transaction.
|
|
16
16
|
*/
|
|
17
17
|
export declare function transactionQuery(tx: StorageTransaction, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
|
|
18
|
+
/** One index range of the live scan: a unit key and its exclusive lower bound. */
|
|
19
|
+
export interface LiveKey {
|
|
20
|
+
readonly var: string;
|
|
21
|
+
readonly value: string;
|
|
22
|
+
readonly after: number;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* One row of a live-window page: a candidate commit joined to its metadata
|
|
26
|
+
* (absent when the commit vanished) and one of its changes (absent when it
|
|
27
|
+
* has none), in (commitSeq, change index) order.
|
|
28
|
+
*/
|
|
29
|
+
export interface LiveWindowRow {
|
|
30
|
+
readonly commitSeq: number;
|
|
31
|
+
readonly meta?: {
|
|
32
|
+
readonly actorId: string;
|
|
33
|
+
readonly createdAtMs: number;
|
|
34
|
+
};
|
|
35
|
+
readonly change?: StoredChange;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The §4.5 live scan over a backend's page read. Each distinct unit key
|
|
39
|
+
* (the first variable, keys sorted) becomes one index range starting at the
|
|
40
|
+
* lowest bound of the units that share it; `readPage` returns up to `limit`
|
|
41
|
+
* candidate commits above every range's bound. A change is kept when a unit
|
|
42
|
+
* covers its table, the pair's effective scopes match it, and its commit
|
|
43
|
+
* lies above that unit's own bound. Every candidate advances the scan, so a
|
|
44
|
+
* page of non-matching candidates never repeats.
|
|
45
|
+
*/
|
|
46
|
+
export declare function readLiveWindowPages(query: LiveWindowQuery, readPage: (keys: readonly LiveKey[], limit: number) => Promise<readonly LiveWindowRow[]>): Promise<LiveWindow>;
|
package/dist/storage-query.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { matchesEffective } from './scopes.js';
|
|
1
2
|
import { StorageQueryError } from './storage-errors.js';
|
|
2
3
|
/**
|
|
3
4
|
* Fail loudly instead of making an unsupported unscoped scan look empty.
|
|
@@ -46,3 +47,70 @@ export async function transactionQuery(tx, query) {
|
|
|
46
47
|
}
|
|
47
48
|
return tx.queryAuthoritative(query);
|
|
48
49
|
}
|
|
50
|
+
/**
|
|
51
|
+
* The §4.5 live scan over a backend's page read. Each distinct unit key
|
|
52
|
+
* (the first variable, keys sorted) becomes one index range starting at the
|
|
53
|
+
* lowest bound of the units that share it; `readPage` returns up to `limit`
|
|
54
|
+
* candidate commits above every range's bound. A change is kept when a unit
|
|
55
|
+
* covers its table, the pair's effective scopes match it, and its commit
|
|
56
|
+
* lies above that unit's own bound. Every candidate advances the scan, so a
|
|
57
|
+
* page of non-matching candidates never repeats.
|
|
58
|
+
*/
|
|
59
|
+
export async function readLiveWindowPages(query, readPage) {
|
|
60
|
+
const bounds = new Map();
|
|
61
|
+
for (const unit of query.units) {
|
|
62
|
+
if (unit.tables.size === 0)
|
|
63
|
+
continue;
|
|
64
|
+
const variable = Object.keys(unit.scopes).sort()[0];
|
|
65
|
+
const value = variable === undefined ? undefined : unit.scopes[variable];
|
|
66
|
+
if (variable === undefined || value === undefined) {
|
|
67
|
+
throw new StorageQueryError('sync.storage.scan_requires_scope');
|
|
68
|
+
}
|
|
69
|
+
const id = JSON.stringify([variable, value]);
|
|
70
|
+
const prior = bounds.get(id);
|
|
71
|
+
if (prior === undefined || unit.afterSeq < prior.after) {
|
|
72
|
+
bounds.set(id, { var: variable, value, after: unit.afterSeq });
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const commits = [];
|
|
76
|
+
const limit = Math.max(64, query.limitChanges);
|
|
77
|
+
let delivered = 0;
|
|
78
|
+
let scanned = -1;
|
|
79
|
+
while (bounds.size > 0) {
|
|
80
|
+
const rows = await readPage([...bounds.values()].map((key) => ({
|
|
81
|
+
...key,
|
|
82
|
+
after: Math.max(key.after, scanned),
|
|
83
|
+
})), limit);
|
|
84
|
+
let candidates = 0;
|
|
85
|
+
for (let i = 0; i < rows.length;) {
|
|
86
|
+
const head = rows[i];
|
|
87
|
+
if (head === undefined)
|
|
88
|
+
break;
|
|
89
|
+
candidates += 1;
|
|
90
|
+
scanned = head.commitSeq;
|
|
91
|
+
const changes = [];
|
|
92
|
+
for (; rows[i]?.commitSeq === head.commitSeq; i++) {
|
|
93
|
+
const change = rows[i]?.change;
|
|
94
|
+
if (change !== undefined &&
|
|
95
|
+
query.units.some((unit) => {
|
|
96
|
+
const effective = unit.tables.get(change.table);
|
|
97
|
+
return (head.commitSeq > unit.afterSeq &&
|
|
98
|
+
effective !== undefined &&
|
|
99
|
+
matchesEffective(change.scopes, effective));
|
|
100
|
+
})) {
|
|
101
|
+
changes.push(change);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
if (head.meta === undefined || changes.length === 0)
|
|
105
|
+
continue;
|
|
106
|
+
commits.push({ commitSeq: head.commitSeq, ...head.meta, changes });
|
|
107
|
+
delivered += changes.length;
|
|
108
|
+
if (delivered >= query.limitChanges) {
|
|
109
|
+
return { commits, throughSeq: head.commitSeq };
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
if (candidates < limit)
|
|
113
|
+
break;
|
|
114
|
+
}
|
|
115
|
+
return { commits, throughSeq: query.throughSeq };
|
|
116
|
+
}
|
package/dist/storage.d.ts
CHANGED
|
@@ -11,13 +11,14 @@ import type { AuthoritativeRelationPlan } from './authoritative-query.js';
|
|
|
11
11
|
* - the pruning horizon per §4.6;
|
|
12
12
|
* - current-row reads for write authorization (§3.4) and conflict handling
|
|
13
13
|
* (§6.2);
|
|
14
|
-
* - per-(partition, clientId)
|
|
15
|
-
* (§4.5, §8.1)
|
|
14
|
+
* - the per-(partition, clientId) client record: registration list,
|
|
15
|
+
* catching-up units and record cursor (§4.5, §8.1);
|
|
16
|
+
* - the per-outbox acknowledged watermark (§6.3.2).
|
|
16
17
|
*
|
|
17
18
|
* The interface is async throughout so a Postgres implementation slots in
|
|
18
19
|
* without touching the core. All methods are partition-local (§2.1).
|
|
19
20
|
*/
|
|
20
|
-
import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
|
|
21
|
+
import type { PushOperationResult, RowValue, ScopeMap, UnitScopes } from '@syncular/core';
|
|
21
22
|
import type { CompiledSchema } from './schema.js';
|
|
22
23
|
export interface CommitPruneQuery {
|
|
23
24
|
readonly logEpoch: string;
|
|
@@ -77,6 +78,35 @@ export interface PreparedPushApply {
|
|
|
77
78
|
readonly gate: ServeGate;
|
|
78
79
|
/** The already-persisted outcome for this key, or `undefined` on a miss. */
|
|
79
80
|
readonly persisted: StoredPushResult | undefined;
|
|
81
|
+
/**
|
|
82
|
+
* The partition's delete floor (§2.2): the highest version any applied
|
|
83
|
+
* delete recorded, `0` before the first. An insert starts one above it.
|
|
84
|
+
*/
|
|
85
|
+
readonly deleteFloor: number;
|
|
86
|
+
/**
|
|
87
|
+
* The outbox watermark `W` after §6.3.2 step 1; present iff the call
|
|
88
|
+
* carried an {@link OutboxSettlement}. A commit of the request whose
|
|
89
|
+
* `persisted` is `undefined` and whose `clientSeq` is below `W` is
|
|
90
|
+
* expired (`sync.commit_expired`); at or above `W` it was never seen.
|
|
91
|
+
*/
|
|
92
|
+
readonly watermark?: number;
|
|
93
|
+
}
|
|
94
|
+
/** The outbox position of one pushed commit (§6.3.2). */
|
|
95
|
+
export interface OutboxSequence {
|
|
96
|
+
readonly outboxId: string;
|
|
97
|
+
readonly clientSeq: number;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* One push request's outbox, for the §9 settlement of results stored before
|
|
101
|
+
* wire version 4 and §6.3.2 steps 1 and 2.
|
|
102
|
+
*/
|
|
103
|
+
export interface OutboxSettlement {
|
|
104
|
+
readonly outboxId: string;
|
|
105
|
+
/** Every `PUSH_COMMIT` of the request in frame order. */
|
|
106
|
+
readonly commits: readonly {
|
|
107
|
+
readonly clientCommitId: string;
|
|
108
|
+
readonly clientSeq: number;
|
|
109
|
+
}[];
|
|
80
110
|
}
|
|
81
111
|
/** Why `serveGate` refuses, or `undefined` when this request may serve. */
|
|
82
112
|
export type ServeGateRefusal = {
|
|
@@ -126,12 +156,26 @@ export interface NewChange {
|
|
|
126
156
|
readonly table: string;
|
|
127
157
|
readonly rowId: string;
|
|
128
158
|
readonly op: 'upsert' | 'delete';
|
|
129
|
-
/**
|
|
130
|
-
|
|
159
|
+
/**
|
|
160
|
+
* The row's `server_version` after the write (§2.2): an upsert's written
|
|
161
|
+
* version, a delete's advanced version, which its tombstone records and
|
|
162
|
+
* the delete floor rises to.
|
|
163
|
+
*/
|
|
164
|
+
readonly rowVersion: number;
|
|
131
165
|
readonly scopes: Record<string, string>;
|
|
132
166
|
/** Present for upsert. */
|
|
133
167
|
readonly payload?: Uint8Array;
|
|
134
168
|
}
|
|
169
|
+
/** §2.2 delete-precedence tombstone of a row deleted within the horizon. */
|
|
170
|
+
export interface Tombstone {
|
|
171
|
+
readonly commitSeq: number;
|
|
172
|
+
/**
|
|
173
|
+
* The deleted row's last `server_version` and stored scopes. Both are
|
|
174
|
+
* absent on a tombstone written before servers recorded them.
|
|
175
|
+
*/
|
|
176
|
+
readonly serverVersion?: number;
|
|
177
|
+
readonly scopes?: Record<string, string>;
|
|
178
|
+
}
|
|
135
179
|
export interface NewCommit {
|
|
136
180
|
readonly clientId: string;
|
|
137
181
|
readonly clientCommitId: string;
|
|
@@ -146,10 +190,16 @@ export interface NewCommit {
|
|
|
146
190
|
* its tombstone.
|
|
147
191
|
*/
|
|
148
192
|
export declare function rowsLiveAfterDelete(changes: readonly NewChange[]): Set<string>;
|
|
193
|
+
/**
|
|
194
|
+
* The delete floor a commit raises the partition's to (§2.2): the highest
|
|
195
|
+
* version of a delete that leaves a tombstone, `0` without one.
|
|
196
|
+
*/
|
|
197
|
+
export declare function commitDeleteFloor(changes: readonly NewChange[]): number;
|
|
149
198
|
export interface StoredChange {
|
|
150
199
|
readonly table: string;
|
|
151
200
|
readonly rowId: string;
|
|
152
201
|
readonly op: 'upsert' | 'delete';
|
|
202
|
+
/** Absent only on a delete logged before wire version 4. */
|
|
153
203
|
readonly rowVersion?: number;
|
|
154
204
|
readonly scopes: Record<string, string>;
|
|
155
205
|
readonly payload?: Uint8Array;
|
|
@@ -242,23 +292,43 @@ export interface StoredPushResult {
|
|
|
242
292
|
};
|
|
243
293
|
readonly results: readonly PushOperationResult[];
|
|
244
294
|
}
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
295
|
+
/** The registration list a client last sent, with its digest (§4.1). */
|
|
296
|
+
export interface ClientRegistration {
|
|
297
|
+
/** Scope maps in registration order. */
|
|
298
|
+
readonly units: readonly UnitScopes[];
|
|
299
|
+
/** The 32-byte registration digest. */
|
|
300
|
+
readonly digest: Uint8Array;
|
|
301
|
+
}
|
|
302
|
+
/** A unit still catching up after the client's last completed round (§4.1). */
|
|
303
|
+
export interface CatchingUpUnit {
|
|
304
|
+
/** The unit id (§4.1). */
|
|
248
305
|
readonly id: string;
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
readonly scopes: ScopeMap;
|
|
306
|
+
/** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
|
|
307
|
+
readonly cursor: number;
|
|
252
308
|
}
|
|
309
|
+
/** The §4.5 client record. */
|
|
253
310
|
export interface ClientRecord {
|
|
254
311
|
readonly clientId: string;
|
|
255
312
|
readonly actorId: string;
|
|
256
|
-
/** SSP2 version last accepted from this client
|
|
313
|
+
/** SSP2 version last accepted from this client. */
|
|
257
314
|
readonly wireVersion: number;
|
|
258
|
-
/**
|
|
315
|
+
/** The record cursor (§4.5); feeds the §4.6 retention watermark. */
|
|
259
316
|
readonly cursor: number;
|
|
260
317
|
readonly updatedAtMs: number;
|
|
261
|
-
|
|
318
|
+
/**
|
|
319
|
+
* Schema version of the latest completed round; realtime projects deltas
|
|
320
|
+
* through its codec. Absent on a record written before wire version 4.
|
|
321
|
+
*/
|
|
322
|
+
readonly schemaVersion?: number;
|
|
323
|
+
/**
|
|
324
|
+
* The stored registration list; absent when none is stored (§9: a record
|
|
325
|
+
* written before wire version 4 holds none). On `putClientRecord`, absent
|
|
326
|
+
* keeps the stored list and digest: a round writes them only when its
|
|
327
|
+
* list traveled.
|
|
328
|
+
*/
|
|
329
|
+
readonly registration?: ClientRegistration;
|
|
330
|
+
/** Catching-up units in registration order; the rest of the list is live. */
|
|
331
|
+
readonly catchingUp: readonly CatchingUpUnit[];
|
|
262
332
|
/** When this client's last sync round finished, successfully or not. */
|
|
263
333
|
readonly lastRoundAtMs?: number;
|
|
264
334
|
/** Code of the last round when it failed; absent after a successful round. */
|
|
@@ -277,23 +347,42 @@ export interface ClientRecordWriteOptions {
|
|
|
277
347
|
}
|
|
278
348
|
/** The round-state fields of a stored `sync_clients` row. */
|
|
279
349
|
export declare function clientRoundState(lastRoundAtMs: number | null, lastErrorCode: string | null, consecutiveFailures: number): Pick<ClientRecord, 'lastRoundAtMs' | 'lastErrorCode' | 'consecutiveFailures'>;
|
|
280
|
-
|
|
281
|
-
|
|
350
|
+
/** One unit of the §4.5 scan set. */
|
|
351
|
+
export interface LiveScanUnit {
|
|
352
|
+
/** The unit's scope map; its first variable (keys sorted) is its index key. */
|
|
353
|
+
readonly scopes: UnitScopes;
|
|
354
|
+
/** Exclusive lower bound: `R`, the unit's cursor `P`, or its pin. */
|
|
355
|
+
readonly afterSeq: number;
|
|
282
356
|
/**
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
*
|
|
357
|
+
* The unit's active (unit, table) pairs: covered table → effective scopes
|
|
358
|
+
* (§3.2). A change of table `t` matches iff its stored scopes satisfy the
|
|
359
|
+
* pair for `t` and its commit lies above `afterSeq`.
|
|
286
360
|
*/
|
|
287
|
-
readonly
|
|
288
|
-
|
|
289
|
-
|
|
361
|
+
readonly tables: ReadonlyMap<string, ScopeMap>;
|
|
362
|
+
}
|
|
363
|
+
export interface LiveWindowQuery {
|
|
364
|
+
readonly units: readonly LiveScanUnit[];
|
|
365
|
+
/** `maxCommitSeq` read at the start of the pull. */
|
|
290
366
|
readonly throughSeq: number;
|
|
291
|
-
/**
|
|
367
|
+
/** The `limitCommits` budget: stop after the commit that reaches it. */
|
|
292
368
|
readonly limitChanges: number;
|
|
293
369
|
}
|
|
370
|
+
/** The commits of one live section (§4.5). */
|
|
371
|
+
export interface LiveWindow {
|
|
372
|
+
/** Oldest first, each with its matching changes in change order. */
|
|
373
|
+
readonly commits: readonly StoredCommit[];
|
|
374
|
+
/**
|
|
375
|
+
* `T`: `query.throughSeq`, or the last delivered `commitSeq` when the
|
|
376
|
+
* budget cut the section.
|
|
377
|
+
*/
|
|
378
|
+
readonly throughSeq: number;
|
|
379
|
+
}
|
|
294
380
|
export interface RowScanQuery {
|
|
295
381
|
readonly table: string;
|
|
296
|
-
/**
|
|
382
|
+
/**
|
|
383
|
+
* Effective scopes (§3.2): a row matches iff, for every key, its stored
|
|
384
|
+
* value is in the list. Candidates come from the inverted row-scope index.
|
|
385
|
+
*/
|
|
297
386
|
readonly scopeFilter: ScopeMap;
|
|
298
387
|
/** Resume after this rowId (exclusive); `null` = start of table. */
|
|
299
388
|
readonly afterRowId: string | null;
|
|
@@ -373,6 +462,13 @@ export interface RowListQuery {
|
|
|
373
462
|
readonly afterRowId: string | null;
|
|
374
463
|
readonly limit: number;
|
|
375
464
|
}
|
|
465
|
+
/** One §6.3.2 watermark row. */
|
|
466
|
+
export interface PushWatermark {
|
|
467
|
+
readonly clientId: string;
|
|
468
|
+
readonly outboxId: string;
|
|
469
|
+
/** `W`: results of this outbox below it are deleted. */
|
|
470
|
+
readonly throughSeq: number;
|
|
471
|
+
}
|
|
376
472
|
/** A stored push outcome with the client that sent it. */
|
|
377
473
|
export interface ClientPushResult {
|
|
378
474
|
readonly clientId: string;
|
|
@@ -453,17 +549,17 @@ export interface StorageTransaction {
|
|
|
453
549
|
readonly rowIds: readonly string[];
|
|
454
550
|
}[]): Promise<void>;
|
|
455
551
|
/**
|
|
456
|
-
* §5 delete-precedence tombstone read: the
|
|
457
|
-
*
|
|
458
|
-
*
|
|
459
|
-
*
|
|
460
|
-
*
|
|
552
|
+
* §5 delete-precedence tombstone read: the newest applied delete of this
|
|
553
|
+
* row still within the pruning horizon, or `undefined` when no tombstone
|
|
554
|
+
* exists. Consulted only when an upsert's stored row is absent. Required:
|
|
555
|
+
* in-tree adapters implement it on the transaction's own connection with
|
|
556
|
+
* read-your-own-writes semantics.
|
|
461
557
|
*/
|
|
462
|
-
|
|
558
|
+
getTombstone(table: string, rowId: string): Promise<Tombstone | undefined>;
|
|
463
559
|
/**
|
|
464
|
-
* Remove the row's tombstone because the row
|
|
465
|
-
* transaction
|
|
466
|
-
*
|
|
560
|
+
* Remove the row's tombstone because the row is live again in this
|
|
561
|
+
* transaction: an insert over its tombstone (§6.2) or a §2.2 scope move.
|
|
562
|
+
* A no-op when no tombstone exists.
|
|
467
563
|
*/
|
|
468
564
|
clearTombstone(table: string, rowId: string): Promise<void>;
|
|
469
565
|
/**
|
|
@@ -508,11 +604,18 @@ export interface StorageTransaction {
|
|
|
508
604
|
* are built; a storage with per-statement network cost folds that read-ahead
|
|
509
605
|
* into the admission read and answers the following `getRow` calls from it.
|
|
510
606
|
* Missing support fails closed before an app-row mutation.
|
|
607
|
+
*
|
|
608
|
+
* `outbox`, passed with the first commit of a request that carries an
|
|
609
|
+
* `outboxId`, settles the client's results stored before wire version 4
|
|
610
|
+
* (§9) and runs §6.3.2 steps 1 and 2 under the same lock, before the read
|
|
611
|
+
* of `persisted`. Those writes survive `commitRejectedPushResult`; the
|
|
612
|
+
* caller commits this transaction whatever the commit's outcome, so the
|
|
613
|
+
* settlement runs exactly once per request.
|
|
511
614
|
*/
|
|
512
615
|
preparePushApply(clientId: string, clientCommitId: string, runningSchemaVersion: number, targets?: readonly {
|
|
513
616
|
readonly table: string;
|
|
514
617
|
readonly rowIds: readonly string[];
|
|
515
|
-
}[]): Promise<PreparedPushApply>;
|
|
618
|
+
}[], outbox?: OutboxSettlement): Promise<PreparedPushApply>;
|
|
516
619
|
/**
|
|
517
620
|
* Rejection finalization while the push-apply serialization lock is still
|
|
518
621
|
* held: discard every candidate write, persist the rejected idempotency
|
|
@@ -521,7 +624,7 @@ export interface StorageTransaction {
|
|
|
521
624
|
* push so a concurrent duplicate cannot rerun operations, validators, or
|
|
522
625
|
* merges.
|
|
523
626
|
*/
|
|
524
|
-
commitRejectedPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<StoredPushResult>;
|
|
627
|
+
commitRejectedPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<StoredPushResult>;
|
|
525
628
|
upsertRow(table: string, row: StoredRow, context?: {
|
|
526
629
|
readonly opIndex: number;
|
|
527
630
|
}): Promise<void>;
|
|
@@ -536,9 +639,11 @@ export interface StorageTransaction {
|
|
|
536
639
|
enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
|
|
537
640
|
/**
|
|
538
641
|
* Persist an idempotency outcome only when the key is still absent. The
|
|
539
|
-
* first writer wins; callers read the canonical value after commit.
|
|
642
|
+
* first writer wins; callers read the canonical value after commit. A
|
|
643
|
+
* result without `sequence` (no `outboxId`, §6.10, §12.3) is never deleted
|
|
644
|
+
* by a watermark.
|
|
540
645
|
*/
|
|
541
|
-
putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
|
|
646
|
+
putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<void>;
|
|
542
647
|
/**
|
|
543
648
|
* Advance this partition's checkpoint only while `owner_epoch` still
|
|
544
649
|
* matches, so the owner-epoch CAS rides inside the caller's transaction.
|
|
@@ -595,7 +700,10 @@ export interface ServerStorage {
|
|
|
595
700
|
* back without a write, so a request that only reads takes no write lock.
|
|
596
701
|
*/
|
|
597
702
|
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
|
|
598
|
-
/**
|
|
703
|
+
/**
|
|
704
|
+
* Rotate log continuity after restore and delete the partition's client
|
|
705
|
+
* records. Watermark rows stay (§6.3.2).
|
|
706
|
+
*/
|
|
599
707
|
rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
|
|
600
708
|
/** Registry entries ordered by partition for maintenance loops. */
|
|
601
709
|
listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
|
|
@@ -695,22 +803,25 @@ export interface ServerStorage {
|
|
|
695
803
|
/** Delete a bounded set of aged terminal rows. Never deletes active work. */
|
|
696
804
|
pruneReactions?(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
|
|
697
805
|
/**
|
|
698
|
-
*
|
|
699
|
-
*
|
|
700
|
-
*
|
|
806
|
+
* The §4.5 live section: every commit in `(min afterSeq, throughSeq]`
|
|
807
|
+
* carrying a change that matches a unit of the scan set, oldest first,
|
|
808
|
+
* each with its matching changes once, in change order, across tables.
|
|
809
|
+
* Stops after the commit whose matching changes reach `limitChanges`
|
|
810
|
+
* (never splitting a commit). Candidates come from the change-scope key
|
|
811
|
+
* index, one index range per distinct unit key, never from a log scan.
|
|
701
812
|
*/
|
|
702
|
-
|
|
813
|
+
readLiveWindow(partition: string, query: LiveWindowQuery): Promise<LiveWindow>;
|
|
703
814
|
/**
|
|
704
|
-
* Newest commitSeq whose change to `query.table` carries
|
|
705
|
-
*
|
|
706
|
-
* the
|
|
707
|
-
*
|
|
708
|
-
*
|
|
709
|
-
*
|
|
815
|
+
* Newest commitSeq whose change to `query.table` carries the unit's value
|
|
816
|
+
* of its first variable (keys sorted): the `readLiveWindow` candidate rule,
|
|
817
|
+
* so no change the unit would receive for the table sits above it. 0 when
|
|
818
|
+
* the index holds none (never written, or pruned). The §4.7 sqlite-lane
|
|
819
|
+
* scope pin reads it; it MUST be one index lookup, independent of the
|
|
820
|
+
* table's history.
|
|
710
821
|
*/
|
|
711
822
|
latestScopedChangeSeq(partition: string, query: {
|
|
712
823
|
readonly table: string;
|
|
713
|
-
readonly
|
|
824
|
+
readonly scopes: UnitScopes;
|
|
714
825
|
}): Promise<number>;
|
|
715
826
|
/** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
|
|
716
827
|
scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
|
|
@@ -741,10 +852,13 @@ export interface ServerStorage {
|
|
|
741
852
|
scanRowsByIndex?(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
|
|
742
853
|
getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
|
|
743
854
|
/**
|
|
744
|
-
* Write the record for a completed round.
|
|
745
|
-
*
|
|
746
|
-
*
|
|
747
|
-
*
|
|
855
|
+
* Write the record for a completed round (§4.5). A record without
|
|
856
|
+
* `registration` keeps the stored list and digest. The round-state fields
|
|
857
|
+
* reset: the stored last round is a success at `lastRoundAtMs` (default
|
|
858
|
+
* `updatedAtMs`) with no failures, unless `keepRoundOutcome` is set, which
|
|
859
|
+
* leaves the reported code and streak in place (the round carried a
|
|
860
|
+
* `ROUND_FAILURE` report, §1.5/§4.5). An `unregistered` answer rewrites the
|
|
861
|
+
* stored record with only `lastRoundAtMs` moved.
|
|
748
862
|
*/
|
|
749
863
|
putClientRecord(partition: string, record: ClientRecord, options?: ClientRecordWriteOptions): Promise<void>;
|
|
750
864
|
/**
|
|
@@ -755,15 +869,17 @@ export interface ServerStorage {
|
|
|
755
869
|
*/
|
|
756
870
|
recordClientRoundFailure(partition: string, clientId: string, actorId: string, errorCode: string, atMs: number): Promise<void>;
|
|
757
871
|
/**
|
|
758
|
-
*
|
|
759
|
-
*
|
|
760
|
-
*
|
|
872
|
+
* §8.2 ack: atomically raise an existing record's cursor to `cursor`,
|
|
873
|
+
* capped at the lowest non-negative cursor of its catching-up units, and
|
|
874
|
+
* its activity timestamp, both monotonically. Every other field stays;
|
|
875
|
+
* requires the matching actor and the current log epoch. A missing record
|
|
876
|
+
* or a mismatched identity is unchanged.
|
|
761
877
|
*/
|
|
762
878
|
advanceClientCursor(partition: string, clientId: string, actorId: string, logEpoch: string, cursor: number, updatedAtMs: number): Promise<void>;
|
|
763
|
-
/**
|
|
764
|
-
*
|
|
765
|
-
|
|
766
|
-
|
|
879
|
+
/**
|
|
880
|
+
* Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
|
|
881
|
+
* none are active. A bootstrapping client (cursor < 0) holds no cursor.
|
|
882
|
+
*/
|
|
767
883
|
getActiveClientCursorFloor(partition: string, cutoffMs: number): Promise<number | null>;
|
|
768
884
|
/** Cursor records for client listings and administrative counts. */
|
|
769
885
|
listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
|
|
@@ -791,9 +907,11 @@ export interface ServerStorage {
|
|
|
791
907
|
* `eraseScopeValueHistory`: under the partition write lock, removes up to
|
|
792
908
|
* `limit` upsert change records of `table` at or below `throughSeq` whose
|
|
793
909
|
* scopes bind `variable` to `value`, then up to `limit` change scope index
|
|
794
|
-
* entries of that binding whose commit holds no such change any more
|
|
910
|
+
* entries of that binding whose commit holds no such change any more,
|
|
911
|
+
* then strips `serverRow` from up to `limit` stored conflict results of
|
|
912
|
+
* `table` whose conflict authorization scopes bind `variable` to `value`.
|
|
795
913
|
* Delete change records stay: clients behind the erasure still need them.
|
|
796
|
-
* Returns the number of records removed.
|
|
914
|
+
* Returns the number of records removed or stripped.
|
|
797
915
|
*/
|
|
798
916
|
listScopeValueRows?(partition: string, query: ScopeValueQuery): Promise<string[]>;
|
|
799
917
|
eraseScopeValueHistory?(partition: string, query: ScopeValueHistoryQuery): Promise<number>;
|
|
@@ -804,7 +922,7 @@ export interface ServerStorage {
|
|
|
804
922
|
* calls them.
|
|
805
923
|
*
|
|
806
924
|
* `listClientRecords`: every stored client record for the partition
|
|
807
|
-
* (cursor, last-seen,
|
|
925
|
+
* (cursor, last-seen, registration list): the "who's connected" view.
|
|
808
926
|
* `listCommitMetadata`: the commit log without payloads (metadata +
|
|
809
927
|
* touched tables), the newest-oriented window an operator inspects.
|
|
810
928
|
* `scopeActivity`: the recent commits touching one scope key, via the
|
|
@@ -819,6 +937,9 @@ export interface ServerStorage {
|
|
|
819
937
|
* `listPushResults`: every stored idempotency outcome for one
|
|
820
938
|
* clientCommitId across the partition's clients, scanning the retained
|
|
821
939
|
* outcomes without a dedicated index.
|
|
940
|
+
* `listPushWatermarks`: the §6.3.2 watermark rows of every client whose
|
|
941
|
+
* retained commit log carries the clientCommitId; a commit whose result
|
|
942
|
+
* the watermark deleted reads as "expired below sequence `throughSeq`".
|
|
822
943
|
* `listPartitions`: the partition-only compatibility view of
|
|
823
944
|
* `listPartitionRegistry`, sorted.
|
|
824
945
|
*/
|
|
@@ -830,6 +951,7 @@ export interface ServerStorage {
|
|
|
830
951
|
listRows?(partition: string, query: RowListQuery): Promise<StoredRow[]>;
|
|
831
952
|
countRows?(partition: string, table: string): Promise<number>;
|
|
832
953
|
listPushResults?(partition: string, clientCommitId: string): Promise<ClientPushResult[]>;
|
|
954
|
+
listPushWatermarks?(partition: string, clientCommitId: string): Promise<PushWatermark[]>;
|
|
833
955
|
listPartitions(): Promise<string[]>;
|
|
834
956
|
}
|
|
835
957
|
/** One scope binding of one table, budgeted (§4.6.1). */
|
package/dist/storage.js
CHANGED
|
@@ -64,6 +64,21 @@ export function rowsLiveAfterDelete(changes) {
|
|
|
64
64
|
}
|
|
65
65
|
return live;
|
|
66
66
|
}
|
|
67
|
+
/**
|
|
68
|
+
* The delete floor a commit raises the partition's to (§2.2): the highest
|
|
69
|
+
* version of a delete that leaves a tombstone, `0` without one.
|
|
70
|
+
*/
|
|
71
|
+
export function commitDeleteFloor(changes) {
|
|
72
|
+
const live = rowsLiveAfterDelete(changes);
|
|
73
|
+
let floor = 0;
|
|
74
|
+
for (const change of changes) {
|
|
75
|
+
if (change.op === 'delete' &&
|
|
76
|
+
!live.has(`${change.table}\u0000${change.rowId}`)) {
|
|
77
|
+
floor = Math.max(floor, change.rowVersion);
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
return floor;
|
|
81
|
+
}
|
|
67
82
|
/** The round-state fields of a stored `sync_clients` row. */
|
|
68
83
|
export function clientRoundState(lastRoundAtMs, lastErrorCode, consecutiveFailures) {
|
|
69
84
|
return {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.60.0",
|
|
4
4
|
"description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
|
|
69
69
|
},
|
|
70
70
|
"dependencies": {
|
|
71
|
-
"@syncular/core": "0.
|
|
71
|
+
"@syncular/core": "0.60.0"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@electric-sql/pglite": "^0.5.4"
|