@syncular/server-workers 0.78.2 → 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.
- package/README.md +19 -4
- package/dist/index.d.ts +31 -40
- package/dist/index.js +31 -44
- package/dist/realtime-do.d.ts +100 -18
- package/dist/realtime-do.js +313 -32
- package/package.json +4 -4
- package/src/index.ts +61 -69
- package/src/realtime-do.ts +450 -34
package/dist/realtime-do.js
CHANGED
|
@@ -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
|
-
* ##
|
|
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.
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
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
|
|
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
|
|
252
|
-
*
|
|
253
|
-
*
|
|
254
|
-
*
|
|
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 ===
|
|
287
|
-
|
|
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
|
-
/**
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
this.#getHub()
|
|
501
|
-
|
|
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
|
|
563
|
-
*
|
|
564
|
-
*
|
|
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
|
-
|
|
578
|
-
|
|
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
|
-
/**
|
|
698
|
-
|
|
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.
|
|
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.
|
|
49
|
-
"@syncular/server": "0.
|
|
50
|
-
"@syncular/server-hono": "0.
|
|
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
|
|
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
|
|
200
|
-
*
|
|
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(
|
|
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
|
|
429
|
-
* carried on internal headers to the DO's upgrade endpoint (the DO
|
|
430
|
-
* Worker to have authenticated — the DO namespace is private to the
|
|
431
|
-
*
|
|
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
|
|
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(
|
|
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
|