@syncular/server-workers 0.78.3 → 0.79.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.
@@ -88,15 +88,29 @@
88
88
  * sessions, and re-arms while sockets remain. The host owns the alarm: a
89
89
  * subclass that needs another alarm schedule cannot share it.
90
90
  *
91
- * ## The wake path (external-command fan-out)
91
+ * ## Fanout between objects (§8.9)
92
92
  *
93
93
  * Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
94
- * are forwarded into this DO and fan out in-process. An
95
- * external authoritative command host that already provides equivalent D1
96
- * partition serialization may call `/__wake` after its own commit so sockets
97
- * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
94
+ * are forwarded into this DO and fan out in-process. A commit applied
95
+ * elsewhere reaches the partition's object through
96
+ * `durableObjectRealtimeNotifier`: a POST to the fanout path carrying the
97
+ * commit, which the object delivers to its hub as a delta.
98
+ *
99
+ * On PostgreSQL the Worker may shard sockets over several objects
100
+ * (`WorkersRealtimeOptions.shard`) and run every round itself. The
101
+ * partition's object (`idFromName(partition)`) then holds no socket: it keeps
102
+ * the names of the shard objects that registered with it in its storage and
103
+ * relays every fanout message to each of them. A shard registers when it
104
+ * accepts a socket, before its hub connects it; a shard that answers a relay with 404 (no socket
105
+ * left) is removed unless it registered again meanwhile. A shard's hub
106
+ * (`RealtimeHubConfig.fanout`) sends the commits of its own rounds through the
107
+ * partition's object too, so every shard, the shard itself included, receives
108
+ * each commit once. A host scope refresh (`refreshScopes` on the notifier)
109
+ * takes the same path. A relay that fails leaves a record of what the shard
110
+ * owes in the partition object's storage, and the alarm retries it every
111
+ * second until the shard answers or is removed.
98
112
  */
99
- import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, decodeRequestBody, encodeHeartbeat, errorBody, eraseScopeValue, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
113
+ import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, decodeRequestBody, encodeHeartbeat, errorBody, eraseScopeValue, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, emitEvent, SyncularAdmin, } from '@syncular/server';
100
114
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
101
115
  import { decodeRequest } from '@syncular/core';
