@syncular/server 0.59.0 → 0.60.1

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.
Files changed (54) hide show
  1. package/README.md +20 -16
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +42 -40
  4. package/dist/context.d.ts +6 -8
  5. package/dist/context.js +1 -3
  6. package/dist/d1-storage.js +42 -24
  7. package/dist/errors.js +8 -0
  8. package/dist/events.d.ts +35 -17
  9. package/dist/frame-bytes.js +24 -6
  10. package/dist/handler.js +486 -223
  11. package/dist/local-authority.js +7 -9
  12. package/dist/operations.d.ts +5 -2
  13. package/dist/operations.js +20 -29
  14. package/dist/postgres-storage.d.ts +24 -19
  15. package/dist/postgres-storage.js +249 -168
  16. package/dist/pull.d.ts +68 -53
  17. package/dist/pull.js +258 -287
  18. package/dist/push.d.ts +12 -3
  19. package/dist/push.js +95 -32
  20. package/dist/realtime.d.ts +17 -11
  21. package/dist/realtime.js +65 -90
  22. package/dist/relational-rows.d.ts +0 -57
  23. package/dist/relational-rows.js +4 -100
  24. package/dist/seed.js +10 -15
  25. package/dist/segment-download.d.ts +4 -1
  26. package/dist/segment-download.js +4 -2
  27. package/dist/sqlite-dialect.d.ts +36 -59
  28. package/dist/sqlite-dialect.js +255 -159
  29. package/dist/sqlite-storage.js +24 -20
  30. package/dist/storage-query.d.ts +30 -1
  31. package/dist/storage-query.js +68 -0
  32. package/dist/storage.d.ts +156 -54
  33. package/dist/storage.js +15 -0
  34. package/package.json +2 -2
  35. package/src/admin.ts +87 -59
  36. package/src/context.ts +7 -11
  37. package/src/d1-storage.ts +49 -33
  38. package/src/errors.ts +8 -0
  39. package/src/events.ts +36 -17
  40. package/src/frame-bytes.ts +26 -6
  41. package/src/handler.ts +628 -286
  42. package/src/local-authority.ts +10 -11
  43. package/src/operations.ts +44 -42
  44. package/src/postgres-storage.ts +336 -226
  45. package/src/pull.ts +394 -414
  46. package/src/push.ts +116 -21
  47. package/src/realtime.ts +85 -129
  48. package/src/relational-rows.ts +4 -107
  49. package/src/seed.ts +13 -19
  50. package/src/segment-download.ts +8 -3
  51. package/src/sqlite-dialect.ts +363 -204
  52. package/src/sqlite-storage.ts +45 -25
  53. package/src/storage-query.ts +102 -0
  54. package/src/storage.ts +185 -58
package/dist/handler.js CHANGED
@@ -9,17 +9,16 @@
9
9
  * A `SyncError` thrown after streaming began becomes an in-band `ERROR`
10
10
  * frame (§1.6).
11
11
  */
12
- import { DecodeError, decodeMessage, } from '@syncular/core';
12
+ import { DecodeError, decodeRequest, echoDigest, registrationDigest, unitId, } from '@syncular/core';
13
13
  import { clockOf, limitsOf, REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
14
14
  import { reportError, SyncError, syncError } from './errors.js';
15
15
  import { emitEvent, } from './events.js';
16
16
  import { END_FRAME_BYTES, encodeResponseFrame, responseEnvelopeHeader, } from './frame-bytes.js';
17
- import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, prepareSections, preparedSection, } from './pull.js';
17
+ import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, bootstrapSegments, clampPullLimits, commitFrame, coveredTables, planBootstrap, planUnit, } from './pull.js';
18
18
  import { processPushCommitWithTrace } from './push.js';
19
19
  import { serveNotReadyError } from './readiness.js';
20
20
  import { compileSchema } from './schema.js';
21
21
  import { schemaWindowOf, projectRowPayload } from './schema-window.js';
22
- import { computeEffective } from './scopes.js';
23
22
  import { StorageQueryError } from './storage-errors.js';
24
23
  import { serveGateRefusal, serveGateTokenChanged, } from './storage.js';
25
24
  function validateResolvedKeys(allowed, schema) {
@@ -27,7 +26,10 @@ function validateResolvedKeys(allowed, schema) {
27
26
  if (!schema.declaredVariables.has(key)) {
28
27
  // §3.2 step 3: a resolver returning undeclared keys is a server
29
28
  // bug — fail the request, do not guess.
30
- throw syncError('sync.invalid_subscription', `resolveScopes returned undeclared scope variable ${JSON.stringify(key)} (§3.2)`);
29
+ throw syncError('sync.invalid_subscription', 'resolveScopes returned an undeclared scope variable (§3.2)', JSON.stringify({
30
+ reason: 'undeclared_resolved_variable',
31
+ variable: key,
32
+ }));
31
33
  }
32
34
  }
33
35
  }
