@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 +5 -0
- package/dist/realtime-do.d.ts +43 -15
- package/dist/realtime-do.js +39 -13
- package/package.json +5 -4
- package/src/realtime-do.ts +123 -55
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
|
@@ -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`).
|
|
10
|
-
* partition's
|
|
11
|
-
* explicit FIFO — the per-partition serialization point D1 requires.
|
|
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
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
|
|
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
|
/**
|
package/dist/realtime-do.js
CHANGED
|
@@ -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`).
|
|
10
|
-
* partition's
|
|
11
|
-
* explicit FIFO — the per-partition serialization point D1 requires.
|
|
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,
|
|
137
|
+
constructor(state, storage, config) {
|
|
136
138
|
this.#state = state;
|
|
137
|
-
this.#storage =
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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
|
-
|
|
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.
|
|
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/
|
|
49
|
-
"@syncular/server
|
|
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
54
|
"miniflare": "4.20260701.0"
|
|
54
55
|
}
|
|
55
56
|
}
|
package/src/realtime-do.ts
CHANGED
|
@@ -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`).
|
|
10
|
-
* partition's
|
|
11
|
-
* explicit FIFO — the per-partition serialization point D1 requires.
|
|
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
|
-
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
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
|
|
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
|
|
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:
|
|
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 =
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
-
|
|
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),
|