102
116
  /**
@@ -140,8 +154,126 @@ function encodeAttachment(identity, presence) {
140
154
  }
141
155
  return Uint8Array.from(bytes);
142
156
  }
157
+ /**
158
+ * Fanout body: a u32 length, the message as UTF-8 JSON with each change
159
+ * payload replaced by its byte length, then the payloads in change order.
160
+ */
161
+ function encodeFanout(message) {
162
+ const payloads = [];
163
+ const head = new TextEncoder().encode(JSON.stringify('commit' in message
164
+ ? {
165
+ ...message,
166
+ commit: {
167
+ ...message.commit,
168
+ changes: message.commit.changes.map(({ payload, ...change }) => {
169
+ if (payload === undefined)
170
+ return change;
171
+ payloads.push(payload);
172
+ return { ...change, payloadBytes: payload.byteLength };
173
+ }),
174
+ },
175
+ }
176
+ : message));
177
+ const bytes = new Uint8Array(payloads.reduce((total, p) => total + p.byteLength, 4 + head.byteLength));
178
+ new DataView(bytes.buffer).setUint32(0, head.byteLength);
179
+ bytes.set(head, 4);
180
+ let at = 4 + head.byteLength;
181
+ for (const payload of payloads) {
182
+ bytes.set(payload, at);
183
+ at += payload.byteLength;
184
+ }
185
+ return bytes;
186
+ }
187
+ function decodeFanout(bytes) {
188
+ const length = new DataView(bytes.buffer, bytes.byteOffset).getUint32(0);
189
+ const message = JSON.parse(new TextDecoder().decode(bytes.subarray(4, 4 + length)));
190
+ if (!('commit' in message))
191
+ return message;
192
+ let at = 4 + length;
193
+ return {
194
+ partition: message.partition,
195
+ commit: {
196
+ ...message.commit,
197
+ changes: message.commit.changes.map(({ payloadBytes, ...change }) => payloadBytes === undefined
198
+ ? change
199
+ : { ...change, payload: bytes.slice(at, (at += payloadBytes)) }),
200
+ },
201
+ };
202
+ }
203
+ /**
204
+ * The `RealtimeNotifier` (§8.2, §8.9) that sends a commit, or a client's
205
+ * changed registrations, to the partition's Durable Object, which delivers it
206
+ * to its own sockets and relays it to every shard registered with it, retrying
207
+ * a shard whose relay failed. Pass it as the Worker config's `realtime`
208
+ * whenever the Worker applies commits itself: sharded sockets, or an external
209
+ * command host. A failed request to the partition's object never fails the
210
+ * push, whose commit is durable: the notifier retries it three times in
211
+ * `waitUntil` and emits `realtime.relay_failed` when the last one fails.
212
+ *
213
+ * `refreshScopes(partition, actorId?)` is `RealtimeHub.refreshScopes` for
214
+ * every object of the partition: call it after a grant changes. It throws when
215
+ * the partition's object did not take the refresh.
216
+ */
217
+ export function durableObjectRealtimeNotifier(namespace, options) {
218
+ // A synthetic origin: the DO reads only the path and the body. The partition
219
+ // object answers 204, or 404 when no object of the partition holds a socket.
220
+ const send = async (message, body = encodeFanout(message)) => {
221
+ try {
222
+ const response = await namespace
223
+ .get(namespace.idFromName(message.partition))
224
+ .fetch(new Request(`https://do${REALTIME_DO_FANOUT_PATH}`, {
225
+ method: 'POST',
226
+ body,
227
+ }));
228
+ return response.status;
229
+ }
230
+ catch {
231
+ return 0;
232
+ }
233
+ };
234
+ const deliver = async (message) => {
235
+ const body = encodeFanout(message);
236
+ const status = await send(message, body);
237
+ if (status === 204 || status === 404)
238
+ return;
239
+ options.waitUntil((async () => {
240
+ for (let attempt = 1; attempt <= 3; attempt++) {
241
+ await (options.retryDelay?.(attempt) ??
242
+ new Promise((resolve) => setTimeout(resolve, 250 * 4 ** (attempt - 1))));
243
+ const retried = await send(message, body);
244
+ if (retried === 204 || retried === 404)
245
+ return;
246
+ }
247
+ if (options.events !== undefined) {
248
+ emitEvent(options.events, {
249
+ type: 'realtime.relay_failed',
250
+ atMs: Date.now(),
251
+ partition: message.partition,
252
+ ...('commit' in message
253
+ ? { commitSeq: message.commit.commitSeq }
254
+ : {}),
255
+ attempts: 4,
256
+ });
257
+ }
258
+ })());
259
+ };
260
+ return {
261
+ notifyCommit: (partition, commit) => deliver({ partition, commit }),
262
+ notifySubscriptions: (partition, clientId) => deliver({ partition, clientId }),
263
+ async refreshScopes(partition, actorId) {
264
+ const status = await send({
265
+ partition,
266
+ refresh: actorId === undefined ? {} : { actorId },
267
+ });
268
+ if (status !== 204 && status !== 404) {
269
+ throw new SyncError('sync.internal_error', 'realtime scope refresh failed', JSON.stringify({ status }));
270
+ }
271
+ },
272
+ };
273
+ }
143
274
  /** Internal control-request paths on the DO stub (never client-facing). */
144
- export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
275
+ export const REALTIME_DO_FANOUT_PATH = '/__syncular_realtime/fanout';
276
+ export const REALTIME_DO_SHARDS_PATH = '/__syncular_realtime/shards';
145
277
  export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
146
278
  export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
147
279
  export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
