@syncular/server-workers 0.35.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.
package/README.md CHANGED
@@ -318,6 +318,11 @@ compatible with the host's declared subset.
318
318
 
319
319
  Add the DO binding + migration to `wrangler.toml` (see `wrangler.toml.example`).
320
320
 
321
+ For PostgreSQL behind Hyperdrive, pass the storage instead of the D1 binding:
322
+ `new SyncularRealtimeHost(this.ctx, new PostgresServerStorage(executor), config)`
323
+ with `config: RealtimeDOConfig<PostgresServerStorage>`. The host runs the same
324
+ partition FIFO over it; `syncConfig` receives that storage.
325
+
321
326
  ### Real-workerd smoke: a manual recipe (why no automated lane)
322
327
 
323
328
  The hermetic tests (`test/realtime-do.test.ts`) drive the **real**
@@ -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 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[];
@@ -89,24 +90,32 @@ export type WebSocketPairLike = {
89
90
  1: WebSocketLike;
90
91
  };
91
92
  /**
92
- * The host env a `SyncularRealtimeDO` reads. Supplied by the DO runtime via
93
- * the class constructor's second arg. `DB` is the D1 binding (the same one the
94
- * outer Worker config uses); `configFactory` builds the hub config from `env`.
93
+ * A storage the host coordinates: any `ServerStorage` with an idempotent
94
+ * `migrate()`, which the host runs before prune, erase and admin actions.
95
+ * `D1ServerStorage` and `PostgresServerStorage` qualify.
95
96
  */
