@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.
Files changed (103) hide show
  1. package/README.md +49 -36
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +46 -40
  4. package/dist/blob-handlers.d.ts +25 -31
  5. package/dist/blob-handlers.js +63 -41
  6. package/dist/blob-store.d.ts +42 -24
  7. package/dist/blob-store.js +0 -0
  8. package/dist/bucket-blob-store.d.ts +12 -8
  9. package/dist/bucket-blob-store.js +54 -45
  10. package/dist/bucket-segment-store.js +18 -16
  11. package/dist/content-encoding.d.ts +5 -2
  12. package/dist/content-encoding.js +42 -13
  13. package/dist/context.d.ts +19 -5
  14. package/dist/context.js +19 -1
  15. package/dist/d1-storage.d.ts +14 -98
  16. package/dist/d1-storage.js +249 -1119
  17. package/dist/errors.js +16 -0
  18. package/dist/events.d.ts +36 -18
  19. package/dist/frame-bytes.js +24 -6
  20. package/dist/handler.js +503 -208
  21. package/dist/local-authority.d.ts +2 -0
  22. package/dist/local-authority.js +24 -12
  23. package/dist/object-bucket.d.ts +2 -0
  24. package/dist/operations-realtime.js +69 -50
  25. package/dist/operations.d.ts +5 -2
  26. package/dist/operations.js +20 -29
  27. package/dist/pg-executor-pglite.d.ts +5 -6
  28. package/dist/pg-executor-pglite.js +22 -14
  29. package/dist/pg-executor.d.ts +4 -1
  30. package/dist/postgres-storage.d.ts +24 -19
  31. package/dist/postgres-storage.js +420 -262
  32. package/dist/pull.d.ts +70 -47
  33. package/dist/pull.js +270 -301
  34. package/dist/push.d.ts +12 -3
  35. package/dist/push.js +361 -173
  36. package/dist/realtime.d.ts +85 -39
  37. package/dist/realtime.js +355 -219
  38. package/dist/relational-rows.d.ts +21 -66
  39. package/dist/relational-rows.js +28 -109
  40. package/dist/s3-blob-store.d.ts +11 -12
  41. package/dist/s3-blob-store.js +20 -13
  42. package/dist/s3-object-bucket.d.ts +8 -1
  43. package/dist/s3-object-bucket.js +16 -3
  44. package/dist/schema.d.ts +14 -0
  45. package/dist/schema.js +23 -0
  46. package/dist/scopes.d.ts +6 -2
  47. package/dist/scopes.js +22 -4
  48. package/dist/seed.js +10 -16
  49. package/dist/segment-download.d.ts +4 -1
  50. package/dist/segment-download.js +22 -6
  51. package/dist/signed-url.d.ts +2 -2
  52. package/dist/signed-url.js +9 -2
  53. package/dist/sigv4.d.ts +8 -2
  54. package/dist/sigv4.js +8 -4
  55. package/dist/sqlite-blob-store.d.ts +1 -1
  56. package/dist/sqlite-blob-store.js +23 -22
  57. package/dist/sqlite-dialect.d.ts +164 -84
  58. package/dist/sqlite-dialect.js +1145 -150
  59. package/dist/sqlite-lease-store.js +13 -18
  60. package/dist/sqlite-storage.d.ts +9 -62
  61. package/dist/sqlite-storage.js +303 -1123
  62. package/dist/storage-query.d.ts +30 -1
  63. package/dist/storage-query.js +68 -0
  64. package/dist/storage.d.ts +185 -63
  65. package/dist/storage.js +15 -0
  66. package/package.json +2 -2
  67. package/src/admin.ts +99 -57
  68. package/src/blob-handlers.ts +91 -72
  69. package/src/blob-store.ts +0 -0
  70. package/src/bucket-blob-store.ts +75 -48
  71. package/src/bucket-segment-store.ts +20 -15
  72. package/src/content-encoding.ts +48 -16
  73. package/src/context.ts +33 -6
  74. package/src/d1-storage.ts +350 -1700
  75. package/src/errors.ts +16 -0
  76. package/src/events.ts +37 -18
  77. package/src/frame-bytes.ts +26 -6
  78. package/src/handler.ts +654 -261
  79. package/src/local-authority.ts +27 -14
  80. package/src/object-bucket.ts +2 -0
  81. package/src/operations-realtime.ts +85 -61
  82. package/src/operations.ts +44 -42
  83. package/src/pg-executor-pglite.ts +27 -23
  84. package/src/pg-executor.ts +5 -1
  85. package/src/postgres-storage.ts +557 -354
  86. package/src/pull.ts +406 -440
  87. package/src/push.ts +466 -220
  88. package/src/realtime.ts +447 -290
  89. package/src/relational-rows.ts +43 -121
  90. package/src/s3-blob-store.ts +23 -13
  91. package/src/s3-object-bucket.ts +20 -2
  92. package/src/schema.ts +31 -0
  93. package/src/scopes.ts +23 -3
  94. package/src/seed.ts +13 -20
  95. package/src/segment-download.ts +33 -7
  96. package/src/signed-url.ts +10 -4
  97. package/src/sigv4.ts +17 -4
  98. package/src/sqlite-blob-store.ts +27 -26
  99. package/src/sqlite-dialect.ts +1851 -199
  100. package/src/sqlite-lease-store.ts +12 -23
  101. package/src/sqlite-storage.ts +390 -1821
  102. package/src/storage-query.ts +102 -0
  103. package/src/storage.ts +215 -67
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,56 +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
- if (request.wireVersion >= 2 &&
123
- header.logEpoch === undefined &&
124
- pushes.length > 0) {
127
+ if (header.logEpoch === undefined && pushes.length > 0) {
125
128
  throw syncError('sync.invalid_request', 'epoch acquisition requests must not carry push commits (§2.1)');
126
129
  }
127
- const epochReset = request.wireVersion >= 2 && header.logEpoch !== registry.logEpoch;
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
+ };
128
143
  if (header.schemaVersion !== schema.version) {
129
144
  // §2.4: no degraded encoding — answer with the schema floor (§1.6).
130
145
  // No lease is issued on a floor round (§7.3.3).
131
- return {
132
- wireVersion: request.wireVersion,
133
- logEpoch: registry.logEpoch,
134
- epochReset,
135
- header,
136
- roundFailure,
137
- pushes,
138
- pull,
139
- subscriptions: [],
140
- resolved: { ok: false },
141
- schemaFloor: true,
142
- leaseToEmit: undefined,
143
- };
144
- }
145
- if (epochReset) {
146
- return {
147
- wireVersion: request.wireVersion,
148
- logEpoch: registry.logEpoch,
149
- epochReset: true,
150
- header,
151
- roundFailure,
152
- pushes: [],
153
- pull: undefined,
154
- subscriptions: [],
155
- resolved: { ok: false },
156
- schemaFloor: false,
157
- leaseToEmit: undefined,
158
- };
146
+ return { ...unserved, schemaFloor: true };
159
147
  }
