@syncular/server-workers 0.35.0 → 0.36.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**
@@ -71,7 +71,7 @@
71
71
  * partition serialization may call `/__wake` after its own commit so sockets
72
72
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
73
73
  */
74
- import { D1ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver } from '@syncular/server';
74
+ import { D1ServerStorage, type ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver } from '@syncular/server';
75
75
  export interface DurableObjectStateLike {
76
76
  acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
77
77
  getWebSockets(tag?: string): WebSocketLike[];
@@ -89,24 +89,32 @@ export type WebSocketPairLike = {
89
89
  1: WebSocketLike;
90
90
  };
91
91
  /**
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`.
92
+ * A storage the host coordinates: any `ServerStorage` with an idempotent
93
+ * `migrate()`, which the host runs before prune, erase and admin actions.
94
+ * `D1ServerStorage` and `PostgresServerStorage` qualify.
95
95
  */
96
- export type RealtimeDOConfig = ({
96
+ export type RealtimeHostStorage = ServerStorage & {
97
+ migrate(): Promise<void>;
98
+ };
99
+ /**
100
+ * The config of a `SyncularRealtimeHost`. `S` is the storage the host
101
+ * coordinates: `D1ServerStorage` when the host is built from a D1 binding,
102
+ * otherwise the storage passed to the constructor.
103
+ */
104
+ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> = ({
97
105
  /**
98
106
  * Preferred: build the complete canonical sync config around the DO's
99
- * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
107
+ * coordinated storage. Reuse this factory for the outer HTTP adapter
100
108
  * so HTTP-forwarded and socket rounds cannot drift by capability.
101
109
  */
102
- syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
110
+ syncConfig(storage: S): RealtimeHubConfig;
103
111
  readonly hubConfig?: never;
104
112
  } | {
105
113
  /**
106
114
  * @deprecated Use `syncConfig`. This compatibility shape predates the
107
115
  * canonical HTTP/realtime capability contract.
108
116
  */
109
- hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
117
+ hubConfig(storage: S): RealtimeHubConfigInput;
110
118
  readonly syncConfig?: never;
111
119
  }) & {
112
120
  /**
@@ -128,7 +136,7 @@ export type RealtimeDOConfig = ({
128
136
  };
129
137
  /**
130
138
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
131
- * the DO from its D1 binding, so it is omitted here).
139
+ * the DO, so it is omitted here).
132
140
  */
133
141
  export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
134
142
  /** The identity the upgrade request must carry (resolved by the Worker). */
@@ -156,7 +164,7 @@ export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
156
164
  *
157
165
  * ```ts
158
166
  * export class SyncularRealtimeDO extends DurableObject {
159
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
167
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
160
168
  * fetch(req: Request) { return this.#impl.fetch(req); }
161
169
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
162
170
  * return this.#impl.webSocketMessage(ws, msg);
@@ -169,9 +177,17 @@ export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
169
177
  * The reference host is `SyncularRealtimeHost` below; the tests drive it
170
178
  * directly over the DO double.
171
179
  */
172
- export declare class SyncularRealtimeHost {
180
+ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1ServerStorage> {
173
181
  #private;
174
- constructor(state: DurableObjectStateLike, db: D1Database, config: RealtimeDOConfig);
182
+ /**
183
+ * Host a partition over a D1 binding (the host builds the coordinated
184
+ * `D1ServerStorage`) or over a storage the caller built, such as a
185
+ * `PostgresServerStorage` behind Hyperdrive. The host owns the storage's
186
+ * serialization: every HTTP and socket round enters the partition FIFO
187
+ * before the storage is used.
188
+ */
189
+ constructor(state: DurableObjectStateLike, db: D1Database, config: RealtimeDOConfig<D1ServerStorage>);
190
+ constructor(state: DurableObjectStateLike, storage: S, config: RealtimeDOConfig<S>);
175
191
  /**
176
192
  * The DO `fetch` handler: routes the internal upgrade + wake control paths.
177
193
  * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
@@ -99,7 +99,7 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
99
99
  *
100
100
  * ```ts
101
101
  * export class SyncularRealtimeDO extends DurableObject {
102
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
102
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
103
103
  * fetch(req: Request) { return this.#impl.fetch(req); }
104
104
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
105
105
  * return this.#impl.webSocketMessage(ws, msg);
@@ -132,13 +132,14 @@ export class SyncularRealtimeHost {
132
132
  #rehydrated = false;
133
133
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
134
134
  #partitionTail = Promise.resolve();
135
- constructor(state, db, config) {
135
+ constructor(state, storage, config) {
136
136
  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
- });
137
+ this.#storage =
138
+ 'prepare' in storage
139
+ ? // One DO is selected per partition, and every round enters
140
+ // #serializePartition before this storage is used.
141
+ new D1ServerStorage(storage, { pushApplySerialized: true })
142
+ : storage;
142
143
  this.#config = config;
143
144
  }
144
145
  #getHub() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.35.0",
3
+ "version": "0.36.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/server": "0.36.0",
49
+ "@syncular/server-hono": "0.36.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@syncular/core": "0.35.0",
52
+ "@electric-sql/pglite": "^0.5.4",
53
+ "@syncular/core": "0.36.0",
53
54
  "miniflare": "4.20260701.0"
54
55
  }
55
56
  }
@@ -76,6 +76,7 @@ import {
76
76
  composeEvents,
77
77
  createRealtimeHub,
78
78
  D1ServerStorage,
79
+ type ServerStorage,
79
80
  errorBody,
80
81
  eraseScopeValue,
81
82
  type EraseScopeValueOptions,
@@ -119,50 +120,60 @@ export interface WebSocketLike {
119
120
  export type WebSocketPairLike = { 0: WebSocketLike; 1: WebSocketLike };
120
121
 
121
122
  /**
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`.
123
+ * A storage the host coordinates: any `ServerStorage` with an idempotent
124
+ * `migrate()`, which the host runs before prune, erase and admin actions.
125
+ * `D1ServerStorage` and `PostgresServerStorage` qualify.
125
126
  */
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;
127
+ export type RealtimeHostStorage = ServerStorage & {
128
+ migrate(): Promise<void>;
161
129
  };
162
130
 
131
+ /**
132
+ * The config of a `SyncularRealtimeHost`. `S` is the storage the host
133
+ * coordinates: `D1ServerStorage` when the host is built from a D1 binding,
134
+ * otherwise the storage passed to the constructor.
135
+ */
136
+ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> =
137
+ (
138
+ | {
139
+ /**
140
+ * Preferred: build the complete canonical sync config around the DO's
141
+ * coordinated storage. Reuse this factory for the outer HTTP adapter
142
+ * so HTTP-forwarded and socket rounds cannot drift by capability.
143
+ */
144
+ syncConfig(storage: S): RealtimeHubConfig;
145
+ readonly hubConfig?: never;
146
+ }
147
+ | {
148
+ /**
149
+ * @deprecated Use `syncConfig`. This compatibility shape predates the
150
+ * canonical HTTP/realtime capability contract.
151
+ */
152
+ hubConfig(storage: S): RealtimeHubConfigInput;
153
+ readonly syncConfig?: never;
154
+ }
155
+ ) & {
156
+ /**
157
+ * Events the admin console keeps for this partition; default 1000. The DO
158
+ * composes its event ring into the sync config's `events` and serves the
159
+ * admin routes the Worker forwards (`WorkersFetchHandlerOptions.admin`),
160
+ * so the event tail, metrics, failures and client drill-down see this
161
+ * partition's rounds.
162
+ */
163
+ readonly adminRingCapacity?: number;
164
+ /**
165
+ * Registered remote queries and commands (REMOTE.md). The Worker forwards
166
+ * `POST <mount>/operations` here, so a command applies on the partition
167
+ * FIFO and fans out to the partition's sockets like a pushed commit. A
168
+ * `RemoteOperationResolver` chooses the registry, the commit actor, and
169
+ * the scope resolver per request (REMOTE.md §5.1).
170
+ */
171
+ readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
172
+ };
173
+
163
174
  /**
164
175
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
165
- * the DO from its D1 binding, so it is omitted here).
176
+ * the DO, so it is omitted here).
166
177
  */
167
178
  export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
168
179
 
@@ -211,7 +222,7 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
211
222
  *
212
223
  * ```ts
213
224
  * export class SyncularRealtimeDO extends DurableObject {
214
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
225
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
215
226
  * fetch(req: Request) { return this.#impl.fetch(req); }
216
227
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
217
228
  * return this.#impl.webSocketMessage(ws, msg);
@@ -224,10 +235,12 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
224
235
  * The reference host is `SyncularRealtimeHost` below; the tests drive it
225
236
  * directly over the DO double.
226
237
  */
227
- export class SyncularRealtimeHost {
238
+ export class SyncularRealtimeHost<
239
+ S extends RealtimeHostStorage = D1ServerStorage,
240
+ > {
228
241
  readonly #state: DurableObjectStateLike;
229
- readonly #storage: D1ServerStorage;
230
- readonly #config: RealtimeDOConfig;
242
+ readonly #storage: RealtimeHostStorage;
243
+ readonly #config: RealtimeDOConfig<RealtimeHostStorage>;
231
244
  #hub: RealtimeHub | undefined;
232
245
  #admin: SyncularAdmin | undefined;
233
246
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
@@ -245,17 +258,35 @@ export class SyncularRealtimeHost {
245
258
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
246
259
  #partitionTail: Promise<void> = Promise.resolve();
247
260
 
261
+ /**
262
+ * Host a partition over a D1 binding (the host builds the coordinated
263
+ * `D1ServerStorage`) or over a storage the caller built, such as a
264
+ * `PostgresServerStorage` behind Hyperdrive. The host owns the storage's
265
+ * serialization: every HTTP and socket round enters the partition FIFO
266
+ * before the storage is used.
267
+ */
248
268
  constructor(
249
269
  state: DurableObjectStateLike,
250
270
  db: D1Database,
251
- config: RealtimeDOConfig,
271
+ config: RealtimeDOConfig<D1ServerStorage>,
272
+ );
273
+ constructor(
274
+ state: DurableObjectStateLike,
275
+ storage: S,
276
+ config: RealtimeDOConfig<S>,
277
+ );
278
+ constructor(
279
+ state: DurableObjectStateLike,
280
+ storage: D1Database | S,
281
+ config: RealtimeDOConfig<D1ServerStorage> | RealtimeDOConfig<S>,
252
282
  ) {
253
283
  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
- });
284
+ this.#storage =
285
+ 'prepare' in storage
286
+ ? // One DO is selected per partition, and every round enters
287
+ // #serializePartition before this storage is used.
288
+ new D1ServerStorage(storage, { pushApplySerialized: true })
289
+ : storage;
259
290
  this.#config = config;
260
291
  }
261
292