96
- export type RealtimeDOConfig = ({
97
+ export type RealtimeHostStorage = ServerStorage & {
98
+ migrate(): Promise<void>;
99
+ };
100
+ /**
101
+ * The config of a `SyncularRealtimeHost`. `S` is the storage the host
102
+ * coordinates: `D1ServerStorage` when the host is built from a D1 binding,
103
+ * otherwise the storage passed to the constructor.
104
+ */
105
+ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> = ({
97
106
  /**
98
107
  * Preferred: build the complete canonical sync config around the DO's
99
- * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
108
+ * coordinated storage. Reuse this factory for the outer HTTP adapter
100
109
  * so HTTP-forwarded and socket rounds cannot drift by capability.
101
110
  */
102
- syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
111
+ syncConfig(storage: S): RealtimeHubConfig;
103
112
  readonly hubConfig?: never;
104
113
  } | {
105
114
  /**
106
115
  * @deprecated Use `syncConfig`. This compatibility shape predates the
107
116
  * canonical HTTP/realtime capability contract.
108
117
  */
109
- hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
118
+ hubConfig(storage: S): RealtimeHubConfigInput;
110
119
  readonly syncConfig?: never;
111
120
  }) & {
112
121
  /**
@@ -128,7 +137,7 @@ export type RealtimeDOConfig = ({
128
137
  };
129
138
  /**
130
139
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
131
- * the DO from its D1 binding, so it is omitted here).
140
+ * the DO, so it is omitted here).
132
141
  */
133
142
  export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
134
143
  /** The identity the upgrade request must carry (resolved by the Worker). */
@@ -156,7 +165,7 @@ export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
156
165
  *
157
166
  * ```ts
158
167
  * export class SyncularRealtimeDO extends DurableObject {
159
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
168
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
160
169
  * fetch(req: Request) { return this.#impl.fetch(req); }
161
170
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
162
171
  * return this.#impl.webSocketMessage(ws, msg);
@@ -169,9 +178,17 @@ export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
169
178
  * The reference host is `SyncularRealtimeHost` below; the tests drive it
170
179
  * directly over the DO double.
171
180
  */
172
- export declare class SyncularRealtimeHost {
181
+ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1ServerStorage> {
173
182
  #private;
174
- constructor(state: DurableObjectStateLike, db: D1Database, config: RealtimeDOConfig);
183
+ /**
184
+ * Host a partition over a D1 binding (the host builds the coordinated
185
+ * `D1ServerStorage`) or over a storage the caller built, such as a
186
+ * `PostgresServerStorage` behind Hyperdrive. The host owns the storage's
187
+ * serialization: every HTTP and socket round enters the partition FIFO
188
+ * before the storage is used.
189
+ */
190
+ constructor(state: DurableObjectStateLike, db: D1Database, config: RealtimeDOConfig<D1ServerStorage>);
191
+ constructor(state: DurableObjectStateLike, storage: S, config: RealtimeDOConfig<S>);
175
192
  /**
176
193
  * The DO `fetch` handler: routes the internal upgrade + wake control paths.
177
194
  * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
@@ -179,6 +196,17 @@ export declare class SyncularRealtimeHost {
179
196
  * and accepts external-command wakes at `/__syncular_realtime/wake`.
180
197
  */
181
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>;
182
210
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
183
211
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number>;
184
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 &&
@@ -99,7 +101,7 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
99
101
  *
100
102
  * ```ts
101
103
  * export class SyncularRealtimeDO extends DurableObject {
102
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
104
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
103
105
  * fetch(req: Request) { return this.#impl.fetch(req); }
104
106
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
105
107
  * return this.#impl.webSocketMessage(ws, msg);
@@ -132,13 +134,14 @@ export class SyncularRealtimeHost {
132
134
  #rehydrated = false;
133
135
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
134
136
  #partitionTail = Promise.resolve();
135
- constructor(state, db, config) {
137
+ constructor(state, storage, config) {
136
138
  this.#state = state;
137
- this.#storage = new D1ServerStorage(db, {
138
- // Every HTTP/socket sync round enters #serializePartition before this
139
- // storage is used. One DO is selected per partition.
140
- pushApplySerialized: true,
141
- });
139
+ this.#storage =
140
+ 'prepare' in storage
141
+ ? // One DO is selected per partition, and every round enters
142
+ // #serializePartition before this storage is used.
143
+ new D1ServerStorage(storage, { pushApplySerialized: true })
144
+ : storage;
142
145
  this.#config = config;
143
146
  }
144
147
  #getHub() {
@@ -176,7 +179,21 @@ export class SyncularRealtimeHost {
176
179
  async fetch(request) {
177
180
  const url = new URL(request.url);
178
181
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
179
- 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));
180
197
  }
181
198
  if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
182
199
  return this.#serializePartition(() => this.#handleOperation(request));
@@ -192,6 +209,16 @@ export class SyncularRealtimeHost {
192
209
  }
193
210
  return new Response('not found', { status: 404 });
194
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
+ }
195
222
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
196
223
  pruneCommitLog(options) {
197
224
  return this.#serializePartition(async () => {
@@ -283,7 +310,7 @@ export class SyncularRealtimeHost {
283
310
  return Response.json(errorBody(sync), { status: sync.httpStatus });
284
311
  }
285
312
  }
286
- async #handleSync(request) {
313
+ async #handleSync(request, bytes) {
287
314
  const contentType = request.headers
288
315
  .get('content-type')
289
316
  ?.split(';')[0]
@@ -298,7 +325,6 @@ export class SyncularRealtimeHost {
298
325
  return Response.json(errorBody(error), { status: error.httpStatus });
299
326
  }
300
327
  try {
301
- const bytes = new Uint8Array(await request.arrayBuffer());
302
328
  const out = await handleSyncRequest(bytes, this.#getHub().requestContextFor(identity));
303
329
  return new Response(out.slice().buffer, {
304
330
  status: 200,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.35.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,11 +45,12 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/server": "0.35.0",
49
- "@syncular/server-hono": "0.35.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
- "@syncular/core": "0.35.0",
53
+ "@electric-sql/pglite": "^0.5.4",
53
54
  "miniflare": "4.20260701.0"
54
55
  }
55
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
@@ -76,6 +77,7 @@ import {
76
77
  composeEvents,
77
78
  createRealtimeHub,
78
79
  D1ServerStorage,
80
+ type ServerStorage,
79
81
  errorBody,
80
82
  eraseScopeValue,
81
83
  type EraseScopeValueOptions,
@@ -94,8 +96,10 @@ import {
94
96
  SyncError,
95
97
  SyncularAdmin,
96
98
  type SyncularErrorRoute,
99
+ type SyncRequestContext,
97
100
  } from '@syncular/server';
98
101
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
102
+ import { decodeMessage } from '@syncular/core';
99
103
 
100
104
  // -- The Durable Object platform surface this class uses (structural) -------
101
105
  // Declared locally so the package takes no `@cloudflare/workers-types`
@@ -119,50 +123,60 @@ export interface WebSocketLike {
119
123
  export type WebSocketPairLike = { 0: WebSocketLike; 1: WebSocketLike };
120
124
 
121
125
  /**
122
- * The host env a `SyncularRealtimeDO` reads. Supplied by the DO runtime via
123
- * the class constructor's second arg. `DB` is the D1 binding (the same one the
124
- * outer Worker config uses); `configFactory` builds the hub config from `env`.
126
+ * A storage the host coordinates: any `ServerStorage` with an idempotent
127
+ * `migrate()`, which the host runs before prune, erase and admin actions.
128
+ * `D1ServerStorage` and `PostgresServerStorage` qualify.
125
129
  */
126
- export type RealtimeDOConfig = (
127
- | {
128
- /**
129
- * Preferred: build the complete canonical sync config around the DO's
130
- * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
131
- * so HTTP-forwarded and socket rounds cannot drift by capability.
132
- */
133
- syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
134
- readonly hubConfig?: never;
135
- }
136
- | {
137
- /**
138
- * @deprecated Use `syncConfig`. This compatibility shape predates the
139
- * canonical HTTP/realtime capability contract.
140
- */
141
- hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
142
- readonly syncConfig?: never;
143
- }
144
- ) & {
145
- /**
146
- * Events the admin console keeps for this partition; default 1000. The DO
147
- * composes its event ring into the sync config's `events` and serves the
148
- * admin routes the Worker forwards (`WorkersFetchHandlerOptions.admin`),
149
- * so the event tail, metrics, failures and client drill-down see this
150
- * partition's rounds.
151
- */
152
- readonly adminRingCapacity?: number;
153
- /**
154
- * Registered remote queries and commands (REMOTE.md). The Worker forwards
155
- * `POST <mount>/operations` here, so a command applies on the partition
156
- * FIFO and fans out to the partition's sockets like a pushed commit. A
157
- * `RemoteOperationResolver` chooses the registry, the commit actor, and
158
- * the scope resolver per request (REMOTE.md §5.1).
159
- */
160
- readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
130
+ export type RealtimeHostStorage = ServerStorage & {
131
+ migrate(): Promise<void>;
161
132
  };
162
133
 
134
+ /**
135
+ * The config of a `SyncularRealtimeHost`. `S` is the storage the host
136
+ * coordinates: `D1ServerStorage` when the host is built from a D1 binding,
137
+ * otherwise the storage passed to the constructor.
138
+ */
139
+ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> =
140
+ (
141
+ | {
142
+ /**
143
+ * Preferred: build the complete canonical sync config around the DO's
144
+ * coordinated storage. Reuse this factory for the outer HTTP adapter
145
+ * so HTTP-forwarded and socket rounds cannot drift by capability.
146
+ */
147
+ syncConfig(storage: S): RealtimeHubConfig;
148
+ readonly hubConfig?: never;
149
+ }
150
+ | {
151
+ /**
152
+ * @deprecated Use `syncConfig`. This compatibility shape predates the
153
+ * canonical HTTP/realtime capability contract.
154
+ */
155
+ hubConfig(storage: S): RealtimeHubConfigInput;
156
+ readonly syncConfig?: never;
157
+ }
158
+ ) & {
159
+ /**
160
+ * Events the admin console keeps for this partition; default 1000. The DO
161
+ * composes its event ring into the sync config's `events` and serves the
162
+ * admin routes the Worker forwards (`WorkersFetchHandlerOptions.admin`),
163
+ * so the event tail, metrics, failures and client drill-down see this
164
+ * partition's rounds.
165
+ */
166
+ readonly adminRingCapacity?: number;
167
+ /**
168
+ * Registered remote queries and commands (REMOTE.md). The Worker forwards
169
+ * `POST <mount>/operations` here, so a command applies on the partition
170
+ * FIFO and fans out to the partition's sockets like a pushed commit. A
171
+ * `RemoteOperationResolver` chooses the registry, the commit actor, and
172
+ * the scope resolver per request (REMOTE.md §5.1).
173
+ */
174
+ readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
175
+ };
176
+
163
177
  /**
164
178
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
165
- * the DO from its D1 binding, so it is omitted here).
179
+ * the DO, so it is omitted here).
166
180
  */
167
181
  export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
168
182
 
@@ -211,7 +225,7 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
211
225
  *
212
226
  * ```ts
213
227
  * export class SyncularRealtimeDO extends DurableObject {
214
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
228
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
215
229
  * fetch(req: Request) { return this.#impl.fetch(req); }
216
230
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
217
231
  * return this.#impl.webSocketMessage(ws, msg);
@@ -224,10 +238,12 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
224
238
  * The reference host is `SyncularRealtimeHost` below; the tests drive it
225
239
  * directly over the DO double.
226
240
  */
227
- export class SyncularRealtimeHost {
241
+ export class SyncularRealtimeHost<
242
+ S extends RealtimeHostStorage = D1ServerStorage,
243
+ > {
228
244
  readonly #state: DurableObjectStateLike;
229
- readonly #storage: D1ServerStorage;
230
- readonly #config: RealtimeDOConfig;
245
+ readonly #storage: RealtimeHostStorage;
246
+ readonly #config: RealtimeDOConfig<RealtimeHostStorage>;
231
247
  #hub: RealtimeHub | undefined;
232
248
  #admin: SyncularAdmin | undefined;
233
249
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
@@ -245,17 +261,35 @@ export class SyncularRealtimeHost {
245
261
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
246
262
  #partitionTail: Promise<void> = Promise.resolve();
247
263
 
264
+ /**
265
+ * Host a partition over a D1 binding (the host builds the coordinated
266
+ * `D1ServerStorage`) or over a storage the caller built, such as a
267
+ * `PostgresServerStorage` behind Hyperdrive. The host owns the storage's
268
+ * serialization: every HTTP and socket round enters the partition FIFO
269
+ * before the storage is used.
270
+ */
248
271
  constructor(
249
272
  state: DurableObjectStateLike,
250
273
  db: D1Database,
251
- config: RealtimeDOConfig,
274
+ config: RealtimeDOConfig<D1ServerStorage>,
275
+ );
276
+ constructor(
277
+ state: DurableObjectStateLike,
278
+ storage: S,
279
+ config: RealtimeDOConfig<S>,
280
+ );
281
+ constructor(
282
+ state: DurableObjectStateLike,
283
+ storage: D1Database | S,
284
+ config: RealtimeDOConfig<D1ServerStorage> | RealtimeDOConfig<S>,
252
285
  ) {
253
286
  this.#state = state;
254
- this.#storage = new D1ServerStorage(db, {
255
- // Every HTTP/socket sync round enters #serializePartition before this
256
- // storage is used. One DO is selected per partition.
257
- pushApplySerialized: true,
258
- });
287
+ this.#storage =
288
+ 'prepare' in storage
289
+ ? // One DO is selected per partition, and every round enters
290
+ // #serializePartition before this storage is used.
291
+ new D1ServerStorage(storage, { pushApplySerialized: true })
292
+ : storage;
259
293
  this.#config = config;
260
294
  }
261
295
 
@@ -304,7 +338,22 @@ export class SyncularRealtimeHost {
304
338
  async fetch(request: Request): Promise<Response> {
305
339
  const url = new URL(request.url);
306
340
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
307
- 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));
308
357
  }
309
358
  if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
310
359
  return this.#serializePartition(() => this.#handleOperation(request));
@@ -321,6 +370,26 @@ export class SyncularRealtimeHost {
321
370
  return new Response('not found', { status: 404 });
322
371
  }
323
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
+
324
393
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
325
394
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number> {
326
395
  return this.#serializePartition(async () => {
@@ -431,7 +500,7 @@ export class SyncularRealtimeHost {
431
500
  }
432
501
  }
433
502
 
434
- async #handleSync(request: Request): Promise<Response> {
503
+ async #handleSync(request: Request, bytes: Uint8Array): Promise<Response> {
435
504
  const contentType = request.headers
436
505
  .get('content-type')
437
506
  ?.split(';')[0]
@@ -449,7 +518,6 @@ export class SyncularRealtimeHost {
449
518
  return Response.json(errorBody(error), { status: error.httpStatus });
450
519
  }
451
520
  try {
452
- const bytes = new Uint8Array(await request.arrayBuffer());
453
521
  const out = await handleSyncRequest(
454
522
  bytes,
455
523
  this.#getHub().requestContextFor(identity),