@syncular/server 0.59.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 +20 -16
- package/dist/admin.d.ts +32 -20
- package/dist/admin.js +42 -40
- package/dist/context.d.ts +6 -8
- package/dist/context.js +1 -3
- package/dist/d1-storage.js +42 -24
- package/dist/errors.js +8 -0
- package/dist/events.d.ts +35 -17
- package/dist/frame-bytes.js +24 -6
- package/dist/handler.js +486 -223
- package/dist/local-authority.js +7 -9
- package/dist/operations.d.ts +5 -2
- package/dist/operations.js +20 -29
- package/dist/postgres-storage.d.ts +24 -19
- package/dist/postgres-storage.js +249 -168
- package/dist/pull.d.ts +68 -53
- package/dist/pull.js +258 -287
- package/dist/push.d.ts +12 -3
- package/dist/push.js +95 -32
- package/dist/realtime.d.ts +17 -11
- package/dist/realtime.js +65 -90
- package/dist/relational-rows.d.ts +0 -57
- package/dist/relational-rows.js +0 -97
- package/dist/seed.js +10 -15
- package/dist/segment-download.d.ts +4 -1
- package/dist/segment-download.js +4 -2
- package/dist/sqlite-dialect.d.ts +36 -59
- package/dist/sqlite-dialect.js +255 -159
- package/dist/sqlite-storage.js +24 -20
- package/dist/storage-query.d.ts +30 -1
- package/dist/storage-query.js +68 -0
- package/dist/storage.d.ts +156 -54
- package/dist/storage.js +15 -0
- package/package.json +2 -2
- package/src/admin.ts +87 -59
- package/src/context.ts +7 -11
- package/src/d1-storage.ts +49 -33
- package/src/errors.ts +8 -0
- package/src/events.ts +36 -17
- package/src/frame-bytes.ts +26 -6
- package/src/handler.ts +628 -286
- package/src/local-authority.ts +10 -11
- package/src/operations.ts +44 -42
- package/src/postgres-storage.ts +336 -226
- package/src/pull.ts +394 -414
- package/src/push.ts +116 -21
- package/src/realtime.ts +85 -129
- package/src/relational-rows.ts +0 -105
- package/src/seed.ts +13 -19
- package/src/segment-download.ts +8 -3
- package/src/sqlite-dialect.ts +363 -204
- package/src/sqlite-storage.ts +45 -25
- package/src/storage-query.ts +102 -0
- package/src/storage.ts +185 -58
package/src/sqlite-storage.ts
CHANGED
|
@@ -16,7 +16,7 @@ import {
|
|
|
16
16
|
StorageConstraintError,
|
|
17
17
|
StorageQueryError,
|
|
18
18
|
} from './storage-errors';
|
|
19
|
-
import { serveGateRefusal } from './storage';
|
|
19
|
+
import { commitDeleteFloor, serveGateRefusal } from './storage';
|
|
20
20
|
import { serveNotReadyError } from './readiness';
|
|
21
21
|
import {
|
|
22
22
|
assertPhysicalColumns,
|
|
@@ -40,11 +40,12 @@ import {
|
|
|
40
40
|
} from './relational-rows';
|
|
41
41
|
import type { CompiledSchema, CompiledTable } from './schema';
|
|
42
42
|
import {
|
|
43
|
-
SQLITE_ADDED_COLUMNS,
|
|
44
43
|
SQLITE_DDL,
|
|
44
|
+
SQLITE_UPGRADE_PROBE,
|
|
45
45
|
SqliteFamilyStorage,
|
|
46
46
|
SqliteFamilyTransaction,
|
|
47
47
|
type SqliteStatementSpec,
|
|
48
|
+
sqliteUpgradeDdl,
|
|
48
49
|
} from './sqlite-dialect';
|
|
49
50
|
import {
|
|
50
51
|
SqliteAdapterRequiredError,
|
|
@@ -58,6 +59,8 @@ import type {
|
|
|
58
59
|
CheckpointDeclaration,
|
|
59
60
|
IndexRowScanQuery,
|
|
60
61
|
NewCommit,
|
|
62
|
+
OutboxSequence,
|
|
63
|
+
OutboxSettlement,
|
|
61
64
|
PreparedPushApply,
|
|
62
65
|
RowScanQuery,
|
|
63
66
|
ServerStorage,
|
|
@@ -162,22 +165,37 @@ class SqliteTransaction
|
|
|
162
165
|
readonly table: string;
|
|
163
166
|
readonly rowIds: readonly string[];
|
|
164
167
|
}[] = [],
|
|
168
|
+
outbox?: OutboxSettlement,
|
|
165
169
|
): Promise<PreparedPushApply> {
|
|
166
170
|
this.assertOpen();
|
|
167
171
|
// BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
|
|
172
|
+
// The settlement precedes the savepoint, so a rejection keeps it.
|
|
173
|
+
const settled =
|
|
174
|
+
outbox === undefined
|
|
175
|
+
? undefined
|
|
176
|
+
: await this.settleOutbox(clientId, clientCommitId, outbox);
|
|
168
177
|
this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
|
|
169
178
|
this.#pushApplySavepoint = true;
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
179
|
+
const gate = await this.#storage.readServeGate(
|
|
180
|
+
this.partition,
|
|
181
|
+
runningSchemaVersion,
|
|
182
|
+
);
|
|
183
|
+
const [floor] = await this.all<{ delete_floor: number }>(
|
|
184
|
+
'SELECT delete_floor FROM sync_partitions WHERE partition=?',
|
|
185
|
+
[this.partition],
|
|
186
|
+
);
|
|
187
|
+
const deleteFloor = floor?.delete_floor ?? 0;
|
|
188
|
+
return settled === undefined
|
|
189
|
+
? {
|
|
190
|
+
gate,
|
|
191
|
+
deleteFloor,
|
|
192
|
+
persisted: await this.#storage.getPushResult(
|
|
193
|
+
this.partition,
|
|
194
|
+
clientId,
|
|
195
|
+
clientCommitId,
|
|
196
|
+
),
|
|
197
|
+
}
|
|
198
|
+
: { gate, deleteFloor, ...settled };
|
|
181
199
|
}
|
|
182
200
|
|
|
183
201
|
async lockPartition(): Promise<void> {
|
|
@@ -214,6 +232,7 @@ class SqliteTransaction
|
|
|
214
232
|
clientId: string,
|
|
215
233
|
clientCommitId: string,
|
|
216
234
|
result: StoredPushResult,
|
|
235
|
+
sequence?: OutboxSequence,
|
|
217
236
|
): Promise<StoredPushResult> {
|
|
218
237
|
this.assertOpen();
|
|
219
238
|
if (!this.#pushApplySavepoint) {
|
|
@@ -222,7 +241,7 @@ class SqliteTransaction
|
|
|
222
241
|
this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_push_candidate');
|
|
223
242
|
this.#storage.db.exec('RELEASE SAVEPOINT syncular_push_candidate');
|
|
224
243
|
this.#pushApplySavepoint = false;
|
|
225
|
-
await this.putPushResult(clientId, clientCommitId, result);
|
|
244
|
+
await this.putPushResult(clientId, clientCommitId, result, sequence);
|
|
226
245
|
await this.commit();
|
|
227
246
|
// The idempotency re-check found no record under the writer lock, so the
|
|
228
247
|
// insert above is the canonical outcome.
|
|
@@ -255,10 +274,10 @@ class SqliteTransaction
|
|
|
255
274
|
[p],
|
|
256
275
|
);
|
|
257
276
|
const commitSeq = (row?.max_commit_seq ?? 0) + 1;
|
|
258
|
-
this.run(
|
|
259
|
-
|
|
260
|
-
p,
|
|
261
|
-
|
|
277
|
+
this.run(
|
|
278
|
+
'UPDATE sync_partitions SET max_commit_seq=?, delete_floor=max(delete_floor, ?) WHERE partition=?',
|
|
279
|
+
[commitSeq, commitDeleteFloor(commit.changes), p],
|
|
280
|
+
);
|
|
262
281
|
this.run(
|
|
263
282
|
'INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)',
|
|
264
283
|
[
|
|
@@ -347,13 +366,14 @@ export class SqliteServerStorage
|
|
|
347
366
|
super();
|
|
348
367
|
this.db = db;
|
|
349
368
|
this.db.exec(SQLITE_DDL);
|
|
350
|
-
for (const
|
|
351
|
-
|
|
352
|
-
.query<{ name: string }, []>(
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
369
|
+
for (const statement of sqliteUpgradeDdl(
|
|
370
|
+
this.db
|
|
371
|
+
.query<{ tbl: string; name: string }, SqliteValue[]>(
|
|
372
|
+
SQLITE_UPGRADE_PROBE.sql,
|
|
373
|
+
)
|
|
374
|
+
.all(...SQLITE_UPGRADE_PROBE.params),
|
|
375
|
+
)) {
|
|
376
|
+
this.db.exec(statement);
|
|
357
377
|
}
|
|
358
378
|
const commitColumns = this.db
|
|
359
379
|
.query<{ name: string }, []>('PRAGMA table_info("sync_commits")')
|
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,12 @@ export interface NewChange {
|
|
|
179
216
|
readonly table: string;
|
|
180
217
|
readonly rowId: string;
|
|
181
218
|
readonly op: 'upsert' | 'delete';
|
|
182
|
-
/** Present for upsert (§2.2). */
|
|
183
|
-
readonly rowVersion?: number;
|
|
184
219
|
/**
|
|
185
|
-
*
|
|
186
|
-
*
|
|
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.
|
|
187
223
|
*/
|
|
188
|
-
readonly
|
|
224
|
+
readonly rowVersion: number;
|
|
189
225
|
readonly scopes: Record<string, string>;
|
|
190
226
|
/** Present for upsert. */
|
|
191
227
|
readonly payload?: Uint8Array;
|
|
@@ -237,10 +273,29 @@ export function rowsLiveAfterDelete(
|
|
|
237
273
|
return live;
|
|
238
274
|
}
|
|
239
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
|
+
|
|
240
294
|
export interface StoredChange {
|
|
241
295
|
readonly table: string;
|
|
242
296
|
readonly rowId: string;
|
|
243
297
|
readonly op: 'upsert' | 'delete';
|
|
298
|
+
/** Absent only on a delete logged before wire version 4. */
|
|
244
299
|
readonly rowVersion?: number;
|
|
245
300
|
readonly scopes: Record<string, string>;
|
|
246
301
|
readonly payload?: Uint8Array;
|
|
@@ -348,24 +403,45 @@ export interface StoredPushResult {
|
|
|
348
403
|
readonly results: readonly PushOperationResult[];
|
|
349
404
|
}
|
|
350
405
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
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). */
|
|
354
417
|
readonly id: string;
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
readonly scopes: ScopeMap;
|
|
418
|
+
/** `-1`, the bootstrap pin, or the post-bootstrap cursor `P`. */
|
|
419
|
+
readonly cursor: number;
|
|
358
420
|
}
|
|
359
421
|
|
|
422
|
+
/** The §4.5 client record. */
|
|
360
423
|
export interface ClientRecord {
|
|
361
424
|
readonly clientId: string;
|
|
362
425
|
readonly actorId: string;
|
|
363
|
-
/** SSP2 version last accepted from this client
|
|
426
|
+
/** SSP2 version last accepted from this client. */
|
|
364
427
|
readonly wireVersion: number;
|
|
365
|
-
/**
|
|
428
|
+
/** The record cursor (§4.5); feeds the §4.6 retention watermark. */
|
|
366
429
|
readonly cursor: number;
|
|
367
430
|
readonly updatedAtMs: number;
|
|
368
|
-
|
|
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[];
|
|
369
445
|
/** When this client's last sync round finished, successfully or not. */
|
|
370
446
|
readonly lastRoundAtMs?: number;
|
|
371
447
|
/** Code of the last round when it failed; absent after a successful round. */
|
|
@@ -400,24 +476,45 @@ export function clientRoundState(
|
|
|
400
476
|
};
|
|
401
477
|
}
|
|
402
478
|
|
|
403
|
-
|
|
404
|
-
|
|
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;
|
|
405
485
|
/**
|
|
406
|
-
*
|
|
407
|
-
*
|
|
408
|
-
*
|
|
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`.
|
|
409
489
|
*/
|
|
410
|
-
readonly
|
|
411
|
-
|
|
412
|
-
|
|
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. */
|
|
413
496
|
readonly throughSeq: number;
|
|
414
|
-
/**
|
|
497
|
+
/** The `limitCommits` budget: stop after the commit that reaches it. */
|
|
415
498
|
readonly limitChanges: number;
|
|
416
499
|
}
|
|
417
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
|
+
|
|
418
512
|
export interface RowScanQuery {
|
|
419
513
|
readonly table: string;
|
|
420
|
-
/**
|
|
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
|
+
*/
|
|
421
518
|
readonly scopeFilter: ScopeMap;
|
|
422
519
|
/** Resume after this rowId (exclusive); `null` = start of table. */
|
|
423
520
|
readonly afterRowId: string | null;
|
|
@@ -506,6 +603,14 @@ export interface RowListQuery {
|
|
|
506
603
|
readonly limit: number;
|
|
507
604
|
}
|
|
508
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
|
+
|
|
509
614
|
/** A stored push outcome with the client that sent it. */
|
|
510
615
|
export interface ClientPushResult {
|
|
511
616
|
readonly clientId: string;
|
|
@@ -663,6 +768,13 @@ export interface StorageTransaction {
|
|
|
663
768
|
* are built; a storage with per-statement network cost folds that read-ahead
|
|
664
769
|
* into the admission read and answers the following `getRow` calls from it.
|
|
665
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.
|
|
666
778
|
*/
|
|
667
779
|
preparePushApply(
|
|
668
780
|
clientId: string,
|
|
@@ -672,6 +784,7 @@ export interface StorageTransaction {
|
|
|
672
784
|
readonly table: string;
|
|
673
785
|
readonly rowIds: readonly string[];
|
|
674
786
|
}[],
|
|
787
|
+
outbox?: OutboxSettlement,
|
|
675
788
|
): Promise<PreparedPushApply>;
|
|
676
789
|
/**
|
|
677
790
|
* Rejection finalization while the push-apply serialization lock is still
|
|
@@ -685,6 +798,7 @@ export interface StorageTransaction {
|
|
|
685
798
|
clientId: string,
|
|
686
799
|
clientCommitId: string,
|
|
687
800
|
result: StoredPushResult,
|
|
801
|
+
sequence?: OutboxSequence,
|
|
688
802
|
): Promise<StoredPushResult>;
|
|
689
803
|
upsertRow(
|
|
690
804
|
table: string,
|
|
@@ -702,12 +816,15 @@ export interface StorageTransaction {
|
|
|
702
816
|
enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
|
|
703
817
|
/**
|
|
704
818
|
* Persist an idempotency outcome only when the key is still absent. The
|
|
705
|
-
* 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.
|
|
706
822
|
*/
|
|
707
823
|
putPushResult(
|
|
708
824
|
clientId: string,
|
|
709
825
|
clientCommitId: string,
|
|
710
826
|
result: StoredPushResult,
|
|
827
|
+
sequence?: OutboxSequence,
|
|
711
828
|
): Promise<void>;
|
|
712
829
|
/**
|
|
713
830
|
* Advance this partition's checkpoint only while `owner_epoch` still
|
|
@@ -799,7 +916,10 @@ export interface ServerStorage {
|
|
|
799
916
|
authenticatedAtMs: number,
|
|
800
917
|
initialLogEpoch: string,
|
|
801
918
|
): Promise<PartitionRegistryEntry>;
|
|
802
|
-
/**
|
|
919
|
+
/**
|
|
920
|
+
* Rotate log continuity after restore and delete the partition's client
|
|
921
|
+
* records. Watermark rows stay (§6.3.2).
|
|
922
|
+
*/
|
|
803
923
|
rotatePartitionLogEpoch(
|
|
804
924
|
partition: string,
|
|
805
925
|
logEpoch: string,
|
|
@@ -988,26 +1108,29 @@ export interface ServerStorage {
|
|
|
988
1108
|
): Promise<PrunedReactionCounts>;
|
|
989
1109
|
|
|
990
1110
|
/**
|
|
991
|
-
*
|
|
992
|
-
*
|
|
993
|
-
*
|
|
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.
|
|
994
1117
|
*/
|
|
995
|
-
|
|
1118
|
+
readLiveWindow(
|
|
996
1119
|
partition: string,
|
|
997
|
-
query:
|
|
998
|
-
): Promise<
|
|
1120
|
+
query: LiveWindowQuery,
|
|
1121
|
+
): Promise<LiveWindow>;
|
|
999
1122
|
|
|
1000
1123
|
/**
|
|
1001
|
-
* Newest commitSeq whose change to `query.table` carries
|
|
1002
|
-
*
|
|
1003
|
-
* the
|
|
1004
|
-
*
|
|
1005
|
-
*
|
|
1006
|
-
*
|
|
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.
|
|
1007
1130
|
*/
|
|
1008
1131
|
latestScopedChangeSeq(
|
|
1009
1132
|
partition: string,
|
|
1010
|
-
query: { readonly table: string; readonly
|
|
1133
|
+
query: { readonly table: string; readonly scopes: UnitScopes },
|
|
1011
1134
|
): Promise<number>;
|
|
1012
1135
|
|
|
1013
1136
|
/** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
|
|
@@ -1052,10 +1175,13 @@ export interface ServerStorage {
|
|
|
1052
1175
|
clientId: string,
|
|
1053
1176
|
): Promise<ClientRecord | undefined>;
|
|
1054
1177
|
/**
|
|
1055
|
-
* Write the record for a completed round.
|
|
1056
|
-
*
|
|
1057
|
-
*
|
|
1058
|
-
*
|
|
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.
|
|
1059
1185
|
*/
|
|
1060
1186
|
putClientRecord(
|
|
1061
1187
|
partition: string,
|
|
@@ -1076,9 +1202,11 @@ export interface ServerStorage {
|
|
|
1076
1202
|
atMs: number,
|
|
1077
1203
|
): Promise<void>;
|
|
1078
1204
|
/**
|
|
1079
|
-
*
|
|
1080
|
-
*
|
|
1081
|
-
*
|
|
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.
|
|
1082
1210
|
*/
|
|
1083
1211
|
advanceClientCursor(
|
|
1084
1212
|
partition: string,
|
|
@@ -1088,14 +1216,6 @@ export interface ServerStorage {
|
|
|
1088
1216
|
cursor: number,
|
|
1089
1217
|
updatedAtMs: number,
|
|
1090
1218
|
): Promise<void>;
|
|
1091
|
-
/** Advance an existing client's ACK cursor and timestamp atomically,
|
|
1092
|
-
* preserving actor, wire version, and subscriptions. Missing records stay absent. */
|
|
1093
|
-
updateClientCursor(
|
|
1094
|
-
partition: string,
|
|
1095
|
-
clientId: string,
|
|
1096
|
-
cursor: number,
|
|
1097
|
-
updatedAtMs: number,
|
|
1098
|
-
): Promise<void>;
|
|
1099
1219
|
/**
|
|
1100
1220
|
* Minimum non-negative cursor with updatedAtMs >= cutoff (§4.6); null when
|
|
1101
1221
|
* none are active. A bootstrapping client (cursor < 0) holds no cursor.
|
|
@@ -1157,7 +1277,7 @@ export interface ServerStorage {
|
|
|
1157
1277
|
* calls them.
|
|
1158
1278
|
*
|
|
1159
1279
|
* `listClientRecords`: every stored client record for the partition
|
|
1160
|
-
* (cursor, last-seen,
|
|
1280
|
+
* (cursor, last-seen, registration list): the "who's connected" view.
|
|
1161
1281
|
* `listCommitMetadata`: the commit log without payloads (metadata +
|
|
1162
1282
|
* touched tables), the newest-oriented window an operator inspects.
|
|
1163
1283
|
* `scopeActivity`: the recent commits touching one scope key, via the
|
|
@@ -1172,6 +1292,9 @@ export interface ServerStorage {
|
|
|
1172
1292
|
* `listPushResults`: every stored idempotency outcome for one
|
|
1173
1293
|
* clientCommitId across the partition's clients, scanning the retained
|
|
1174
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`".
|
|
1175
1298
|
* `listPartitions`: the partition-only compatibility view of
|
|
1176
1299
|
* `listPartitionRegistry`, sorted.
|
|
1177
1300
|
*/
|
|
@@ -1198,6 +1321,10 @@ export interface ServerStorage {
|
|
|
1198
1321
|
partition: string,
|
|
1199
1322
|
clientCommitId: string,
|
|
1200
1323
|
): Promise<ClientPushResult[]>;
|
|
1324
|
+
listPushWatermarks?(
|
|
1325
|
+
partition: string,
|
|
1326
|
+
clientCommitId: string,
|
|
1327
|
+
): Promise<PushWatermark[]>;
|
|
1201
1328
|
listPartitions(): Promise<string[]>;
|
|
1202
1329
|
}
|
|
1203
1330
|
|