@syncular/server 0.57.0 → 0.59.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 (91) hide show
  1. package/README.md +31 -22
  2. package/dist/admin.js +8 -4
  3. package/dist/blob-handlers.d.ts +25 -31
  4. package/dist/blob-handlers.js +63 -41
  5. package/dist/blob-store.d.ts +42 -24
  6. package/dist/blob-store.js +0 -0
  7. package/dist/bucket-blob-store.d.ts +12 -8
  8. package/dist/bucket-blob-store.js +54 -45
  9. package/dist/bucket-segment-store.js +18 -16
  10. package/dist/content-encoding.d.ts +5 -2
  11. package/dist/content-encoding.js +42 -13
  12. package/dist/context.d.ts +16 -0
  13. package/dist/context.js +21 -1
  14. package/dist/d1-storage.d.ts +14 -98
  15. package/dist/d1-storage.js +223 -1111
  16. package/dist/errors.js +8 -0
  17. package/dist/events.d.ts +1 -1
  18. package/dist/handler.js +135 -103
  19. package/dist/local-authority.d.ts +2 -0
  20. package/dist/local-authority.js +17 -3
  21. package/dist/object-bucket.d.ts +2 -0
  22. package/dist/operations-realtime.js +69 -50
  23. package/dist/pg-executor-pglite.d.ts +5 -6
  24. package/dist/pg-executor-pglite.js +22 -14
  25. package/dist/pg-executor.d.ts +4 -1
  26. package/dist/postgres-storage.d.ts +1 -1
  27. package/dist/postgres-storage.js +182 -105
  28. package/dist/pull.d.ts +28 -20
  29. package/dist/pull.js +85 -87
  30. package/dist/push.js +272 -147
  31. package/dist/realtime.d.ts +68 -28
  32. package/dist/realtime.js +297 -136
  33. package/dist/relational-rows.d.ts +27 -15
  34. package/dist/relational-rows.js +38 -22
  35. package/dist/s3-blob-store.d.ts +11 -12
  36. package/dist/s3-blob-store.js +20 -13
  37. package/dist/s3-object-bucket.d.ts +8 -1
  38. package/dist/s3-object-bucket.js +16 -3
  39. package/dist/schema.d.ts +14 -0
  40. package/dist/schema.js +23 -0
  41. package/dist/scopes.d.ts +6 -2
  42. package/dist/scopes.js +22 -4
  43. package/dist/seed.js +1 -2
  44. package/dist/segment-download.js +18 -4
  45. package/dist/signed-url.d.ts +2 -2
  46. package/dist/signed-url.js +9 -2
  47. package/dist/sigv4.d.ts +8 -2
  48. package/dist/sigv4.js +8 -4
  49. package/dist/sqlite-blob-store.d.ts +1 -1
  50. package/dist/sqlite-blob-store.js +23 -22
  51. package/dist/sqlite-dialect.d.ts +150 -47
  52. package/dist/sqlite-dialect.js +987 -88
  53. package/dist/sqlite-lease-store.js +13 -18
  54. package/dist/sqlite-storage.d.ts +9 -62
  55. package/dist/sqlite-storage.js +293 -1117
  56. package/dist/storage.d.ts +32 -12
  57. package/package.json +2 -2
  58. package/src/admin.ts +16 -2
  59. package/src/blob-handlers.ts +91 -72
  60. package/src/blob-store.ts +0 -0
  61. package/src/bucket-blob-store.ts +75 -48
  62. package/src/bucket-segment-store.ts +20 -15
  63. package/src/content-encoding.ts +48 -16
  64. package/src/context.ts +32 -1
  65. package/src/d1-storage.ts +326 -1692
  66. package/src/errors.ts +8 -0
  67. package/src/events.ts +1 -1
  68. package/src/handler.ts +178 -127
  69. package/src/local-authority.ts +17 -3
  70. package/src/object-bucket.ts +2 -0
  71. package/src/operations-realtime.ts +85 -61
  72. package/src/pg-executor-pglite.ts +27 -23
  73. package/src/pg-executor.ts +5 -1
  74. package/src/postgres-storage.ts +231 -138
  75. package/src/pull.ts +133 -147
  76. package/src/push.ts +356 -205
  77. package/src/realtime.ts +380 -179
  78. package/src/relational-rows.ts +54 -27
  79. package/src/s3-blob-store.ts +23 -13
  80. package/src/s3-object-bucket.ts +20 -2
  81. package/src/schema.ts +31 -0
  82. package/src/scopes.ts +23 -3
  83. package/src/seed.ts +1 -2
  84. package/src/segment-download.ts +25 -4
  85. package/src/signed-url.ts +10 -4
  86. package/src/sigv4.ts +17 -4
  87. package/src/sqlite-blob-store.ts +27 -26
  88. package/src/sqlite-dialect.ts +1607 -114
  89. package/src/sqlite-lease-store.ts +12 -23
  90. package/src/sqlite-storage.ts +360 -1811
  91. package/src/storage.ts +33 -12
package/src/realtime.ts CHANGED
@@ -27,15 +27,19 @@ import {
27
27
  MessageStreamScanner,
28
28
  PROTOCOL_WIRE_VERSION,
29
29
  type PresenceKind,
30
- parseRealtimePresencePublish,
31
30
  REALTIME_TAG_DELTA,
32
31
  REALTIME_TAG_ROUND,
33
32
  type ResponseFrame,
34
33
  type ScopeMap,
35
34
  type WakeReason,
36
35
  } from '@syncular/core';
