@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/src/storage-query.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
import type { ScopeMap } from '@syncular/core';
|
|
2
2
|
import type { CompiledTable, IndexSchema } from './schema';
|
|
3
|
+
import { matchesEffective } from './scopes';
|
|
3
4
|
import type {
|
|
4
5
|
AuthoritativeQueryRequest,
|
|
5
6
|
AuthoritativeQueryResult,
|
|
6
7
|
IndexRowScanQuery,
|
|
8
|
+
LiveWindow,
|
|
9
|
+
LiveWindowQuery,
|
|
7
10
|
RowScanQuery,
|
|
8
11
|
StorageTransaction,
|
|
12
|
+
StoredChange,
|
|
13
|
+
StoredCommit,
|
|
9
14
|
} from './storage';
|
|
10
15
|
import { StorageQueryError } from './storage-errors';
|
|
11
16
|
|
|
@@ -73,3 +78,100 @@ export async function transactionQuery(
|
|
|
73
78
|
}
|
|
74
79
|
return tx.queryAuthoritative(query);
|
|
75
80
|
}
|
|
81
|
+
|
|
82
|
+
/** One index range of the live scan: a unit key and its exclusive lower bound. */
|
|
83
|
+
export interface LiveKey {
|
|
84
|
+
readonly var: string;
|
|
85
|
+
readonly value: string;
|
|
86
|
+
readonly after: number;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* One row of a live-window page: a candidate commit joined to its metadata
|
|
91
|
+
* (absent when the commit vanished) and one of its changes (absent when it
|
|
92
|
+
* has none), in (commitSeq, change index) order.
|
|
93
|
+
*/
|
|
94
|
+
export interface LiveWindowRow {
|
|
95
|
+
readonly commitSeq: number;
|
|
96
|
+
readonly meta?: { readonly actorId: string; readonly createdAtMs: number };
|
|
97
|
+
readonly change?: StoredChange;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The §4.5 live scan over a backend's page read. Each distinct unit key
|
|
102
|
+
* (the first variable, keys sorted) becomes one index range starting at the
|
|
103
|
+
* lowest bound of the units that share it; `readPage` returns up to `limit`
|
|
104
|
+
* candidate commits above every range's bound. A change is kept when a unit
|
|
105
|
+
* covers its table, the pair's effective scopes match it, and its commit
|
|
106
|
+
* lies above that unit's own bound. Every candidate advances the scan, so a
|
|
107
|
+
* page of non-matching candidates never repeats.
|
|
108
|
+
*/
|
|
109
|
+
export async function readLiveWindowPages(
|
|
110
|
+
query: LiveWindowQuery,
|
|
111
|
+
readPage: (
|
|
112
|
+
keys: readonly LiveKey[],
|
|
113
|
+
limit: number,
|
|
114
|
+
) => Promise<readonly LiveWindowRow[]>,
|
|
115
|
+
): Promise<LiveWindow> {
|
|
116
|
+
const bounds = new Map<string, LiveKey>();
|
|
117
|
+
for (const unit of query.units) {
|
|
118
|
+
if (unit.tables.size === 0) continue;
|
|
119
|
+
const variable = Object.keys(unit.scopes).sort()[0];
|
|
120
|
+
const value = variable === undefined ? undefined : unit.scopes[variable];
|
|
121
|
+
if (variable === undefined || value === undefined) {
|
|
122
|
+
throw new StorageQueryError('sync.storage.scan_requires_scope');
|
|
123
|
+
}
|
|
124
|
+
const id = JSON.stringify([variable, value]);
|
|
125
|
+
const prior = bounds.get(id);
|
|
126
|
+
if (prior === undefined || unit.afterSeq < prior.after) {
|
|
127
|
+
bounds.set(id, { var: variable, value, after: unit.afterSeq });
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
const commits: StoredCommit[] = [];
|
|
131
|
+
const limit = Math.max(64, query.limitChanges);
|
|
132
|
+
let delivered = 0;
|
|
133
|
+
let scanned = -1;
|
|
134
|
+
while (bounds.size > 0) {
|
|
135
|
+
const rows = await readPage(
|
|
136
|
+
[...bounds.values()].map((key) => ({
|
|
137
|
+
...key,
|
|
138
|
+
after: Math.max(key.after, scanned),
|
|
139
|
+
})),
|
|
140
|
+
limit,
|
|
141
|
+
);
|
|
142
|
+
let candidates = 0;
|
|
143
|
+
for (let i = 0; i < rows.length;) {
|
|
144
|
+
const head = rows[i];
|
|
145
|
+
if (head === undefined) break;
|
|
146
|
+
candidates += 1;
|
|
147
|
+
scanned = head.commitSeq;
|
|
148
|
+
const changes: StoredChange[] = [];
|
|
149
|
+
for (; rows[i]?.commitSeq === head.commitSeq; i++) {
|
|
150
|
+
const change = rows[i]?.change;
|
|
151
|
+
if (
|
|
152
|
+
change !== undefined &&
|
|
153
|
+
query.units.some((unit) => {
|
|
154
|
+
const effective: ScopeMap | undefined = unit.tables.get(
|
|
155
|
+
change.table,
|
|
156
|
+
);
|
|
157
|
+
return (
|
|
158
|
+
head.commitSeq > unit.afterSeq &&
|
|
159
|
+
effective !== undefined &&
|
|
160
|
+
matchesEffective(change.scopes, effective)
|
|
161
|
+
);
|
|
162
|
+
})
|
|
163
|
+
) {
|
|
164
|
+
changes.push(change);
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
if (head.meta === undefined || changes.length === 0) continue;
|
|
168
|
+
commits.push({ commitSeq: head.commitSeq, ...head.meta, changes });
|
|
169
|
+
delivered += changes.length;
|
|
170
|
+
if (delivered >= query.limitChanges) {
|
|
171
|
+
return { commits, throughSeq: head.commitSeq };
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
if (candidates < limit) break;
|
|
175
|
+
}
|
|
176
|
+
return { commits, throughSeq: query.throughSeq };
|
|
177
|
+
}
|
package/src/storage.ts
CHANGED
|
@@ -11,13 +11,19 @@ import type { AuthoritativeRelationPlan } from './authoritative-query';
|
|
|
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 {
|
|
21
|
+
import type {
|
|
22
|
+
PushOperationResult,
|
|
23
|
+
RowValue,
|
|
24
|
+
ScopeMap,
|
|
25
|
+
UnitScopes,
|
|
26
|
+
} from '@syncular/core';
|
|
21
27
|
import type { CompiledSchema } from './schema';
|
|
22
28
|
|
|
23
29
|
export interface CommitPruneQuery {
|
|
@@ -84,6 +90,37 @@ export interface PreparedPushApply {
|
|
|
84
90
|
readonly gate: ServeGate;
|
|
85
91
|
/** The already-persisted outcome for this key, or `undefined` on a miss. */
|
|
86
92
|
readonly persisted: StoredPushResult | undefined;
|
|
93
|
+
/**
|
|
94
|
+
* The partition's delete floor (§2.2): the highest version any applied
|
|
95
|
+
* delete recorded, `0` before the first. An insert starts one above it.
|
|
96
|
+
*/
|
|
97
|
+
readonly deleteFloor: number;
|
|
98
|
+
/**
|
|
99
|
+
* The outbox watermark `W` after §6.3.2 step 1; present iff the call
|
|
100
|
+
* carried an {@link OutboxSettlement}. A commit of the request whose
|
|
101
|
+
* `persisted` is `undefined` and whose `clientSeq` is below `W` is
|
|
102
|
+
* expired (`sync.commit_expired`); at or above `W` it was never seen.
|
|
103
|
+
*/
|
|
104
|
+
readonly watermark?: number;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** The outbox position of one pushed commit (§6.3.2). */
|
|
108
|
+
export interface OutboxSequence {
|
|
109
|
+
readonly outboxId: string;
|
|
110
|
+
readonly clientSeq: number;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* One push request's outbox, for the §9 settlement of results stored before
|
|
115
|
+
* wire version 4 and §6.3.2 steps 1 and 2.
|
|
116
|
+
*/
|
|
117
|
+
export interface OutboxSettlement {
|
|
118
|
+
readonly outboxId: string;
|
|
119
|
+
/** Every `PUSH_COMMIT` of the request in frame order. */
|
|
120
|
+
readonly commits: readonly {
|
|
121
|
+
readonly clientCommitId: string;
|
|
122
|
+
readonly clientSeq: number;
|
|
123
|
+
}[];
|
|
87
124
|
}
|
|
88
125
|
|
|
89
126
|
/** Why `serveGate` refuses, or `undefined` when this request may serve. */
|
|
@@ -179,13 +216,28 @@ export interface NewChange {
|
|
|
179
216
|
readonly table: string;
|
|
180
217
|
readonly rowId: string;
|
|
181
218
|
readonly op: 'upsert' | 'delete';
|
|
182
|
-
/**
|
|
183
|
-
|
|
219
|
+
/**
|
|
220
|
+
* The row's `server_version` after the write (§2.2): an upsert's written
|
|
221
|
+
* version, a delete's advanced version, which its tombstone records and
|
|
222
|
+
* the delete floor rises to.
|
|
223
|
+
*/
|
|
224
|
+
readonly rowVersion: number;
|
|
184
225
|
readonly scopes: Record<string, string>;
|
|
185
226
|
/** Present for upsert. */
|
|
186
227
|
readonly payload?: Uint8Array;
|
|
187
228
|
}
|
|
188
229
|
|
|
230
|
+
/** §2.2 delete-precedence tombstone of a row deleted within the horizon. */
|
|
231
|
+
export interface Tombstone {
|
|
232
|
+
readonly commitSeq: number;
|
|
233
|
+
/**
|
|
234
|
+
* The deleted row's last `server_version` and stored scopes. Both are
|
|
235
|
+
* absent on a tombstone written before servers recorded them.
|
|
236
|
+
*/
|
|
237
|
+
readonly serverVersion?: number;
|
|
238
|
+
readonly scopes?: Record<string, string>;
|
|
239
|
+
}
|
|
240
|
+
|
|
189
241
|
export interface NewCommit {
|
|
190
242
|
readonly clientId: string;
|
|
191
243
|
readonly clientCommitId: string;
|
|
@@ -221,10 +273,29 @@ export function rowsLiveAfterDelete(
|
|
|
221
273
|
return live;
|
|
222
274
|
}
|
|
223
275
|
|
|
276
|
+
/**
|
|
277
|
+
* The delete floor a commit raises the partition's to (§2.2): the highest
|
|
278
|
+
* version of a delete that leaves a tombstone, `0` without one.
|
|
279
|
+
*/
|
|
280
|
+
export function commitDeleteFloor(changes: readonly NewChange[]): number {
|
|
281
|
+
const live = rowsLiveAfterDelete(changes);
|
|
282
|
+
let floor = 0;
|
|
283
|
+
for (const change of changes) {
|
|
284
|
+
if (
|
|
285
|
+
change.op === 'delete' &&
|
|
286
|
+
!live.has(`${change.table}\u0000${change.rowId}`)
|
|
287
|
+
) {
|
|
288
|
+
floor = Math.max(floor, change.rowVersion);
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
return floor;
|
|
292
|
+
}
|
|
293
|
+
|
|
224
294
|
export interface StoredChange {
|
|
225
295
|
readonly table: string;
|
|
226
296
|
readonly rowId: string;
|
|
227
297
|
readonly op: 'upsert' | 'delete';
|
|
298
|
+
/** Absent only on a delete logged before wire version 4. */
|
|
228
299
|
readonly rowVersion?: number;
|
|
229
300
|
readonly scopes: Record<string, string>;
|
|
230
301
|
readonly payload?: Uint8Array;
|
|
@@ -332,24 +403,45 @@ export interface StoredPushResult {
|
|
|
332
403
|
readonly results: readonly PushOperationResult[];
|
|
333
404
|
}
|
|
334
405
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
406
|
+
/** The registration list a client last sent, with its digest (§4.1). */
|
|
407
|
+
export interface ClientRegistration {
|
|
408
|
+
/** Scope maps in registration order. */
|
|
409
|
+
readonly units: readonly UnitScopes[];
|
|
410
|
+
/** The 32-byte registration digest. */
|
|
411
|
+
readonly digest: Uint8Array;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
/** A unit still catching up after the client's last completed round (§4.1). */
|
|
415
|
+
export interface CatchingUpUnit {
|
|
416
|
+
/** The unit id (§4.1). */
|
|
338
417
|
readonly id: string;
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
readonly scopes: ScopeMap;
|
|
418
|
+
/** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
|
|
419
|
+
readonly cursor: number;
|
|
342
420
|
}
|
|
343
421
|
|
|
422
|
+
/** The §4.5 client record. */
|
|
344
423
|
export interface ClientRecord {
|
|
345
424
|
readonly clientId: string;
|
|
346
425
|
readonly actorId: string;
|
|
347
|
-
/** SSP2 version last accepted from this client
|
|
426
|
+
/** SSP2 version last accepted from this client. */
|
|
348
427
|
readonly wireVersion: number;
|
|
349
|
-
/**
|
|
428
|
+
/** The record cursor (§4.5); feeds the §4.6 retention watermark. */
|
|
350
429
|
readonly cursor: number;
|
|
351
430
|
readonly updatedAtMs: number;
|
|
352
|
-
|
|
431
|
+
/**
|
|
432
|
+
* Schema version of the latest completed round; realtime projects deltas
|
|
433
|
+
* through its codec. Absent on a record written before wire version 4.
|
|
434
|
+
*/
|
|
435
|
+
readonly schemaVersion?: number;
|
|
436
|
+
/**
|
|
437
|
+
* The stored registration list; absent when none is stored (§9: a record
|
|
438
|
+
* written before wire version 4 holds none). On `putClientRecord`, absent
|
|
439
|
+
* keeps the stored list and digest: a round writes them only when its
|
|
440
|
+
* list traveled.
|
|
441
|
+
*/
|
|
442
|
+
readonly registration?: ClientRegistration;
|
|
443
|
+
/** Catching-up units in registration order; the rest of the list is live. */
|
|
444
|
+
readonly catchingUp: readonly CatchingUpUnit[];
|
|
353
445
|
/** When this client's last sync round finished, successfully or not. */
|
|
354
446
|
readonly lastRoundAtMs?: number;
|
|
355
447
|
/** Code of the last round when it failed; absent after a successful round. */
|
|
@@ -384,24 +476,45 @@ export function clientRoundState(
|
|
|
384
476
|
};
|
|
385
477
|
}
|
|
386
478
|
|
|
387
|
-
|
|
388
|
-
|
|
479
|
+
/** One unit of the §4.5 scan set. */
|
|
480
|
+
export interface LiveScanUnit {
|
|
481
|
+
/** The unit's scope map; its first variable (keys sorted) is its index key. */
|
|
482
|
+
readonly scopes: UnitScopes;
|
|
483
|
+
/** Exclusive lower bound: `R`, the unit's cursor `P`, or its pin. */
|
|
484
|
+
readonly afterSeq: number;
|
|
389
485
|
/**
|
|
390
|
-
*
|
|
391
|
-
*
|
|
392
|
-
*
|
|
486
|
+
* The unit's active (unit, table) pairs: covered table → effective scopes
|
|
487
|
+
* (§3.2). A change of table `t` matches iff its stored scopes satisfy the
|
|
488
|
+
* pair for `t` and its commit lies above `afterSeq`.
|
|
393
489
|
*/
|
|
394
|
-
readonly
|
|
395
|
-
|
|
396
|
-
|
|
490
|
+
readonly tables: ReadonlyMap<string, ScopeMap>;
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
export interface LiveWindowQuery {
|
|
494
|
+
readonly units: readonly LiveScanUnit[];
|
|
495
|
+
/** `maxCommitSeq` read at the start of the pull. */
|
|
397
496
|
readonly throughSeq: number;
|
|
398
|
-
/**
|
|
497
|
+
/** The `limitCommits` budget: stop after the commit that reaches it. */
|
|
399
498
|
readonly limitChanges: number;
|
|
400
499
|
}
|
|
401
500
|
|
|
501
|
+
/** The commits of one live section (§4.5). */
|
|
502
|
+
export interface LiveWindow {
|
|
503
|
+
/** Oldest first, each with its matching changes in change order. */
|
|
504
|
+
readonly commits: readonly StoredCommit[];
|
|
505
|
+
/**
|
|
506
|
+
* `T`: `query.throughSeq`, or the last delivered `commitSeq` when the
|
|
507
|
+
* budget cut the section.
|
|
508
|
+
*/
|
|
509
|
+
readonly throughSeq: number;
|
|
510
|
+
}
|
|
511
|
+
|
|
402
512
|
export interface RowScanQuery {
|
|
403
513
|
readonly table: string;
|
|
404
|
-
/**
|
|
514
|
+
/**
|
|
515
|
+
* Effective scopes (§3.2): a row matches iff, for every key, its stored
|
|
516
|
+
* value is in the list. Candidates come from the inverted row-scope index.
|
|
517
|
+
*/
|
|
405
518
|
readonly scopeFilter: ScopeMap;
|
|
406
519
|
/** Resume after this rowId (exclusive); `null` = start of table. */
|
|
407
520
|
readonly afterRowId: string | null;
|
|
@@ -490,6 +603,14 @@ export interface RowListQuery {
|
|
|
490
603
|
readonly limit: number;
|
|
491
604
|
}
|
|
492
605
|
|
|
606
|
+
/** One §6.3.2 watermark row. */
|
|
607
|
+
export interface PushWatermark {
|
|
608
|
+
readonly clientId: string;
|
|
609
|
+
readonly outboxId: string;
|
|
610
|
+
/** `W`: results of this outbox below it are deleted. */
|
|
611
|
+
readonly throughSeq: number;
|
|
612
|
+
}
|
|
613
|
+
|
|
493
614
|
/** A stored push outcome with the client that sent it. */
|
|
494
615
|
export interface ClientPushResult {
|
|
495
616
|
readonly clientId: string;
|
|
@@ -590,17 +711,17 @@ export interface StorageTransaction {
|
|
|
590
711
|
}[],
|
|
591
712
|
): Promise<void>;
|
|
592
713
|
/**
|
|
593
|
-
* §5 delete-precedence tombstone read: the
|
|
594
|
-
*
|
|
595
|
-
*
|
|
596
|
-
*
|
|
597
|
-
*
|
|
714
|
+
* §5 delete-precedence tombstone read: the newest applied delete of this
|
|
715
|
+
* row still within the pruning horizon, or `undefined` when no tombstone
|
|
716
|
+
* exists. Consulted only when an upsert's stored row is absent. Required:
|
|
717
|
+
* in-tree adapters implement it on the transaction's own connection with
|
|
718
|
+
* read-your-own-writes semantics.
|
|
598
719
|
*/
|
|
599
|
-
|
|
720
|
+
getTombstone(table: string, rowId: string): Promise<Tombstone | undefined>;
|
|
600
721
|
/**
|
|
601
|
-
* Remove the row's tombstone because the row
|
|
602
|
-
* transaction
|
|
603
|
-
*
|
|
722
|
+
* Remove the row's tombstone because the row is live again in this
|
|
723
|
+
* transaction: an insert over its tombstone (§6.2) or a §2.2 scope move.
|
|
724
|
+
* A no-op when no tombstone exists.
|
|
604
725
|
*/
|
|
605
726
|
clearTombstone(table: string, rowId: string): Promise<void>;
|
|
606
727
|
/**
|
|
@@ -647,6 +768,13 @@ export interface StorageTransaction {
|
|
|
647
768
|
* are built; a storage with per-statement network cost folds that read-ahead
|
|
648
769
|
* into the admission read and answers the following `getRow` calls from it.
|
|
649
770
|
* Missing support fails closed before an app-row mutation.
|
|
771
|
+
*
|
|
772
|
+
* `outbox`, passed with the first commit of a request that carries an
|
|
773
|
+
* `outboxId`, settles the client's results stored before wire version 4
|
|
774
|
+
* (§9) and runs §6.3.2 steps 1 and 2 under the same lock, before the read
|
|
775
|
+
* of `persisted`. Those writes survive `commitRejectedPushResult`; the
|
|
776
|
+
* caller commits this transaction whatever the commit's outcome, so the
|
|
777
|
+
* settlement runs exactly once per request.
|
|
650
778
|
*/
|
|
651
779
|
preparePushApply(
|
|
652
780
|
clientId: string,
|
|
@@ -656,6 +784,7 @@ export interface StorageTransaction {
|
|
|
656
784
|
readonly table: string;
|
|
657
785
|
readonly rowIds: readonly string[];
|
|
658
786
|
}[],
|
|
787
|
+
outbox?: OutboxSettlement,
|
|
659
788
|
): Promise<PreparedPushApply>;
|
|
660
789
|
/**
|
|
661
790
|
* Rejection finalization while the push-apply serialization lock is still
|
|
@@ -669,6 +798,7 @@ export interface StorageTransaction {
|
|
|
669
798
|
clientId: string,
|
|
670
799
|
clientCommitId: string,
|
|
671
800
|
result: StoredPushResult,
|
|
801
|
+
sequence?: OutboxSequence,
|
|
672
802
|
): Promise<StoredPushResult>;
|
|
673
803
|
upsertRow(
|
|
674
804
|
table: string,
|
|
@@ -686,12 +816,15 @@ export interface StorageTransaction {
|
|
|
686
816
|
enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
|
|
687
817
|
/**
|
|
688
818
|
* Persist an idempotency outcome only when the key is still absent. The
|
|
689
|
-
* first writer wins; callers read the canonical value after commit.
|
|
819
|
+
* first writer wins; callers read the canonical value after commit. A
|
|
820
|
+
* result without `sequence` (no `outboxId`, §6.10, §12.3) is never deleted
|
|
821
|
+
* by a watermark.
|
|
690
822
|
*/
|
|
691
823
|
putPushResult(
|
|
692
824
|
clientId: string,
|
|
693
825
|
clientCommitId: string,
|
|
694
826
|
result: StoredPushResult,
|
|
827
|
+
sequence?: OutboxSequence,
|
|
695
828
|
): Promise<void>;
|
|
696
829
|
/**
|
|
697
830
|
* Advance this partition's checkpoint only while `owner_epoch` still
|
|
@@ -783,7 +916,10 @@ export interface ServerStorage {
|
|
|
783
916
|
authenticatedAtMs: number,
|
|
784
917
|
initialLogEpoch: string,
|
|
785
918
|
): Promise<PartitionRegistryEntry>;
|
|
786
|
-
/**
|
|
919
|
+
/**
|
|
920
|
+
* Rotate log continuity after restore and delete the partition's client
|
|
921
|
+
* records. Watermark rows stay (§6.3.2).
|
|
922
|
+
*/
|
|
787
923
|
rotatePartitionLogEpoch(
|
|
788
924
|
partition: string,
|
|
789
925
|
logEpoch: string,
|
|
@@ -972,26 +1108,29 @@ export interface ServerStorage {
|
|
|
972
1108
|
): Promise<PrunedReactionCounts>;
|
|
973
1109
|
|
|
974
1110
|
/**
|
|
975
|
-
*
|
|
976
|
-
*
|
|
977
|
-
*
|
|
1111
|
+
* The §4.5 live section: every commit in `(min afterSeq, throughSeq]`
|
|
1112
|
+
* carrying a change that matches a unit of the scan set, oldest first,
|
|
1113
|
+
* each with its matching changes once, in change order, across tables.
|
|
1114
|
+
* Stops after the commit whose matching changes reach `limitChanges`
|
|
1115
|
+
* (never splitting a commit). Candidates come from the change-scope key
|
|
1116
|
+
* index, one index range per distinct unit key, never from a log scan.
|
|
978
1117
|
*/
|
|
979
|
-
|
|
1118
|
+
readLiveWindow(
|
|
980
1119
|
partition: string,
|
|
981
|
-
query:
|
|
982
|
-
): Promise<
|
|
1120
|
+
query: LiveWindowQuery,
|
|
1121
|
+
): Promise<LiveWindow>;
|
|
983
1122
|
|
|
984
1123
|
/**
|
|
985
|
-
* Newest commitSeq whose change to `query.table` carries
|
|
986
|
-
*
|
|
987
|
-
* the
|
|
988
|
-
*
|
|
989
|
-
*
|
|
990
|
-
*
|
|
1124
|
+
* Newest commitSeq whose change to `query.table` carries the unit's value
|
|
1125
|
+
* of its first variable (keys sorted): the `readLiveWindow` candidate rule,
|
|
1126
|
+
* so no change the unit would receive for the table sits above it. 0 when
|
|
1127
|
+
* the index holds none (never written, or pruned). The §4.7 sqlite-lane
|
|
1128
|
+
* scope pin reads it; it MUST be one index lookup, independent of the
|
|
1129
|
+
* table's history.
|
|
991
1130
|
*/
|
|
992
1131
|
latestScopedChangeSeq(
|
|
993
1132
|
partition: string,
|
|
994
|
-
query: { readonly table: string; readonly
|
|
1133
|
+
query: { readonly table: string; readonly scopes: UnitScopes },
|
|
995
1134
|
): Promise<number>;
|
|
996
1135
|
|
|
997
1136
|
/** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
|
|
@@ -1036,10 +1175,13 @@ export interface ServerStorage {
|
|
|
1036
1175
|
clientId: string,
|
|
1037
1176
|
): Promise<ClientRecord | undefined>;
|
|
1038
1177
|
/**
|
|
1039
|
-
* Write the record for a completed round.
|
|
1040
|
-
*
|
|
1041
|
-
*
|
|
1042
|
-
*
|
|
1178
|
+
* Write the record for a completed round (§4.5). A record without
|
|
1179
|
+
* `registration` keeps the stored list and digest. The round-state fields
|
|
1180
|
+
* reset: the stored last round is a success at `lastRoundAtMs` (default
|
|
1181
|
+
* `updatedAtMs`) with no failures, unless `keepRoundOutcome` is set, which
|
|
1182
|
+
* leaves the reported code and streak in place (the round carried a
|
|
1183
|
+
* `ROUND_FAILURE` report, §1.5/§4.5). An `unregistered` answer rewrites the
|
|
1184
|
+
* stored record with only `lastRoundAtMs` moved.
|
|
1043
1185
|
*/
|
|
1044
1186
|
putClientRecord(
|
|
1045
1187
|
partition: string,
|
|
@@ -1060,9 +1202,11 @@ export interface ServerStorage {
|
|
|
1060
1202
|
atMs: number,
|
|
1061
1203
|
): Promise<void>;
|
|
1062
1204
|
/**
|
|
1063
|
-
*
|
|
1064
|
-
*
|
|
1065
|
-
*
|
|
1205
|
+
* §8.2 ack: atomically raise an existing record's cursor to `cursor`,
|
|
1206
|
+
* capped at the lowest non-negative cursor of its catching-up units, and
|
|
1207
|
+
* its activity timestamp, both monotonically. Every other field stays;
|
|
1208
|
+
* requires the matching actor and the current log epoch. A missing record
|
|
1209
|
+
* or a mismatched identity is unchanged.
|
|
1066
1210
|
*/
|
|
1067
1211
|
advanceClientCursor(
|
|
1068
1212
|
partition: string,
|
|
@@ -1072,15 +1216,10 @@ export interface ServerStorage {
|
|
|
1072
1216
|
cursor: number,
|
|
1073
1217
|
updatedAtMs: number,
|
|
1074
1218
|
): Promise<void>;
|
|
1075
|
-
/**
|
|
1076
|
-
*
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
clientId: string,
|
|
1080
|
-
cursor: number,
|
|
1081
|
-
updatedAtMs: number,
|
|
1082
|
-
): Promise<void>;
|
|
1083
|
-
/** Minimum cursor with updatedAtMs >= cutoff; null when none are active. */
|
|
1219
|
+
/**
|
|
1220
|
+
* Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
|
|
1221
|
+
* none are active. A bootstrapping client (cursor < 0) holds no cursor.
|
|
1222
|
+
*/
|
|
1084
1223
|
getActiveClientCursorFloor(
|
|
1085
1224
|
partition: string,
|
|
1086
1225
|
cutoffMs: number,
|
|
@@ -1116,9 +1255,11 @@ export interface ServerStorage {
|
|
|
1116
1255
|
* `eraseScopeValueHistory`: under the partition write lock, removes up to
|
|
1117
1256
|
* `limit` upsert change records of `table` at or below `throughSeq` whose
|
|
1118
1257
|
* scopes bind `variable` to `value`, then up to `limit` change scope index
|
|
1119
|
-
* entries of that binding whose commit holds no such change any more
|
|
1258
|
+
* entries of that binding whose commit holds no such change any more,
|
|
1259
|
+
* then strips `serverRow` from up to `limit` stored conflict results of
|
|
1260
|
+
* `table` whose conflict authorization scopes bind `variable` to `value`.
|
|
1120
1261
|
* Delete change records stay: clients behind the erasure still need them.
|
|
1121
|
-
* Returns the number of records removed.
|
|
1262
|
+
* Returns the number of records removed or stripped.
|
|
1122
1263
|
*/
|
|
1123
1264
|
listScopeValueRows?(
|
|
1124
1265
|
partition: string,
|
|
@@ -1136,7 +1277,7 @@ export interface ServerStorage {
|
|
|
1136
1277
|
* calls them.
|
|
1137
1278
|
*
|
|
1138
1279
|
* `listClientRecords`: every stored client record for the partition
|
|
1139
|
-
* (cursor, last-seen,
|
|
1280
|
+
* (cursor, last-seen, registration list): the "who's connected" view.
|
|
1140
1281
|
* `listCommitMetadata`: the commit log without payloads (metadata +
|
|
1141
1282
|
* touched tables), the newest-oriented window an operator inspects.
|
|
1142
1283
|
* `scopeActivity`: the recent commits touching one scope key, via the
|
|
@@ -1151,6 +1292,9 @@ export interface ServerStorage {
|
|
|
1151
1292
|
* `listPushResults`: every stored idempotency outcome for one
|
|
1152
1293
|
* clientCommitId across the partition's clients, scanning the retained
|
|
1153
1294
|
* outcomes without a dedicated index.
|
|
1295
|
+
* `listPushWatermarks`: the §6.3.2 watermark rows of every client whose
|
|
1296
|
+
* retained commit log carries the clientCommitId; a commit whose result
|
|
1297
|
+
* the watermark deleted reads as "expired below sequence `throughSeq`".
|
|
1154
1298
|
* `listPartitions`: the partition-only compatibility view of
|
|
1155
1299
|
* `listPartitionRegistry`, sorted.
|
|
1156
1300
|
*/
|
|
@@ -1177,6 +1321,10 @@ export interface ServerStorage {
|
|
|
1177
1321
|
partition: string,
|
|
1178
1322
|
clientCommitId: string,
|
|
1179
1323
|
): Promise<ClientPushResult[]>;
|
|
1324
|
+
listPushWatermarks?(
|
|
1325
|
+
partition: string,
|
|
1326
|
+
clientCommitId: string,
|
|
1327
|
+
): Promise<PushWatermark[]>;
|
|
1180
1328
|
listPartitions(): Promise<string[]>;
|
|
1181
1329
|
}
|
|
1182
1330
|
|