148
+ if (epochReset)
149
+ return { ...unserved, schemaFloor: false };
160
150
  if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
161
151
  throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
162
152
  }
@@ -169,49 +159,80 @@ async function planRequest(request, ctx, schema, registry) {
169
159
  const totalOperations = pushes.reduce((n, p) => n + p.operations.length, 0);
170
160
  const limits = limitsOf(ctx);
171
161
  if (totalOperations > limits.maxOperationsPerRequest) {
172
- 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
+ }));
173
166
  }
174
- if (pull !== undefined) {
175
- // §4.2: rows support is mandatory (bits 0 and 1) — reject its absence
176
- // as request validation (the MAY of §1.7).
177
- if ((pull.accept & (ACCEPT_INLINE_ROWS | ACCEPT_EXTERNAL_ROWS)) === 0) {
178
- throw syncError('sync.invalid_request', 'accept must include rows-segment support (bits 0 and 1, §4.2)');
179
- }
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
+ }));
180
177
  }
181
- // Request validation for subscriptions (§1.7): duplicate ids, unknown
182
- // tables, undeclared scope keys, requested '*'.
183
- const seenIds = new Set();
184
- const validated = [];
185
- for (const frame of subFrames) {
186
- if (seenIds.has(frame.id)) {
187
- throw syncError('sync.invalid_subscription', `duplicate subscription id ${JSON.stringify(frame.id)} (§4.1)`);
188
- }
189
- seenIds.add(frame.id);
190
- const table = schema.tables.get(frame.table);
191
- if (table === undefined) {
192
- throw syncError('sync.unknown_table', `subscription names unknown table ${JSON.stringify(frame.table)} (§4.3)`);
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({
181
+ limit: 'maxSubscriptionsPerRequest',
182
+ max: limits.maxSubscriptionsPerRequest,
183
+ actual: unitFrames.length,
184
+ }));
185
+ }
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) {
194
+ throw syncError('sync.invalid_request', 'accept must include rows-segment support (bits 0 and 1, §4.2)');
193
195
  }
