@syncular/server-workers 0.34.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 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
@@ -181,6 +197,11 @@ export declare class SyncularRealtimeHost {
181
197
  fetch(request: Request): Promise<Response>;
182
198
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
183
199
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number>;
200
+ /**
201
+ * §4.6.1 scope-value erasure on the partition FIFO: one budgeted step per
202
+ * call, its delete commit fanned out to connected sockets.
203
+ */
204
+ eraseScopeValue(options: EraseScopeValueOptions): Promise<EraseScopeValueResult>;
184
205
  /** Hibernation callback: an inbound frame. */
185
206
  webSocketMessage(ws: WebSocketLike, message: ArrayBuffer | string): Promise<void>;
186
207
  /** Hibernation callback: the socket closed. */
@@ -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 { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
74
+ import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, eraseScopeValue, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
75
75
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
76
76
  function isAttachment(value) {
77
77
  return (typeof value === 'object' &&
@@ -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() {
@@ -199,6 +200,19 @@ export class SyncularRealtimeHost {
199
200
  return pruneCommitLog({ ...options, storage: this.#storage });
200
201
  });
201
202
  }
203
+ /**
204
+ * §4.6.1 scope-value erasure on the partition FIFO: one budgeted step per
205
+ * call, its delete commit fanned out to connected sockets.
206
+ */
207
+ eraseScopeValue(options) {
208
+ return this.#serializePartition(async () => {
209
+ await this.#storage.migrate();
210
+ return eraseScopeValue(this.#getHub().requestContextFor({
211
+ partition: options.partition,
212
+ actorId: options.actorId ?? 'syncular.erase',
213
+ }), options);
214
+ });
215
+ }
202
216
  #serializePartition(operation) {
203
217
  const run = async () => {
204
218
  await this.#rehydrateSockets();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.34.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.34.0",
49
- "@syncular/server-hono": "0.34.0"
48
+ "@syncular/server": "0.36.0",
49
+ "@syncular/server-hono": "0.36.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@syncular/core": "0.34.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,7 +76,11 @@ import {
76
76
  composeEvents,
77
77
  createRealtimeHub,
78
78
  D1ServerStorage,
79
+ type ServerStorage,
79
80
  errorBody,
81
+ eraseScopeValue,
82
+ type EraseScopeValueOptions,
83
+ type EraseScopeValueResult,
80
84
  handleRemoteOperation,
81
85
  handleSyncRequest,
82
86
  pruneCommitLog,
@@ -116,50 +120,60 @@ export interface WebSocketLike {
116
120
  export type WebSocketPairLike = { 0: WebSocketLike; 1: WebSocketLike };
117
121
 
118
122
  /**
119
- * The host env a `SyncularRealtimeDO` reads. Supplied by the DO runtime via
120
- * the class constructor's second arg. `DB` is the D1 binding (the same one the
121
- * 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.
122
126
  */
123
- export type RealtimeDOConfig = (
124
- | {
125
- /**
126
- * Preferred: build the complete canonical sync config around the DO's
127
- * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
128
- * so HTTP-forwarded and socket rounds cannot drift by capability.
129
- */
130
- syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
131
- readonly hubConfig?: never;
132
- }
133
- | {
134
- /**
135
- * @deprecated Use `syncConfig`. This compatibility shape predates the
136
- * canonical HTTP/realtime capability contract.
137
- */
138
- hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
139
- readonly syncConfig?: never;
140
- }
141
- ) & {
142
- /**
143
- * Events the admin console keeps for this partition; default 1000. The DO
144
- * composes its event ring into the sync config's `events` and serves the
145
- * admin routes the Worker forwards (`WorkersFetchHandlerOptions.admin`),
146
- * so the event tail, metrics, failures and client drill-down see this
147
- * partition's rounds.
148
- */
149
- readonly adminRingCapacity?: number;
150
- /**
151
- * Registered remote queries and commands (REMOTE.md). The Worker forwards
152
- * `POST <mount>/operations` here, so a command applies on the partition
153
- * FIFO and fans out to the partition's sockets like a pushed commit. A
154
- * `RemoteOperationResolver` chooses the registry, the commit actor, and
155
- * the scope resolver per request (REMOTE.md §5.1).
156
- */
157
- readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
127
+ export type RealtimeHostStorage = ServerStorage & {
128
+ migrate(): Promise<void>;
158
129
  };
159
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
+
160
174
  /**
161
175
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
162
- * the DO from its D1 binding, so it is omitted here).
176
+ * the DO, so it is omitted here).
163
177
  */
164
178
  export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
165
179
 
@@ -208,7 +222,7 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
208
222
  *
209
223
  * ```ts
210
224
  * export class SyncularRealtimeDO extends DurableObject {
211
- * #impl = new SyncularRealtimeHost(this.ctx, this.env, config);
225
+ * #impl = new SyncularRealtimeHost(this.ctx, this.env.DB, config);
212
226
  * fetch(req: Request) { return this.#impl.fetch(req); }
213
227
  * webSocketMessage(ws: WebSocket, msg: ArrayBuffer | string) {
214
228
  * return this.#impl.webSocketMessage(ws, msg);
@@ -221,10 +235,12 @@ export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
221
235
  * The reference host is `SyncularRealtimeHost` below; the tests drive it
222
236
  * directly over the DO double.
223
237
  */
224
- export class SyncularRealtimeHost {
238
+ export class SyncularRealtimeHost<
239
+ S extends RealtimeHostStorage = D1ServerStorage,
240
+ > {
225
241
  readonly #state: DurableObjectStateLike;
226
- readonly #storage: D1ServerStorage;
227
- readonly #config: RealtimeDOConfig;
242
+ readonly #storage: RealtimeHostStorage;
243
+ readonly #config: RealtimeDOConfig<RealtimeHostStorage>;
228
244
  #hub: RealtimeHub | undefined;
229
245
  #admin: SyncularAdmin | undefined;
230
246
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
@@ -242,17 +258,35 @@ export class SyncularRealtimeHost {
242
258
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
243
259
  #partitionTail: Promise<void> = Promise.resolve();
244
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
+ */
245
268
  constructor(
246
269
  state: DurableObjectStateLike,
247
270
  db: D1Database,
248
- 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>,
249
282
  ) {
250
283
  this.#state = state;
251
- this.#storage = new D1ServerStorage(db, {
252
- // Every HTTP/socket sync round enters #serializePartition before this
253
- // storage is used. One DO is selected per partition.
254
- pushApplySerialized: true,
255
- });
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;
256
290
  this.#config = config;
257
291
  }
258
292
 
@@ -326,6 +360,25 @@ export class SyncularRealtimeHost {
326
360
  });
327
361
  }
328
362
 
363
+ /**
364
+ * §4.6.1 scope-value erasure on the partition FIFO: one budgeted step per
365
+ * call, its delete commit fanned out to connected sockets.
366
+ */
367
+ eraseScopeValue(
368
+ options: EraseScopeValueOptions,
369
+ ): Promise<EraseScopeValueResult> {
370
+ return this.#serializePartition(async () => {
371
+ await this.#storage.migrate();
372
+ return eraseScopeValue(
373
+ this.#getHub().requestContextFor({
374
+ partition: options.partition,
375
+ actorId: options.actorId ?? 'syncular.erase',
376
+ }),
377
+ options,
378
+ );
379
+ });
380
+ }
381
+
329
382
  #serializePartition<T>(operation: () => Promise<T>): Promise<T> {
330
383
  const run = async (): Promise<T> => {
331
384
  await this.#rehydrateSockets();