@syncular/server-workers 0.78.3 → 0.79.1

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
@@ -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` remains available for
238
- an external authoritative command host that already provides equally strong
239
- partition serialization and needs to wake the DO after its own commit; it is
240
- not a substitute for the `/sync` coordinator.
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 StoredCommit, type SyncServerConfig } from '@syncular/server';
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 and uses the same namespace as the D1
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 HTTP pushes
142
- * wake the partition's DO:
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 partition's DO stub. The identity is
183
- * carried on internal headers to the DO's upgrade endpoint (the DO trusts the
184
- * Worker to have authenticated — the DO namespace is private to the Worker).
185
- * The DO is selected by `idFromName(partition)`: one DO per partition (§8.2).
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 durableObjectRealtimeNotifier(namespace: DurableObjectNamespaceLike): {
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, REALTIME_DO_WAKE_PATH, SYNC_DO_REQUEST_PATH, writeIdentityHeaders, writeRequestIdentityHeaders, } from './realtime-do.js';
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 HTTP pushes
53
- * wake the partition's DO:
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 partition's DO stub. The identity is
235
- * carried on internal headers to the DO's upgrade endpoint (the DO trusts the
236
- * Worker to have authenticated — the DO namespace is private to the Worker).
237
- * The DO is selected by `idFromName(partition)`: one DO per partition (§8.2).
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 stub = namespace.get(namespace.idFromName(identity.partition));
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
@@ -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
- * ## The wake path (external-command fan-out)
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. An
95
- * external authoritative command host that already provides equivalent D1
96
- * partition serialization may call `/__wake` after its own commit so sockets
97
- * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
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 alarm half of the DO storage API; the host owns the alarm and
104
- * drives §8.5 heartbeats with it. */
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 REALTIME_DO_WAKE_PATH = "/__syncular_realtime/wake";
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 upgrade + wake control paths.
246
- * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
247
- * resolved identity in headers (see `forwardRealtimeUpgrade` in `index.ts`),
248
- * and accepts external-command wakes at `/__syncular_realtime/wake`.
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 and re-arm
272
- * while sockets remain. The frame goes straight to the hibernatable sockets,
273
- * so a heartbeat rebuilds no session.
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
- /** Write the resolved identity onto an upgrade request's headers (Worker side). */
303
- export declare function writeIdentityHeaders(headers: Headers, identity: RealtimeUpgradeIdentity): void;
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];