37
- import type { SyncRequestContext, SyncServerConfig } from './context';
36
+ import type {
37
+ ServerLimits,
38
+ SyncRequestContext,
39
+ SyncServerConfig,
40
+ } from './context';
38
41
  import {
42
+ limitsOf,
39
43
  REMOTE_COMMAND_CLIENT_ID_PREFIX,
40
44
  RESOLVER_OUTAGE,
41
45
  touchAuthenticatedPartition,
@@ -62,7 +66,7 @@ import {
62
66
  matchesEffective,
63
67
  type ResolvedScopes,
64
68
  } from './scopes';
65
- import type { ServerStorage, StoredCommit } from './storage';
69
+ import type { ClientRecord, ServerStorage, StoredCommit } from './storage';
66
70
 
67
71
  /**
68
72
  * Realtime adds fanout/presence tuning to the canonical sync-server config;
@@ -72,9 +76,19 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
72
76
  /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
73
77
  readonly maxDeltaBytes?: number;
74
78
  /**
75
- * §8.6 presence: cap on the serialized size (bytes) of a published
76
- * presence document. An over-cap publish is rejected loudly to the
77
- * publisher with `presence.too_large` and fans out nothing. Default 16 KiB.
79
+ * §8.2 flow control: sent deltas a session may leave unacknowledged before
80
+ * the server stops sending it deltas and answers with a `catchup-required`
81
+ * wake-up. Default 256.
82
+ */
83
+ readonly maxUnackedDeltas?: number;
84
+ /** §8.2 flow control: bytes of unacknowledged deltas per session. Default
85
+ * 4 MiB. */
86
+ readonly maxUnackedDeltaBytes?: number;
87
+ /**
88
+ * §8.6.2 presence cap per connection: the UTF-8 bytes of each held scope
89
+ * key plus its serialized document, summed over the connection's keys. A
90
+ * publish that would exceed it is answered with `presence.too_large` and
91
+ * changes nothing. Default 8,192.
78
92
  */
79
93
  readonly maxPresenceBytes?: number;
80
94
  /**
@@ -104,6 +118,13 @@ export interface RealtimeConnectOptions {
104
118
  * `session.close()` from its socket-close handler as usual.
105
119
  */
106
120
  readonly closeSocket?: () => void;
121
+ /**
122
+ * §8.6.1: called after every change to this connection's own presence
123
+ * documents with all of them, scope key → serialized document, so a host
124
+ * whose memory can be evicted keeps them with the connection and hands
125
+ * them back to `restore`. Not called once the connection closed.
126
+ */
127
+ readonly onPresence?: (presence: ReadonlyMap<string, string>) => void;
107
128
  }
108
129
 
