@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 +5 -0
- package/dist/realtime-do.d.ts +28 -12
- package/dist/realtime-do.js +8 -7
- package/package.json +5 -4
- package/src/realtime-do.ts +80 -49
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**
|
package/dist/realtime-do.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
|
|
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
|
package/dist/realtime-do.js
CHANGED
|
@@ -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,
|
|
135
|
+
constructor(state, storage, config) {
|
|
136
136
|
this.#state = state;
|
|
137
|
-
this.#storage =
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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.
|
|
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.
|
|
49
|
-
"@syncular/server-hono": "0.
|
|
48
|
+
"@syncular/server": "0.36.0",
|
|
49
|
+
"@syncular/server-hono": "0.36.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@
|
|
52
|
+
"@electric-sql/pglite": "^0.5.4",
|
|
53
|
+
"@syncular/core": "0.36.0",
|
|
53
54
|
"miniflare": "4.20260701.0"
|
|
54
55
|
}
|
|
55
56
|
}
|
package/src/realtime-do.ts
CHANGED
|
@@ -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
|
-
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
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
|
|
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
|
|
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:
|
|
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 =
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
|