@syncular/server-workers 0.78.3 → 0.79.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 +19 -4
- package/dist/index.d.ts +31 -40
- package/dist/index.js +31 -44
- package/dist/realtime-do.d.ts +100 -18
- package/dist/realtime-do.js +313 -32
- package/package.json +4 -4
- package/src/index.ts +61 -69
- package/src/realtime-do.ts +450 -34
package/README.md
CHANGED
|
@@ -234,10 +234,25 @@ authoritative.
|
|
|
234
234
|
|
|
235
235
|
Authenticated HTTP `/sync` rounds are forwarded into the same partition DO as
|
|
236
236
|
socket rounds. Applied commits therefore fan out through the in-DO hub without
|
|
237
|
-
a post-commit wake race. `durableObjectRealtimeNotifier`
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
237
|
+
a post-commit wake race. `durableObjectRealtimeNotifier` sends a commit that
|
|
238
|
+
another host applied to the partition's DO, which delivers it to its sockets
|
|
239
|
+
as a delta; it is not a substitute for the `/sync` coordinator on D1.
|
|
240
|
+
|
|
241
|
+
### PostgreSQL: rounds in the Worker, sockets in shards (SPEC §8.9)
|
|
242
|
+
|
|
243
|
+
On PostgreSQL the database lock serializes pushes, so the Worker can run every
|
|
244
|
+
round itself. Set `shard` in the `realtime` options to place each socket in an
|
|
245
|
+
object named `JSON.stringify([partition, shard])`, set the Worker config's
|
|
246
|
+
`realtime` to `durableObjectRealtimeNotifier(env.REALTIME, { waitUntil })`
|
|
247
|
+
(it retries a failed request to the partition's object there), and pass
|
|
248
|
+
`namespace: env.REALTIME` in `RealtimeDOConfig`. The partition's object then
|
|
249
|
+
holds no socket: shards register with it and it relays every commit to them,
|
|
250
|
+
retrying a shard whose relay failed from its alarm. Call
|
|
251
|
+
`durableObjectRealtimeNotifier(env.REALTIME, { waitUntil }).refreshScopes(partition, actorId)`
|
|
252
|
+
after a grant changes; it reaches the sessions in every shard.
|
|
253
|
+
A scope resolver reads its grants under `prepareReadTransaction`, so a pull
|
|
254
|
+
never waits on a push. The setup, its costs and its Wrangler configuration are
|
|
255
|
+
on the docs page (`apps/docs/src/content/server-workers.md`).
|
|
241
256
|
|
|
242
257
|
### Wiring
|
|
243
258
|
|
package/dist/index.d.ts
CHANGED
|
@@ -28,10 +28,14 @@
|
|
|
28
28
|
* `realtime` option to mount `/realtime`; its namespace also coordinates D1
|
|
29
29
|
* `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
|
|
30
30
|
* WebSockets are optional, the per-partition push queue is not.
|
|
31
|
+
*
|
|
32
|
+
* On PostgreSQL, `WorkersRealtimeOptions.shard` spreads sockets over several
|
|
33
|
+
* objects and leaves every HTTP round, segment and blob download to the
|
|
34
|
+
* Worker; the database lock serializes pushes (§6.3, §8.9).
|
|
31
35
|
*/
|
|
32
|
-
import { type D1Database, D1ServerStorage, type
|
|
36
|
+
import { type D1Database, D1ServerStorage, type SyncServerConfig } from '@syncular/server';
|
|
33
37
|
import { type SyncularAdminGuards, type SyncularHonoOptions } from '@syncular/server-hono';
|
|
34
|
-
import { type RealtimeUpgradeIdentity } from './realtime-do.js';
|
|
38
|
+
import { type DurableObjectNamespaceLike, type RealtimeUpgradeIdentity } from './realtime-do.js';
|
|
35
39
|
export { type D1Database, D1ServerStorage } from '@syncular/server';
|
|
36
40
|
export * from './r2-stores.js';
|
|
37
41
|
export * from './realtime-do.js';
|
|
@@ -48,22 +52,10 @@ export interface ExecutionContextLike {
|
|
|
48
52
|
waitUntil(promise: Promise<unknown>): void;
|
|
49
53
|
passThroughOnException?(): void;
|
|
50
54
|
}
|
|
51
|
-
/** A DO stub — the callable handle to one Durable Object instance. */
|
|
52
|
-
export interface DurableObjectStubLike {
|
|
53
|
-
fetch(request: Request): Promise<Response>;
|
|
54
|
-
}
|
|
55
|
-
/** A DO namespace binding: `idFromName` → `get(id)` → a stub. */
|
|
56
|
-
export interface DurableObjectNamespaceLike {
|
|
57
|
-
idFromName(name: string): DurableObjectIdLike;
|
|
58
|
-
get(id: DurableObjectIdLike): DurableObjectStubLike;
|
|
59
|
-
}
|
|
60
|
-
export interface DurableObjectIdLike {
|
|
61
|
-
toString(): string;
|
|
62
|
-
}
|
|
63
55
|
/**
|
|
64
56
|
* Realtime wiring for `createWorkersFetchHandler`. Supplying it mounts the
|
|
65
|
-
* `GET <mount>/realtime` upgrade route
|
|
66
|
-
* `/sync` coordinator.
|
|
57
|
+
* `GET <mount>/realtime` upgrade route. Without `shard`, the same namespace
|
|
58
|
+
* is the `/sync` coordinator.
|
|
67
59
|
*/
|
|
68
60
|
export interface WorkersRealtimeOptions {
|
|
69
61
|
/** The DO namespace binding (wrangler `[[durable_objects.bindings]]`). */
|
|
@@ -85,6 +77,17 @@ export interface WorkersRealtimeOptions {
|
|
|
85
77
|
* cookie.
|
|
86
78
|
*/
|
|
87
79
|
readonly allowedOrigins?: readonly string[];
|
|
80
|
+
/**
|
|
81
|
+
* §8.9: hold the partition's sockets in several objects, one per value this
|
|
82
|
+
* returns for an authenticated upgrade (for example the Facility the
|
|
83
|
+
* session works in).
|
|
84
|
+
* The Worker then runs every `/sync` and `/operations` request itself, so
|
|
85
|
+
* the storage must lock partitions in the database (PostgreSQL), the
|
|
86
|
+
* Worker config's `realtime` must be `durableObjectRealtimeNotifier` over
|
|
87
|
+
* this namespace (or call it), and `RealtimeDOConfig.namespace` must be
|
|
88
|
+
* set. Presence reaches only peers in the same object.
|
|
89
|
+
*/
|
|
90
|
+
readonly shard?: (identity: RealtimeUpgradeIdentity, request: Request) => string;
|
|
88
91
|
}
|
|
89
92
|
/** Resolve the per-env realtime wiring for one Worker invocation. */
|
|
90
93
|
export type WorkersRealtimeFactory<Env = unknown> = (env: Env, ctx: ExecutionContextLike) => WorkersRealtimeOptions | Promise<WorkersRealtimeOptions>;
|
|
@@ -138,16 +141,18 @@ export interface WorkersFetchHandlerOptions<Env = unknown> {
|
|
|
138
141
|
* ```
|
|
139
142
|
*
|
|
140
143
|
* With realtime over a Durable Object, pass the options form and thread the
|
|
141
|
-
* `durableObjectRealtimeNotifier` into the config's `realtime` so
|
|
142
|
-
*
|
|
144
|
+
* `durableObjectRealtimeNotifier` into the config's `realtime` so a commit the
|
|
145
|
+
* Worker applies reaches the partition's DO:
|
|
143
146
|
*
|
|
144
147
|
* ```ts
|
|
145
148
|
* export default {
|
|
146
149
|
* fetch: createWorkersFetchHandler<Env>({
|
|
147
|
-
* config: (env) => ({
|
|
150
|
+
* config: (env, ctx) => ({
|
|
148
151
|
* config: {
|
|
149
152
|
* ...syncConfig(env),
|
|
150
|
-
* realtime: durableObjectRealtimeNotifier(env.REALTIME
|
|
153
|
+
* realtime: durableObjectRealtimeNotifier(env.REALTIME, {
|
|
154
|
+
* waitUntil: (promise) => ctx.waitUntil(promise),
|
|
155
|
+
* }),
|
|
151
156
|
* },
|
|
152
157
|
* authenticate: (req) => authenticate(req, env),
|
|
153
158
|
* }),
|
|
@@ -179,27 +184,13 @@ export declare function forwardSyncRequest(request: Request, namespace: DurableO
|
|
|
179
184
|
readonly context?: string;
|
|
180
185
|
}, path?: string): Promise<Response>;
|
|
181
186
|
/**
|
|
182
|
-
* Forward a `/realtime` upgrade to the
|
|
183
|
-
* carried on internal headers to the DO's upgrade endpoint (the DO
|
|
184
|
-
* Worker to have authenticated — the DO namespace is private to the
|
|
185
|
-
*
|
|
186
|
-
|
|
187
|
-
export declare function forwardRealtimeUpgrade(request: Request, namespace: DurableObjectNamespaceLike, identity: RealtimeUpgradeIdentity): Promise<Response>;
|
|
188
|
-
/**
|
|
189
|
-
* A `RealtimeNotifier` (§8.2) for an external authoritative command host that
|
|
190
|
-
* already serializes its D1 writes and must wake the partition's DO. The DO
|
|
191
|
-
* calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
|
|
192
|
-
* delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
|
|
193
|
-
* Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
|
|
194
|
-
*
|
|
195
|
-
* Ordinary Workers `/sync` does not need this: it already lands on the DO and
|
|
196
|
-
* fans out in-process. This wake is fire-and-forget:
|
|
197
|
-
* a DO fetch failure never fails the push (the commit is already durable in
|
|
198
|
-
* D1; the client's next pull or reconnect self-heals).
|
|
187
|
+
* Forward a `/realtime` upgrade to the DO stub that holds the socket. The
|
|
188
|
+
* identity is carried on internal headers to the DO's upgrade endpoint (the DO
|
|
189
|
+
* trusts the Worker to have authenticated — the DO namespace is private to the
|
|
190
|
+
* Worker). Without `shard` the DO is `idFromName(partition)`, one per
|
|
191
|
+
* partition; with it, `idFromName(JSON.stringify([partition, shard]))` (§8.9).
|
|
199
192
|
*/
|
|
200
|
-
export declare function
|
|
201
|
-
notifyCommit: (partition: string, commit: StoredCommit) => Promise<void>;
|
|
202
|
-
};
|
|
193
|
+
export declare function forwardRealtimeUpgrade(request: Request, namespace: DurableObjectNamespaceLike, identity: RealtimeUpgradeIdentity, shard?: string): Promise<Response>;
|
|
203
194
|
/**
|
|
204
195
|
* Convenience: a `D1ServerStorage` over a Worker's D1 binding. `migrate` is
|
|
205
196
|
* NOT called here — apply the schema with `wrangler d1 migrations` (see the
|
package/dist/index.js
CHANGED
|
@@ -28,10 +28,14 @@
|
|
|
28
28
|
* `realtime` option to mount `/realtime`; its namespace also coordinates D1
|
|
29
29
|
* `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
|
|
30
30
|
* WebSockets are optional, the per-partition push queue is not.
|
|
31
|
+
*
|
|
32
|
+
* On PostgreSQL, `WorkersRealtimeOptions.shard` spreads sockets over several
|
|
33
|
+
* objects and leaves every HTTP round, segment and blob download to the
|
|
34
|
+
* Worker; the database lock serializes pushes (§6.3, §8.9).
|
|
31
35
|
*/
|
|
32
36
|
import { acceptsEncoding, D1ServerStorage, errorBody, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, varyOnAcceptEncoding, } from '@syncular/server';
|
|
33
37
|
import { createSyncularAdminRoutes, createSyncularHono, } from '@syncular/server-hono';
|
|
34
|
-
import { adminRequestForDurableObject, OPERATIONS_DO_REQUEST_PATH, REALTIME_DO_UPGRADE_PATH,
|
|
38
|
+
import { adminRequestForDurableObject, OPERATIONS_DO_REQUEST_PATH, REALTIME_DO_UPGRADE_PATH, SYNC_DO_REQUEST_PATH, writeIdentityHeaders, writeRequestIdentityHeaders, } from './realtime-do.js';
|
|
35
39
|
export { D1ServerStorage } from '@syncular/server';
|
|
36
40
|
export * from './r2-stores.js';
|
|
37
41
|
export * from './realtime-do.js';
|
|
@@ -49,16 +53,18 @@ export * from './realtime-do.js';
|
|
|
49
53
|
* ```
|
|
50
54
|
*
|
|
51
55
|
* With realtime over a Durable Object, pass the options form and thread the
|
|
52
|
-
* `durableObjectRealtimeNotifier` into the config's `realtime` so
|
|
53
|
-
*
|
|
56
|
+
* `durableObjectRealtimeNotifier` into the config's `realtime` so a commit the
|
|
57
|
+
* Worker applies reaches the partition's DO:
|
|
54
58
|
*
|
|
55
59
|
* ```ts
|
|
56
60
|
* export default {
|
|
57
61
|
* fetch: createWorkersFetchHandler<Env>({
|
|
58
|
-
* config: (env) => ({
|
|
62
|
+
* config: (env, ctx) => ({
|
|
59
63
|
* config: {
|
|
60
64
|
* ...syncConfig(env),
|
|
61
|
-
* realtime: durableObjectRealtimeNotifier(env.REALTIME
|
|
65
|
+
* realtime: durableObjectRealtimeNotifier(env.REALTIME, {
|
|
66
|
+
* waitUntil: (promise) => ctx.waitUntil(promise),
|
|
67
|
+
* }),
|
|
62
68
|
* },
|
|
63
69
|
* authenticate: (req) => authenticate(req, env),
|
|
64
70
|
* }),
|
|
@@ -90,9 +96,16 @@ export function createWorkersFetchHandler(factoryOrOptions) {
|
|
|
90
96
|
return upgraded;
|
|
91
97
|
}
|
|
92
98
|
const honoOptions = await options.config(env, ctx);
|
|
99
|
+
if (realtime?.shard !== undefined &&
|
|
100
|
+
(options.coordinator !== undefined ||
|
|
101
|
+
honoOptions.config.realtime === undefined)) {
|
|
102
|
+
throw new Error('createWorkersFetchHandler: sharded realtime runs /sync in the Worker; pass no coordinator and set config.realtime to durableObjectRealtimeNotifier(namespace)');
|
|
103
|
+
}
|
|
93
104
|
const coordinator = options.coordinator !== undefined
|
|
94
105
|
? await options.coordinator(env, ctx)
|
|
95
|
-
: realtime
|
|
106
|
+
: realtime?.shard === undefined
|
|
107
|
+
? realtime
|
|
108
|
+
: undefined;
|
|
96
109
|
const partitionPath = coordinator !== undefined ? partitionRequestPath(request) : undefined;
|
|
97
110
|
if (coordinator !== undefined && partitionPath !== undefined) {
|
|
98
111
|
if (partitionPath === OPERATIONS_DO_REQUEST_PATH &&
|
|
@@ -228,50 +241,24 @@ async function handleRealtimeUpgrade(request, realtime) {
|
|
|
228
241
|
if (identity === undefined) {
|
|
229
242
|
return new Response('unauthorized', { status: 401 });
|
|
230
243
|
}
|
|
231
|
-
return forwardRealtimeUpgrade(request, realtime.namespace, identity);
|
|
244
|
+
return forwardRealtimeUpgrade(request, realtime.namespace, identity, realtime.shard?.(identity, request));
|
|
232
245
|
}
|
|
233
246
|
/**
|
|
234
|
-
* Forward a `/realtime` upgrade to the
|
|
235
|
-
* carried on internal headers to the DO's upgrade endpoint (the DO
|
|
236
|
-
* Worker to have authenticated — the DO namespace is private to the
|
|
237
|
-
*
|
|
247
|
+
* Forward a `/realtime` upgrade to the DO stub that holds the socket. The
|
|
248
|
+
* identity is carried on internal headers to the DO's upgrade endpoint (the DO
|
|
249
|
+
* trusts the Worker to have authenticated — the DO namespace is private to the
|
|
250
|
+
* Worker). Without `shard` the DO is `idFromName(partition)`, one per
|
|
251
|
+
* partition; with it, `idFromName(JSON.stringify([partition, shard]))` (§8.9).
|
|
238
252
|
*/
|
|
239
|
-
export function forwardRealtimeUpgrade(request, namespace, identity) {
|
|
240
|
-
const
|
|
253
|
+
export function forwardRealtimeUpgrade(request, namespace, identity, shard) {
|
|
254
|
+
const name = shard === undefined
|
|
255
|
+
? identity.partition
|
|
256
|
+
: JSON.stringify([identity.partition, shard]);
|
|
257
|
+
const stub = namespace.get(namespace.idFromName(name));
|
|
241
258
|
const forwarded = new Request(new URL(REALTIME_DO_UPGRADE_PATH, request.url), request);
|
|
242
|
-
writeIdentityHeaders(forwarded.headers, identity);
|
|
259
|
+
writeIdentityHeaders(forwarded.headers, identity, shard === undefined ? undefined : name);
|
|
243
260
|
return stub.fetch(forwarded);
|
|
244
261
|
}
|
|
245
|
-
/**
|
|
246
|
-
* A `RealtimeNotifier` (§8.2) for an external authoritative command host that
|
|
247
|
-
* already serializes its D1 writes and must wake the partition's DO. The DO
|
|
248
|
-
* calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
|
|
249
|
-
* delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
|
|
250
|
-
* Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
|
|
251
|
-
*
|
|
252
|
-
* Ordinary Workers `/sync` does not need this: it already lands on the DO and
|
|
253
|
-
* fans out in-process. This wake is fire-and-forget:
|
|
254
|
-
* a DO fetch failure never fails the push (the commit is already durable in
|
|
255
|
-
* D1; the client's next pull or reconnect self-heals).
|
|
256
|
-
*/
|
|
257
|
-
export function durableObjectRealtimeNotifier(namespace) {
|
|
258
|
-
return {
|
|
259
|
-
async notifyCommit(partition) {
|
|
260
|
-
try {
|
|
261
|
-
const stub = namespace.get(namespace.idFromName(partition));
|
|
262
|
-
// A synthetic origin — the DO only reads the path + JSON body.
|
|
263
|
-
await stub.fetch(new Request(`https://do${REALTIME_DO_WAKE_PATH}`, {
|
|
264
|
-
method: 'POST',
|
|
265
|
-
headers: { 'content-type': 'application/json' },
|
|
266
|
-
body: JSON.stringify({ partition }),
|
|
267
|
-
}));
|
|
268
|
-
}
|
|
269
|
-
catch {
|
|
270
|
-
// Fire-and-forget: the commit is durable; the DO wake is best-effort.
|
|
271
|
-
}
|
|
272
|
-
},
|
|
273
|
-
};
|
|
274
|
-
}
|
|
275
262
|
/**
|
|
276
263
|
* Convenience: a `D1ServerStorage` over a Worker's D1 binding. `migrate` is
|
|
277
264
|
* NOT called here — apply the schema with `wrangler d1 migrations` (see the
|
package/dist/realtime-do.d.ts
CHANGED
|
@@ -88,25 +88,59 @@
|
|
|
88
88
|
* sessions, and re-arms while sockets remain. The host owns the alarm: a
|
|
89
89
|
* subclass that needs another alarm schedule cannot share it.
|
|
90
90
|
*
|
|
91
|
-
* ##
|
|
91
|
+
* ## Fanout between objects (§8.9)
|
|
92
92
|
*
|
|
93
93
|
* Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
|
|
94
|
-
* are forwarded into this DO and fan out in-process.
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
94
|
+
* are forwarded into this DO and fan out in-process. A commit applied
|
|
95
|
+
* elsewhere reaches the partition's object through
|
|
96
|
+
* `durableObjectRealtimeNotifier`: a POST to the fanout path carrying the
|
|
97
|
+
* commit, which the object delivers to its hub as a delta.
|
|
98
|
+
*
|
|
99
|
+
* On PostgreSQL the Worker may shard sockets over several objects
|
|
100
|
+
* (`WorkersRealtimeOptions.shard`) and run every round itself. The
|
|
101
|
+
* partition's object (`idFromName(partition)`) then holds no socket: it keeps
|
|
102
|
+
* the names of the shard objects that registered with it in its storage and
|
|
103
|
+
* relays every fanout message to each of them. A shard registers when it
|
|
104
|
+
* accepts a socket, before its hub connects it; a shard that answers a relay with 404 (no socket
|
|
105
|
+
* left) is removed unless it registered again meanwhile. A shard's hub
|
|
106
|
+
* (`RealtimeHubConfig.fanout`) sends the commits of its own rounds through the
|
|
107
|
+
* partition's object too, so every shard, the shard itself included, receives
|
|
108
|
+
* each commit once. A host scope refresh (`refreshScopes` on the notifier)
|
|
109
|
+
* takes the same path. A relay that fails leaves a record of what the shard
|
|
110
|
+
* owes in the partition object's storage, and the alarm retries it every
|
|
111
|
+
* second until the shard answers or is removed.
|
|
98
112
|
*/
|
|
99
|
-
import { D1ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver, type ServerStorage, type SyncRequestContext } from '@syncular/server';
|
|
113
|
+
import { D1ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResult, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry, type RemoteOperationResolver, type RealtimeNotifier, type ServerStorage, type SyncularServerEvents, type SyncRequestContext } from '@syncular/server';
|
|
100
114
|
export interface DurableObjectStateLike {
|
|
101
115
|
acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
|
|
116
|
+
/** Keeps work alive after a response: the notifier's retries (§8.9). */
|
|
117
|
+
waitUntil(promise: Promise<unknown>): void;
|
|
102
118
|
getWebSockets(tag?: string): WebSocketLike[];
|
|
103
|
-
/** The
|
|
104
|
-
*
|
|
119
|
+
/** The DO storage API the host uses: the alarm drives §8.5 heartbeats, and
|
|
120
|
+
* the partition's object keeps its registered shards as keys. */
|
|
105
121
|
readonly storage: {
|
|
106
122
|
getAlarm(): Promise<number | null>;
|
|
107
123
|
setAlarm(scheduledTime: number): Promise<void>;
|
|
124
|
+
get(key: string): Promise<unknown>;
|
|
125
|
+
put(key: string, value: string): Promise<void>;
|
|
126
|
+
delete(key: string): Promise<boolean>;
|
|
127
|
+
list(options: {
|
|
128
|
+
prefix: string;
|
|
129
|
+
}): Promise<Map<string, unknown>>;
|
|
108
130
|
};
|
|
109
131
|
}
|
|
132
|
+
/** A DO stub: the callable handle to one Durable Object instance. */
|
|
133
|
+
export interface DurableObjectStubLike {
|
|
134
|
+
fetch(request: Request): Promise<Response>;
|
|
135
|
+
}
|
|
136
|
+
/** A DO namespace binding: `idFromName` → `get(id)` → a stub. */
|
|
137
|
+
export interface DurableObjectNamespaceLike {
|
|
138
|
+
idFromName(name: string): DurableObjectIdLike;
|
|
139
|
+
get(id: DurableObjectIdLike): DurableObjectStubLike;
|
|
140
|
+
}
|
|
141
|
+
export interface DurableObjectIdLike {
|
|
142
|
+
toString(): string;
|
|
143
|
+
}
|
|
110
144
|
export interface WebSocketLike {
|
|
111
145
|
accept?(): void;
|
|
112
146
|
send(data: string | ArrayBuffer | ArrayBufferView): void;
|
|
@@ -170,6 +204,15 @@ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> =
|
|
|
170
204
|
* the scope resolver per request (REMOTE.md §5.1).
|
|
171
205
|
*/
|
|
172
206
|
readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
|
|
207
|
+
/**
|
|
208
|
+
* The namespace this class is bound to. Required when the Worker shards
|
|
209
|
+
* sockets (`WorkersRealtimeOptions.shard`, §8.9): a shard registers with
|
|
210
|
+
* the partition's object through it, the partition's object relays every
|
|
211
|
+
* commit to the registered shards, and a shard's own rounds send their
|
|
212
|
+
* commits through the partition's object. The storage must lock
|
|
213
|
+
* partitions in the database (PostgreSQL); a D1 host refuses it.
|
|
214
|
+
*/
|
|
215
|
+
readonly namespace?: DurableObjectNamespaceLike;
|
|
173
216
|
};
|
|
174
217
|
/**
|
|
175
218
|
* The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
|
|
@@ -189,6 +232,38 @@ export declare class PresenceAttachmentError extends Error {
|
|
|
189
232
|
readonly attachmentLimitBytes: number;
|
|
190
233
|
});
|
|
191
234
|
}
|
|
235
|
+
/** Options of `durableObjectRealtimeNotifier`. */
|
|
236
|
+
export interface DurableObjectRealtimeNotifierOptions {
|
|
237
|
+
/**
|
|
238
|
+
* Keeps the retries of a failed request alive after the response: the
|
|
239
|
+
* Worker's `ctx.waitUntil`, or the Durable Object state's.
|
|
240
|
+
*/
|
|
241
|
+
readonly waitUntil: (promise: Promise<unknown>) => void;
|
|
242
|
+
/** Receives `realtime.relay_failed` when the retries give up. */
|
|
243
|
+
readonly events?: SyncularServerEvents;
|
|
244
|
+
/**
|
|
245
|
+
* Resolves when retry `attempt` (1 to 3) may start. Default: after 250 ms,
|
|
246
|
+
* 1 s and 4 s.
|
|
247
|
+
*/
|
|
248
|
+
readonly retryDelay?: (attempt: number) => Promise<void>;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* The `RealtimeNotifier` (§8.2, §8.9) that sends a commit, or a client's
|
|
252
|
+
* changed registrations, to the partition's Durable Object, which delivers it
|
|
253
|
+
* to its own sockets and relays it to every shard registered with it, retrying
|
|
254
|
+
* a shard whose relay failed. Pass it as the Worker config's `realtime`
|
|
255
|
+
* whenever the Worker applies commits itself: sharded sockets, or an external
|
|
256
|
+
* command host. A failed request to the partition's object never fails the
|
|
257
|
+
* push, whose commit is durable: the notifier retries it three times in
|
|
258
|
+
* `waitUntil` and emits `realtime.relay_failed` when the last one fails.
|
|
259
|
+
*
|
|
260
|
+
* `refreshScopes(partition, actorId?)` is `RealtimeHub.refreshScopes` for
|
|
261
|
+
* every object of the partition: call it after a grant changes. It throws when
|
|
262
|
+
* the partition's object did not take the refresh.
|
|
263
|
+
*/
|
|
264
|
+
export declare function durableObjectRealtimeNotifier(namespace: DurableObjectNamespaceLike, options: DurableObjectRealtimeNotifierOptions): RealtimeNotifier & {
|
|
265
|
+
refreshScopes(partition: string, actorId?: string): Promise<void>;
|
|
266
|
+
};
|
|
192
267
|
/** The identity the upgrade request must carry (resolved by the Worker). */
|
|
193
268
|
export interface RealtimeUpgradeIdentity {
|
|
194
269
|
readonly partition: string;
|
|
@@ -198,7 +273,8 @@ export interface RealtimeUpgradeIdentity {
|
|
|
198
273
|
readonly context?: string;
|
|
199
274
|
}
|
|
200
275
|
/** Internal control-request paths on the DO stub (never client-facing). */
|
|
201
|
-
export declare const
|
|
276
|
+
export declare const REALTIME_DO_FANOUT_PATH = "/__syncular_realtime/fanout";
|
|
277
|
+
export declare const REALTIME_DO_SHARDS_PATH = "/__syncular_realtime/shards";
|
|
202
278
|
export declare const REALTIME_DO_UPGRADE_PATH = "/__syncular_realtime/upgrade";
|
|
203
279
|
export declare const SYNC_DO_REQUEST_PATH = "/__syncular_realtime/sync";
|
|
204
280
|
export declare const OPERATIONS_DO_REQUEST_PATH = "/__syncular_realtime/operations";
|
|
@@ -242,10 +318,10 @@ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1Serv
|
|
|
242
318
|
constructor(state: DurableObjectStateLike, db: D1Database, config: RealtimeDOConfig<D1ServerStorage>);
|
|
243
319
|
constructor(state: DurableObjectStateLike, storage: S, config: RealtimeDOConfig<S>);
|
|
244
320
|
/**
|
|
245
|
-
* The DO `fetch` handler: routes the internal
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
321
|
+
* The DO `fetch` handler: routes the internal control paths. The Worker
|
|
322
|
+
* forwards `GET <mount>/realtime` here as an upgrade with the resolved
|
|
323
|
+
* identity in headers (see `forwardRealtimeUpgrade` in `index.ts`), and
|
|
324
|
+
* commits applied elsewhere arrive at the fanout path (§8.9).
|
|
249
325
|
*/
|
|
250
326
|
fetch(request: Request): Promise<Response>;
|
|
251
327
|
/**
|
|
@@ -268,9 +344,11 @@ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1Serv
|
|
|
268
344
|
*/
|
|
269
345
|
eraseScopeValue(options: EraseScopeValueOptions): Promise<EraseScopeValueResult>;
|
|
270
346
|
/**
|
|
271
|
-
* The Durable Object alarm: send a §8.5 heartbeat to every socket
|
|
272
|
-
*
|
|
273
|
-
*
|
|
347
|
+
* The Durable Object alarm: send a §8.5 heartbeat to every socket, retry
|
|
348
|
+
* every shard that owes a failed relay (§8.9), and re-arm: after the
|
|
349
|
+
* heartbeat interval while sockets remain, after one second while a shard
|
|
350
|
+
* still owes. The heartbeat goes straight to the hibernatable sockets, so it
|
|
351
|
+
* rebuilds no session.
|
|
274
352
|
*/
|
|
275
353
|
alarm(): Promise<void>;
|
|
276
354
|
/** Hibernation callback: an inbound frame. */
|
|
@@ -299,7 +377,11 @@ export declare function writeRequestIdentityHeaders(headers: Headers, identity:
|
|
|
299
377
|
readonly actorId: string;
|
|
300
378
|
readonly context?: string;
|
|
301
379
|
}): void;
|
|
302
|
-
/**
|
|
303
|
-
|
|
380
|
+
/**
|
|
381
|
+
* Write the resolved identity, and the object name of a sharded upgrade's
|
|
382
|
+
* shard (§8.9), onto an upgrade request's headers (Worker side). A shard
|
|
383
|
+
* header the client sent is removed when the upgrade is not sharded.
|
|
384
|
+
*/
|
|
385
|
+
export declare function writeIdentityHeaders(headers: Headers, identity: RealtimeUpgradeIdentity, shard?: string): void;
|
|
304
386
|
/** The D1 binding, re-declared structurally (see `d1-storage.ts`). */
|
|
305
387
|
export type D1Database = ConstructorParameters<typeof D1ServerStorage>[0];
|