@@ -200,8 +332,13 @@ export class SyncularRealtimeHost {
200
332
  #rehydration;
201
333
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
202
334
  #partitionTail = Promise.resolve();
335
+ /** The shard name this instance registered with the partition's object. */
336
+ #registeredShard;
203
337
  constructor(state, storage, config) {
204
338
  this.#state = state;
339
+ if (config.namespace !== undefined && 'prepare' in storage) {
340
+ throw new Error('RealtimeDOConfig.namespace needs a storage that locks partitions in the database; D1 pushes need the partition FIFO');
341
+ }
205
342
  this.#storage =
206
343
  'prepare' in storage
207
344
  ? // One DO is selected per partition, and every round enters
@@ -230,6 +367,12 @@ export class SyncularRealtimeHost {
230
367
  ? composeEvents(ring, config.events)
231
368
  : ring,
232
369
  };
370
+ if (this.#config.namespace !== undefined) {
371
+ withRing.fanout = durableObjectRealtimeNotifier(this.#config.namespace, {
372
+ waitUntil: (promise) => this.#state.waitUntil(promise),
373
+ events: withRing.events,
374
+ });
375
+ }
233
376
  const hub = createRealtimeHub(withRing);
234
377
  const cap = hub.maxPresenceBytes;
235
378
  this.#presenceReserve =
@@ -248,10 +391,10 @@ export class SyncularRealtimeHost {
248
391
  return this.#hub;
249
392
  }
250
393
  /**
251
- * The DO `fetch` handler: routes the internal upgrade + wake control paths.
252
- * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
253
- * resolved identity in headers (see `forwardRealtimeUpgrade` in `index.ts`),
254
- * and accepts external-command wakes at `/__syncular_realtime/wake`.
394
+ * The DO `fetch` handler: routes the internal control paths. The Worker
395
+ * forwards `GET <mount>/realtime` here as an upgrade with the resolved
396
+ * identity in headers (see `forwardRealtimeUpgrade` in `index.ts`), and
397
+ * commits applied elsewhere arrive at the fanout path (§8.9).
255
398
  */
256
399
  async fetch(request) {
257
400
  await this.#rehydrateSockets();
@@ -283,8 +426,15 @@ export class SyncularRealtimeHost {
283
426
  if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
284
427
  return this.#serializePartition(() => this.#handleOperation(request));
285
428
  }
286
- if (url.pathname === REALTIME_DO_WAKE_PATH) {
287
- return this.#serializePartition(() => this.#handleWake(request));
429
+ if (url.pathname === REALTIME_DO_FANOUT_PATH) {
430
+ // Beside the FIFO: a round that applied this commit may be waiting on
431
+ // the relay that delivers it here.
432
+ return this.#handleFanout(request);
433
+ }
434
+ if (url.pathname === REALTIME_DO_SHARDS_PATH) {
435
+ const { shard, token } = (await request.json());
436
+ await this.#state.storage.put(`shard:${shard}`, token);
437
+ return new Response(null, { status: 204 });
288
438
  }
289
439
  if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
290
440
  return this.#handleUpgrade(request);
@@ -487,18 +637,102 @@ export class SyncularRealtimeHost {
487
637
  return routes.fetch(routed);
488
638
  });
489
639
  }
490
- /** §8.3 wake: an external coordinated command landed; re-pull the delta. */
491
- async #handleWake(request) {
492
- const body = (await request.json().catch(() => null));
493
- const partition = body?.partition;
494
- if (typeof partition !== 'string') {
495
- return new Response('bad wake', { status: 400 });
496
- }
497
- // Wake only if this DO actually holds sockets (a cold DO has none — the
498
- // socket that would care is on this DO by construction, so a wake to a
499
- // DO with no sockets is simply a no-op, not an error).
500
- this.#getHub().wake(partition, 'catchup-required');
501
- return new Response(null, { status: 204 });
640
+ /**
641
+ * §8.9: deliver a message to this object's sockets, then relay it to every
642
+ * shard registered here. A relay that fails (a thrown request, any status
643
+ * but 2xx and 404) leaves the shard owing what the message carried, and the
644
+ * alarm retries it. This object answers 404 when it holds no socket and no
645
+ * shard.
646
+ */
647
+ async #handleFanout(request) {
648
+ const bytes = new Uint8Array(await request.arrayBuffer());
649
+ const message = decodeFanout(bytes);
650
+ const hub = this.#getHub();
651
+ if ('commit' in message) {
652
+ await hub.notifyCommit(message.partition, message.commit);
653
+ }
654
+ else if ('clientId' in message) {
655
+ await hub.notifySubscriptions(message.partition, message.clientId);
656
+ }
657
+ else if ('refresh' in message) {
658
+ await hub.refreshScopes(message.partition, message.refresh.actorId);
659
+ }
660
+ else {
661
+ if (message.owed.refresh)
662
+ await hub.refreshScopes(message.partition);
663
+ if (message.owed.registrations) {
664
+ hub.wake(message.partition, 'catchup-required');
665
+ }
666
+ if (message.owed.commitSeq !== undefined) {
667
+ hub.wakeBehind(message.partition, message.owed.commitSeq);
668
+ }
669
+ }
670
+ const shards = await this.#state.storage.list({ prefix: 'shard:' });
671
+ const owes = 'commit' in message
672
+ ? { commitSeq: message.commit.commitSeq }
673
+ : 'clientId' in message
674
+ ? { registrations: true }
675
+ : 'refresh' in message
676
+ ? { refresh: true }
677
+ : message.owed;
678
+ await Promise.all([...shards].map(async ([key, token]) => {
679
+ const shard = key.slice('shard:'.length);
680
+ const status = await this.#relay(shard, token, bytes);
681
+ if (status !== 'failed')
682
+ return;
683
+ const stored = await this.#state.storage.get(`owed:${shard}`);
684
+ const before = typeof stored === 'string'
685
+ ? JSON.parse(stored).owed
686
+ : {};
687
+ const commitSeq = Math.max(before.commitSeq ?? -1, owes.commitSeq ?? -1);
688
+ const owed = {
689
+ ...(commitSeq >= 0 ? { commitSeq } : {}),
690
+ ...(before.refresh || owes.refresh ? { refresh: true } : {}),
691
+ ...(before.registrations || owes.registrations
692
+ ? { registrations: true }
693
+ : {}),
694
+ };
695
+ await this.#state.storage.put(`owed:${shard}`, JSON.stringify({ partition: message.partition, owed }));
696
+ const at = await this.#state.storage.getAlarm();
697
+ if (at === null || at > Date.now() + 1_000) {
698
+ await this.#state.storage.setAlarm(Date.now() + 1_000);
699
+ }
700
+ }));
701
+ if (this.#state.getWebSockets().length > 0 || shards.size > 0) {
702
+ return new Response(null, { status: 204 });
703
+ }
704
+ this.#registeredShard = undefined;
705
+ return new Response(null, { status: 404 });
706
+ }
707
+ /**
708
+ * Send a fanout body to a registered shard. A shard that answers 404 holds
709
+ * no socket: it is removed with what it owes, unless it registered again
710
+ * with a new token meanwhile.
711
+ */
712
+ async #relay(shard, token, body) {
713
+ const namespace = this.#config.namespace;
714
+ if (namespace === undefined) {
715
+ throw new Error('a registered shard needs RealtimeDOConfig.namespace');
716
+ }
717
+ let status = 0;
718
+ try {
719
+ const response = await namespace.get(namespace.idFromName(shard)).fetch(new Request(`https://do${REALTIME_DO_FANOUT_PATH}`, {
720
+ method: 'POST',
721
+ body,
722
+ }));
723
+ status = response.status;
724
+ }
725
+ catch {
726
+ return 'failed';
727
+ }
728
+ if (status === 404) {
729
+ if ((await this.#state.storage.get(`shard:${shard}`)) === token) {
730
+ await this.#state.storage.delete(`shard:${shard}`);
731
+ await this.#state.storage.delete(`owed:${shard}`);
732
+ }
733
+ return 'gone';
734
+ }
735
+ return status >= 200 && status < 300 ? 'delivered' : 'failed';
502
736
  }
