@syncular/server-workers 0.36.0 → 0.37.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.
@@ -6,9 +6,10 @@
6
6
  * ## The shape
7
7
  *
8
8
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
9
- * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
10
- * partition's sync rounds, sockets, and commit fan-out live behind its
11
- * explicit FIFO — the per-partition serialization point D1 requires. Because
9
+ * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). A
10
+ * partition's writing rounds, socket rounds, and commit fan-out live behind
11
+ * its explicit FIFO — the per-partition serialization point D1 requires. An
12
+ * HTTP round without `PUSH_COMMIT` frames runs beside it. Because
12
13
  * the hub is the
13
14
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
14
15
  * socket fans its full delta out to the partition's other sockets with no
@@ -71,7 +72,7 @@
71
72
  * partition serialization may call `/__wake` after its own commit so sockets
72
73
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
73
74
  */
74
- import { D1ServerStorage, type ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver } from '@syncular/server';
75
+ import { D1ServerStorage, type ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver, type SyncRequestContext } from '@syncular/server';
75
76
  export interface DurableObjectStateLike {
76
77
  acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
77
78
  getWebSockets(tag?: string): WebSocketLike[];
@@ -195,6 +196,17 @@ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1Serv
195
196
  * and accepts external-command wakes at `/__syncular_realtime/wake`.
196
197
  */
197
198
  fetch(request: Request): Promise<Response>;
199
+ /**
200
+ * Run host work on the partition FIFO, after the sessions of hibernated
201
+ * sockets are rebuilt: a server-side command, a reaction drain, an import.
202
+ * `contextFor` returns the sync context of the hub for an actor; a commit
203
+ * made through it (`handleRemoteOperation`, `eraseScopeValue`, a push)
204
+ * reaches the matching sockets as a delta, so the host needs no wake.
205
+ */
206
+ serialized<T>(work: (contextFor: (identity: {
207
+ readonly partition: string;
208
+ readonly actorId: string;
209
+ }) => SyncRequestContext) => Promise<T>): Promise<T>;
198
210
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
199
211
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number>;
200
212
  /**
@@ -6,9 +6,10 @@
6
6
  * ## The shape
7
7
  *
8
8
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
9
- * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
10
- * partition's sync rounds, sockets, and commit fan-out live behind its
11
- * explicit FIFO — the per-partition serialization point D1 requires. Because
9
+ * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). A
10
+ * partition's writing rounds, socket rounds, and commit fan-out live behind
11
+ * its explicit FIFO — the per-partition serialization point D1 requires. An
12
+ * HTTP round without `PUSH_COMMIT` frames runs beside it. Because
12
13
  * the hub is the
13
14
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
14
15
  * socket fans its full delta out to the partition's other sockets with no
@@ -73,6 +74,7 @@
73
74
  */
74
75
  import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, eraseScopeValue, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
75
76
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
77
+ import { decodeMessage } from '@syncular/core';
76
78
  function isAttachment(value) {
77
79
  return (typeof value === 'object' &&
78
80
  value !== null &&
@@ -177,7 +179,21 @@ export class SyncularRealtimeHost {
177
179
  async fetch(request) {
178
180
  const url = new URL(request.url);
179
181
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
180
- return this.#serializePartition(() => this.#handleSync(request));
182
+ const bytes = new Uint8Array(await request.arrayBuffer());
183
+ // A round without PUSH_COMMIT frames writes only its own client
184
+ // record, so it runs beside the FIFO instead of queueing behind every
185
+ // other client's round. An undecodable request takes the FIFO and
186
+ // fails in the handler.
187
+ let pullOnly = false;
188
+ try {
189
+ pullOnly = decodeMessage(bytes).frames.every((frame) => frame.type !== 'PUSH_COMMIT');
190
+ }
191
+ catch { }
192
+ if (pullOnly) {
193
+ await this.#rehydrateSockets();
194
+ return this.#handleSync(request, bytes);
195
+ }
196
+ return this.#serializePartition(() => this.#handleSync(request, bytes));
181
197
  }
182
198
  if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
183
199
  return this.#serializePartition(() => this.#handleOperation(request));
@@ -193,6 +209,16 @@ export class SyncularRealtimeHost {
193
209
  }
194
210
  return new Response('not found', { status: 404 });
195
211
  }
212
+ /**
213
+ * Run host work on the partition FIFO, after the sessions of hibernated
214
+ * sockets are rebuilt: a server-side command, a reaction drain, an import.
215
+ * `contextFor` returns the sync context of the hub for an actor; a commit
216
+ * made through it (`handleRemoteOperation`, `eraseScopeValue`, a push)
217
+ * reaches the matching sockets as a delta, so the host needs no wake.
218
+ */
219
+ serialized(work) {
220
+ return this.#serializePartition(() => work((identity) => this.#getHub().requestContextFor(identity)));
221
+ }
196
222
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
197
223
  pruneCommitLog(options) {
198
224
  return this.#serializePartition(async () => {
@@ -284,7 +310,7 @@ export class SyncularRealtimeHost {
284
310
  return Response.json(errorBody(sync), { status: sync.httpStatus });
285
311
  }
286
312
  }
287
- async #handleSync(request) {
313
+ async #handleSync(request, bytes) {
288
314
  const contentType = request.headers
289
315
  .get('content-type')
290
316
  ?.split(';')[0]
@@ -299,7 +325,6 @@ export class SyncularRealtimeHost {
299
325
  return Response.json(errorBody(error), { status: error.httpStatus });
300
326
  }
301
327
  try {
302
- const bytes = new Uint8Array(await request.arrayBuffer());
303
328
  const out = await handleSyncRequest(bytes, this.#getHub().requestContextFor(identity));
304
329
  return new Response(out.slice().buffer, {
305
330
  status: 200,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.36.0",
3
+ "version": "0.37.0",
4
4
  "description": "Cloudflare Workers adapter for the Syncular sync server",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -45,12 +45,12 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/server": "0.36.0",
49
- "@syncular/server-hono": "0.36.0"
48
+ "@syncular/core": "0.37.0",
49
+ "@syncular/server": "0.37.0",
50
+ "@syncular/server-hono": "0.37.0"
50
51
  },
51
52
  "devDependencies": {
52
53
  "@electric-sql/pglite": "^0.5.4",
53
- "@syncular/core": "0.36.0",
54
54
  "miniflare": "4.20260701.0"
55
55
  }
56
56
  }
@@ -6,9 +6,10 @@
6
6
  * ## The shape
7
7
  *
8
8
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
9
- * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
10
- * partition's sync rounds, sockets, and commit fan-out live behind its
11
- * explicit FIFO — the per-partition serialization point D1 requires. Because
9
+ * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). A
10
+ * partition's writing rounds, socket rounds, and commit fan-out live behind
11
+ * its explicit FIFO — the per-partition serialization point D1 requires. An
12
+ * HTTP round without `PUSH_COMMIT` frames runs beside it. Because
12
13
  * the hub is the
13
14
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
14
15
  * socket fans its full delta out to the partition's other sockets with no
@@ -95,8 +96,10 @@ import {
95
96
  SyncError,
96
97
  SyncularAdmin,
97
98
  type SyncularErrorRoute,
99
+ type SyncRequestContext,
98
100
  } from '@syncular/server';
99
101
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
102
+ import { decodeMessage } from '@syncular/core';
100
103
 
101
104
  // -- The Durable Object platform surface this class uses (structural) -------
102
105
  // Declared locally so the package takes no `@cloudflare/workers-types`
@@ -335,7 +338,22 @@ export class SyncularRealtimeHost<
335
338
  async fetch(request: Request): Promise<Response> {
336
339
  const url = new URL(request.url);
337
340
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
338
- return this.#serializePartition(() => this.#handleSync(request));
341
+ const bytes = new Uint8Array(await request.arrayBuffer());
342
+ // A round without PUSH_COMMIT frames writes only its own client
343
+ // record, so it runs beside the FIFO instead of queueing behind every
344
+ // other client's round. An undecodable request takes the FIFO and
345
+ // fails in the handler.
346
+ let pullOnly = false;
347
+ try {
348
+ pullOnly = decodeMessage(bytes).frames.every(
349
+ (frame) => frame.type !== 'PUSH_COMMIT',
350
+ );
351
+ } catch {}
352
+ if (pullOnly) {
353
+ await this.#rehydrateSockets();
354
+ return this.#handleSync(request, bytes);
355
+ }
356
+ return this.#serializePartition(() => this.#handleSync(request, bytes));
339
357
  }
340
358
  if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
341
359
  return this.#serializePartition(() => this.#handleOperation(request));
@@ -352,6 +370,26 @@ export class SyncularRealtimeHost<
352
370
  return new Response('not found', { status: 404 });
353
371
  }
354
372
 
373
+ /**
374
+ * Run host work on the partition FIFO, after the sessions of hibernated
375
+ * sockets are rebuilt: a server-side command, a reaction drain, an import.
376
+ * `contextFor` returns the sync context of the hub for an actor; a commit
377
+ * made through it (`handleRemoteOperation`, `eraseScopeValue`, a push)
378
+ * reaches the matching sockets as a delta, so the host needs no wake.
379
+ */
380
+ serialized<T>(
381
+ work: (
382
+ contextFor: (identity: {
383
+ readonly partition: string;
384
+ readonly actorId: string;
385
+ }) => SyncRequestContext,
386
+ ) => Promise<T>,
387
+ ): Promise<T> {
388
+ return this.#serializePartition(() =>
389
+ work((identity) => this.#getHub().requestContextFor(identity)),
390
+ );
391
+ }
392
+
355
393
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
356
394
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number> {
357
395
  return this.#serializePartition(async () => {
@@ -462,7 +500,7 @@ export class SyncularRealtimeHost<
462
500
  }
463
501
  }
464
502
 
465
- async #handleSync(request: Request): Promise<Response> {
503
+ async #handleSync(request: Request, bytes: Uint8Array): Promise<Response> {
466
504
  const contentType = request.headers
467
505
  .get('content-type')
468
506
  ?.split(';')[0]
@@ -480,7 +518,6 @@ export class SyncularRealtimeHost<
480
518
  return Response.json(errorBody(error), { status: error.httpStatus });
481
519
  }
482
520
  try {
483
- const bytes = new Uint8Array(await request.arrayBuffer());
484
521
  const out = await handleSyncRequest(
485
522
  bytes,
486
523
  this.#getHub().requestContextFor(identity),