@syncular/server-workers 0.58.0 → 0.59.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 -13
- package/dist/index.d.ts +8 -0
- package/dist/index.js +7 -0
- package/dist/r2-stores.d.ts +7 -3
- package/dist/r2-stores.js +6 -3
- package/dist/realtime-do.d.ts +71 -17
- package/dist/realtime-do.js +197 -117
- package/package.json +4 -4
- package/src/index.ts +20 -0
- package/src/r2-stores.ts +8 -3
- package/src/realtime-do.ts +242 -118
package/README.md
CHANGED
|
@@ -69,8 +69,9 @@ function syncConfig(env: Env): SyncServerConfig {
|
|
|
69
69
|
// Worker serves the bytes inline through GET /segments/:id and
|
|
70
70
|
// GET /blobs/:id.
|
|
71
71
|
resolveScopes: (args) => resolveScopes(args, env),
|
|
72
|
-
// No `sqliteImageBuilder`: Workers has no SQLite engine, so bit-2
|
|
73
|
-
//
|
|
72
|
+
// No `sqliteImageBuilder`: Workers has no SQLite engine, so a bit-2
|
|
73
|
+
// client receives a stored image when one exists for its scope and the
|
|
74
|
+
// rows lane otherwise (§5.3 support floor).
|
|
74
75
|
};
|
|
75
76
|
}
|
|
76
77
|
|
|
@@ -94,8 +95,9 @@ the Worker reads those objects through the binding. The keys are
|
|
|
94
95
|
`{prefix}blob/{partition}/sha256/{hex}`.
|
|
95
96
|
|
|
96
97
|
Segments and blobs are served inline on the binding path. `GET /segments/:id`
|
|
97
|
-
|
|
98
|
-
re-authorizes the referencing rows before
|
|
98
|
+
buffers and compresses a segment of up to 16 MiB and streams a larger one
|
|
99
|
+
without buffering it, and `GET /blobs/:id` re-authorizes the referencing rows before
|
|
100
|
+
it reads the bytes. Choose
|
|
99
101
|
`S3SegmentStore` and `S3BlobStore` with `s3PresignedUrls` and
|
|
100
102
|
`s3PresignedBlobUrls` when clients should download from R2 directly; that path
|
|
101
103
|
needs the R2 endpoint plus an access key as secrets.
|
|
@@ -211,15 +213,18 @@ A `RealtimeSession` is in-memory only. The honest rule, as built:
|
|
|
211
213
|
async generator draining over `ws.send`; while pending it holds the DO's
|
|
212
214
|
event loop, so the DO cannot be evicted mid-round. (This is the same
|
|
213
215
|
property the §8.7 "one round in flight" rule already relies on.)
|
|
214
|
-
- **On the first
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
216
|
+
- **On the first event after a wake** (a socket message or close, an
|
|
217
|
+
upgrade, a forwarded `/sync`, `/operations` or admin request), each socket
|
|
218
|
+
carries a serialized attachment (`ws.serializeAttachment`: the minimal
|
|
219
|
+
`{clientId, actorId, partition}` §8.1 identity, written at accept time) but
|
|
220
|
+
no live session. The host rebuilds every socket's session once through
|
|
221
|
+
`hub.restore(...)`, which touches the partition and reads its latest
|
|
222
|
+
sequence once and reloads each registration list from the client record in
|
|
223
|
+
D1. Every event waits for that one rebuild, so a push never fans out while
|
|
224
|
+
sessions are missing. A restored session sends no `hello`: the client was
|
|
225
|
+
greeted at the real upgrade. Cursor and registrations are the durable truth
|
|
226
|
+
in D1; nothing in-flight is lost because nothing in-flight can be
|
|
227
|
+
hibernated.
|
|
223
228
|
|
|
224
229
|
So the serialized attachment is deliberately minimal — the three identity
|
|
225
230
|
fields `connect` needs. Everything else is re-derived from D1, which is
|
|
@@ -287,6 +292,7 @@ export class SyncularRealtimeDO extends DurableObject<Env> {
|
|
|
287
292
|
}
|
|
288
293
|
webSocketClose(ws: WebSocket) { return this.#host.webSocketClose(ws); }
|
|
289
294
|
webSocketError(ws: WebSocket) { return this.#host.webSocketError(ws); }
|
|
295
|
+
alarm() { return this.#host.alarm(); }
|
|
290
296
|
}
|
|
291
297
|
|
|
292
298
|
export default {
|
package/dist/index.d.ts
CHANGED
|
@@ -77,6 +77,14 @@ export interface WorkersRealtimeOptions {
|
|
|
77
77
|
readonly authenticate: (request: Request) => RealtimeUpgradeIdentity | undefined | Promise<RealtimeUpgradeIdentity | undefined>;
|
|
78
78
|
/** The mount path segment for the upgrade route; default `/realtime`. */
|
|
79
79
|
readonly path?: string;
|
|
80
|
+
/**
|
|
81
|
+
* Origins a browser upgrade may come from, such as
|
|
82
|
+
* `['https://app.example.com']`. When set, an upgrade whose `Origin` header
|
|
83
|
+
* names another origin answers 403 before `authenticate` runs. Native
|
|
84
|
+
* clients send no `Origin` and pass. Set it whenever `authenticate` reads a
|
|
85
|
+
* cookie.
|
|
86
|
+
*/
|
|
87
|
+
readonly allowedOrigins?: readonly string[];
|
|
80
88
|
}
|
|
81
89
|
/** Resolve the per-env realtime wiring for one Worker invocation. */
|
|
82
90
|
export type WorkersRealtimeFactory<Env = unknown> = (env: Env, ctx: ExecutionContextLike) => WorkersRealtimeOptions | Promise<WorkersRealtimeOptions>;
|
package/dist/index.js
CHANGED
|
@@ -217,6 +217,13 @@ async function handleRealtimeUpgrade(request, realtime) {
|
|
|
217
217
|
if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
|
|
218
218
|
return new Response('expected a websocket upgrade', { status: 426 });
|
|
219
219
|
}
|
|
220
|
+
const origin = request.headers.get('origin');
|
|
221
|
+
if (origin !== null &&
|
|
222
|
+
realtime.allowedOrigins !== undefined &&
|
|
223
|
+
!realtime.allowedOrigins.includes(origin)) {
|
|
224
|
+
const error = new SyncError('sync.forbidden', 'realtime upgrade origin is not allowed');
|
|
225
|
+
return Response.json(errorBody(error), { status: error.httpStatus });
|
|
226
|
+
}
|
|
220
227
|
const identity = await realtime.authenticate(request);
|
|
221
228
|
if (identity === undefined) {
|
|
222
229
|
return new Response('unauthorized', { status: 401 });
|
package/dist/r2-stores.d.ts
CHANGED
|
@@ -15,9 +15,11 @@
|
|
|
15
15
|
*
|
|
16
16
|
* There are no `presign*` methods here. A binding cannot mint a provider URL,
|
|
17
17
|
* so segments and blobs are served inline through `GET /segments/:id` and
|
|
18
|
-
* `GET /blobs/:id
|
|
19
|
-
* in the isolate
|
|
20
|
-
*
|
|
18
|
+
* `GET /blobs/:id`. Both routes stream the R2 object body through `open`
|
|
19
|
+
* without buffering it in the isolate; the blob route checks existence and
|
|
20
|
+
* authorizes the referencing rows before it opens the object. Configure no
|
|
21
|
+
* `signedUrls` / `blobSignedUrls` for a binding deployment, so the core
|
|
22
|
+
* serves inline.
|
|
21
23
|
*
|
|
22
24
|
* The binding surface is declared structurally below, so this package keeps
|
|
23
25
|
* taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
|
|
@@ -37,6 +39,8 @@ export interface R2ObjectLike {
|
|
|
37
39
|
/** Unquoted object ETag (the CAS token; R2 also reports `httpEtag`). */
|
|
38
40
|
readonly etag: string;
|
|
39
41
|
readonly size: number;
|
|
42
|
+
/** Upload time; the blob sweep's age for an object without metadata. */
|
|
43
|
+
readonly uploaded: Date;
|
|
40
44
|
readonly customMetadata?: Readonly<Record<string, string>>;
|
|
41
45
|
}
|
|
42
46
|
/** `R2ObjectBody`: the object plus its bytes. */
|
package/dist/r2-stores.js
CHANGED
|
@@ -15,9 +15,11 @@
|
|
|
15
15
|
*
|
|
16
16
|
* There are no `presign*` methods here. A binding cannot mint a provider URL,
|
|
17
17
|
* so segments and blobs are served inline through `GET /segments/:id` and
|
|
18
|
-
* `GET /blobs/:id
|
|
19
|
-
* in the isolate
|
|
20
|
-
*
|
|
18
|
+
* `GET /blobs/:id`. Both routes stream the R2 object body through `open`
|
|
19
|
+
* without buffering it in the isolate; the blob route checks existence and
|
|
20
|
+
* authorizes the referencing rows before it opens the object. Configure no
|
|
21
|
+
* `signedUrls` / `blobSignedUrls` for a binding deployment, so the core
|
|
22
|
+
* serves inline.
|
|
21
23
|
*
|
|
22
24
|
* The binding surface is declared structurally below, so this package keeps
|
|
23
25
|
* taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
|
|
@@ -55,6 +57,7 @@ function r2ObjectBucket(bucket) {
|
|
|
55
57
|
return {
|
|
56
58
|
etag: object.etag,
|
|
57
59
|
size: object.size,
|
|
60
|
+
lastModifiedMs: object.uploaded.getTime(),
|
|
58
61
|
metadata: metadataOf(object),
|
|
59
62
|
};
|
|
60
63
|
},
|
package/dist/realtime-do.d.ts
CHANGED
|
@@ -46,23 +46,45 @@
|
|
|
46
46
|
* an async generator draining over `ws.send`; while it is pending it holds
|
|
47
47
|
* the DO's event loop, so the DO cannot be evicted mid-round. (This is the
|
|
48
48
|
* same property the §8.7 "one round in flight" rule relies on.)
|
|
49
|
-
* - **
|
|
50
|
-
* HTTP sync round
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
49
|
+
* - **Before any entry point proceeds after a wake** (a socket frame or
|
|
50
|
+
* close, an HTTP sync round including a pull-only one, an upgrade, a
|
|
51
|
+
* command, an admin request), every accepted socket has a serialized
|
|
52
|
+
* attachment (`ws.serializeAttachment`: its identity, written at accept
|
|
53
|
+
* time, and its presence documents, rewritten on every change) but no
|
|
54
|
+
* live session. The host rebuilds the
|
|
55
|
+
* session of every socket in `getWebSockets()` once, through one promise
|
|
56
|
+
* every entry point awaits, so no commit fans out to a partly rebuilt hub
|
|
57
|
+
* and sockets that stayed quiet through the hibernation keep receiving
|
|
58
|
+
* deltas. `hub.restore(...)` reloads each registration list from the
|
|
59
|
+
* client record (the §8.1 load-at-upgrade rule), touches the partition
|
|
60
|
+
* and reads its latest sequence once, and sends no `hello`: the client
|
|
61
|
+
* was greeted at the real upgrade. Cursor/registration are the durable
|
|
62
|
+
* truth in storage; nothing in-flight is lost because nothing in-flight
|
|
63
|
+
* can be hibernated.
|
|
64
|
+
*
|
|
65
|
+
* The attachment holds what storage cannot: the identity `restore` needs and
|
|
66
|
+
* the connection's §8.6 presence documents, which `restore` seeds silently so
|
|
67
|
+
* a close after a wake still sends `leave` and a new socket still receives
|
|
68
|
+
* the snapshot. Everything else (`cursor`, `registrations`, `lastKnownSeq`)
|
|
69
|
+
* is re-derived from storage, which is authoritative.
|
|
70
|
+
*
|
|
71
|
+
* The attachment is one `Uint8Array`, so its structured-clone size is its
|
|
72
|
+
* byte length plus fixed framing: the identity as UTF-8 JSON and a newline,
|
|
73
|
+
* then per presence key a varint key length, the key's UTF-8 bytes, the
|
|
74
|
+
* document's UTF-8 JSON and a newline (a JSON text holds no raw newline).
|
|
75
|
+
* Each key costs at least 3 counted bytes (a non-empty key and `{}`) and at
|
|
76
|
+
* most 2 framing bytes below 128 key bytes, so a connection within
|
|
77
|
+
* `maxPresenceBytes` needs at most `cap + floor(2 * cap / 3)` presence
|
|
78
|
+
* bytes. The hub refuses a cap whose worst case leaves no room for an empty
|
|
79
|
+
* identity, and the upgrade refuses an identity that does not fit beside the
|
|
80
|
+
* worst case, so no presence change can overflow the attachment.
|
|
81
|
+
*
|
|
82
|
+
* ## Heartbeats (§8.5)
|
|
83
|
+
*
|
|
84
|
+
* The host arms the Durable Object alarm when a socket connects. `alarm()`
|
|
85
|
+
* sends `heartbeat` straight to every hibernatable socket, without rebuilding
|
|
86
|
+
* sessions, and re-arms while sockets remain. The host owns the alarm: a
|
|
87
|
+
* subclass that needs another alarm schedule cannot share it.
|
|
66
88
|
*
|
|
67
89
|
* ## The wake path (external-command fan-out)
|
|
68
90
|
*
|
|
@@ -76,6 +98,12 @@ import { D1ServerStorage, type EraseScopeValueOptions, type EraseScopeValueResul
|
|
|
76
98
|
export interface DurableObjectStateLike {
|
|
77
99
|
acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
|
|
78
100
|
getWebSockets(tag?: string): WebSocketLike[];
|
|
101
|
+
/** The alarm half of the DO storage API; the host owns the alarm and
|
|
102
|
+
* drives §8.5 heartbeats with it. */
|
|
103
|
+
readonly storage: {
|
|
104
|
+
getAlarm(): Promise<number | null>;
|
|
105
|
+
setAlarm(scheduledTime: number): Promise<void>;
|
|
106
|
+
};
|
|
79
107
|
}
|
|
80
108
|
export interface WebSocketLike {
|
|
81
109
|
accept?(): void;
|
|
@@ -126,6 +154,12 @@ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> =
|
|
|
126
154
|
* partition's rounds.
|
|
127
155
|
*/
|
|
128
156
|
readonly adminRingCapacity?: number;
|
|
157
|
+
/**
|
|
158
|
+
* §8.5 heartbeat interval in ms; default 30000. The host sends `heartbeat`
|
|
159
|
+
* to every socket from the Durable Object alarm, which stays armed while
|
|
160
|
+
* sockets are connected.
|
|
161
|
+
*/
|
|
162
|
+
readonly heartbeatIntervalMs?: number;
|
|
129
163
|
/**
|
|
130
164
|
* Registered remote queries and commands (REMOTE.md). The Worker forwards
|
|
131
165
|
* `POST <mount>/operations` here, so a command applies on the partition
|
|
@@ -140,6 +174,19 @@ export type RealtimeDOConfig<S extends RealtimeHostStorage = D1ServerStorage> =
|
|
|
140
174
|
* the DO, so it is omitted here).
|
|
141
175
|
*/
|
|
142
176
|
export type RealtimeHubConfigInput = Omit<RealtimeHubConfig, 'storage'>;
|
|
177
|
+
/** `maxPresenceBytes` leaves no room in a socket attachment for an empty
|
|
178
|
+
* identity beside a full presence budget (§8.6.1). */
|
|
179
|
+
export declare class PresenceAttachmentError extends Error {
|
|
180
|
+
readonly details: {
|
|
181
|
+
readonly maxPresenceBytes: number;
|
|
182
|
+
readonly attachmentLimitBytes: number;
|
|
183
|
+
};
|
|
184
|
+
readonly code = "realtime.presence_exceeds_attachment";
|
|
185
|
+
constructor(details: {
|
|
186
|
+
readonly maxPresenceBytes: number;
|
|
187
|
+
readonly attachmentLimitBytes: number;
|
|
188
|
+
});
|
|
189
|
+
}
|
|
143
190
|
/** The identity the upgrade request must carry (resolved by the Worker). */
|
|
144
191
|
export interface RealtimeUpgradeIdentity {
|
|
145
192
|
readonly partition: string;
|
|
@@ -172,6 +219,7 @@ export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
|
|
|
172
219
|
* }
|
|
173
220
|
* webSocketClose(ws: WebSocket) { return this.#impl.webSocketClose(ws); }
|
|
174
221
|
* webSocketError(ws: WebSocket) { return this.#impl.webSocketError(ws); }
|
|
222
|
+
* alarm() { return this.#impl.alarm(); }
|
|
175
223
|
* }
|
|
176
224
|
* ```
|
|
177
225
|
*
|
|
@@ -214,6 +262,12 @@ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1Serv
|
|
|
214
262
|
* call, its delete commit fanned out to connected sockets.
|
|
215
263
|
*/
|
|
216
264
|
eraseScopeValue(options: EraseScopeValueOptions): Promise<EraseScopeValueResult>;
|
|
265
|
+
/**
|
|
266
|
+
* The Durable Object alarm: send a §8.5 heartbeat to every socket and re-arm
|
|
267
|
+
* while sockets remain. The frame goes straight to the hibernatable sockets,
|
|
268
|
+
* so a heartbeat rebuilds no session.
|
|
269
|
+
*/
|
|
270
|
+
alarm(): Promise<void>;
|
|
217
271
|
/** Hibernation callback: an inbound frame. */
|
|
218
272
|
webSocketMessage(ws: WebSocketLike, message: ArrayBuffer | string): Promise<void>;
|
|
219
273
|
/** Hibernation callback: the socket closed. */
|