194
- for (const [key, values] of Object.entries(frame.scopes)) {
195
- if (!table.declaredVariables.has(key)) {
196
- 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' }));
197
203
  }
198
- if (values.includes('*')) {
199
- 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);
200
231
  }
201
232
  }
202
- validated.push({ frame, table: frame.table });
203
233
  }
204
234
  const { resolved, leaseToEmit } = await resolveOnce(ctx, header.clientId, compileSchema(ctx.schema));
205
- const subscriptions = validated.map(({ frame }) => {
206
- const table = schema.tables.get(frame.table);
207
- if (table === undefined)
208
- throw new Error('unreachable: validated table');
209
- const outcome = computeEffective(frame.scopes, resolved);
210
- if (outcome.status === 'active') {
211
- return { frame, table, status: 'active', effective: outcome.effective };
212
- }
213
- return { frame, table, status: 'revoked', effective: {} };
214
- });
235
+ const progress = new Map(progressFrames.map((frame) => [frame.id, frame]));
215
236
  return {
216
237
  wireVersion: request.wireVersion,
217
238
  logEpoch: registry.logEpoch,
@@ -219,13 +240,26 @@ async function planRequest(request, ctx, schema, registry) {
219
240
  header,
220
241
  roundFailure,
221
242
  pushes,
222
- pull,
223
- 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,
224
255
  resolved,
225
256
  schemaFloor: false,
226
257
  leaseToEmit,
227
258
  };
228
259
  }