@@ -69,8 +71,8 @@ async function resolveOnce(ctx, clientId, schema) {
69
71
  catch (error) {
70
72
  if (error instanceof SyncError)
71
73
  throw error;
72
- // §3.2 rule 5 / §3.4 step 4: fail loud, never leak — subscriptions
73
- // revoke and writes reject with sync.forbidden. A throw is NOT an
74
+ // §3.2 rule 5 / §3.4 step 4: fail loud, never leak — units revoke and
75
+ // writes reject with sync.forbidden. A throw is NOT an
74
76
  // outage (§7.3.3): it never reaches the lease.
75
77
  const events = ctx.events;
76
78
  if (events !== undefined) {
@@ -107,54 +109,44 @@ async function planRequest(request, ctx, schema, registry) {
107
109
  }
108
110
  const pushes = [];
109
111
  let roundFailure;
110
- let pull;
111
- const subFrames = [];
112
+ let pullHeader;
113
+ const unitFrames = [];
114
+ const progressFrames = [];
112
115
  for (const frame of request.frames) {
113
116
  if (frame.type === 'ROUND_FAILURE')
114
117
  roundFailure = frame;
115
118
  else if (frame.type === 'PUSH_COMMIT')
116
119
  pushes.push(frame);
117
120
  else if (frame.type === 'PULL_HEADER')
118
- pull = frame;
119
- else if (frame.type === 'SUBSCRIPTION')
120
- subFrames.push(frame);
121
+ pullHeader = frame;
122
+ else if (frame.type === 'UNIT')
123
+ unitFrames.push(frame);
124
+ else if (frame.type === 'PROGRESS')
125
+ progressFrames.push(frame);
121
126
  }
122
127
  if (header.logEpoch === undefined && pushes.length > 0) {
123
128
  throw syncError('sync.invalid_request', 'epoch acquisition requests must not carry push commits (§2.1)');
124
129
  }
125
130
  const epochReset = header.logEpoch !== registry.logEpoch;
131
+ const unserved = {
132
+ wireVersion: request.wireVersion,
133
+ logEpoch: registry.logEpoch,
134
+ epochReset,
135
+ header,
136
+ roundFailure,
137
+ pushes: [],
138
+ pull: undefined,
139
+ record: undefined,
140
+ resolved: { ok: false },
141
+ leaseToEmit: undefined,
142
+ };
126
143
  if (header.schemaVersion !== schema.version) {
127
144
  // §2.4: no degraded encoding — answer with the schema floor (§1.6).
128
145
  // No lease is issued on a floor round (§7.3.3).
129
- return {
130
- wireVersion: request.wireVersion,
131
- logEpoch: registry.logEpoch,
132
- epochReset,
133
- header,
134
- roundFailure,
135
- pushes,
136
- pull,
137
- subscriptions: [],
138
- resolved: { ok: false },
139
- schemaFloor: true,
140
- leaseToEmit: undefined,
141
- };
142
- }
143
- if (epochReset) {
144
- return {
145
- wireVersion: request.wireVersion,
146
- logEpoch: registry.logEpoch,
147
- epochReset: true,
148
- header,
149
- roundFailure,
150
- pushes: [],
151
- pull: undefined,
152
- subscriptions: [],
153
- resolved: { ok: false },
154
- schemaFloor: false,
155
- leaseToEmit: undefined,
156
- };
146
+ return { ...unserved, schemaFloor: true };
157
147
  }
148
+ if (epochReset)
149
+ return { ...unserved, schemaFloor: false };
158
150
  if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
159
151
  throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
160
152
  }
@@ -167,70 +159,80 @@ async function planRequest(request, ctx, schema, registry) {
167
159
  const totalOperations = pushes.reduce((n, p) => n + p.operations.length, 0);
168
160
  const limits = limitsOf(ctx);
169
161
  if (totalOperations > limits.maxOperationsPerRequest) {
170
- throw syncError('sync.too_many_operations', `request carries ${totalOperations} operations (cap ${limits.maxOperationsPerRequest}, §6.1)`);
162
+ throw syncError('sync.too_many_operations', 'request carries more operations than the server accepts (§6.1)', JSON.stringify({
163
+ max: limits.maxOperationsPerRequest,
164
+ actual: totalOperations,
165
+ }));
166
+ }
167
+ // §6.1 sequence rules: with an outbox every clientSeq is ≥ 1 and strictly
168
+ // increasing in frame order; without one every clientSeq is 0.
169
+ if (pushes.some((push, i) => header.outboxId === undefined
170
+ ? push.clientSeq !== 0
171
+ : push.clientSeq < 1 ||
172
+ (i > 0 && push.clientSeq <= pushes[i - 1].clientSeq))) {
173
+ throw syncError('sync.invalid_request', 'push commits break the clientSeq rules (§6.1)', JSON.stringify({
174
+ outbox: header.outboxId !== undefined,
175
+ clientSeqs: pushes.map((push) => push.clientSeq),
176
+ }));
171
177
  }
172
- // §1.7: subscription caps, checked before any subscription is planned.
173
- if (subFrames.length > limits.maxSubscriptionsPerRequest) {
174
- throw syncError('sync.limit_exceeded', 'request carries more subscriptions than the server accepts (§1.7)', JSON.stringify({
178
+ // §1.7: the UNIT cap, checked before any unit is planned.
179
+ if (unitFrames.length > limits.maxSubscriptionsPerRequest) {
180
+ throw syncError('sync.limit_exceeded', 'request carries more units than the server accepts (§1.7)', JSON.stringify({
175
181
  limit: 'maxSubscriptionsPerRequest',
176
182
  max: limits.maxSubscriptionsPerRequest,
177
- actual: subFrames.length,
183
+ actual: unitFrames.length,
178
184
  }));
179
185
  }
180
- for (const frame of subFrames) {
181
- let values = 0;
182
- for (const list of Object.values(frame.scopes))
183
- values += list.length;
184
- if (values > limits.maxScopeValuesPerSubscription) {
185
- throw syncError('sync.limit_exceeded', 'subscription requests more scope values than the server accepts (§1.7)', JSON.stringify({
186
- limit: 'maxScopeValuesPerSubscription',
187
- max: limits.maxScopeValuesPerSubscription,
188
- actual: values,
189
- subscriptionId: frame.id,
190
- }));
191
- }
192
- }
193
- if (pull !== undefined) {
194
- // §4.2: rows support is mandatory (bits 0 and 1) — reject its absence
195
- // as request validation (the MAY of §1.7).
196
- if ((pull.accept & (ACCEPT_INLINE_ROWS | ACCEPT_EXTERNAL_ROWS)) === 0) {
186
+ // §4.1: the effective list is the traveling list, or the stored list the
187
+ // digest names; a digest naming neither answers `unregistered`.
188
+ let list;
189
+ let registration;
190
+ if (pullHeader !== undefined) {
191
+ // §4.2: rows support is mandatory (bits 0 and 1).
192
+ if ((pullHeader.accept & (ACCEPT_INLINE_ROWS | ACCEPT_EXTERNAL_ROWS)) ===
193
+ 0) {
197
194
  throw syncError('sync.invalid_request', 'accept must include rows-segment support (bits 0 and 1, §4.2)');
198
195
  }
199
- }
200
- // Request validation for subscriptions (§1.7): duplicate ids, unknown
201
- // tables, undeclared scope keys, requested '*'.
202
- const seenIds = new Set();
203
- const validated = [];
204
- for (const frame of subFrames) {
205
- if (seenIds.has(frame.id)) {
206
- throw syncError('sync.invalid_subscription', `duplicate subscription id ${JSON.stringify(frame.id)} (§4.1)`);
207
- }
208
- seenIds.add(frame.id);
209
- const table = schema.tables.get(frame.table);
210
- if (table === undefined) {
211
- throw syncError('sync.unknown_table', `subscription names unknown table ${JSON.stringify(frame.table)} (§4.3)`);
212
- }
213
- for (const [key, values] of Object.entries(frame.scopes)) {
214
- if (!table.declaredVariables.has(key)) {
215
- throw syncError('sync.invalid_subscription', `requested scope key ${JSON.stringify(key)} is not declared by table ${JSON.stringify(frame.table)} (§3.2)`);
196
+ const traveling = unitFrames.length > 0 ||
197
+ sameBytes(pullHeader.registrationDigest, registrationDigest([]));
198
+ if (traveling) {
199
+ const units = unitFrames.map((frame) => frame.scopes);
200
+ const digest = registrationDigest(units);
201
+ if (!sameBytes(digest, pullHeader.registrationDigest)) {
202
+ throw syncError('sync.invalid_subscription', 'the registration digest differs from the traveling list (§4.1)', JSON.stringify({ reason: 'registration_digest' }));
216
203
  }
217
- if (values.includes('*')) {
218
- throw syncError('sync.invalid_subscription', `requested scope value '*' is reserved for allowed scopes (§3.2)`);
204
+ registration = { units, digest };
205
+ }
206
+ const units = registration?.units ??
207
+ (record?.registration !== undefined &&
208
+ sameBytes(record.registration.digest, pullHeader.registrationDigest)
209
+ ? record.registration.units
210
+ : undefined);
211
+ if (units !== undefined) {
212
+ const ids = new Set();
213
+ list = units.map((scopes) => {
214
+ const tables = coveredTables(schema, scopes);
215
+ const id = unitId(scopes);
216
+ if (ids.has(id)) {
217
+ throw syncError('sync.invalid_subscription', 'the registration list names a scope map twice (§4.1)', JSON.stringify({ reason: 'duplicate_unit', scopes }));
218
+ }
219
+ ids.add(id);
220
+ return { scopes, tables };
221
+ });
222
+ const progressed = new Set();
223
+ for (const frame of progressFrames) {
224
+ if (!ids.has(frame.id) || progressed.has(frame.id)) {
225
+ throw syncError('sync.invalid_subscription', 'a PROGRESS frame names no registered unit or repeats one (§4.1)', JSON.stringify({
226
+ reason: ids.has(frame.id) ? 'duplicate_progress' : 'unknown_unit',
227
+ id: frame.id,
228
+ }));
229
+ }
230
+ progressed.add(frame.id);
219
231
  }
220
232
  }
221
- validated.push({ frame, table: frame.table });
222
233
  }
223
234
  const { resolved, leaseToEmit } = await resolveOnce(ctx, header.clientId, compileSchema(ctx.schema));
224
- const subscriptions = validated.map(({ frame }) => {
225
- const table = schema.tables.get(frame.table);
226
- if (table === undefined)
227
- throw new Error('unreachable: validated table');
228
- const outcome = computeEffective(table.declaredVariables, frame.scopes, resolved);
229
- if (outcome.status === 'active') {
230
- return { frame, table, status: 'active', effective: outcome.effective };
231
- }
232
- return { frame, table, status: 'revoked', effective: {} };
233
- });
235
+ const progress = new Map(progressFrames.map((frame) => [frame.id, frame]));
234
236
  return {
235
237
  wireVersion: request.wireVersion,
236
238
  logEpoch: registry.logEpoch,
@@ -238,13 +240,26 @@ async function planRequest(request, ctx, schema, registry) {
238
240
  header,
239
241
  roundFailure,
240
242
  pushes,
241
- pull,
242
- subscriptions,
243
+ pull: pullHeader === undefined
244
+ ? undefined
245
+ : {
246
+ header: pullHeader,
247
+ limits: clampPullLimits(pullHeader),
248
+ registration,
249
+ units: list?.map(({ scopes, tables }) => {
250
+ const plan = planUnit(scopes, tables, resolved);
251
+ return { plan, progress: progress.get(plan.id) };
252
+ }),
253
+ },
254
+ record,
243
255
  resolved,
244
256
  schemaFloor: false,
245
257
  leaseToEmit,
246
258
  };
247
259
  }
260
+ function sameBytes(a, b) {
261
+ return a.length === b.length && a.every((byte, i) => byte === b[i]);
262
+ }
248
263
  function pushResultDetailsFrame(frame) {
249
264
  const entries = frame.results.flatMap((result) => result.status === 'error' && result.details !== undefined
250
265
  ? [{ opIndex: result.opIndex, details: result.details }]
@@ -359,12 +374,33 @@ async function* streamResponse(plan, ctx, schema, report) {
359
374
  });
360
375
  }
361
376
  }
377
+ const { clientId, outboxId } = plan.header;
362
378
  try {
363
379
  // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
364
380
  const currentSchema = compileSchema(ctx.schema);
365
381
  let acceptedThrough = 0;
366
- for (const push of plan.pushes) {
367
- const processed = await processPushCommitWithTrace(ctx, currentSchema, plan.resolved, plan.header.clientId, push, schema);
382
+ // §6.3.2: the request's first commit settles the outbox and reads `W`.
383
+ let watermark = 0;
384
+ for (const [index, push] of plan.pushes.entries()) {
385
+ const processed = await processPushCommitWithTrace(ctx, currentSchema, plan.resolved, clientId, push, schema, outboxId === undefined
386
+ ? undefined
387
+ : {
388
+ outboxId,
389
+ clientSeq: push.clientSeq,
390
+ watermark,
391
+ ...(index === 0
392
+ ? {
393
+ settlement: {
394
+ outboxId,
395
+ commits: plan.pushes.map((commit) => ({
396
+ clientCommitId: commit.clientCommitId,
397
+ clientSeq: commit.clientSeq,
398
+ })),
399
+ },
400
+ }
401
+ : {}),
402
+ });
403
+ watermark = processed.watermark ?? watermark;
368
404
  acceptedThrough = Math.max(acceptedThrough, processed.frame.commitSeq ?? 0);
369
405
  const frame = {
370
406
  ...processed.frame,
@@ -396,7 +432,7 @@ async function* streamResponse(plan, ctx, schema, report) {
396
432
  }),
397
433
  };
398
434
  if (events !== undefined) {
399
- emitPushEvent(events, ctx, plan.header.clientId, push, processed);
435
+ emitPushEvent(events, ctx, clientId, push, processed);
400
436
  }
401
437
  yield encodeResponseFrame(frame, plan.wireVersion);
402
438
  const details = pushResultDetailsFrame(frame);
@@ -404,139 +440,373 @@ async function* streamResponse(plan, ctx, schema, report) {
404
440
  yield encodeResponseFrame(details, plan.wireVersion);
405
441
  }
406
442
  }
407
- // Pull half (§4): subscriptions echoed in request order.
408
- const cursors = [];
409
- if (plan.pull !== undefined) {
410
- const summaries = events !== undefined ? [] : undefined;
411
- const limits = clampPullLimits(plan.pull);
443
+ const previous = plan.record;
444
+ const base = {
445
+ clientId,
446
+ actorId: ctx.actorId,
447
+ wireVersion: plan.wireVersion,
448
+ schemaVersion: schema.version,
449
+ };
450
+ const pull = plan.pull;
451
+ if (pull === undefined) {
452
+ // A push-only round keeps the registration, its states and the cursor;
453
+ // its record binds the actor (§1.5) and anchors the watermark rows
454
+ // (§6.3.2).
455
+ report.persist = () => ctx.storage.putClientRecord(ctx.partition, {
456
+ ...base,
457
+ cursor: previous?.cursor ?? -1,
458
+ updatedAtMs: clockOf(ctx)(),
459
+ catchingUp: previous?.catchingUp ?? [],
460
+ }, plan.roundFailure !== undefined
461
+ ? { keepRoundOutcome: true }
462
+ : undefined);
463
+ }
464
+ else {
465
+ // Pull half (§4): unit sections in registration order, then one live
466
+ // section.
412
467
  const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
413
468
  if (maxSeq < acceptedThrough)
414
469
  throw syncError('sync.storage_stale_read', 'storage returned a commit sequence older than the accepted push; disable query caching for sync storage', JSON.stringify({ acceptedThrough, storageMaxCommitSeq: maxSeq }));
415
- const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
416
- // A window of sections runs its pre-frame reads together, so a batching
417
- // storage answers them in one statement per table. The window holds at
418
- // most 100,000 first-page or window rows (two maximal §4.2 pages): a
419
- // request's read memory follows the configured limits, never its
420
- // subscription count.
421
- const window = Math.max(1, Math.floor(100_000 /
422
- (Math.max(limits.limitSnapshotRows, limits.limitCommits) + 1)));
423
- for (let start = 0; start < plan.subscriptions.length; start += window) {
424
- const batch = plan.subscriptions.slice(start, start + window);
425
- const prepared = await prepareSections(ctx, schema, limits, batch, maxSeq, horizonSeq, plan.logEpoch);
426
- for (const [index, subscription] of batch.entries()) {
427
- const trace = summaries !== undefined ? { segments: [] } : undefined;
428
- const reads = prepared[index];
429
- if (reads === undefined) {
430
- throw new Error('prepareSections lost a plan');
470
+ const { limits } = pull;
471
+ const units = pull.units;
472
+ if (units === undefined) {
473
+ // §4.1: no unit section, no COMMIT; PROGRESS frames are ignored.
474
+ yield encodeResponseFrame({ type: 'LIVE_START', status: 'unregistered', reasonCode: '' }, plan.wireVersion);
475
+ yield encodeResponseFrame({ type: 'LIVE_END', throughSeq: -1, echoDigest: new Uint8Array() }, plan.wireVersion);
476
+ if (events !== undefined) {
477
+ emitEvent(events, {
478
+ type: 'pull.served',
479
+ atMs: clockOf(ctx)(),
480
+ partition: ctx.partition,
481
+ actorId: ctx.actorId,
482
+ clientId,
483
+ acceptedThrough,
484
+ storageMaxCommitSeq: maxSeq,
485
+ registrationTraveled: false,
486
+ units: [],
487
+ live: {
488
+ status: 'unregistered',
489
+ fromCursor: pull.header.cursor,
490
+ throughSeq: -1,
491
+ commits: 0,
492
+ changes: 0,
493
+ },
494
+ });
495
+ }
496
+ // §4.5: an `unregistered` answer writes only the round outcome; the
497
+ // stored record keeps its cursor, timestamp and states.
498
+ if (previous !== undefined) {
499
+ report.persist = () => ctx.storage.putClientRecord(ctx.partition, {
500
+ clientId,
501
+ actorId: previous.actorId,
502
+ wireVersion: previous.wireVersion,
503
+ cursor: previous.cursor,
504
+ updatedAtMs: previous.updatedAtMs,
505
+ lastRoundAtMs: clockOf(ctx)(),
506
+ ...(previous.schemaVersion !== undefined
507
+ ? { schemaVersion: previous.schemaVersion }
508
+ : {}),
509
+ catchingUp: previous.catchingUp,
510
+ }, plan.roundFailure !== undefined
511
+ ? { keepRoundOutcome: true }
512
+ : undefined);
513
+ }
514
+ }
515
+ else {
516
+ const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
517
+ const R = pull.header.cursor;
518
+ const echo = echoDigest(units.map(({ plan: unit }) => ({
519
+ id: unit.id,
520
+ status: unit.status,
521
+ fenced: unit.fenced,
522
+ })));
523
+ // §4.4 rule 1: every unit gets a section when the list traveled or
524
+ // the client holds another echo.
525
+ const echoSections = pull.registration !== undefined ||
526
+ !sameBytes(pull.header.echoDigest, echo);
527
+ const liveUnits = units.some((unit) => unit.progress === undefined && unit.plan.status === 'active');
528
+ // §4.6 replica reset: a live unit with R outside [horizon, max].
529
+ let liveReset = liveUnits && (R < horizonSeq || R > maxSeq);
530
+ const states = units.map(({ plan: unit, progress }) => {
531
+ if (unit.status === 'revoked')
532
+ return { kind: 'revoked' };
533
+ if (progress === undefined)
534
+ return { kind: 'live' };
535
+ // §4.7: a token, cursor -1 or a cursor from the future bootstraps.
536
+ if (progress.bootstrapState === undefined &&
537
+ progress.cursor >= 0 &&
538
+ progress.cursor <= maxSeq) {
539
+ return progress.cursor < horizonSeq
540
+ ? { kind: 'reset' }
541
+ : { kind: 'post', cursor: progress.cursor };
542
+ }
543
+ // Replaced by the section the bootstrap below produces.
544
+ return { kind: 'bootstrap', pin: -1, frames: [], token: '' };
545
+ });
546
+ const traces = units.map(() => events !== undefined ? { segments: [] } : undefined);
547
+ // Bootstrap sections run before the live read: a bootstrap that
548
+ // completes in this response enters the scan set at its pin (§4.5).
549
+ // A window of units runs its pre-frame reads together, so a
550
+ // batching storage answers them in one statement per table. A unit
551
+ // reads ahead the first page of at most `maxSnapshotPages` tables,
552
+ // and a window holds at most 100,000 first-page rows, so read memory
553
+ // follows the configured limits, never the unit count.
554
+ const bootstrapping = states.flatMap((state, index) => state.kind === 'bootstrap' ? [index] : []);
555
+ const firstPages = Math.max(1, Math.floor(100_000 / (limits.limitSnapshotRows + 1)));
556
+ for (let next = 0; next < bootstrapping.length;) {
557
+ const window = [];
558
+ let pages = 0;
559
+ while (next < bootstrapping.length) {
560
+ const index = bootstrapping[next];
561
+ const reads = Math.min(limits.maxSnapshotPages, units[index].plan.pairs.size);
562
+ if (window.length > 0 && pages + reads > firstPages)
563
+ break;
564
+ window.push(index);
565
+ pages += reads;
566
+ next += 1;
567
+ }
568
+ const batch = window.map((index) => ({
569
+ index,
570
+ plan: planBootstrap(ctx, schema, limits, units[index].plan, units[index].progress?.bootstrapState, maxSeq, horizonSeq, plan.logEpoch),
571
+ }));
572
+ for (const { index, plan: bootstrap } of batch) {
573
+ const frames = [];
574
+ const segments = bootstrapSegments(ctx, schema, limits, bootstrap, traces[index], plan.logEpoch);
575
+ let step = await segments.next();
576
+ while (!step.done) {
577
+ frames.push(step.value);
578
+ step = await segments.next();
579
+ }
580
+ states[index] = {
581
+ kind: 'bootstrap',
582
+ pin: bootstrap.pin,
583
+ frames,
584
+ token: step.value,
585
+ };
431
586
  }
432
- const section = preparedSection(ctx, schema, limits, subscription, maxSeq, reads, trace, plan.logEpoch);
433
- let status = 'active';
434
- let bootstrap = false;
435
- let commits = 0;
436
- let changes = 0;
437
- let effectiveScopes = {};
438
- let firstCommitSeq;
439
- let lastCommitSeq;
440
- let step = await section.next();
441
- while (!step.done) {
442
- const frame = step.value;
443
- if (summaries !== undefined) {
444
- if (frame.type === 'SUB_START') {
445
- status = frame.status;
446
- bootstrap = frame.bootstrap;
447
- effectiveScopes = frame.effectiveScopes;
587
+ }
588
+ const bound = (state) => state.kind === 'live'
589
+ ? R
590
+ : state.kind === 'post'
591
+ ? state.cursor
592
+ : state.kind === 'bootstrap' && state.token === undefined
593
+ ? state.pin
594
+ : undefined;
595
+ // §4.5 order of work: read and buffer the live section, then recheck
596
+ // the horizon. A bound below it leaves the scan set (a live unit's
597
+ // resets the live section), and the section is read again.
598
+ let live;
599
+ for (;;) {
600
+ const scan = units.flatMap(({ plan: unit }, index) => {
601
+ const afterSeq = bound(states[index]);
602
+ return afterSeq === undefined
603
+ ? []
604
+ : [{ scopes: unit.scopes, afterSeq, tables: unit.pairs }];
605
+ });
606
+ if (liveReset || scan.length === 0)
607
+ break;
608
+ live = await ctx.storage.readLiveWindow(ctx.partition, {
609
+ units: scan,
610
+ throughSeq: maxSeq,
611
+ limitChanges: limits.limitCommits,
612
+ });
613
+ const recheck = await ctx.storage.getHorizonSeq(ctx.partition);
614
+ let expired = false;
615
+ for (const [index, state] of states.entries()) {
616
+ const afterSeq = bound(state);
617
+ if (afterSeq === undefined || afterSeq >= recheck)
618
+ continue;
619
+ expired = true;
620
+ if (state.kind === 'live')
621
+ liveReset = true;
622
+ else
623
+ states[index] = { kind: 'reset' };
624
+ }
625
+ if (!expired)
626
+ break;
627
+ live = undefined;
628
+ }
629
+ const T = liveReset ? -1 : (live?.throughSeq ?? maxSeq);
630
+ const summaries = [];
631
+ for (const [index, { plan: unit, progress }] of units.entries()) {
632
+ const state = states[index];
633
+ const requestCursor = progress?.cursor ?? R;
634
+ const section = state.kind === 'revoked' ||
635
+ state.kind === 'reset' ||
636
+ state.kind === 'bootstrap' ||
637
+ echoSections;
638
+ if (section) {
639
+ yield encodeResponseFrame(state.kind === 'revoked'
640
+ ? {
641
+ type: 'SUB_START',
642
+ id: unit.id,
643
+ status: 'revoked',
644
+ reasonCode: 'sync.scope_revoked',
645
+ bootstrap: false,
646
+ fenced: [],
448
647
  }
449
- else if (frame.type === 'COMMIT') {
450
- commits += 1;
451
- changes += frame.changes.length;
452
- firstCommitSeq ??= frame.commitSeq;
453
- lastCommitSeq = frame.commitSeq;
648
+ : state.kind === 'reset'
649
+ ? {
650
+ type: 'SUB_START',
651
+ id: unit.id,
652
+ status: 'reset',
653
+ reasonCode: 'sync.cursor_expired',
654
+ bootstrap: false,
655
+ fenced: [],
656
+ }
657
+ : {
658
+ type: 'SUB_START',
659
+ id: unit.id,
660
+ status: 'active',
661
+ reasonCode: '',
662
+ bootstrap: state.kind === 'bootstrap',
663
+ fenced: [...unit.fenced],
664
+ }, plan.wireVersion);
665
+ if (state.kind === 'bootstrap') {
666
+ for (const frame of state.frames) {
667
+ yield encodeResponseFrame(frame, plan.wireVersion);
454
668
  }
455
669
  }
456
- yield encodeResponseFrame(frame, plan.wireVersion);
457
- step = await section.next();
670
+ yield encodeResponseFrame(state.kind === 'bootstrap'
671
+ ? {
672
+ type: 'SUB_END',
673
+ nextCursor: state.pin,
674
+ ...(state.token !== undefined
675
+ ? { bootstrapState: state.token }
676
+ : {}),
677
+ }
678
+ : { type: 'SUB_END', nextCursor: requestCursor }, plan.wireVersion);
458
679
  }
459
- if (step.value.active)
460
- cursors.push(step.value.nextCursor);
461
- if (summaries !== undefined && trace !== undefined) {
462
- summaries.push({
463
- id: subscription.frame.id,
464
- table: subscription.frame.table,
465
- status,
466
- mode: status !== 'active'
467
- ? 'none'
468
- : bootstrap
469
- ? 'bootstrap'
470
- : 'incremental',
471
- requestedScopes: subscription.frame.scopes,
472
- effectiveScopes,
473
- ...(firstCommitSeq !== undefined && lastCommitSeq !== undefined
474
- ? { firstCommitSeq, lastCommitSeq }
475
- : {}),
476
- fromCursor: subscription.frame.cursor,
477
- nextCursor: step.value.nextCursor,
478
- commits,
680
+ summaries.push({
681
+ id: unit.id,
682
+ scopes: unit.scopes,
683
+ status: state.kind === 'revoked' || state.kind === 'reset'
684
+ ? state.kind
685
+ : 'active',
686
+ mode: state.kind === 'revoked' || state.kind === 'reset'
687
+ ? 'none'
688
+ : state.kind === 'post'
689
+ ? 'catching-up'
690
+ : state.kind,
691
+ section,
692
+ fenced: unit.fenced,
693
+ fromCursor: requestCursor,
694
+ segments: traces[index]?.segments ?? [],
695
+ });
696
+ }
697
+ yield encodeResponseFrame(liveReset
698
+ ? {
699
+ type: 'LIVE_START',
700
+ status: 'reset',
701
+ reasonCode: 'sync.cursor_expired',
702
+ }
703
+ : { type: 'LIVE_START', status: 'active', reasonCode: '' }, plan.wireVersion);
704
+ let changes = 0;
705
+ for (const commit of live?.commits ?? []) {
706
+ changes += commit.changes.length;
707
+ yield encodeResponseFrame(commitFrame(commit, currentSchema, schema), plan.wireVersion);
708
+ }
709
+ yield encodeResponseFrame({ type: 'LIVE_END', throughSeq: T, echoDigest: echo }, plan.wireVersion);
710
+ if (events !== undefined) {
711
+ const commits = live?.commits ?? [];
712
+ emitEvent(events, {
713
+ type: 'pull.served',
714
+ atMs: clockOf(ctx)(),
715
+ partition: ctx.partition,
716
+ actorId: ctx.actorId,
717
+ clientId,
718
+ acceptedThrough,
719
+ storageMaxCommitSeq: maxSeq,
720
+ registrationTraveled: pull.registration !== undefined,
721
+ units: summaries,
722
+ live: {
723
+ status: liveReset ? 'reset' : 'active',
724
+ fromCursor: R,
725
+ throughSeq: T,
726
+ commits: commits.length,
479
727
  changes,
480
- segments: trace.segments,
481
- });
728
+ ...(commits.length > 0
729
+ ? {
730
+ firstCommitSeq: commits[0].commitSeq,
731
+ lastCommitSeq: commits.at(-1).commitSeq,
732
+ }
733
+ : {}),
734
+ },
735
+ });
736
+ }
737
+ // §4.5 join rule J and the record the round writes: the live units,
738
+ // the catching-up ids with their cursors, and the record cursor.
739
+ const joined = Math.max(R, T);
740
+ let anyLive = false;
741
+ const catchingUp = [];
742
+ for (const [index, { plan: unit }] of units.entries()) {
743
+ const state = states[index];
744
+ const catching = (cursor) => {
745
+ catchingUp.push({ id: unit.id, cursor });
746
+ };
747
+ if (state.kind === 'live') {
748
+ if (liveReset)
749
+ catching(-1);
750
+ else
751
+ anyLive = true;
752
+ }
753
+ else if (state.kind === 'revoked' || state.kind === 'reset') {
754
+ catching(-1);
755
+ }
756
+ else if (state.kind === 'bootstrap' && state.token !== undefined) {
757
+ catching(state.pin);
758
+ }
759
+ else {
760
+ // Post-bootstrap, or a bootstrap completed here at its pin.
761
+ const cursor = state.kind === 'post' ? state.cursor : state.pin;
762
+ if (liveReset)
763
+ catching(cursor);
764
+ else if (Math.max(cursor, T) >= joined)
765
+ anyLive = true;
766
+ else
767
+ catching(Math.max(cursor, T));
482
768
  }
483
769
  }
484
- }
485
- if (events !== undefined && summaries !== undefined) {
486
- emitEvent(events, {
487
- type: 'pull.served',
488
- atMs: clockOf(ctx)(),
489
- partition: ctx.partition,
490
- actorId: ctx.actorId,
491
- clientId: plan.header.clientId,
492
- acceptedThrough,
493
- storageMaxCommitSeq: maxSeq,
494
- subscriptions: summaries,
495
- });
770
+ const held = [
771
+ ...(anyLive ? [joined] : []),
772
+ ...catchingUp.map((unit) => unit.cursor).filter((c) => c >= 0),
773
+ ];
774
+ const liveIds = (listed, catching) => JSON.stringify(listed
775
+ .map((scopes) => unitId(scopes))
776
+ .filter((id) => !catching.some((unit) => unit.id === id)));
777
+ const next = {
778
+ ...base,
779
+ cursor: held.length === 0 ? -1 : Math.min(...held),
780
+ updatedAtMs: clockOf(ctx)(),
781
+ ...(pull.registration !== undefined
782
+ ? { registration: pull.registration }
783
+ : {}),
784
+ catchingUp,
785
+ };
786
+ report.persist = async () => {
787
+ await ctx.storage.putClientRecord(ctx.partition, next,
788
+ // §4.5: a round that carried a `ROUND_FAILURE` report completes
789
+ // without clearing the reported code and streak.
790
+ plan.roundFailure !== undefined
791
+ ? { keepRoundOutcome: true }
792
+ : undefined);
793
+ // §8.1: a traveled list or a changed live set re-registers the
794
+ // client's sockets on this hub.
795
+ if (ctx.realtime?.notifySubscriptions !== undefined &&
796
+ (pull.registration !== undefined ||
797
+ liveIds(previous?.registration?.units ?? [], previous?.catchingUp ?? []) !==
798
+ liveIds(units.map(({ plan: unit }) => unit.scopes), catchingUp))) {
799
+ await ctx.realtime.notifySubscriptions(ctx.partition, clientId);
800
+ }
801
+ };
496
802
  }
497
803
  }
498
- // §4.5/§8.1: the cursor watermark and the request's subscription list
499
- // per (partition, clientId), persisted only after the serve gate
500
- // verified the round (§4.5: a failed round leaves the cursor alone).
501
- report.persist = async () => {
502
- const previous = await ctx.storage.getClientRecord(ctx.partition, plan.header.clientId);
503
- const subscriptions = plan.pull !== undefined
504
- ? plan.subscriptions.map((s) => ({
505
- id: s.frame.id,
506
- table: s.frame.table,
507
- scopes: s.frame.scopes,
508
- schemaVersion: schema.version,
509
- }))
510
- : [...(previous?.subscriptions ?? [])];
511
- let cursor = cursors[0] ?? previous?.cursor ?? -1;
512
- for (const next of cursors)
513
- cursor = Math.min(cursor, next);
514
- await ctx.storage.putClientRecord(ctx.partition, {
515
- clientId: plan.header.clientId,
516
- actorId: ctx.actorId,
517
- wireVersion: plan.wireVersion,
518
- cursor,
519
- updatedAtMs: clockOf(ctx)(),
520
- subscriptions,
521
- },
522
- // §4.5: a round that carried a `ROUND_FAILURE` report completes
523
- // without clearing the reported code and streak; the next request
524
- // without the frame clears them as a plain completed round does.
525
- plan.roundFailure !== undefined
526
- ? { keepRoundOutcome: true }
527
- : undefined);
528
- if (ctx.realtime?.notifySubscriptions !== undefined &&
529
- JSON.stringify((previous?.subscriptions ?? []).map((s) => [s.id, s.table, s.scopes])) !==
530
- JSON.stringify(subscriptions.map((s) => [s.id, s.table, s.scopes]))) {
531
- await ctx.realtime.notifySubscriptions(ctx.partition, plan.header.clientId);
532
- }
533
- };
534
804
  }
535
805
  catch (error) {
536
806
  if (error instanceof SyncError) {
537
807
  report.outcome = 'error';
538
808
  report.errorCode = error.code;
539
- await recordRoundFailure(ctx, plan.header.clientId, error);
809
+ await recordRoundFailure(ctx, clientId, error);
540
810
  // §1.6: in-band ERROR, then END, nothing else.
541
811
  yield encodeResponseFrame({
542
812
  type: 'ERROR',
@@ -599,7 +869,7 @@ export async function createSyncResponseStream(bytes, ctx) {
599
869
  errorCode: error instanceof SyncError ? error.code : 'internal',
600
870
  pushCommits: 0,
601
871
  pulled: false,
602
- subscriptions: 0,
872
+ units: 0,
603
873
  });
604
874
  await recordRoundFailure(ctx, clientId, error);
605
875
  throw error;
@@ -608,11 +878,8 @@ export async function createSyncResponseStream(bytes, ctx) {
608
878
  /** The `REQ_HEADER` clientId of a request that failed before planning. */
609
879
  function requestClientId(bytes) {
610
880
  try {
611
- const message = decodeMessage(bytes);
612
- const header = message.frames[0];
613
- return message.msgKind === 'request' && header?.type === 'REQ_HEADER'
614
- ? header.clientId
615
- : undefined;
881
+ const header = decodeRequest(bytes).frames[0];
882
+ return header?.type === 'REQ_HEADER' ? header.clientId : undefined;
616
883
  }
617
884
  catch {
618
885
  return undefined;
@@ -651,11 +918,7 @@ async function* recordedStream(stream, ctx, clientId) {
651
918
  async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
652
919
  let request;
653
920
  try {
654
- const message = decodeMessage(bytes);
655
- if (message.msgKind !== 'request') {
656
- throw syncError('sync.invalid_request', 'expected a request message');
657
- }
658
- request = message;
921
+ request = decodeRequest(bytes);
659
922
  }
660
923
  catch (error) {
661
924
  if (error instanceof DecodeError) {
@@ -752,7 +1015,7 @@ async function* instrumentedStream(stream, ctx, events, plan, report, bytesIn, s
752
1015
  : {}),
753
1016
  pushCommits: plan.pushes.length,
754
1017
  pulled: plan.pull !== undefined,
755
- subscriptions: plan.subscriptions.length,
1018
+ units: plan.pull?.units?.length ?? 0,
756
1019
  });
757
1020
  };
758
1021
  try {