@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/realtime.js CHANGED
@@ -7,8 +7,8 @@
7
7
  * queues the ack's cursor write without awaiting it, so `drain()` is the
8
8
  * awaitable boundary a host uses before closing its storage or ending a
9
9
  * hibernatable event (§8.2). Initial
10
- * subscription registration comes from the client's most recent pull
11
- * (§8.1, loaded from the client record); a sync round completed on the
10
+ * registration comes from the live units of the client record (§8.1); a sync
11
+ * round completed on the
12
12
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
13
13
  * response messages pushed as `0x00`-tagged binary (§8.2/§8.7); sync
14
14
  * rounds ride the same socket as `0x01`-tagged byte-stream chunks driven
@@ -16,28 +16,29 @@
16
16
  * one handler, two framings); the only JSON data-plane server event is
17
17
  * the `sync` wake-up (§8.3).
18
18
  */
19
- import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, isSupportedProtocolWireVersion, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
20
- import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
19
+ import { DecodeError, decodeRequest, encodeResponse, encodePresenceError, encodePresenceFanout, isSupportedProtocolWireVersion, MessageStreamScanner, PROTOCOL_WIRE_VERSION, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, unitId, } from '@syncular/core';
20
+ import { limitsOf, REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
21
21
  import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
22
22
  import { emitEvent } from './events.js';
23
23
  import { composeEvents } from './events-ring.js';
24
24
  import { createSyncResponseStream } from './handler.js';
25
+ import { commitFrame, coveredTables, planUnit } from './pull.js';
25
26
  import { compileSchema, } from './schema.js';
26
- import { schemaWindowOf, projectRowPayload } from './schema-window.js';
27
- import { computeEffective, matchesEffective, } from './scopes.js';
27
+ import { schemaWindowOf } from './schema-window.js';
28
+ import { matchesEffective } from './scopes.js';
28
29
  const DEFAULT_MAX_DELTA_BYTES = 1024 * 1024;
29
- const DEFAULT_MAX_PRESENCE_BYTES = 16 * 1024;
30
+ const DEFAULT_MAX_PRESENCE_BYTES = 8192;
31
+ const DEFAULT_MAX_UNACKED_DELTAS = 256;
32
+ const DEFAULT_MAX_UNACKED_DELTA_BYTES = 4 * 1024 * 1024;
30
33
  /**
31
- * §8.6 presence registry — pure in-memory ephemeral state, keyed per
32
- * `(partition, scopeKey)` → the set of present sessions and their
33
- * documents. It never touches `ServerStorage`; a server restart loses all
34
- * presence (§8.6.1). Fanout is scoped to registered peers only — the
35
- * privacy floor (§8.6.3).
34
+ * §8.6 presence index: per `(partition, scopeKey)`, the sessions holding a
35
+ * document there. The documents live with their session (§8.6.1). Pure
36
+ * in-memory state that never touches `ServerStorage`.
36
37
  */
37
38
  class PresenceRegistry {
38
- /** partition → scopeKey → session → document. */
39
+ /** partition → scopeKey → sessions with a document on the key. */
39
40
  #byKey = new Map();
40
- #keyMap(partition, scopeKey) {
41
+ add(partition, scopeKey, session) {
41
42
  let byScope = this.#byKey.get(partition);
42
43
  if (byScope === undefined) {
43
44
  byScope = new Map();
@@ -45,60 +46,22 @@ class PresenceRegistry {
45
46
  }
46
47
  let sessions = byScope.get(scopeKey);
47
48
  if (sessions === undefined) {
48
- sessions = new Map();
49
+ sessions = new Set();
49
50
  byScope.set(scopeKey, sessions);
50
51
  }
51
- return sessions;
52
+ sessions.add(session);
52
53
  }
53
- /** Current documents on a key, excluding one session (the snapshot,
54
- * §8.6.4). */
55
- snapshot(partition, scopeKey, exclude) {
54
+ delete(partition, scopeKey, session) {
56
55
  const sessions = this.#byKey.get(partition)?.get(scopeKey);
57
56
  if (sessions === undefined)
58
- return [];
59
- const out = [];
60
- for (const [session, doc] of sessions) {
61
- if (session !== exclude)
62
- out.push({ session, doc });
63
- }
64
- return out;
65
- }
66
- /** Store/replace a session's document for a key. Returns whether this is
67
- * the session's FIRST document on the key (join) or a replacement
68
- * (update). */
69
- set(partition, scopeKey, session, doc) {
70
- const sessions = this.#keyMap(partition, scopeKey);
71
- const kind = sessions.has(session) ? 'update' : 'join';
72
- sessions.set(session, doc);
73
- return kind;
74
- }
75
- /** Remove a session's document for a key. Returns true if one existed. */
76
- clear(partition, scopeKey, session) {
77
- const sessions = this.#byKey.get(partition)?.get(scopeKey);
78
- if (sessions === undefined)
79
- return false;
80
- const existed = sessions.delete(session);
57
+ return;
58
+ sessions.delete(session);
81
59
  if (sessions.size === 0)
82
60
  this.#byKey.get(partition)?.delete(scopeKey);
83
- return existed;
84
- }
85
- /** Every key a session currently holds a document on (for leave-on-drop
86
- * and registration-change re-derivation). */
87
- keysOf(partition, session) {
88
- const byScope = this.#byKey.get(partition);
89
- if (byScope === undefined)
90
- return [];
91
- const keys = [];
92
- for (const [scopeKey, sessions] of byScope) {
93
- if (sessions.has(session))
94
- keys.push(scopeKey);
95
- }
96
- return keys;
97
61
  }
98
- /** Sessions currently registered as peers on a key (for fanout). */
62
+ /** Sessions holding a document on a key. */
99
63
  peers(partition, scopeKey) {
100
- const sessions = this.#byKey.get(partition)?.get(scopeKey);
101
- return sessions === undefined ? [] : [...sessions.keys()];
64
+ return [...(this.#byKey.get(partition)?.get(scopeKey) ?? [])];
102
65
  }
103
66
  }
104
67
  /** The scope keys a set of registrations covers (§3.1: `prefix:value`). A
@@ -135,6 +98,11 @@ export class RealtimeSession {
135
98
  lastKnownSeq;
136
99
  /** Replaced at socket-round completion (§8.7); initial set from §8.1. */
137
100
  registrations;
101
+ /** The scope keys `registrations` cover: the presence grant (§8.6.3). */
102
+ scopeKeys;
103
+ /** Sent deltas the client has not acknowledged, in commit order (§8.2). */
104
+ #unacked = [];
105
+ #unackedBytes = 0;
138
106
  /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
139
107
  openedAtMs;
140
108
  #send;
@@ -148,6 +116,8 @@ export class RealtimeSession {
148
116
  * token identifies the owning round so a finished round's cleanup
149
117
  * never clobbers a follow-up round's in-flight marker. */
150
118
  #requestScanner;
119
+ /** Bytes the scanner holds, against `maxRequestBytes` (§1.7). */
120
+ #requestBytes = 0;
151
121
  #activeRound;
152
122
  /** Deltas wait for every round response and registration refresh to finish. */
153
123
  #roundsRefreshing = 0;
@@ -155,6 +125,11 @@ export class RealtimeSession {
155
125
  #deferredBytes = 0;
156
126
  #deferredRegistrations;
157
127
  #closed = false;
128
+ /** §8.6.1: this connection's presence documents by scope key, and their
129
+ * summed charge against `maxPresenceBytes` (§8.6.2). */
130
+ #presence = new Map();
131
+ #presenceBytes = 0;
132
+ #onPresence;
158
133
  /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
159
134
  * document coalesced while over the cap. */
160
135
  #presenceRate = new Map();
@@ -180,9 +155,11 @@ export class RealtimeSession {
180
155
  this.wakePending = cursor < latestSeq;
181
156
  this.#wakeRequiredThroughSeq = cursor < latestSeq ? latestSeq : 0;
182
157
  this.registrations = registrations;
158
+ this.scopeKeys = hub.scopeKeysOf(registrations);
183
159
  this.openedAtMs = clock();
184
160
  this.#send = options.send;
185
161
  this.#closeSocket = options.closeSocket;
162
+ this.#onPresence = options.onPresence;
186
163
  this.#hub = hub;
187
164
  this.#clock = clock;
188
165
  this.#maxDeltaBytes = maxDeltaBytes;
@@ -204,7 +181,7 @@ export class RealtimeSession {
204
181
  // §8.6.2: client→server presence carries `event: 'presence'` (server
205
182
  // control messages carry `event`; the ack carries `type`, §8.1).
206
183
  if (parsed.event === 'presence') {
207
- this.#handlePresence(text);
184
+ this.#handlePresence(parsed.data);
208
185
  return;
209
186
  }
210
187
  if (parsed.type !== 'ack')
@@ -212,6 +189,9 @@ export class RealtimeSession {
212
189
  const cursor = parsed.cursor;
213
190
  if (typeof cursor !== 'number' || !Number.isSafeInteger(cursor))
214
191
  return;
192
+ while ((this.#unacked[0]?.commitSeq ?? Infinity) <= cursor) {
193
+ this.#unackedBytes -= this.#unacked.shift().bytes;
194
+ }
215
195
  this.cursor = Math.max(this.cursor, cursor);
216
196
  // The client may have caught up through another binding (§8.4). Its ack
217
197
  // proves those commits no longer need socket notifications, so the next
@@ -236,22 +216,28 @@ export class RealtimeSession {
236
216
  throw failure;
237
217
  });
238
218
  }
239
- /** §8.6.2 inbound presence publish/leave from the client. */
240
- #handlePresence(text) {
241
- let publish;
242
- try {
243
- publish = parseRealtimePresencePublish(text);
244
- }
245
- catch {
219
+ /**
220
+ * §8.6.2 inbound presence publish/leave from the client: the `data` of the
221
+ * control message `handleMessage` parsed, a non-empty `scopeKey` and a
222
+ * `doc` that is an object or `null`.
223
+ */
224
+ #handlePresence(data) {
225
+ const publish = typeof data === 'object' && data !== null && !Array.isArray(data)
226
+ ? data
227
+ : undefined;
228
+ const scopeKey = publish?.scopeKey;
229
+ const doc = publish?.doc;
230
+ if (typeof scopeKey !== 'string' ||
231
+ scopeKey.length === 0 ||
232
+ (doc !== null && (typeof doc !== 'object' || Array.isArray(doc)))) {
246
233
  // A malformed known event is a parse error (§8.1) — a broken client;
247
234
  // drop the connection loudly rather than silently ignore.
248
235
  this.#violation('malformed presence control message (§8.6.2)');
249
236
  return;
250
237
  }
251
- const { scopeKey, doc } = publish.data;
252
238
  // §8.6.3 authorization: the publish key must be in the connection's
253
239
  // registered effective scopes.
254
- if (!this.#currentScopeKeys().has(scopeKey)) {
240
+ if (!this.scopeKeys.has(scopeKey)) {
255
241
  this.#sendSafe(encodePresenceError(scopeKey, 'presence.forbidden', this.#clock()));
256
242
  return;
257
243
  }
@@ -259,17 +245,34 @@ export class RealtimeSession {
259
245
  this.#leavePresence(scopeKey);
260
246
  return;
261
247
  }
262
- // §8.6.2 size cap: fail loud to the publisher, fan out nothing.
263
- const serialized = JSON.stringify(doc);
264
- if (serialized.length > this.#hub.maxPresenceBytes) {
265
- this.#sendSafe(encodePresenceError(scopeKey, 'presence.too_large', this.#clock()));
266
- return;
248
+ const entry = this.#presenceEntry(scopeKey, doc);
249
+ if (entry !== undefined)
250
+ this.#publishPresence(scopeKey, entry);
251
+ }
252
+ /**
253
+ * §8.6.2 size cap per connection: the key's and document's UTF-8 bytes,
254
+ * added to the connection's documents on its other keys, stay within
255
+ * `maxPresenceBytes`. Over the cap the publisher alone hears
256
+ * `presence.too_large` and nothing changes.
257
+ */
258
+ #presenceEntry(scopeKey, doc) {
259
+ const json = JSON.stringify(doc);
260
+ const budget = this.#hub.maxPresenceBytes -
261
+ this.#presenceBytes +
262
+ (this.#presence.get(scopeKey)?.bytes ?? 0);
263
+ // A string never has fewer UTF-8 bytes than UTF-16 code units, so the
264
+ // unit count rejects first.
265
+ if (scopeKey.length + json.length <= budget) {
266
+ const bytes = new TextEncoder().encode(scopeKey + json).byteLength;
267
+ if (bytes <= budget)
268
+ return { doc, json, bytes };
267
269
  }
268
- this.#publishPresence(scopeKey, doc);
270
+ this.#sendSafe(encodePresenceError(scopeKey, 'presence.too_large', this.#clock()));
271
+ return undefined;
269
272
  }
270
273
  /** §8.6.4: store + fan out a publish, honoring the rate cap (latest-wins
271
274
  * coalesce). */
272
- #publishPresence(scopeKey, doc) {
275
+ #publishPresence(scopeKey, entry) {
273
276
  const minInterval = this.#hub.presenceMinIntervalMs;
274
277
  if (minInterval > 0) {
275
278
  const now = this.#clock();
@@ -277,24 +280,45 @@ export class RealtimeSession {
277
280
  if (rate !== undefined && now - rate.lastFanoutMs < minInterval) {
278
281
  // Over the cap: keep only the latest document, fan it out at the
279
282
  // window edge (never an error, never a stale/lost latest, §8.6.4).
280
- rate.pending = doc;
283
+ rate.pending = entry.doc;
281
284
  if (rate.timer === undefined) {
282
285
  const delay = minInterval - (now - rate.lastFanoutMs);
283
286
  rate.timer = setTimeout(() => {
284
287
  delete rate.timer;
285
288
  const pending = rate.pending;
286
289
  delete rate.pending;
287
- if (pending !== undefined)
288
- this.#fanoutPublish(scopeKey, pending);
290
+ // The connection's other keys may have grown since: the cap
291
+ // holds when the document is stored.
292
+ const latest = pending === undefined
293
+ ? undefined
294
+ : this.#presenceEntry(scopeKey, pending);
295
+ if (latest !== undefined)
296
+ this.#fanoutPublish(scopeKey, latest);
289
297
  }, delay);
290
298
  }
291
299
  return;
292
300
  }
293
301
  }
294
- this.#fanoutPublish(scopeKey, doc);
302
+ this.#fanoutPublish(scopeKey, entry);
295
303
  }
296
- #fanoutPublish(scopeKey, doc) {
297
- const kind = this.#hub.presence.set(this.partition, scopeKey, this, doc);
304
+ #fanoutPublish(scopeKey, entry) {
305
+ // §8.6.1: the peer identity is (actorId, clientId). Another session of
306
+ // this identity (a stale socket of a reconnected client) loses its
307
+ // document silently, so its later close announces nothing.
308
+ let replaced = false;
309
+ for (const peer of this.#hub.presence.peers(this.partition, scopeKey)) {
310
+ if (peer !== this &&
311
+ peer.actorId === this.actorId &&
312
+ peer.clientId === this.clientId) {
313
+ replaced = peer.forgetPresence(scopeKey) || replaced;
314
+ }
315
+ }
316
+ const held = this.#presence.get(scopeKey);
317
+ const kind = replaced || held !== undefined ? 'update' : 'join';
318
+ this.#presenceBytes += entry.bytes - (held?.bytes ?? 0);
319
+ this.#presence.set(scopeKey, entry);
320
+ this.#hub.presence.add(this.partition, scopeKey, this);
321
+ this.#reportPresence();
298
322
  let rate = this.#presenceRate.get(scopeKey);
299
323
  if (rate === undefined) {
300
324
  rate = { lastFanoutMs: this.#clock() };
@@ -303,34 +327,61 @@ export class RealtimeSession {
303
327
  else {
304
328
  rate.lastFanoutMs = this.#clock();
305
329
  }
306
- this.#hub.fanoutPresence(this, scopeKey, kind, doc);
330
+ this.#hub.fanoutPresence(this, scopeKey, kind, entry.doc);
331
+ }
332
+ /** §8.6.1: hand the host this connection's documents after a change. */
333
+ #reportPresence() {
334
+ if (this.#closed || this.#onPresence === undefined)
335
+ return;
336
+ this.#onPresence(new Map([...this.#presence].map(([key, entry]) => [key, entry.json])));
337
+ }
338
+ /** §8.6.1: hold the documents a host kept for this connection across an
339
+ * eviction, without fanout: peers already saw them. */
340
+ seedPresence(presence) {
341
+ for (const [scopeKey, json] of presence) {
342
+ const bytes = new TextEncoder().encode(scopeKey + json).byteLength;
343
+ this.#presence.set(scopeKey, {
344
+ doc: JSON.parse(json),
345
+ json,
346
+ bytes,
347
+ });
348
+ this.#presenceBytes += bytes;
349
+ this.#hub.presence.add(this.partition, scopeKey, this);
350
+ }
307
351
  }
308
352
  /** §8.6.1/§8.6.3: clear this session's document for a key and fan a
309
353
  * leave to the remaining peers. */
310
354
  #leavePresence(scopeKey) {
311
- const existed = this.#hub.presence.clear(this.partition, scopeKey, this);
355
+ if (this.forgetPresence(scopeKey))
356
+ this.#hub.fanoutPresence(this, scopeKey, 'leave', null);
357
+ }
358
+ /** Clear this session's document for a key without fanout, including a
359
+ * coalesced publish still pending. Returns whether a document existed. */
360
+ forgetPresence(scopeKey) {
312
361
  const rate = this.#presenceRate.get(scopeKey);
313
362
  if (rate?.timer !== undefined)
314
363
  clearTimeout(rate.timer);
315
364
  this.#presenceRate.delete(scopeKey);
316
- if (existed)
317
- this.#hub.fanoutPresence(this, scopeKey, 'leave', null);
365
+ const held = this.#presence.get(scopeKey);
366
+ if (held === undefined)
367
+ return false;
368
+ this.#presence.delete(scopeKey);
369
+ this.#presenceBytes -= held.bytes;
370
+ this.#hub.presence.delete(this.partition, scopeKey, this);
371
+ this.#reportPresence();
372
+ return true;
318
373
  }
319
374
  /** Deliver a fanout event to this session (called by the hub for peers,
320
375
  * §8.6.3 receive authorization checked by the caller). */
321
376
  receivePresence(scopeKey, kind, actorId, clientId, doc) {
322
377
  this.#sendSafe(encodePresenceFanout(scopeKey, kind, actorId, clientId, doc, this.#clock()));
323
378
  }
324
- /** The scope keys this connection currently holds (§8.6.3). */
325
- #currentScopeKeys() {
326
- return this.#hub.scopeKeysOf(this.registrations);
327
- }
328
379
  /** §8.6.3: drop presence on keys the connection no longer holds and
329
380
  * deliver the snapshot on keys it newly holds. Called after a
330
381
  * registration change (§8.7 round end, §8.1 reconnect handled by
331
382
  * connect's snapshot). */
332
383
  reconcilePresence(previousKeys) {
333
- const currentKeys = this.#currentScopeKeys();
384
+ const currentKeys = this.scopeKeys;
334
385
  // Keys lost: leave my own published docs; presence delivery stops
335
386
  // naturally (peers no longer fan to me — I am not registered).
336
387
  for (const key of previousKeys) {
@@ -346,8 +397,11 @@ export class RealtimeSession {
346
397
  /** §8.6.4 snapshot: a burst of `join`s for peers already present on a
347
398
  * key, delivered to this session only. */
348
399
  #deliverSnapshot(scopeKey) {
349
- for (const peer of this.#hub.presence.snapshot(this.partition, scopeKey, this)) {
350
- this.receivePresence(scopeKey, 'join', peer.session.actorId, peer.session.clientId, peer.doc);
400
+ for (const peer of this.#hub.presence.peers(this.partition, scopeKey)) {
401
+ const held = peer.#presence.get(scopeKey);
402
+ if (peer === this || held === undefined)
403
+ continue;
404
+ this.receivePresence(scopeKey, 'join', peer.actorId, peer.clientId, held.doc);
351
405
  }
352
406
  }
353
407
  /** §8.6.1: on disconnect, leave every key this session was present on. */
@@ -356,9 +410,8 @@ export class RealtimeSession {
356
410
  this.#deferredDeltas = [];
357
411
  this.#deferredBytes = 0;
358
412
  this.#deferredRegistrations = undefined;
359
- for (const key of this.#hub.presence.keysOf(this.partition, this)) {
413
+ for (const key of [...this.#presence.keys()])
360
414
  this.#leavePresence(key);
361
- }
362
415
  for (const rate of this.#presenceRate.values()) {
363
416
  if (rate.timer !== undefined)
364
417
  clearTimeout(rate.timer);
@@ -368,7 +421,7 @@ export class RealtimeSession {
368
421
  /** Snapshot delivery on connect (§8.6.4) — the newly-registered
369
422
  * connection sees who is already present on each of its keys. */
370
423
  deliverInitialPresence() {
371
- for (const key of this.#currentScopeKeys())
424
+ for (const key of this.scopeKeys)
372
425
  this.#deliverSnapshot(key);
373
426
  }
374
427
  /**
@@ -394,6 +447,17 @@ export class RealtimeSession {
394
447
  return;
395
448
  }
396
449
  const chunk = bytes.subarray(1);
450
+ // §1.7: the assembled request counts against `maxRequestBytes`; past it
451
+ // the stream has no acceptable end, so the connection drops (§8.7).
452
+ this.#requestBytes =
453
+ this.#requestScanner === undefined
454
+ ? chunk.length
455
+ : this.#requestBytes + chunk.length;
456
+ if (this.#requestBytes > this.#hub.limits.maxRequestBytes) {
457
+ this.#requestScanner = undefined;
458
+ this.#violation('request exceeds maxRequestBytes (§1.7)');
459
+ return;
460
+ }
397
461
  this.#requestScanner ??= new MessageStreamScanner();
398
462
  let done;
399
463
  try {
@@ -434,9 +498,8 @@ export class RealtimeSession {
434
498
  try {
435
499
  // §8.7: the round's clientId must match the connection's —
436
500
  // registration identity would otherwise be ambiguous.
437
- const decoded = decodeMessage(requestBytes);
438
- const header = decoded.frames[0];
439
- if (decoded.msgKind !== 'request' || header?.type !== 'REQ_HEADER') {
501
+ const header = decodeRequest(requestBytes).frames[0];
502
+ if (header?.type !== 'REQ_HEADER') {
440
503
  throw syncError('sync.invalid_request', 'expected a request message');
441
504
  }
442
505
  if (header.clientId !== this.clientId) {
@@ -547,8 +610,9 @@ export class RealtimeSession {
547
610
  * failed, because that round applied nothing.
548
611
  */
549
612
  /**
550
- * A pull outside this connection changed the client's subscriptions. A
551
- * round in flight on the connection reloads them at its end anyway.
613
+ * A pull outside this connection changed the client's registration list
614
+ * or live set. A round in flight on the connection reloads it at its end
615
+ * anyway.
552
616
  */
553
617
  async refreshAfterPull() {
554
618
  if (this.#activeRound !== undefined)
@@ -559,7 +623,7 @@ export class RealtimeSession {
559
623
  const generation = ++this.#registrationGeneration;
560
624
  let registrations;
561
625
  try {
562
- registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
626
+ registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId, await this.#storage.getClientRecord(this.partition, this.clientId));
563
627
  }
564
628
  catch {
565
629
  if (!failClosed) {
@@ -577,8 +641,9 @@ export class RealtimeSession {
577
641
  // §8.6.3: a registration change re-derives the presence grant — capture
578
642
  // the keys before, reconcile after (leaves on lost keys, snapshots on
579
643
  // gained keys).
580
- const previousKeys = this.#currentScopeKeys();
644
+ const previousKeys = this.scopeKeys;
581
645
  this.registrations = registrations;
646
+ this.scopeKeys = this.#hub.scopeKeysOf(registrations);
582
647
  this.reconcilePresence(previousKeys);
583
648
  }
584
649
  /** §8.7 protocol violation: drop the connection, fail loud. The
@@ -615,10 +680,7 @@ export class RealtimeSession {
615
680
  }
616
681
  }
617
682
  sendHeartbeat() {
618
- this.#sendSafe(JSON.stringify({
619
- event: 'heartbeat',
620
- data: { timestamp: this.#clock() },
621
- }));
683
+ this.#sendSafe(encodeHeartbeat(this.#clock()));
622
684
  }
623
685
  sendWake(reason) {
624
686
  this.#deferredDeltas = [];
@@ -652,26 +714,10 @@ export class RealtimeSession {
652
714
  deliverCommit(commit) {
653
715
  const contiguous = commit.commitSeq === this.lastKnownSeq + 1;
654
716
  this.lastKnownSeq = Math.max(this.lastKnownSeq, commit.commitSeq);
655
- const sections = [];
656
- for (const registration of this.registrations) {
657
- const changes = commit.changes
658
- .filter((change) => change.table === registration.table &&
659
- matchesEffective(change.scopes, registration.effective))
660
- .map((change) => ({
661
- tableIndex: 0,
662
- rowId: change.rowId,
663
- op: change.op,
664
- ...(change.rowVersion !== undefined
665
- ? { rowVersion: change.rowVersion }
666
- : {}),
667
- scopes: change.scopes,
668
- ...(change.payload !== undefined
669
- ? { row: this.#hub.projectPayload(registration, change.payload) }
670
- : {}),
671
- }));
672
- if (changes.length > 0)
673
- sections.push({ registration, changes });
674
- }
717
+ // §8.2: one COMMIT holding every change that matches a registration of
718
+ // the connection, once each, in change order.
719
+ const changes = commit.changes.filter((change) => this.registrations.some((registration) => change.table === registration.table &&
720
+ matchesEffective(change.scopes, registration.effective)));
675
721
  if (!contiguous) {
676
722
  // Pushes allocate commitSeq under the partition lock but notify after
677
723
  // commit, so racing notifications may arrive out of order. A gap,
@@ -697,7 +743,7 @@ export class RealtimeSession {
697
743
  }
698
744
  this.#deferredRegistrations = registrations;
699
745
  }
700
- if (sections.length === 0)
746
+ if (changes.length === 0)
701
747
  return;
702
748
  if (this.wakePending) {
703
749
  // §8.2: deltas must be cursor-contiguous; while the client is behind
@@ -705,37 +751,19 @@ export class RealtimeSession {
705
751
  this.sendWake('catchup-required');
706
752
  return;
707
753
  }
708
- const frames = [
709
- {
710
- type: 'RESP_HEADER',
711
- ...(this.wireVersion >= 2
712
- ? { logEpoch: this.logEpoch, resetRequired: false }
713
- : {}),
714
- },
715
- ];
716
- for (const section of sections) {
717
- frames.push({
718
- type: 'SUB_START',
719
- id: section.registration.id,
720
- status: 'active',
721
- reasonCode: '',
722
- effectiveScopes: section.registration.effective,
723
- bootstrap: false,
724
- });
725
- frames.push({
726
- type: 'COMMIT',
727
- commitSeq: commit.commitSeq,
728
- createdAtMs: commit.createdAtMs,
729
- actorId: commit.actorId,
730
- tables: [section.registration.table],
731
- changes: section.changes,
732
- });
733
- frames.push({ type: 'SUB_END', nextCursor: commit.commitSeq });
734
- }
735
- const bytes = encodeMessage({
754
+ const bytes = encodeResponse({
736
755
  wireVersion: this.wireVersion,
737
756
  msgKind: 'response',
738
- frames,
757
+ frames: [
758
+ { type: 'RESP_HEADER', logEpoch: this.logEpoch, resetRequired: false },
759
+ { type: 'LIVE_START', status: 'active', reasonCode: '' },
760
+ commitFrame({ ...commit, changes }, this.#hub.schema, this.registrations[0].schema),
761
+ {
762
+ type: 'LIVE_END',
763
+ throughSeq: commit.commitSeq,
764
+ echoDigest: new Uint8Array(),
765
+ },
766
+ ],
739
767
  });
740
768
  if (bytes.length > this.#maxDeltaBytes) {
741
769
  this.sendWake('delta-too-large');
@@ -745,7 +773,7 @@ export class RealtimeSession {
745
773
  const tagged = new Uint8Array(bytes.length + 1);
746
774
  tagged[0] = REALTIME_TAG_DELTA;
747
775
  tagged.set(bytes, 1);
748
- const changeCount = sections.reduce((n, s) => n + s.changes.length, 0);
776
+ const changeCount = changes.length;
749
777
  if (this.#roundsRefreshing > 0) {
750
778
  if (this.#deferredBytes + tagged.length > this.#maxDeltaBytes) {
751
779
  this.sendWake('catchup-required');
@@ -762,6 +790,20 @@ export class RealtimeSession {
762
790
  this.#sendDelta(tagged, commit.commitSeq, changeCount);
763
791
  }
764
792
  #sendDelta(tagged, commitSeq, changes) {
793
+ // A wake earlier in a deferred flush suppresses the rest of it.
794
+ if (this.wakePending)
795
+ return;
796
+ // §8.2 flow control: a client this far behind on acks catches up by pull;
797
+ // its acknowledgement after that round lifts the suppression. One delta
798
+ // always fits, so `maxDeltaBytes` alone bounds a single message.
799
+ if (this.#unacked.length >= this.#hub.maxUnackedDeltas ||
800
+ (this.#unacked.length > 0 &&
801
+ this.#unackedBytes + tagged.length > this.#hub.maxUnackedDeltaBytes)) {
802
+ this.sendWake('catchup-required');
803
+ return;
804
+ }
805
+ this.#unacked.push({ commitSeq, bytes: tagged.length });
806
+ this.#unackedBytes += tagged.length;
765
807
  this.#sendSafe(tagged);
766
808
  this.cursor = Math.max(this.cursor, commitSeq);
767
809
  const events = this.#events;
@@ -786,6 +828,8 @@ export class RealtimeSession {
786
828
  export class RealtimeHub {
787
829
  #config;
788
830
  #schema;
831
+ /** The validated configured limits (§1.7); a bad value throws here. */
832
+ limits;
789
833
  #sessions = new Set();
790
834
  /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
791
835
  presence = new PresenceRegistry();
@@ -793,9 +837,11 @@ export class RealtimeHub {
793
837
  this.#config = config;
794
838
  this.#schema = compileSchema(config.schema);
795
839
  schemaWindowOf(config.schema, config.schemaWindow);
840
+ this.limits = limitsOf(config);
796
841
  }
797
- projectPayload(registration, payload) {
798
- return projectRowPayload(this.#schema.tables.get(registration.table), registration.codec, payload);
842
+ /** The current compiled schema: the storage codec of fanned-out changes. */
843
+ get schema() {
844
+ return this.#schema;
799
845
  }
800
846
  /**
801
847
  * Compose `sink` into the hub's `events`, so socket rounds and sessions
@@ -827,6 +873,14 @@ export class RealtimeHub {
827
873
  get maxPresenceBytes() {
828
874
  return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;
829
875
  }
876
+ /** §8.2 flow control: unacknowledged deltas per session. */
877
+ get maxUnackedDeltas() {
878
+ return this.#config.maxUnackedDeltas ?? DEFAULT_MAX_UNACKED_DELTAS;
879
+ }
880
+ /** §8.2 flow control: unacknowledged delta bytes per session. */
881
+ get maxUnackedDeltaBytes() {
882
+ return this.#config.maxUnackedDeltaBytes ?? DEFAULT_MAX_UNACKED_DELTA_BYTES;
883
+ }
830
884
  /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
831
885
  get presenceMinIntervalMs() {
832
886
  return this.#config.presenceMinIntervalMs ?? 0;
@@ -847,17 +901,16 @@ export class RealtimeHub {
847
901
  if (session.partition !== origin.partition)
848
902
  continue;
849
903
  // Receive authorization (§8.6.3): the receiver must itself hold the key.
850
- if (!this.scopeKeysOf(session.registrations).has(scopeKey))
904
+ if (!session.scopeKeys.has(scopeKey))
851
905
  continue;
852
906
  session.receivePresence(scopeKey, kind, origin.actorId, origin.clientId, doc);
853
907
  }
854
908
  }
855
909
  /**
856
- * Resolve the client record's subscription list into per-connection
910
+ * Resolve the client record's live units into per-connection
857
911
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
858
912
  */
859
- async loadRegistrations(partition, actorId, clientId) {
860
- const record = await this.#config.storage.getClientRecord(partition, clientId);
913
+ async loadRegistrations(partition, actorId, clientId, record) {
861
914
  let resolved;
862
915
  try {
863
916
  const allowed = await this.#config.resolveScopes({
@@ -886,29 +939,35 @@ export class RealtimeHub {
886
939
  }
887
940
  resolved = { ok: false };
888
941
  }
942
+ // §8.1: the stored list minus the catching-up units, each live unit's
943
+ // active pairs under the schema version of the client's latest round.
944
+ const schema = schemaWindowOf(this.#config.schema, this.#config.schemaWindow).find((candidate) => candidate.version === record?.schemaVersion);
889
945
  const registrations = [];
890
- for (const subscription of record?.subscriptions ?? []) {
891
- const window = schemaWindowOf(this.#config.schema, this.#config.schemaWindow);
892
- const selected = subscription.schemaVersion === undefined &&
893
- this.#config.schemaWindow === undefined
894
- ? this.#schema
895
- : window.find((schema) => schema.version === subscription.schemaVersion);
896
- const table = selected?.tables.get(subscription.table);
897
- if (table === undefined)
946
+ if (schema === undefined)
947
+ return registrations;
948
+ for (const scopes of record?.registration?.units ?? []) {
949
+ const id = unitId(scopes);
950
+ if (record?.catchingUp.some((unit) => unit.id === id))
898
951
  continue;
899
- const keysValid = Object.keys(subscription.scopes).every((key) => table.declaredVariables.has(key));
900
- if (!keysValid)
901
- continue;
902
- const outcome = computeEffective(subscription.scopes, resolved);
903
- if (outcome.status !== 'active')
952
+ let tables;
953
+ try {
954
+ tables = coveredTables(schema, scopes);
955
+ }
956
+ catch {
957
+ // A unit the client's schema version no longer serves registers
958
+ // nothing; the client's next pull fails loud on it (§4.1).
904
959
  continue;
905
- registrations.push({
906
- id: subscription.id,
907
- codec: table,
908
- table: subscription.table,
909
- schemaVersion: subscription.schemaVersion ?? this.#config.schema.version,
910
- effective: outcome.effective,
911
- });
960
+ }
961
+ const unit = planUnit(scopes, tables, resolved);
962
+ for (const [table, effective] of unit.pairs) {
963
+ registrations.push({
964
+ schema,
965
+ id: unit.id,
966
+ table,
967
+ schemaVersion: schema.version,
968
+ effective,
969
+ });
970
+ }
912
971
  }
913
972
  return registrations;
914
973
  }
@@ -946,17 +1005,75 @@ export class RealtimeHub {
946
1005
  return this.requestContextFor(session);
947
1006
  }
948
1007
  /**
949
- * Register a connected socket (§8.1): load the client's last pull's
950
- * subscription list, resolve + intersect scopes, send `hello`.
1008
+ * Register a connected socket (§8.1): load the client record's live
1009
+ * units, resolve their effective scopes, send `hello`.
1010
+ */
1011
+ connect(options) {
1012
+ return this.#open(options, undefined);
1013
+ }
1014
+ /**
1015
+ * Rebuild the sessions of sockets that outlived their host's memory, such as
1016
+ * a hibernated Durable Object (§8.1). Each client saw `hello` and the
1017
+ * presence snapshot at its real upgrade, so neither is sent again. The
1018
+ * partition is touched and its latest sequence read once per partition, and
1019
+ * each client record once. The caller holds back commits until this
1020
+ * resolves, so the shared latest sequence stays current.
1021
+ *
1022
+ * `presence` is the connection's last `onPresence` report; the session
1023
+ * holds it again without fanout (§8.6.1). Once every session is back, a
1024
+ * key the reloaded registrations no longer cover leaves, and so does every
1025
+ * key of a socket whose session could not be rebuilt.
951
1026
  */
952
- async connect(options) {
1027
+ async restore(sockets) {
1028
+ const partitions = new Map();
1029
+ const results = [];
1030
+ for (const options of sockets) {
1031
+ try {
1032
+ let shared = partitions.get(options.partition);
1033
+ if (shared === undefined) {
1034
+ const { logEpoch } = await touchAuthenticatedPartition({
1035
+ ...this.#config,
1036
+ partition: options.partition,
1037
+ actorId: options.actorId,
1038
+ });
1039
+ shared = {
1040
+ logEpoch,
1041
+ latestSeq: await this.#config.storage.getMaxCommitSeq(options.partition),
1042
+ };
1043
+ partitions.set(options.partition, shared);
1044
+ }
1045
+ const value = await this.#open(options, shared);
1046
+ if (options.presence !== undefined)
1047
+ value.seedPresence(options.presence);
1048
+ results.push({ status: 'fulfilled', value });
1049
+ }
1050
+ catch (reason) {
1051
+ results.push({ status: 'rejected', reason });
1052
+ }
1053
+ }
1054
+ for (const [i, result] of results.entries()) {
1055
+ const held = [...(sockets[i].presence?.keys() ?? [])];
1056
+ if (result.status === 'fulfilled') {
1057
+ const session = result.value;
1058
+ session.reconcilePresence(new Set([...session.scopeKeys, ...held]));
1059
+ }
1060
+ else {
1061
+ for (const key of held) {
1062
+ this.fanoutPresence(sockets[i], key, 'leave', null);
1063
+ }
1064
+ }
1065
+ }
1066
+ return results;
1067
+ }
1068
+ async #open(options, restored) {
953
1069
  const { storage } = this.#config;
954
1070
  const clock = this.#config.clock ?? Date.now;
955
- const registry = await touchAuthenticatedPartition({
956
- ...this.#config,
957
- partition: options.partition,
958
- actorId: options.actorId,
959
- });
1071
+ const logEpoch = restored?.logEpoch ??
1072
+ (await touchAuthenticatedPartition({
1073
+ ...this.#config,
1074
+ partition: options.partition,
1075
+ actorId: options.actorId,
1076
+ })).logEpoch;
960
1077
  if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
961
1078
  throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
962
1079
  }
@@ -964,34 +1081,35 @@ export class RealtimeHub {
964
1081
  if (record !== undefined && record.actorId !== options.actorId) {
965
1082
  throw syncError('sync.invalid_client_id', 'clientId is bound to a different actor in this partition (§1.5)');
966
1083
  }
967
- const registrations = await this.loadRegistrations(options.partition, options.actorId, options.clientId);
968
- const latestSeq = await storage.getMaxCommitSeq(options.partition);
1084
+ const registrations = await this.loadRegistrations(options.partition, options.actorId, options.clientId, record);
1085
+ const latestSeq = restored?.latestSeq ?? (await storage.getMaxCommitSeq(options.partition));
969
1086
  const cursor = record?.cursor ?? -1;
970
- const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, registry.logEpoch, record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
1087
+ const session = new RealtimeSession(this, options, registrations, cursor, latestSeq, clock, this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES, storage, logEpoch, record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
971
1088
  ? record.wireVersion
972
1089
  : PROTOCOL_WIRE_VERSION, this.#config.events);
973
1090
  this.#sessions.add(session);
974
- const helloResult = options.send(JSON.stringify({
975
- event: 'hello',
976
- data: {
977
- protocolVersion: 1,
978
- sessionId: session.sessionId,
979
- actorId: options.actorId,
980
- clientId: options.clientId,
981
- cursor,
982
- latestCursor: latestSeq,
983
- requiresSync: record === undefined ||
984
- cursor < latestSeq ||
985
- (this.#config.schemaWindow !== undefined &&
986
- record.subscriptions.some((subscription) => !schemaWindowOf(this.#config.schema, this.#config.schemaWindow).some((schema) => schema.version === subscription.schemaVersion))),
987
- timestamp: clock(),
988
- },
989
- }));
990
- if (helloResult instanceof Promise)
991
- helloResult.catch(() => { });
992
- // §8.6.4: the newly-registered connection sees who is already present
993
- // on each key it holds (a burst of joins, after hello).
994
- session.deliverInitialPresence();
1091
+ if (restored === undefined) {
1092
+ const helloResult = options.send(JSON.stringify({
1093
+ event: 'hello',
1094
+ data: {
1095
+ protocolVersion: 1,
1096
+ sessionId: session.sessionId,
1097
+ actorId: options.actorId,
1098
+ clientId: options.clientId,
1099
+ cursor,
1100
+ latestCursor: latestSeq,
1101
+ requiresSync: record?.registration === undefined ||
1102
+ cursor < latestSeq ||
1103
+ !schemaWindowOf(this.#config.schema, this.#config.schemaWindow).some((schema) => schema.version === record.schemaVersion),
1104
+ timestamp: clock(),
1105
+ },
1106
+ }));
1107
+ if (helloResult instanceof Promise)
1108
+ helloResult.catch(() => { });
1109
+ // §8.6.4: the newly-registered connection sees who is already present
1110
+ // on each key it holds (a burst of joins, after hello).
1111
+ session.deliverInitialPresence();
1112
+ }
995
1113
  const events = this.#config.events;
996
1114
  if (events !== undefined) {
997
1115
  emitEvent(events, {
@@ -1038,7 +1156,8 @@ export class RealtimeHub {
1038
1156
  }
1039
1157
  }
1040
1158
  /**
1041
- * RealtimeNotifier: a pull changed a client's subscription list (§8.7).
1159
+ * RealtimeNotifier: a pull changed a client's registration list or live
1160
+ * set (§8.1).
1042
1161
  * Its sockets reload their registrations with the round-end semantics, so
1043
1162
  * an unreadable record keeps the previous registrations.
1044
1163
  */
@@ -1087,6 +1206,22 @@ export class RealtimeHub {
1087
1206
  for (const session of this.#sessions)
1088
1207
  session.sendWake(reason);
1089
1208
  }
1209
+ /**
1210
+ * §8.5: send `heartbeat` to every session. The host calls this on its
1211
+ * heartbeat interval (suggested 30 s); a client that hears nothing for twice
1212
+ * the interval treats the socket as lost.
1213
+ */
1214
+ heartbeat() {
1215
+ for (const session of this.#sessions)
1216
+ session.sendHeartbeat();
1217
+ }
1218
+ }
1219
+ /** The §8.5 `heartbeat` control message. */
1220
+ export function encodeHeartbeat(timestampMs) {
1221
+ return JSON.stringify({
1222
+ event: 'heartbeat',
1223
+ data: { timestamp: timestampMs },
1224
+ });
1090
1225
  }
1091
1226
  export function createRealtimeHub(config) {
1092
1227
  return new RealtimeHub(config);
@@ -1095,13 +1230,14 @@ export function createRealtimeHub(config) {
1095
1230
  * request-level failure becomes a minimal RESP_HEADER/ERROR/END
1096
1231
  * response message delivered as the round's response stream. */
1097
1232
  function errorResponseBytes(error, wireVersion, logEpoch) {
1098
- return encodeMessage({
1233
+ return encodeResponse({
1099
1234
  wireVersion,
1100
1235
  msgKind: 'response',
1101
1236
  frames: [
1102
1237
  {
1103
1238
  type: 'RESP_HEADER',
1104
- ...(wireVersion >= 2 ? { logEpoch, resetRequired: false } : {}),
1239
+ logEpoch,
1240
+ resetRequired: false,
1105
1241
  },
1106
1242
  {
1107
1243
  type: 'ERROR',