260
+ function sameBytes(a, b) {
261
+ return a.length === b.length && a.every((byte, i) => byte === b[i]);
262
+ }
229
263
  function pushResultDetailsFrame(frame) {
230
264
  const entries = frame.results.flatMap((result) => result.status === 'error' && result.details !== undefined
231
265
  ? [{ opIndex: result.opIndex, details: result.details }]
@@ -298,15 +332,13 @@ async function* streamResponse(plan, ctx, schema, report) {
298
332
  const events = ctx.events;
299
333
  yield responseEnvelopeHeader(plan.wireVersion);
300
334
  if (plan.schemaFloor) {
301
- if (report !== undefined)
302
- report.outcome = 'schema_floor';
335
+ report.outcome = 'schema_floor';
303
336
  yield encodeResponseFrame({
304
337
  type: 'RESP_HEADER',
305
338
  requiredSchemaVersion: schemaWindowOf(ctx.schema, ctx.schemaWindow).at(-1).version,
306
339
  latestSchemaVersion: ctx.schema.version,
307
- ...(plan.wireVersion >= 2
308
- ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
309
- : {}),
340
+ logEpoch: plan.logEpoch,
341
+ resetRequired: plan.epochReset,
310
342
  }, plan.wireVersion);
311
343
  yield END_FRAME_BYTES;
312
344
  return;
@@ -314,15 +346,12 @@ async function* streamResponse(plan, ctx, schema, report) {
314
346
  yield encodeResponseFrame({
315
347
  type: 'RESP_HEADER',
316
348
  latestSchemaVersion: ctx.schema.version,
317
- ...(plan.wireVersion >= 2
318
- ? { logEpoch: plan.logEpoch, resetRequired: plan.epochReset }
319
- : {}),
349
+ logEpoch: plan.logEpoch,
350
+ resetRequired: plan.epochReset,
320
351
  }, plan.wireVersion);
321
352
  if (plan.epochReset) {
322
- if (report !== undefined) {
323
- report.outcome =
324
- plan.header.logEpoch === undefined ? 'epoch_acquired' : 'reset';
325
- }
353
+ report.outcome =
354
+ plan.header.logEpoch === undefined ? 'epoch_acquired' : 'reset';
326
355
  yield END_FRAME_BYTES;
327
356
  return;
328
357
  }
@@ -345,12 +374,33 @@ async function* streamResponse(plan, ctx, schema, report) {
345
374
  });
346
375
  }
347
376
  }
377
+ const { clientId, outboxId } = plan.header;
348
378
  try {
349
379
  // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
350
380
  const currentSchema = compileSchema(ctx.schema);
351
381
  let acceptedThrough = 0;
352
- for (const push of plan.pushes) {
353
- 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;
354
404
  acceptedThrough = Math.max(acceptedThrough, processed.frame.commitSeq ?? 0);
355
405
  const frame = {
356
406
  ...processed.frame,
@@ -382,7 +432,7 @@ async function* streamResponse(plan, ctx, schema, report) {
382
432
  }),
383
433
  };
384
434
  if (events !== undefined) {
385
- emitPushEvent(events, ctx, plan.header.clientId, push, processed);
435
+ emitPushEvent(events, ctx, clientId, push, processed);
386
436
  }
387
437
  yield encodeResponseFrame(frame, plan.wireVersion);
388
438
  const details = pushResultDetailsFrame(frame);
@@ -390,122 +440,373 @@ async function* streamResponse(plan, ctx, schema, report) {
390
440
  yield encodeResponseFrame(details, plan.wireVersion);
391
441
  }
392
442
  }
393
- // Pull half (§4): subscriptions echoed in request order.
394
- const cursors = [];
395
- if (plan.pull !== undefined) {
396
- const summaries = events !== undefined ? [] : undefined;
397
- 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.
398
467
  const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
399
468
  if (maxSeq < acceptedThrough)
400
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 }));
401
- const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
402
- const prepared = await prepareSections(ctx, schema, limits, plan.subscriptions, maxSeq, horizonSeq, plan.logEpoch);
403
- for (const [index, subscription] of plan.subscriptions.entries()) {
404
- const trace = summaries !== undefined ? { segments: [] } : undefined;
405
- const reads = prepared[index];
406
- if (reads === undefined)
407
- throw new Error('prepareSections lost a plan');
408
- const section = preparedSection(ctx, schema, limits, subscription, maxSeq, reads, trace, plan.logEpoch);
409
- let status = 'active';
410
- let bootstrap = false;
411
- let commits = 0;
412
- let changes = 0;
413
- let effectiveScopes = {};
414
- let firstCommitSeq;
415
- let lastCommitSeq;
416
- let step = await section.next();
417
- while (!step.done) {
418
- const frame = step.value;
419
- if (summaries !== undefined) {
420
- if (frame.type === 'SUB_START') {
421
- status = frame.status;
422
- bootstrap = frame.bootstrap;
423
- effectiveScopes = frame.effectiveScopes;
424
- }
425
- else if (frame.type === 'COMMIT') {
426
- commits += 1;
427
- changes += frame.changes.length;
428
- firstCommitSeq ??= frame.commitSeq;
429
- lastCommitSeq = frame.commitSeq;
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();
430
579
  }
580
+ states[index] = {
581
+ kind: 'bootstrap',
582
+ pin: bootstrap.pin,
583
+ frames,
584
+ token: step.value,
585
+ };
431
586
  }
432
- yield encodeResponseFrame(frame, plan.wireVersion);
433
- step = await section.next();
434
587
  }
435
- if (step.value.active)
436
- cursors.push(step.value.nextCursor);
437
- if (summaries !== undefined && trace !== undefined) {
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: [],
647
+ }
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);
668
+ }
669
+ }
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);
679
+ }
438
680
  summaries.push({
439
- id: subscription.frame.id,
440
- table: subscription.frame.table,
441
- status,
442
- mode: status !== 'active'
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'
443
687
  ? 'none'
444
- : bootstrap
445
- ? 'bootstrap'
446
- : 'incremental',
447
- requestedScopes: subscription.frame.scopes,
448
- effectiveScopes,
449
- ...(firstCommitSeq !== undefined && lastCommitSeq !== undefined
450
- ? { firstCommitSeq, lastCommitSeq }
451
- : {}),
452
- fromCursor: subscription.frame.cursor,
453
- nextCursor: step.value.nextCursor,
454
- commits,
455
- changes,
456
- segments: trace.segments,
688
+ : state.kind === 'post'
689
+ ? 'catching-up'
690
+ : state.kind,
691
+ section,
692
+ fenced: unit.fenced,
693
+ fromCursor: requestCursor,
694
+ segments: traces[index]?.segments ?? [],
457
695
  });
458
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,
727
+ changes,
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));
768
+ }
769
+ }
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
+ };
459
802
  }