503
737
  /** The WebSocket upgrade: accept a hibernatable socket, connect the hub. */
504
738
  async #handleUpgrade(request) {
@@ -527,6 +761,27 @@ export class SyncularRealtimeHost {
527
761
  max: ATTACHMENT_LIMIT_BYTES,
528
762
  }));
529
763
  }
764
+ // §8.9: a shard registers with the partition's object after it accepts
765
+ // the socket (so a relay meanwhile does not find it empty and drop it)
766
+ // and before the hub reads the latest sequence, so a commit relayed
767
+ // after that read reaches the session.
768
+ const shard = request.headers.get(REALTIME_SHARD_HEADER);
769
+ if (shard !== null && this.#registeredShard !== shard) {
770
+ const namespace = this.#config.namespace;
771
+ if (namespace === undefined) {
772
+ throw new Error('a sharded realtime upgrade needs RealtimeDOConfig.namespace');
773
+ }
774
+ const registered = await namespace
775
+ .get(namespace.idFromName(identity.partition))
776
+ .fetch(new Request(new URL(REALTIME_DO_SHARDS_PATH, request.url), {
777
+ method: 'POST',
778
+ body: JSON.stringify({ shard, token: crypto.randomUUID() }),
779
+ }));
780
+ if (registered.status !== 204) {
781
+ throw new Error('shard registration failed');
782
+ }
783
+ this.#registeredShard = shard;
784
+ }
530
785
  const session = await hub.connect(this.#connectOptions(server, identity));
531
786
  this.#sessions.set(server, session);
532
787
  if ((await this.#state.storage.getAlarm()) === null) {
@@ -559,9 +814,11 @@ export class SyncularRealtimeHost {
559
814
  };
560
815
  }
561
816
  /**
562
- * The Durable Object alarm: send a §8.5 heartbeat to every socket and re-arm
563
- * while sockets remain. The frame goes straight to the hibernatable sockets,
564
- * so a heartbeat rebuilds no session.
817
+ * The Durable Object alarm: send a §8.5 heartbeat to every socket, retry
818
+ * every shard that owes a failed relay (§8.9), and re-arm: after the
819
+ * heartbeat interval while sockets remain, after one second while a shard
820
+ * still owes. The heartbeat goes straight to the hibernatable sockets, so it
821
+ * rebuilds no session.
565
822
  */
566
823
  async alarm() {
567
824
  const sockets = this.#state.getWebSockets();
@@ -574,8 +831,22 @@ export class SyncularRealtimeHost {
574
831
  // A closing socket; its close callback cleans up.
575
832
  }
576
833
  }
577
- if (sockets.length > 0) {
578
- await this.#state.storage.setAlarm(Date.now() + (this.#config.heartbeatIntervalMs ?? 30_000));
834
+ const storage = this.#state.storage;
835
+ for (const [key, value] of await storage.list({ prefix: 'owed:' })) {
836
+ const shard = key.slice('owed:'.length);
837
+ const token = await storage.get(`shard:${shard}`);
838
+ const message = JSON.parse(String(value));
839
+ // A newer failure may have merged into the record during the retry.
840
+ if ((await this.#relay(shard, token, encodeFanout(message))) ===
841
+ 'delivered' &&
842
+ (await storage.get(key)) === value) {
843
+ await storage.delete(key);
844
+ }
845
+ }
846
+ const owing = (await storage.list({ prefix: 'owed:' })).size > 0;
847
+ if (sockets.length > 0 || owing) {
848
+ await storage.setAlarm(Date.now() +
849
+ (owing ? 1_000 : (this.#config.heartbeatIntervalMs ?? 30_000)));
579
850
  }
580
851
  }
581
852
  /** Hibernation callback: an inbound frame. */
@@ -668,6 +939,8 @@ const REALTIME_ID_HEADER = {
668
939
  context: 'x-syncular-context',
669
940
  };
670
941
  const ADMIN_ACTIONS_HEADER = 'x-syncular-admin-actions';
942
+ /** The object name of the shard a sharded upgrade goes to (§8.9). */
943
+ const REALTIME_SHARD_HEADER = 'x-syncular-shard';
671
944
  /** Address a Worker-authorized admin request to the DO (Worker side). */
672
945
  export function adminRequestForDurableObject(request, routePath, target) {
673
946
  const source = new URL(request.url);
@@ -694,10 +967,18 @@ export function writeRequestIdentityHeaders(headers, identity) {
694
967
  headers.set(REALTIME_ID_HEADER.context, encodeURIComponent(identity.context));
695
968
  }
696
969
  }
697
- /** Write the resolved identity onto an upgrade request's headers (Worker side). */
698
- export function writeIdentityHeaders(headers, identity) {
970
+ /**
971
+ * Write the resolved identity, and the object name of a sharded upgrade's
972
+ * shard (§8.9), onto an upgrade request's headers (Worker side). A shard
973
+ * header the client sent is removed when the upgrade is not sharded.
974
+ */
975
+ export function writeIdentityHeaders(headers, identity, shard) {
699
976
  writeRequestIdentityHeaders(headers, identity);
700
977
  headers.set(REALTIME_ID_HEADER.clientId, identity.clientId);
978
+ if (shard === undefined)
979
+ headers.delete(REALTIME_SHARD_HEADER);
980
+ else
981
+ headers.set(REALTIME_SHARD_HEADER, shard);
701
982
  }
702
983
  function readIdentityHeaders(request) {
703
984
  const partition = request.headers.get(REALTIME_ID_HEADER.partition);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.78.3",
3
+ "version": "0.79.0",
4
4
  "description": "Cloudflare Workers adapter for the Syncular sync server",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -45,9 +45,9 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/core": "0.78.3",
49
- "@syncular/server": "0.78.3",
50
- "@syncular/server-hono": "0.78.3"
48
+ "@syncular/core": "0.79.0",
49
+ "@syncular/server": "0.79.0",
50
+ "@syncular/server-hono": "0.79.0"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@electric-sql/pglite": "^0.5.4",
package/src/index.ts CHANGED
@@ -28,6 +28,10 @@
28
28
  * `realtime` option to mount `/realtime`; its namespace also coordinates D1
29
29
  * `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
30
30
  * WebSockets are optional, the per-partition push queue is not.
31
+ *
32
+ * On PostgreSQL, `WorkersRealtimeOptions.shard` spreads sockets over several
33
+ * objects and leaves every HTTP round, segment and blob download to the
34
+ * Worker; the database lock serializes pushes (§6.3, §8.9).
31
35
  */
32
36
  import {
33
37
  acceptsEncoding,
@@ -35,7 +39,6 @@ import {
35
39
  D1ServerStorage,
36
40
  errorBody,
37
41
  SSP2_CONTENT_TYPE,
38
- type StoredCommit,
39
42
  SyncError,
40
43
  SyncularAdmin,
41
44
  type SyncServerConfig,
@@ -49,9 +52,9 @@ import {
49
52
  } from '@syncular/server-hono';
50
53
  import {
51
54
  adminRequestForDurableObject,
55
+ type DurableObjectNamespaceLike,
52
56
  OPERATIONS_DO_REQUEST_PATH,
53
57
  REALTIME_DO_UPGRADE_PATH,
54
- REALTIME_DO_WAKE_PATH,
55
58
  type RealtimeUpgradeIdentity,
56
59
  SYNC_DO_REQUEST_PATH,
57
60
  writeIdentityHeaders,
@@ -80,27 +83,10 @@ export interface ExecutionContextLike {
80
83
  passThroughOnException?(): void;
81
84
  }
82
85
 
83
- // -- Durable Object bindings (structural; no @cloudflare/workers-types dep) --
84
-
85
- /** A DO stub — the callable handle to one Durable Object instance. */
86
- export interface DurableObjectStubLike {
87
- fetch(request: Request): Promise<Response>;
88
- }
89
-
90
- /** A DO namespace binding: `idFromName` → `get(id)` → a stub. */
91
- export interface DurableObjectNamespaceLike {
92
- idFromName(name: string): DurableObjectIdLike;
93
- get(id: DurableObjectIdLike): DurableObjectStubLike;
94
- }
95
-
96
- export interface DurableObjectIdLike {
97
- toString(): string;
98
- }
99
-
100
86
  /**
101
87
  * Realtime wiring for `createWorkersFetchHandler`. Supplying it mounts the
102
- * `GET <mount>/realtime` upgrade route and uses the same namespace as the D1
103
- * `/sync` coordinator.
88
+ * `GET <mount>/realtime` upgrade route. Without `shard`, the same namespace
89
+ * is the `/sync` coordinator.
104
90
  */
105
91
  export interface WorkersRealtimeOptions {
106
92
  /** The DO namespace binding (wrangler `[[durable_objects.bindings]]`). */
@@ -127,6 +113,20 @@ export interface WorkersRealtimeOptions {
127
113
  * cookie.
128
114
  */
129
115
  readonly allowedOrigins?: readonly string[];
116
+ /**
117
+ * §8.9: hold the partition's sockets in several objects, one per value this
118
+ * returns for an authenticated upgrade (for example the Facility the
119
+ * session works in).
120
+ * The Worker then runs every `/sync` and `/operations` request itself, so
121
+ * the storage must lock partitions in the database (PostgreSQL), the
122
+ * Worker config's `realtime` must be `durableObjectRealtimeNotifier` over
123
+ * this namespace (or call it), and `RealtimeDOConfig.namespace` must be
124
+ * set. Presence reaches only peers in the same object.
125
+ */
126
+ readonly shard?: (
127
+ identity: RealtimeUpgradeIdentity,
128
+ request: Request,
129
+ ) => string;
130
130
  }
131
131
 
132
132
  /** Resolve the per-env realtime wiring for one Worker invocation. */
@@ -196,16 +196,18 @@ export interface WorkersFetchHandlerOptions<Env = unknown> {
196
196
  * ```
197
197
  *
198
198
  * With realtime over a Durable Object, pass the options form and thread the
199
- * `durableObjectRealtimeNotifier` into the config's `realtime` so HTTP pushes
200
- * wake the partition's DO:
199
+ * `durableObjectRealtimeNotifier` into the config's `realtime` so a commit the
200
+ * Worker applies reaches the partition's DO:
201
201
  *
202
202
  * ```ts
203
203
  * export default {
204
204
  * fetch: createWorkersFetchHandler<Env>({
205
- * config: (env) => ({
205
+ * config: (env, ctx) => ({
206
206
  * config: {
207
207
  * ...syncConfig(env),
208
- * realtime: durableObjectRealtimeNotifier(env.REALTIME),
208
+ * realtime: durableObjectRealtimeNotifier(env.REALTIME, {
209
+ * waitUntil: (promise) => ctx.waitUntil(promise),
210
+ * }),
209
211
  * },
210
212
  * authenticate: (req) => authenticate(req, env),
211
213
  * }),
@@ -243,10 +245,21 @@ export function createWorkersFetchHandler<Env = unknown>(
243
245
  if (upgraded !== undefined) return upgraded;
244
246
  }
245
247
  const honoOptions = await options.config(env, ctx);
248
+ if (
249
+ realtime?.shard !== undefined &&
250
+ (options.coordinator !== undefined ||
251
+ honoOptions.config.realtime === undefined)
252
+ ) {
253
+ throw new Error(
254
+ 'createWorkersFetchHandler: sharded realtime runs /sync in the Worker; pass no coordinator and set config.realtime to durableObjectRealtimeNotifier(namespace)',
255
+ );
256
+ }
246
257
  const coordinator =
247
258
  options.coordinator !== undefined
248
259
  ? await options.coordinator(env, ctx)
249
- : realtime;
260
+ : realtime?.shard === undefined
261
+ ? realtime
262
+ : undefined;
250
263
  const partitionPath =
251
264
  coordinator !== undefined ? partitionRequestPath(request) : undefined;
252
265
  if (coordinator !== undefined && partitionPath !== undefined) {
@@ -421,65 +434,44 @@ async function handleRealtimeUpgrade(
421
434
  if (identity === undefined) {
422
435
  return new Response('unauthorized', { status: 401 });
423
436
  }
424
- return forwardRealtimeUpgrade(request, realtime.namespace, identity);
437
+ return forwardRealtimeUpgrade(
438
+ request,
439
+ realtime.namespace,
440
+ identity,
441
+ realtime.shard?.(identity, request),
442
+ );
425
443
  }
426
444
 
427
445
  /**
428
- * Forward a `/realtime` upgrade to the partition's DO stub. The identity is
429
- * carried on internal headers to the DO's upgrade endpoint (the DO trusts the
430
- * Worker to have authenticated — the DO namespace is private to the Worker).
431
- * The DO is selected by `idFromName(partition)`: one DO per partition (§8.2).
446
+ * Forward a `/realtime` upgrade to the DO stub that holds the socket. The
447
+ * identity is carried on internal headers to the DO's upgrade endpoint (the DO
448
+ * trusts the Worker to have authenticated — the DO namespace is private to the
449
+ * Worker). Without `shard` the DO is `idFromName(partition)`, one per
450
+ * partition; with it, `idFromName(JSON.stringify([partition, shard]))` (§8.9).
432
451
  */
433
452
  export function forwardRealtimeUpgrade(
434
453
  request: Request,
435
454
  namespace: DurableObjectNamespaceLike,
436
455
  identity: RealtimeUpgradeIdentity,
456
+ shard?: string,
437
457
  ): Promise<Response> {
438
- const stub = namespace.get(namespace.idFromName(identity.partition));
458
+ const name =
459
+ shard === undefined
460
+ ? identity.partition
461
+ : JSON.stringify([identity.partition, shard]);
462
+ const stub = namespace.get(namespace.idFromName(name));
439
463
  const forwarded = new Request(
440
464
  new URL(REALTIME_DO_UPGRADE_PATH, request.url),
441
465
  request,
442
466
  );
443
- writeIdentityHeaders(forwarded.headers, identity);
467
+ writeIdentityHeaders(
468
+ forwarded.headers,
469
+ identity,
470
+ shard === undefined ? undefined : name,
471
+ );
444
472
  return stub.fetch(forwarded);
445
473
  }
446
474
 
447
- /**
448
- * A `RealtimeNotifier` (§8.2) for an external authoritative command host that
449
- * already serializes its D1 writes and must wake the partition's DO. The DO
450
- * calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
451
- * delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
452
- * Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
453
- *
454
- * Ordinary Workers `/sync` does not need this: it already lands on the DO and
455
- * fans out in-process. This wake is fire-and-forget:
456
- * a DO fetch failure never fails the push (the commit is already durable in
457
- * D1; the client's next pull or reconnect self-heals).
458
- */
459
- export function durableObjectRealtimeNotifier(
460
- namespace: DurableObjectNamespaceLike,
461
- ): {
462
- notifyCommit: (partition: string, commit: StoredCommit) => Promise<void>;
463
- } {
464
- return {
465
- async notifyCommit(partition: string): Promise<void> {
466
- try {
467
- const stub = namespace.get(namespace.idFromName(partition));
468
- // A synthetic origin — the DO only reads the path + JSON body.
469
- await stub.fetch(
470
- new Request(`https://do${REALTIME_DO_WAKE_PATH}`, {
471
- method: 'POST',
472
- headers: { 'content-type': 'application/json' },
473
- body: JSON.stringify({ partition }),
474
- }),
475
- );
476
- } catch {
477
- // Fire-and-forget: the commit is durable; the DO wake is best-effort.
478
- }
479
- },
480
- };
481
- }
482
-
483
475
  /**
484
476
  * Convenience: a `D1ServerStorage` over a Worker's D1 binding. `migrate` is
485
477
  * NOT called here — apply the schema with `wrangler d1 migrations` (see the