@syncular/server-workers 0.57.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 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
- // clients are served the rows lane (§5.3 support floor).
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
- streams the object without buffering it in the isolate, and `GET /blobs/:id`
98
- re-authorizes the referencing rows before it reads the bytes. Choose
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 message after a wake**, the socket carries a serialized
215
- attachment (`ws.serializeAttachment` — the minimal `{clientId, actorId,
216
- partition}` §8.1 identity, written at accept time) but no live session. The
217
- host rebuilds it via `hub.connect(...)`, which reloads the registration list
218
- from the client record in D1 (exactly what a fresh upgrade does, §8.1).
219
- Rehydration is transparent to the client: it was greeted once at the real
220
- upgrade, so the rehydration `hello` is swallowed. Cursor and registrations
221
- are the durable truth in D1; nothing in-flight is lost because nothing
222
- in-flight can be hibernated.
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 });
@@ -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` (the `open` path streams them without buffering the object
19
- * in the isolate). Configure no `signedUrls` / `blobSignedUrls` for a binding
20
- * deployment; the core falls back to inline delivery.
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` (the `open` path streams them without buffering the object
19
- * in the isolate). Configure no `signedUrls` / `blobSignedUrls` for a binding
20
- * deployment; the core falls back to inline delivery.
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
  },
@@ -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
- * - **On the first serialized operation after a wake** (a socket frame, an
50
- * HTTP sync round, a command, a wake), every accepted socket has a
51
- * serialized attachment (`ws.serializeAttachment`, `{clientId, actorId,
52
- * partition}`, written at accept time) but no live session. The host
53
- * reconstructs the session of every socket in `getWebSockets()`, so
54
- * sockets that stayed quiet through the hibernation keep receiving
55
- * deltas. Each session is rebuilt via `hub.connect(...)`, which reloads the registration list from the
56
- * client record in D1 (the §8.1 load-at-upgrade rule — exactly what a
57
- * fresh upgrade does), then dispatch the message into it. Rehydration is
58
- * transparent to the client: it saw `hello` once at the real upgrade, so
59
- * the rehydration `hello` is swallowed (a one-shot filter on the send
60
- * wrapper). Cursor/registration are the durable truth in D1; nothing
61
- * in-flight is lost because nothing in-flight can be hibernated.
62
- *
63
- * So the serialized attachment is deliberately minimal — the three identity
64
- * fields `connect` needs. Everything else (`cursor`, `registrations`,
65
- * `lastKnownSeq`) is re-derived from D1 by `connect`, which is authoritative.
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. */