109
130
  interface Registration {
@@ -115,28 +136,30 @@ interface Registration {
115
136
  }
116
137
 
117
138
  const DEFAULT_MAX_DELTA_BYTES = 1024 * 1024;
118
- const DEFAULT_MAX_PRESENCE_BYTES = 16 * 1024;
139
+ const DEFAULT_MAX_PRESENCE_BYTES = 8192;
140
+ const DEFAULT_MAX_UNACKED_DELTAS = 256;
141
+ const DEFAULT_MAX_UNACKED_DELTA_BYTES = 4 * 1024 * 1024;
119
142
 
120
143
  type PresenceDoc = Record<string, unknown>;
121
144
 
145
+ /** A held presence document, its JSON text, and its charge against the
146
+ * per-connection cap (§8.6.2). */
147
+ interface PresenceEntry {
148
+ readonly doc: PresenceDoc;
149
+ readonly json: string;
150
+ readonly bytes: number;
151
+ }
152
+
122
153
  /**
123
- * §8.6 presence registry — pure in-memory ephemeral state, keyed per
124
- * `(partition, scopeKey)` → the set of present sessions and their
125
- * documents. It never touches `ServerStorage`; a server restart loses all
126
- * presence (§8.6.1). Fanout is scoped to registered peers only — the
127
- * privacy floor (§8.6.3).
154
+ * §8.6 presence index: per `(partition, scopeKey)`, the sessions holding a
155
+ * document there. The documents live with their session (§8.6.1). Pure
156
+ * in-memory state that never touches `ServerStorage`.
128
157
  */
129
158
  class PresenceRegistry {
130
- /** partition → scopeKey → session → document. */
131
- readonly #byKey = new Map<
132
- string,
133
- Map<string, Map<RealtimeSession, PresenceDoc>>
134
- >();
159
+ /** partition → scopeKey → sessions with a document on the key. */
160
+ readonly #byKey = new Map<string, Map<string, Set<RealtimeSession>>>();
135
161
 
136
- #keyMap(
137
- partition: string,
138
- scopeKey: string,
139
- ): Map<RealtimeSession, PresenceDoc> {
162
+ add(partition: string, scopeKey: string, session: RealtimeSession): void {
140
163
  let byScope = this.#byKey.get(partition);
141
164
  if (byScope === undefined) {
142
165
  byScope = new Map();
@@ -144,72 +167,22 @@ class PresenceRegistry {
144
167
  }
145
168
  let sessions = byScope.get(scopeKey);
146
169
  if (sessions === undefined) {
147
- sessions = new Map();
170
+ sessions = new Set();
148
171
  byScope.set(scopeKey, sessions);
149
172
  }
150
- return sessions;
151
- }
152
-
153
- /** Current documents on a key, excluding one session (the snapshot,
154
- * §8.6.4). */
155
- snapshot(
156
- partition: string,
157
- scopeKey: string,
158
- exclude: RealtimeSession,
159
- ): Array<{ session: RealtimeSession; doc: PresenceDoc }> {
160
- const sessions = this.#byKey.get(partition)?.get(scopeKey);
161
- if (sessions === undefined) return [];
162
- const out: Array<{ session: RealtimeSession; doc: PresenceDoc }> = [];
163
- for (const [session, doc] of sessions) {
164
- if (session !== exclude) out.push({ session, doc });
165
- }
166
- return out;
167
- }
168
-
169
- /** Store/replace a session's document for a key. Returns whether this is
170
- * the session's FIRST document on the key (join) or a replacement
171
- * (update). */
172
- set(
173
- partition: string,
174
- scopeKey: string,
175
- session: RealtimeSession,
176
- doc: PresenceDoc,
177
- ): 'join' | 'update' {
178
- const sessions = this.#keyMap(partition, scopeKey);
179
- const kind = sessions.has(session) ? 'update' : 'join';
180
- sessions.set(session, doc);
181
- return kind;
173
+ sessions.add(session);
182
174
  }
183
175
 
184
- /** Remove a session's document for a key. Returns true if one existed. */
185
- clear(
186
- partition: string,
187
- scopeKey: string,
188
- session: RealtimeSession,
189
- ): boolean {
176
+ delete(partition: string, scopeKey: string, session: RealtimeSession): void {
190
177
  const sessions = this.#byKey.get(partition)?.get(scopeKey);
191
- if (sessions === undefined) return false;
192
- const existed = sessions.delete(session);
178
+ if (sessions === undefined) return;
179
+ sessions.delete(session);
193
180
  if (sessions.size === 0) this.#byKey.get(partition)?.delete(scopeKey);
194
- return existed;
195
181
  }
196
182
 
197
- /** Every key a session currently holds a document on (for leave-on-drop
198
- * and registration-change re-derivation). */
199
- keysOf(partition: string, session: RealtimeSession): string[] {
200
- const byScope = this.#byKey.get(partition);
201
- if (byScope === undefined) return [];
202
- const keys: string[] = [];
203
- for (const [scopeKey, sessions] of byScope) {
204
- if (sessions.has(session)) keys.push(scopeKey);
205
- }
206
- return keys;
207
- }
208
-
209
- /** Sessions currently registered as peers on a key (for fanout). */
183
+ /** Sessions holding a document on a key. */
210
184
  peers(partition: string, scopeKey: string): RealtimeSession[] {
211
- const sessions = this.#byKey.get(partition)?.get(scopeKey);
212
- return sessions === undefined ? [] : [...sessions.keys()];
185
+ return [...(this.#byKey.get(partition)?.get(scopeKey) ?? [])];
213
186
  }
214
187
  }
215
188
 
@@ -248,6 +221,11 @@ export class RealtimeSession {
248
221
  lastKnownSeq: number;
249
222
  /** Replaced at socket-round completion (§8.7); initial set from §8.1. */
250
223
  registrations: readonly Registration[];
224
+ /** The scope keys `registrations` cover: the presence grant (§8.6.3). */
225
+ scopeKeys: ReadonlySet<string>;
226
+ /** Sent deltas the client has not acknowledged, in commit order (§8.2). */
227
+ #unacked: { commitSeq: number; bytes: number }[] = [];
228
+ #unackedBytes = 0;
251
229
  /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
252
230
  readonly openedAtMs: number;
253
231
  #send: (data: string | Uint8Array) => void | Promise<void>;
@@ -261,6 +239,8 @@ export class RealtimeSession {
261
239
  * token identifies the owning round so a finished round's cleanup
262
240
  * never clobbers a follow-up round's in-flight marker. */
263
241
  #requestScanner: MessageStreamScanner | undefined;
242
+ /** Bytes the scanner holds, against `maxRequestBytes` (§1.7). */
243
+ #requestBytes = 0;
264
244
  #activeRound: symbol | undefined;
265
245
  /** Deltas wait for every round response and registration refresh to finish. */
266
246
  #roundsRefreshing = 0;
@@ -269,6 +249,11 @@ export class RealtimeSession {
269
249
  #deferredBytes = 0;
270
250
  #deferredRegistrations: string | undefined;
271
251
  #closed = false;
252
+ /** §8.6.1: this connection's presence documents by scope key, and their
253
+ * summed charge against `maxPresenceBytes` (§8.6.2). */
254
+ readonly #presence = new Map<string, PresenceEntry>();
255
+ #presenceBytes = 0;
256
+ #onPresence: ((presence: ReadonlyMap<string, string>) => void) | undefined;
272
257
  /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
273
258
  * document coalesced while over the cap. */
274
259
  #presenceRate = new Map<
@@ -314,9 +299,11 @@ export class RealtimeSession {
314
299
  this.wakePending = cursor < latestSeq;
315
300
  this.#wakeRequiredThroughSeq = cursor < latestSeq ? latestSeq : 0;
316
301
  this.registrations = registrations;
302
+ this.scopeKeys = hub.scopeKeysOf(registrations);
317
303
  this.openedAtMs = clock();
318
304
  this.#send = options.send;
319
305
  this.#closeSocket = options.closeSocket;
306
+ this.#onPresence = options.onPresence;
320
307
  this.#hub = hub;
321
308
  this.#clock = clock;
322
309
  this.#maxDeltaBytes = maxDeltaBytes;
@@ -337,12 +324,15 @@ export class RealtimeSession {
337
324
  // §8.6.2: client→server presence carries `event: 'presence'` (server
338
325
  // control messages carry `event`; the ack carries `type`, §8.1).
339
326
  if ((parsed as { event?: unknown }).event === 'presence') {
340
- this.#handlePresence(text);
327
+ this.#handlePresence((parsed as { data?: unknown }).data);
341
328
  return;
342
329
  }
343
330
  if ((parsed as { type?: unknown }).type !== 'ack') return;
344
331
  const cursor = (parsed as { cursor?: unknown }).cursor;
345
332
  if (typeof cursor !== 'number' || !Number.isSafeInteger(cursor)) return;
333
+ while ((this.#unacked[0]?.commitSeq ?? Infinity) <= cursor) {
334
+ this.#unackedBytes -= this.#unacked.shift()!.bytes;
335
+ }
346
336
  this.cursor = Math.max(this.cursor, cursor);
347
337
  // The client may have caught up through another binding (§8.4). Its ack
348
338
  // proves those commits no longer need socket notifications, so the next
@@ -367,21 +357,31 @@ export class RealtimeSession {
367
357
  });
368
358
  }
369
359
 
370
- /** §8.6.2 inbound presence publish/leave from the client. */
371
- #handlePresence(text: string): void {
372
- let publish: ReturnType<typeof parseRealtimePresencePublish>;
373
- try {
374
- publish = parseRealtimePresencePublish(text);
375
- } catch {
360
+ /**
361
+ * §8.6.2 inbound presence publish/leave from the client: the `data` of the
362
+ * control message `handleMessage` parsed, a non-empty `scopeKey` and a
363
+ * `doc` that is an object or `null`.
364
+ */
365
+ #handlePresence(data: unknown): void {
366
+ const publish =
367
+ typeof data === 'object' && data !== null && !Array.isArray(data)
368
+ ? (data as { scopeKey?: unknown; doc?: unknown })
369
+ : undefined;
370
+ const scopeKey = publish?.scopeKey;
371
+ const doc = publish?.doc;
372
+ if (
373
+ typeof scopeKey !== 'string' ||
374
+ scopeKey.length === 0 ||
375
+ (doc !== null && (typeof doc !== 'object' || Array.isArray(doc)))
376
+ ) {
376
377
  // A malformed known event is a parse error (§8.1) — a broken client;
377
378
  // drop the connection loudly rather than silently ignore.
378
379
  this.#violation('malformed presence control message (§8.6.2)');
379
380
  return;
380
381
  }
381
- const { scopeKey, doc } = publish.data;
382
382
  // §8.6.3 authorization: the publish key must be in the connection's
383
383
  // registered effective scopes.
384
- if (!this.#currentScopeKeys().has(scopeKey)) {
384
+ if (!this.scopeKeys.has(scopeKey)) {
385
385
  this.#sendSafe(
386
386
  encodePresenceError(scopeKey, 'presence.forbidden', this.#clock()),
387
387
  );
@@ -391,20 +391,40 @@ export class RealtimeSession {
391
391
  this.#leavePresence(scopeKey);
392
392
  return;
393
393
  }
394
- // §8.6.2 size cap: fail loud to the publisher, fan out nothing.
395
- const serialized = JSON.stringify(doc);
396
- if (serialized.length > this.#hub.maxPresenceBytes) {
397
- this.#sendSafe(
398
- encodePresenceError(scopeKey, 'presence.too_large', this.#clock()),
399
- );
400
- return;
394
+ const entry = this.#presenceEntry(scopeKey, doc as PresenceDoc);
395
+ if (entry !== undefined) this.#publishPresence(scopeKey, entry);
396
+ }
397
+
398
+ /**
399
+ * §8.6.2 size cap per connection: the key's and document's UTF-8 bytes,
400
+ * added to the connection's documents on its other keys, stay within
401
+ * `maxPresenceBytes`. Over the cap the publisher alone hears
402
+ * `presence.too_large` and nothing changes.
403
+ */
404
+ #presenceEntry(
405
+ scopeKey: string,
406
+ doc: PresenceDoc,
407
+ ): PresenceEntry | undefined {
408
+ const json = JSON.stringify(doc);
409
+ const budget =
410
+ this.#hub.maxPresenceBytes -
411
+ this.#presenceBytes +
412
+ (this.#presence.get(scopeKey)?.bytes ?? 0);
413
+ // A string never has fewer UTF-8 bytes than UTF-16 code units, so the
414
+ // unit count rejects first.
415
+ if (scopeKey.length + json.length <= budget) {
416
+ const bytes = new TextEncoder().encode(scopeKey + json).byteLength;
417
+ if (bytes <= budget) return { doc, json, bytes };
401
418
  }
402
- this.#publishPresence(scopeKey, doc);
419
+ this.#sendSafe(
420
+ encodePresenceError(scopeKey, 'presence.too_large', this.#clock()),
421
+ );
422
+ return undefined;
403
423
  }
404
424
 
405
425
  /** §8.6.4: store + fan out a publish, honoring the rate cap (latest-wins
406
426
  * coalesce). */
407
- #publishPresence(scopeKey: string, doc: PresenceDoc): void {
427
+ #publishPresence(scopeKey: string, entry: PresenceEntry): void {
408
428
  const minInterval = this.#hub.presenceMinIntervalMs;
409
429
  if (minInterval > 0) {
410
430
  const now = this.#clock();
@@ -412,24 +432,48 @@ export class RealtimeSession {
412
432
  if (rate !== undefined && now - rate.lastFanoutMs < minInterval) {
413
433
  // Over the cap: keep only the latest document, fan it out at the
414
434
  // window edge (never an error, never a stale/lost latest, §8.6.4).
415
- rate.pending = doc;
435
+ rate.pending = entry.doc;
416
436
  if (rate.timer === undefined) {
417
437
  const delay = minInterval - (now - rate.lastFanoutMs);
418
438
  rate.timer = setTimeout(() => {
419
439
  delete rate.timer;
420
440
  const pending = rate.pending;
421
441
  delete rate.pending;
422
- if (pending !== undefined) this.#fanoutPublish(scopeKey, pending);
442
+ // The connection's other keys may have grown since: the cap
443
+ // holds when the document is stored.
444
+ const latest =
445
+ pending === undefined
446
+ ? undefined
447
+ : this.#presenceEntry(scopeKey, pending);
448
+ if (latest !== undefined) this.#fanoutPublish(scopeKey, latest);
423
449
  }, delay);
424
450
  }
425
451
  return;
426
452
  }
427
453
  }
428
- this.#fanoutPublish(scopeKey, doc);
454
+ this.#fanoutPublish(scopeKey, entry);
429
455
  }
430
456
 
431
- #fanoutPublish(scopeKey: string, doc: PresenceDoc): void {
432
- const kind = this.#hub.presence.set(this.partition, scopeKey, this, doc);
457
+ #fanoutPublish(scopeKey: string, entry: PresenceEntry): void {
458
+ // §8.6.1: the peer identity is (actorId, clientId). Another session of
459
+ // this identity (a stale socket of a reconnected client) loses its
460
+ // document silently, so its later close announces nothing.
461
+ let replaced = false;
462
+ for (const peer of this.#hub.presence.peers(this.partition, scopeKey)) {
463
+ if (
464
+ peer !== this &&
465
+ peer.actorId === this.actorId &&
466
+ peer.clientId === this.clientId
467
+ ) {
468
+ replaced = peer.forgetPresence(scopeKey) || replaced;
469
+ }
470
+ }
471
+ const held = this.#presence.get(scopeKey);
472
+ const kind = replaced || held !== undefined ? 'update' : 'join';
473
+ this.#presenceBytes += entry.bytes - (held?.bytes ?? 0);
474
+ this.#presence.set(scopeKey, entry);
475
+ this.#hub.presence.add(this.partition, scopeKey, this);
476
+ this.#reportPresence();
433
477
  let rate = this.#presenceRate.get(scopeKey);
434
478
  if (rate === undefined) {
435
479
  rate = { lastFanoutMs: this.#clock() };
@@ -437,17 +481,52 @@ export class RealtimeSession {
437
481
  } else {
438
482
  rate.lastFanoutMs = this.#clock();
439
483
  }
440
- this.#hub.fanoutPresence(this, scopeKey, kind, doc);
484
+ this.#hub.fanoutPresence(this, scopeKey, kind, entry.doc);
485
+ }
486
+
487
+ /** §8.6.1: hand the host this connection's documents after a change. */
488
+ #reportPresence(): void {
489
+ if (this.#closed || this.#onPresence === undefined) return;
490
+ this.#onPresence(
491
+ new Map([...this.#presence].map(([key, entry]) => [key, entry.json])),
492
+ );
493
+ }
494
+
495
+ /** §8.6.1: hold the documents a host kept for this connection across an
496
+ * eviction, without fanout: peers already saw them. */
497
+ seedPresence(presence: ReadonlyMap<string, string>): void {
498
+ for (const [scopeKey, json] of presence) {
499
+ const bytes = new TextEncoder().encode(scopeKey + json).byteLength;
500
+ this.#presence.set(scopeKey, {
501
+ doc: JSON.parse(json) as PresenceDoc,
502
+ json,
503
+ bytes,
504
+ });
505
+ this.#presenceBytes += bytes;
506
+ this.#hub.presence.add(this.partition, scopeKey, this);
507
+ }
441
508
  }
442
509
 
443
510
  /** §8.6.1/§8.6.3: clear this session's document for a key and fan a
444
511
  * leave to the remaining peers. */
445
512
  #leavePresence(scopeKey: string): void {
446
- const existed = this.#hub.presence.clear(this.partition, scopeKey, this);
513
+ if (this.forgetPresence(scopeKey))
514
+ this.#hub.fanoutPresence(this, scopeKey, 'leave', null);
515
+ }
516
+
517
+ /** Clear this session's document for a key without fanout, including a
518
+ * coalesced publish still pending. Returns whether a document existed. */
519
+ forgetPresence(scopeKey: string): boolean {
447
520
  const rate = this.#presenceRate.get(scopeKey);
448
521
  if (rate?.timer !== undefined) clearTimeout(rate.timer);
449
522
  this.#presenceRate.delete(scopeKey);
450
- if (existed) this.#hub.fanoutPresence(this, scopeKey, 'leave', null);
523
+ const held = this.#presence.get(scopeKey);
524
+ if (held === undefined) return false;
525
+ this.#presence.delete(scopeKey);
526
+ this.#presenceBytes -= held.bytes;
527
+ this.#hub.presence.delete(this.partition, scopeKey, this);
528
+ this.#reportPresence();
529
+ return true;
451
530
  }
452
531
 
453
532
  /** Deliver a fanout event to this session (called by the hub for peers,
@@ -471,17 +550,12 @@ export class RealtimeSession {
471
550
  );
472
551
  }
473
552
 
474
- /** The scope keys this connection currently holds (§8.6.3). */
475
- #currentScopeKeys(): Set<string> {
476
- return this.#hub.scopeKeysOf(this.registrations);
477
- }
478
-
479
553
  /** §8.6.3: drop presence on keys the connection no longer holds and
480
554
  * deliver the snapshot on keys it newly holds. Called after a
481
555
  * registration change (§8.7 round end, §8.1 reconnect handled by
482
556
  * connect's snapshot). */
483
557
  reconcilePresence(previousKeys: ReadonlySet<string>): void {
484
- const currentKeys = this.#currentScopeKeys();
558
+ const currentKeys = this.scopeKeys;
485
559
  // Keys lost: leave my own published docs; presence delivery stops
486
560
  // naturally (peers no longer fan to me — I am not registered).
487
561
  for (const key of previousKeys) {
@@ -496,17 +570,15 @@ export class RealtimeSession {
496
570
  /** §8.6.4 snapshot: a burst of `join`s for peers already present on a
497
571
  * key, delivered to this session only. */
498
572
  #deliverSnapshot(scopeKey: string): void {
499
- for (const peer of this.#hub.presence.snapshot(
500
- this.partition,
501
- scopeKey,
502
- this,
503
- )) {
573
+ for (const peer of this.#hub.presence.peers(this.partition, scopeKey)) {
574
+ const held = peer.#presence.get(scopeKey);
575
+ if (peer === this || held === undefined) continue;
504
576
  this.receivePresence(
505
577
  scopeKey,
506
578
  'join',
507
- peer.session.actorId,
508
- peer.session.clientId,
509
- peer.doc,
579
+ peer.actorId,
580
+ peer.clientId,
581
+ held.doc,
510
582
  );
511
583
  }
512
584
  }
@@ -517,9 +589,7 @@ export class RealtimeSession {
517
589
  this.#deferredDeltas = [];
518
590
  this.#deferredBytes = 0;
519
591
  this.#deferredRegistrations = undefined;
520
- for (const key of this.#hub.presence.keysOf(this.partition, this)) {
521
- this.#leavePresence(key);
522
- }
592
+ for (const key of [...this.#presence.keys()]) this.#leavePresence(key);
523
593
  for (const rate of this.#presenceRate.values()) {
524
594
  if (rate.timer !== undefined) clearTimeout(rate.timer);
525
595
  }
@@ -529,7 +599,7 @@ export class RealtimeSession {
529
599
  /** Snapshot delivery on connect (§8.6.4) — the newly-registered
530
600
  * connection sees who is already present on each of its keys. */
531
601
  deliverInitialPresence(): void {
532
- for (const key of this.#currentScopeKeys()) this.#deliverSnapshot(key);
602
+ for (const key of this.scopeKeys) this.#deliverSnapshot(key);
533
603
  }
534
604
 
535
605
  /**
@@ -554,6 +624,17 @@ export class RealtimeSession {
554
624
  return;
555
625
  }
556
626
  const chunk = bytes.subarray(1);
627
+ // §1.7: the assembled request counts against `maxRequestBytes`; past it
628
+ // the stream has no acceptable end, so the connection drops (§8.7).
629
+ this.#requestBytes =
630
+ this.#requestScanner === undefined
631
+ ? chunk.length
632
+ : this.#requestBytes + chunk.length;
633
+ if (this.#requestBytes > this.#hub.limits.maxRequestBytes) {
634
+ this.#requestScanner = undefined;
635
+ this.#violation('request exceeds maxRequestBytes (§1.7)');
636
+ return;
637
+ }
557
638
  this.#requestScanner ??= new MessageStreamScanner();
558
639
  let done: ReturnType<MessageStreamScanner['push']>;
559
640
  try {
@@ -748,6 +829,7 @@ export class RealtimeSession {
748
829
  this.partition,
749
830
  this.actorId,
750
831
  this.clientId,
832
+ await this.#storage.getClientRecord(this.partition, this.clientId),
751
833
  );
752
834
  } catch {
753
835
  if (!failClosed) {
@@ -764,8 +846,9 @@ export class RealtimeSession {
764
846
  // §8.6.3: a registration change re-derives the presence grant — capture
765
847
  // the keys before, reconcile after (leaves on lost keys, snapshots on
766
848
  // gained keys).
767
- const previousKeys = this.#currentScopeKeys();
849
+ const previousKeys = this.scopeKeys;
768
850
  this.registrations = registrations;
851
+ this.scopeKeys = this.#hub.scopeKeysOf(registrations);
769
852
  this.reconcilePresence(previousKeys);
770
853
  }
771
854
 
@@ -813,12 +896,7 @@ export class RealtimeSession {
813
896
  }
814
897
 
815
898
  sendHeartbeat(): void {
816
- this.#sendSafe(
817
- JSON.stringify({
818
- event: 'heartbeat',
819
- data: { timestamp: this.#clock() },
820
- }),
821
- );
899
+ this.#sendSafe(encodeHeartbeat(this.#clock()));
822
900
  }
823
901
 
824
902
  sendWake(reason: WakeReason): void {
@@ -923,9 +1001,8 @@ export class RealtimeSession {
923
1001
  const frames: ResponseFrame[] = [
924
1002
  {
925
1003
  type: 'RESP_HEADER',
926
- ...(this.wireVersion >= 2
927
- ? { logEpoch: this.logEpoch, resetRequired: false }
928
- : {}),
1004
+ logEpoch: this.logEpoch,
1005
+ resetRequired: false,
929
1006
  },
930
1007
  ];
931
1008
  for (const section of sections) {
@@ -978,6 +1055,21 @@ export class RealtimeSession {
978
1055
  }
979
1056
 
980
1057
  #sendDelta(tagged: Uint8Array, commitSeq: number, changes: number): void {
1058
+ // A wake earlier in a deferred flush suppresses the rest of it.
1059
+ if (this.wakePending) return;
1060
+ // §8.2 flow control: a client this far behind on acks catches up by pull;
1061
+ // its acknowledgement after that round lifts the suppression. One delta
1062
+ // always fits, so `maxDeltaBytes` alone bounds a single message.
1063
+ if (
1064
+ this.#unacked.length >= this.#hub.maxUnackedDeltas ||
1065
+ (this.#unacked.length > 0 &&
1066
+ this.#unackedBytes + tagged.length > this.#hub.maxUnackedDeltaBytes)
1067
+ ) {
1068
+ this.sendWake('catchup-required');
1069
+ return;
1070
+ }
1071
+ this.#unacked.push({ commitSeq, bytes: tagged.length });
1072
+ this.#unackedBytes += tagged.length;
981
1073
  this.#sendSafe(tagged);
982
1074
  this.cursor = Math.max(this.cursor, commitSeq);
983
1075
  const events = this.#events;
@@ -1012,6 +1104,8 @@ export interface RealtimeConnection {
1012
1104
  export class RealtimeHub {
1013
1105
  #config: RealtimeHubConfig;
1014
1106
  readonly #schema: CompiledSchema;
1107
+ /** The validated configured limits (§1.7); a bad value throws here. */
1108
+ readonly limits: ServerLimits;
1015
1109
  readonly #sessions = new Set<RealtimeSession>();
1016
1110
  /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
1017
1111
  readonly presence = new PresenceRegistry();
@@ -1020,6 +1114,7 @@ export class RealtimeHub {
1020
1114
  this.#config = config;
1021
1115
  this.#schema = compileSchema(config.schema);
1022
1116
  schemaWindowOf(config.schema, config.schemaWindow);
1117
+ this.limits = limitsOf(config);
1023
1118
  }
1024
1119
 
1025
1120
  projectPayload(registration: Registration, payload: Uint8Array): Uint8Array {
@@ -1064,6 +1159,16 @@ export class RealtimeHub {
1064
1159
  return this.#config.maxPresenceBytes ?? DEFAULT_MAX_PRESENCE_BYTES;
1065
1160
  }
1066
1161
 
1162
+ /** §8.2 flow control: unacknowledged deltas per session. */
1163
+ get maxUnackedDeltas(): number {
1164
+ return this.#config.maxUnackedDeltas ?? DEFAULT_MAX_UNACKED_DELTAS;
1165
+ }
1166
+
1167
+ /** §8.2 flow control: unacknowledged delta bytes per session. */
1168
+ get maxUnackedDeltaBytes(): number {
1169
+ return this.#config.maxUnackedDeltaBytes ?? DEFAULT_MAX_UNACKED_DELTA_BYTES;
1170
+ }
1171
+
1067
1172
  /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
1068
1173
  get presenceMinIntervalMs(): number {
1069
1174
  return this.#config.presenceMinIntervalMs ?? 0;
@@ -1080,7 +1185,7 @@ export class RealtimeHub {
1080
1185
  * The publisher does not receive its own fanout.
1081
1186
  */
1082
1187
  fanoutPresence(
1083
- origin: RealtimeSession,
1188
+ origin: Pick<RealtimeSession, 'partition' | 'actorId' | 'clientId'>,
1084
1189
  scopeKey: string,
1085
1190
  kind: PresenceKind,
1086
1191
  doc: PresenceDoc | null,
@@ -1089,7 +1194,7 @@ export class RealtimeHub {
1089
1194
  if (session === origin) continue;
1090
1195
  if (session.partition !== origin.partition) continue;
1091
1196
  // Receive authorization (§8.6.3): the receiver must itself hold the key.
1092
- if (!this.scopeKeysOf(session.registrations).has(scopeKey)) continue;
1197
+ if (!session.scopeKeys.has(scopeKey)) continue;
1093
1198
  session.receivePresence(
1094
1199
  scopeKey,
1095
1200
  kind,
@@ -1108,11 +1213,8 @@ export class RealtimeHub {
1108
1213
  partition: string,
1109
1214
  actorId: string,
1110
1215
  clientId: string,
1216
+ record: ClientRecord | undefined,
1111
1217
  ): Promise<Registration[]> {
1112
- const record = await this.#config.storage.getClientRecord(
1113
- partition,
1114
- clientId,
1115
- );
1116
1218
  let resolved: ResolvedScopes;
1117
1219
  try {
1118
1220
  const allowed = await this.#config.resolveScopes({
@@ -1159,7 +1261,11 @@ export class RealtimeHub {
1159
1261
  table.declaredVariables.has(key),
1160
1262
  );
1161
1263
  if (!keysValid) continue;
1162
- const outcome = computeEffective(subscription.scopes, resolved);
1264
+ const outcome = computeEffective(
1265
+ table.declaredVariables,
1266
+ subscription.scopes,
1267
+ resolved,
1268
+ );
1163
1269
  if (outcome.status !== 'active') continue;
1164
1270
  registrations.push({
1165
1271
  id: subscription.id,
@@ -1220,14 +1326,87 @@ export class RealtimeHub {
1220
1326
  * Register a connected socket (§8.1): load the client's last pull's
1221
1327
  * subscription list, resolve + intersect scopes, send `hello`.
1222
1328
  */
1223
- async connect(options: RealtimeConnectOptions): Promise<RealtimeSession> {
1329
+ connect(options: RealtimeConnectOptions): Promise<RealtimeSession> {
1330
+ return this.#open(options, undefined);
1331
+ }
1332
+
1333
+ /**
1334
+ * Rebuild the sessions of sockets that outlived their host's memory, such as
1335
+ * a hibernated Durable Object (§8.1). Each client saw `hello` and the
1336
+ * presence snapshot at its real upgrade, so neither is sent again. The
1337
+ * partition is touched and its latest sequence read once per partition, and
1338
+ * each client record once. The caller holds back commits until this
1339
+ * resolves, so the shared latest sequence stays current.
1340
+ *
1341
+ * `presence` is the connection's last `onPresence` report; the session
1342
+ * holds it again without fanout (§8.6.1). Once every session is back, a
1343
+ * key the reloaded registrations no longer cover leaves, and so does every
1344
+ * key of a socket whose session could not be rebuilt.
1345
+ */
1346
+ async restore(
1347
+ sockets: readonly (RealtimeConnectOptions & {
1348
+ readonly presence?: ReadonlyMap<string, string>;
1349
+ })[],
1350
+ ): Promise<PromiseSettledResult<RealtimeSession>[]> {
1351
+ const partitions = new Map<
1352
+ string,
1353
+ { logEpoch: string; latestSeq: number }
1354
+ >();
1355
+ const results: PromiseSettledResult<RealtimeSession>[] = [];
1356
+ for (const options of sockets) {
1357
+ try {
1358
+ let shared = partitions.get(options.partition);
1359
+ if (shared === undefined) {
1360
+ const { logEpoch } = await touchAuthenticatedPartition({
1361
+ ...this.#config,
1362
+ partition: options.partition,
1363
+ actorId: options.actorId,
1364
+ });
1365
+ shared = {
1366
+ logEpoch,
1367
+ latestSeq: await this.#config.storage.getMaxCommitSeq(
1368
+ options.partition,
1369
+ ),
1370
+ };
1371
+ partitions.set(options.partition, shared);
1372
+ }
1373
+ const value = await this.#open(options, shared);
1374
+ if (options.presence !== undefined)
1375
+ value.seedPresence(options.presence);
1376
+ results.push({ status: 'fulfilled', value });
1377
+ } catch (reason) {
1378
+ results.push({ status: 'rejected', reason });
1379
+ }
1380
+ }
1381
+ for (const [i, result] of results.entries()) {
1382
+ const held = [...(sockets[i]!.presence?.keys() ?? [])];
1383
+ if (result.status === 'fulfilled') {
1384
+ const session = result.value;
1385
+ session.reconcilePresence(new Set([...session.scopeKeys, ...held]));
1386
+ } else {
1387
+ for (const key of held) {
1388
+ this.fanoutPresence(sockets[i]!, key, 'leave', null);
1389
+ }
1390
+ }
1391
+ }
1392
+ return results;
1393
+ }
1394
+
1395
+ async #open(
1396
+ options: RealtimeConnectOptions,
1397
+ restored: { logEpoch: string; latestSeq: number } | undefined,
1398
+ ): Promise<RealtimeSession> {
1224
1399
  const { storage } = this.#config;
1225
1400
  const clock = this.#config.clock ?? Date.now;
1226
- const registry = await touchAuthenticatedPartition({
1227
- ...this.#config,
1228
- partition: options.partition,
1229
- actorId: options.actorId,
1230
- });
1401
+ const logEpoch =
1402
+ restored?.logEpoch ??
1403
+ (
1404
+ await touchAuthenticatedPartition({
1405
+ ...this.#config,
1406
+ partition: options.partition,
1407
+ actorId: options.actorId,
1408
+ })
1409
+ ).logEpoch;
1231
1410
  if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
1232
1411
  throw syncError(
1233
1412
  'sync.invalid_client_id',
@@ -1248,8 +1427,10 @@ export class RealtimeHub {
1248
1427
  options.partition,
1249
1428
  options.actorId,
1250
1429
  options.clientId,
1430
+ record,
1251
1431
  );
1252
- const latestSeq = await storage.getMaxCommitSeq(options.partition);
1432
+ const latestSeq =
1433
+ restored?.latestSeq ?? (await storage.getMaxCommitSeq(options.partition));
1253
1434
  const cursor = record?.cursor ?? -1;
1254
1435
  const session = new RealtimeSession(
1255
1436
  this,
@@ -1260,44 +1441,46 @@ export class RealtimeHub {
1260
1441
  clock,
1261
1442
  this.#config.maxDeltaBytes ?? DEFAULT_MAX_DELTA_BYTES,
1262
1443
  storage,
1263
- registry.logEpoch,
1444
+ logEpoch,
1264
1445
  record !== undefined && isSupportedProtocolWireVersion(record.wireVersion)
1265
1446
  ? record.wireVersion
1266
1447
  : PROTOCOL_WIRE_VERSION,
1267
1448
  this.#config.events,
1268
1449
  );
1269
1450
  this.#sessions.add(session);
1270
- const helloResult = options.send(
1271
- JSON.stringify({
1272
- event: 'hello',
1273
- data: {
1274
- protocolVersion: 1,
1275
- sessionId: session.sessionId,
1276
- actorId: options.actorId,
1277
- clientId: options.clientId,
1278
- cursor,
1279
- latestCursor: latestSeq,
1280
- requiresSync:
1281
- record === undefined ||
1282
- cursor < latestSeq ||
1283
- (this.#config.schemaWindow !== undefined &&
1284
- record.subscriptions.some(
1285
- (subscription) =>
1286
- !schemaWindowOf(
1287
- this.#config.schema,
1288
- this.#config.schemaWindow,
1289
- ).some(
1290
- (schema) => schema.version === subscription.schemaVersion,
1291
- ),
1292
- )),
1293
- timestamp: clock(),
1294
- },
1295
- }),
1296
- );
1297
- if (helloResult instanceof Promise) helloResult.catch(() => {});
1298
- // §8.6.4: the newly-registered connection sees who is already present
1299
- // on each key it holds (a burst of joins, after hello).
1300
- session.deliverInitialPresence();
1451
+ if (restored === undefined) {
1452
+ const helloResult = options.send(
1453
+ JSON.stringify({
1454
+ event: 'hello',
1455
+ data: {
1456
+ protocolVersion: 1,
1457
+ sessionId: session.sessionId,
1458
+ actorId: options.actorId,
1459
+ clientId: options.clientId,
1460
+ cursor,
1461
+ latestCursor: latestSeq,
1462
+ requiresSync:
1463
+ record === undefined ||
1464
+ cursor < latestSeq ||
1465
+ (this.#config.schemaWindow !== undefined &&
1466
+ record.subscriptions.some(
1467
+ (subscription) =>
1468
+ !schemaWindowOf(
1469
+ this.#config.schema,
1470
+ this.#config.schemaWindow,
1471
+ ).some(
1472
+ (schema) => schema.version === subscription.schemaVersion,
1473
+ ),
1474
+ )),
1475
+ timestamp: clock(),
1476
+ },
1477
+ }),
1478
+ );
1479
+ if (helloResult instanceof Promise) helloResult.catch(() => {});
1480
+ // §8.6.4: the newly-registered connection sees who is already present
1481
+ // on each key it holds (a burst of joins, after hello).
1482
+ session.deliverInitialPresence();
1483
+ }
1301
1484
  const events = this.#config.events;
1302
1485
  if (events !== undefined) {
1303
1486
  emitEvent(events, {
@@ -1396,6 +1579,23 @@ export class RealtimeHub {
1396
1579
  wakeAll(reason: WakeReason): void {
1397
1580
  for (const session of this.#sessions) session.sendWake(reason);
1398
1581
  }
1582
+
1583
+ /**
1584
+ * §8.5: send `heartbeat` to every session. The host calls this on its
1585
+ * heartbeat interval (suggested 30 s); a client that hears nothing for twice
1586
+ * the interval treats the socket as lost.
1587
+ */
1588
+ heartbeat(): void {
1589
+ for (const session of this.#sessions) session.sendHeartbeat();
1590
+ }
1591
+ }
1592
+
1593
+ /** The §8.5 `heartbeat` control message. */
1594
+ export function encodeHeartbeat(timestampMs: number): string {
1595
+ return JSON.stringify({
1596
+ event: 'heartbeat',
1597
+ data: { timestamp: timestampMs },
1598
+ });
1399
1599
  }
1400
1600
 
1401
1601
  export function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub {
@@ -1416,7 +1616,8 @@ function errorResponseBytes(
1416
1616
  frames: [
1417
1617
  {
1418
1618
  type: 'RESP_HEADER',
1419
- ...(wireVersion >= 2 ? { logEpoch, resetRequired: false } : {}),
1619
+ logEpoch,
1620
+ resetRequired: false,
1420
1621
  },
1421
1622
  {
1422
1623
  type: 'ERROR',