460
- if (events !== undefined && summaries !== undefined) {
461
- emitEvent(events, {
462
- type: 'pull.served',
463
- atMs: clockOf(ctx)(),
464
- partition: ctx.partition,
465
- actorId: ctx.actorId,
466
- clientId: plan.header.clientId,
467
- acceptedThrough,
468
- storageMaxCommitSeq: maxSeq,
469
- subscriptions: summaries,
470
- });
471
- }
472
- }
473
- // §4.5/§8.1: persist the cursor watermark and the request's
474
- // subscription list per (partition, clientId).
475
- const previous = await ctx.storage.getClientRecord(ctx.partition, plan.header.clientId);
476
- const subscriptions = plan.pull !== undefined
477
- ? plan.subscriptions.map((s) => ({
478
- id: s.frame.id,
479
- table: s.frame.table,
480
- scopes: s.frame.scopes,
481
- schemaVersion: schema.version,
482
- }))
483
- : [...(previous?.subscriptions ?? [])];
484
- const cursor = cursors.length > 0 ? Math.min(...cursors) : (previous?.cursor ?? -1);
485
- await ctx.storage.putClientRecord(ctx.partition, {
486
- clientId: plan.header.clientId,
487
- actorId: ctx.actorId,
488
- wireVersion: plan.wireVersion,
489
- cursor,
490
- updatedAtMs: clockOf(ctx)(),
491
- subscriptions,
492
- },
493
- // §4.5: a round that carried a `ROUND_FAILURE` report completes without
494
- // clearing the reported code and streak; the next request without the
495
- // frame clears them as a plain completed round does.
496
- plan.roundFailure !== undefined ? { keepRoundOutcome: true } : undefined);
497
- if (ctx.realtime?.notifySubscriptions !== undefined &&
498
- JSON.stringify((previous?.subscriptions ?? []).map((s) => [s.id, s.table, s.scopes])) !== JSON.stringify(subscriptions.map((s) => [s.id, s.table, s.scopes]))) {
499
- await ctx.realtime.notifySubscriptions(ctx.partition, plan.header.clientId);
500
803
  }
501
804
  }
502
805
  catch (error) {
503
806
  if (error instanceof SyncError) {
504
- if (report !== undefined) {
505
- report.outcome = 'error';
506
- report.errorCode = error.code;
507
- }
508
- await recordRoundFailure(ctx, plan.header.clientId, error);
807
+ report.outcome = 'error';
808
+ report.errorCode = error.code;
809
+ await recordRoundFailure(ctx, clientId, error);
509
810
  // §1.6: in-band ERROR, then END, nothing else.
510
811
  yield encodeResponseFrame({
511
812
  type: 'ERROR',
@@ -568,7 +869,7 @@ export async function createSyncResponseStream(bytes, ctx) {
568
869
  errorCode: error instanceof SyncError ? error.code : 'internal',
569
870
  pushCommits: 0,
570
871
  pulled: false,
571
- subscriptions: 0,
872
+ units: 0,
572
873
  });
573
874
  await recordRoundFailure(ctx, clientId, error);
574
875
  throw error;
@@ -577,11 +878,8 @@ export async function createSyncResponseStream(bytes, ctx) {
577
878
  /** The `REQ_HEADER` clientId of a request that failed before planning. */
578
879
  function requestClientId(bytes) {
579
880
  try {
580
- const message = decodeMessage(bytes);
581
- const header = message.frames[0];
582
- return message.msgKind === 'request' && header?.type === 'REQ_HEADER'
583
- ? header.clientId
584
- : undefined;
881
+ const header = decodeRequest(bytes).frames[0];
882
+ return header?.type === 'REQ_HEADER' ? header.clientId : undefined;
585
883
  }
586
884
  catch {
587
885
  return undefined;
@@ -620,11 +918,7 @@ async function* recordedStream(stream, ctx, clientId) {
620
918
  async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
621
919
  let request;
622
920
  try {
623
- const message = decodeMessage(bytes);
624
- if (message.msgKind !== 'request') {
625
- throw syncError('sync.invalid_request', 'expected a request message');
626
- }
627
- request = message;
921
+ request = decodeRequest(bytes);
628
922
  }
629
923
  catch (error) {
630
924
  if (error instanceof DecodeError) {
@@ -690,6 +984,7 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
690
984
  throw serveNotReadyError(afterRefusal);
691
985
  if (changed !== undefined)
692
986
  throw serveNotReadyError(changed);
987
+ await report.persist?.();
693
988
  for (const chunk of buffered)
694
989
  yield chunk;
695
990
  };
@@ -720,7 +1015,7 @@ async function* instrumentedStream(stream, ctx, events, plan, report, bytesIn, s
720
1015
  : {}),
721
1016
  pushCommits: plan.pushes.length,
722
1017
  pulled: plan.pull !== undefined,
723
- subscriptions: plan.subscriptions.length,
1018
+ units: plan.pull?.units?.length ?? 0,
724
1019
  });
725
1020
  };
726
1021
  try {