@syncular/server-workers 0.32.1 → 0.33.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
@@ -37,47 +37,37 @@ writer fails closed before app-row mutation.
37
37
 
38
38
  ```ts
39
39
  // src/worker.ts
40
+ import { D1ServerStorage, type SyncServerConfig } from '@syncular/server';
40
41
  import {
41
- D1ServerStorage,
42
- S3BlobStore,
43
- S3SegmentStore,
44
- s3PresignedBlobUrls,
45
- s3PresignedUrls,
46
- type SyncServerConfig,
47
- } from '@syncular/server';
48
- import { createWorkersFetchHandler } from '@syncular/server-workers';
42
+ createWorkersFetchHandler,
43
+ R2BlobStore,
44
+ R2SegmentStore,
45
+ } from '@syncular/server-workers';
49
46
  import { schema } from './syncular.generated'; // typegen output
50
47
 
51
48
  interface Env {
52
49
  DB: D1Database; // wrangler.toml [[d1_databases]] binding = "DB"
50
+ BUCKET: R2Bucket; // wrangler.toml [[r2_buckets]] binding = "BUCKET"
53
51
  SYNC_COORDINATOR: DurableObjectNamespace<SyncularRealtimeDO>;
54
- R2_ACCOUNT_ID: string;
55
- R2_ACCESS_KEY_ID: string;
56
- R2_SECRET_ACCESS_KEY: string;
57
52
  SYNC_JWT_SECRET: string;
58
53
  }
59
54
 
60
55
  function syncConfig(env: Env): SyncServerConfig {
61
- const endpoint = `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`;
62
- const r2 = {
63
- endpoint,
64
- region: 'auto' as const,
65
- accessKeyId: env.R2_ACCESS_KEY_ID,
66
- secretAccessKey: env.R2_SECRET_ACCESS_KEY,
67
- };
68
- const segments = new S3SegmentStore({ ...r2, bucket: 'syncular-segments' });
69
- // Durable attachment bytes (§5.9) in R2 — no TTL, no lifecycle rule; the
56
+ // Segment and blob bytes live in R2 through the binding: no S3
57
+ // credentials, no SigV4 signing. The stores run the same logic as the S3
58
+ // stores over a bucket binding, so `wrangler dev --local` works too.
59
+ const segments = new R2SegmentStore(env.BUCKET);
60
+ // Durable attachment bytes (§5.9) in R2: no TTL, no lifecycle rule; the
70
61
  // host schedules `sweepOrphanBlobs` for GC (see the server README runbook).
71
- const blobs = new S3BlobStore({ ...r2, bucket: 'syncular-blobs' });
62
+ const blobs = new R2BlobStore(env.BUCKET);
72
63
  return {
73
64
  schema,
74
65
  storage: new D1ServerStorage(env.DB),
75
66
  segments,
76
67
  blobs,
77
- // §5.4 delegated presign: R2 mints the segment URL directly.
78
- signedUrls: s3PresignedUrls(segments, { ttlSeconds: 900 }),
79
- // §5.9.5 delegated presign for blob downloads (issued post-authz).
80
- blobSignedUrls: s3PresignedBlobUrls(blobs, { ttlSeconds: 900 }),
68
+ // No `signedUrls` / `blobSignedUrls`: a binding cannot presign, so the
69
+ // Worker serves the bytes inline through GET /segments/:id and
70
+ // GET /blobs/:id.
81
71
  resolveScopes: (args) => resolveScopes(args, env),
82
72
  // No `sqliteImageBuilder`: Workers has no SQLite engine, so bit-2
83
73
  // clients are served the rows lane (§5.3 support floor).
@@ -95,6 +85,21 @@ export default {
95
85
  };
96
86
  ```
97
87
 
88
+ `R2SegmentStore` and `R2BlobStore` take the bucket binding (`R2BucketLike`,
89
+ declared structurally in `src/r2-stores.ts`). They write the same object keys as
90
+ `S3SegmentStore` and `S3BlobStore`, so one bucket serves both access paths: a Bun
91
+ or Node host that holds R2 S3 credentials publishes through the S3 endpoint, and
92
+ the Worker reads those objects through the binding. The keys are
93
+ `{prefix}seg/sha256/{hex}` with its `rec/` and `find/` companions, and
94
+ `{prefix}blob/{partition}/sha256/{hex}`.
95
+
96
+ 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
99
+ `S3SegmentStore` and `S3BlobStore` with `s3PresignedUrls` and
100
+ `s3PresignedBlobUrls` when clients should download from R2 directly; that path
101
+ needs the R2 endpoint plus an access key as secrets.
102
+
98
103
  `createWorkersFetchHandler(factory)` builds the Hono app once per request from
99
104
  the factory and delegates. Building per request keeps the handler stateless
100
105
  (no module-global mutable server) — the Workers-correct posture, since each
package/dist/index.d.ts CHANGED
@@ -9,9 +9,13 @@
9
9
  *
10
10
  * - **D1** → `D1ServerStorage` (the sqlite-family storage over the D1
11
11
  * binding, §4.2);
12
- * - **R2 / secrets** → the segment store, blob store, and signed-URL
13
- * config the host assembles from `env` (R2-as-S3 via `S3SegmentStore` +
14
- * `s3PresignedUrls`, or a memory store for tests);
12
+ * - **R2 / segments and blobs** → the segment store, blob store, and
13
+ * signed-URL config the host assembles from `env`. With a bucket binding
14
+ * (`env.BUCKET`), `R2SegmentStore` and `R2BlobStore` (`r2-stores.ts`) put
15
+ * the durable bytes in the same key layout as the S3 stores, with no S3
16
+ * credentials and no presign (bytes are served inline). With R2's S3
17
+ * endpoint, the S3 stores plus `s3PresignedUrls` give delegated presign
18
+ * (§5.4); a memory store serves tests;
15
19
  * - **secrets** → whatever `authenticate` needs.
16
20
  *
17
21
  * ## Realtime (§8): the Durable Object
@@ -29,6 +33,7 @@ import { type D1Database, D1ServerStorage, type StoredCommit, type SyncServerCon
29
33
  import { type SyncularAdminGuards, type SyncularHonoOptions } from '@syncular/server-hono';
30
34
  import { type RealtimeUpgradeIdentity } from './realtime-do.js';
31
35
  export { type D1Database, D1ServerStorage } from '@syncular/server';
36
+ export * from './r2-stores.js';
32
37
  export * from './realtime-do.js';
33
38
  /**
34
39
  * Build the request-scoped config + auth for one Worker invocation from the
@@ -154,14 +159,16 @@ export interface WorkersFetchHandlerOptions<Env = unknown> {
154
159
  */
155
160
  export declare function createWorkersFetchHandler<Env = unknown>(factoryOrOptions: WorkersConfigFactory<Env> | WorkersFetchHandlerOptions<Env>): (request: Request, env: Env, ctx: ExecutionContextLike) => Promise<Response>;
156
161
  /**
157
- * Forward an authenticated HTTP sync round to the partition's Durable Object.
158
- * Pulls and pushes share this path so client-record updates and push apply use
159
- * one ordered partition boundary. Other HTTP routes remain direct.
162
+ * Forward an authenticated HTTP sync round (or, with
163
+ * `OPERATIONS_DO_REQUEST_PATH`, a remote operation) to the partition's
164
+ * Durable Object. Pulls, pushes and commands share this boundary so
165
+ * client-record updates and commit apply use one ordered partition FIFO.
166
+ * Other HTTP routes remain direct.
160
167
  */
161
168
  export declare function forwardSyncRequest(request: Request, namespace: DurableObjectNamespaceLike, identity: {
162
169
  readonly partition: string;
163
170
  readonly actorId: string;
164
- }): Promise<Response>;
171
+ }, path?: string): Promise<Response>;
165
172
  /**
166
173
  * Forward a `/realtime` upgrade to the partition's DO stub. The identity is
167
174
  * carried on internal headers to the DO's upgrade endpoint (the DO trusts the
package/dist/index.js CHANGED
@@ -9,9 +9,13 @@
9
9
  *
10
10
  * - **D1** → `D1ServerStorage` (the sqlite-family storage over the D1
11
11
  * binding, §4.2);
12
- * - **R2 / secrets** → the segment store, blob store, and signed-URL
13
- * config the host assembles from `env` (R2-as-S3 via `S3SegmentStore` +
14
- * `s3PresignedUrls`, or a memory store for tests);
12
+ * - **R2 / segments and blobs** → the segment store, blob store, and
13
+ * signed-URL config the host assembles from `env`. With a bucket binding
14
+ * (`env.BUCKET`), `R2SegmentStore` and `R2BlobStore` (`r2-stores.ts`) put
15
+ * the durable bytes in the same key layout as the S3 stores, with no S3
16
+ * credentials and no presign (bytes are served inline). With R2's S3
17
+ * endpoint, the S3 stores plus `s3PresignedUrls` give delegated presign
18
+ * (§5.4); a memory store serves tests;
15
19
  * - **secrets** → whatever `authenticate` needs.
16
20
  *
17
21
  * ## Realtime (§8): the Durable Object
@@ -27,8 +31,9 @@
27
31
  */
28
32
  import { D1ServerStorage, errorBody, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
29
33
  import { createSyncularAdminRoutes, createSyncularHono, } from '@syncular/server-hono';
30
- import { adminRequestForDurableObject, REALTIME_DO_UPGRADE_PATH, REALTIME_DO_WAKE_PATH, SYNC_DO_REQUEST_PATH, writeIdentityHeaders, writeRequestIdentityHeaders, } from './realtime-do.js';
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';
31
35
  export { D1ServerStorage } from '@syncular/server';
36
+ export * from './r2-stores.js';
32
37
  export * from './realtime-do.js';
33
38
  /**
34
39
  * Wrap a config factory (or a `{ config, realtime }` options object) into a
@@ -88,13 +93,20 @@ export function createWorkersFetchHandler(factoryOrOptions) {
88
93
  const coordinator = options.coordinator !== undefined
89
94
  ? await options.coordinator(env, ctx)
90
95
  : realtime;
91
- if (coordinator !== undefined && isSyncPost(request)) {
96
+ const partitionPath = coordinator !== undefined ? partitionRequestPath(request) : undefined;
97
+ if (coordinator !== undefined && partitionPath !== undefined) {
98
+ if (partitionPath === OPERATIONS_DO_REQUEST_PATH &&
99
+ honoOptions.operations !== undefined) {
100
+ // Commands must apply on the partition FIFO; a registry in the
101
+ // Worker would run them beside it.
102
+ throw new Error('createWorkersFetchHandler: pass operations to the Durable Object config (RealtimeDOConfig.operations), not to the Worker config');
103
+ }
92
104
  const auth = await honoOptions.authenticate(request);
93
105
  if (auth === null) {
94
106
  const error = new SyncError('sync.auth_required');
95
107
  return Response.json(errorBody(error), { status: error.httpStatus });
96
108
  }
97
- return forwardSyncRequest(request, coordinator.namespace, auth);
109
+ return forwardSyncRequest(request, coordinator.namespace, auth, partitionPath);
98
110
  }
99
111
  if (options.admin !== undefined) {
100
112
  const admin = await options.admin(env, ctx);
@@ -129,28 +141,37 @@ export function createWorkersFetchHandler(factoryOrOptions) {
129
141
  return app.fetch(request);
130
142
  };
131
143
  }
132
- function isSyncPost(request) {
144
+ /**
145
+ * The Durable Object path for a request that must run on the partition FIFO:
146
+ * `POST /sync` with the SSP2 content type and `POST /operations` (the DO
147
+ * checks the operations content type). Exactly the routes
148
+ * `createSyncularHono` mounts at the app root; any other path, such as
149
+ * `/admin/sync`, stays with Hono routing.
150
+ */
151
+ function partitionRequestPath(request) {
133
152
  if (request.method !== 'POST')
134
- return false;
153
+ return undefined;
154
+ const pathname = new URL(request.url).pathname;
155
+ if (pathname === '/operations')
156
+ return OPERATIONS_DO_REQUEST_PATH;
135
157
  const contentType = request.headers
136
158
  .get('content-type')
137
159
  ?.split(';')[0]
138
160
  ?.trim();
139
- if (contentType !== SSP2_CONTENT_TYPE)
140
- return false;
141
- // Exactly the route `createSyncularHono` mounts (`POST /sync` at the app
142
- // root, which is where this handler serves the Hono app). Any other path —
143
- // e.g. `/admin/sync` — stays with Hono routing.
144
- return new URL(request.url).pathname === '/sync';
161
+ if (pathname === '/sync' && contentType === SSP2_CONTENT_TYPE)
162
+ return SYNC_DO_REQUEST_PATH;
163
+ return undefined;
145
164
  }
146
165
  /**
147
- * Forward an authenticated HTTP sync round to the partition's Durable Object.
148
- * Pulls and pushes share this path so client-record updates and push apply use
149
- * one ordered partition boundary. Other HTTP routes remain direct.
166
+ * Forward an authenticated HTTP sync round (or, with
167
+ * `OPERATIONS_DO_REQUEST_PATH`, a remote operation) to the partition's
168
+ * Durable Object. Pulls, pushes and commands share this boundary so
169
+ * client-record updates and commit apply use one ordered partition FIFO.
170
+ * Other HTTP routes remain direct.
150
171
  */
151
- export function forwardSyncRequest(request, namespace, identity) {
172
+ export function forwardSyncRequest(request, namespace, identity, path = SYNC_DO_REQUEST_PATH) {
152
173
  const stub = namespace.get(namespace.idFromName(identity.partition));
153
- const forwarded = new Request(new URL(SYNC_DO_REQUEST_PATH, request.url), request);
174
+ const forwarded = new Request(new URL(path, request.url), request);
154
175
  writeRequestIdentityHeaders(forwarded.headers, identity);
155
176
  return stub.fetch(forwarded);
156
177
  }
@@ -0,0 +1,104 @@
1
+ /**
2
+ * R2-binding segment and blob stores (SPEC.md §5.1, §5.9.2) for Cloudflare
3
+ * Workers.
4
+ *
5
+ * `R2SegmentStore` and `R2BlobStore` run the same bucket-generic store logic
6
+ * as `S3SegmentStore` and `S3BlobStore` (`BucketSegmentStore` /
7
+ * `BucketBlobStore` in `@syncular/server`) over the Worker's `env.BUCKET`
8
+ * binding instead of the S3 REST API. No S3 credentials, no SigV4 signing, and
9
+ * no outbound request: every read and write is a binding call, which works the
10
+ * same under `wrangler dev --local`.
11
+ *
12
+ * The object key layout is identical to the S3 stores, so one bucket serves
13
+ * both access paths: a Bun or Node host can publish segments and blobs through
14
+ * the S3 API while the Worker reads them through the binding.
15
+ *
16
+ * There are no `presign*` methods here. A binding cannot mint a provider URL,
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.
21
+ *
22
+ * The binding surface is declared structurally below, so this package keeps
23
+ * taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
24
+ * is assignable to `R2BucketLike`.
25
+ */
26
+ import { BucketBlobStore, type BucketBlobStoreOptions, BucketSegmentStore, type BucketSegmentStoreOptions } from '@syncular/server';
27
+ /** `R2Conditional`: the precondition R2 evaluates before it writes. */
28
+ export interface R2ConditionLike {
29
+ /** Write only if the stored ETag equals this one. */
30
+ readonly etagMatches?: string;
31
+ /** Write only if the stored ETag differs; `*` means "only when absent". */
32
+ readonly etagDoesNotMatch?: string;
33
+ }
34
+ /** `R2Object`: one stored object's description. */
35
+ export interface R2ObjectLike {
36
+ readonly key: string;
37
+ /** Unquoted object ETag (the CAS token; R2 also reports `httpEtag`). */
38
+ readonly etag: string;
39
+ readonly size: number;
40
+ readonly customMetadata?: Readonly<Record<string, string>>;
41
+ }
42
+ /** `R2ObjectBody`: the object plus its bytes. */
43
+ export interface R2ObjectBodyLike extends R2ObjectLike {
44
+ readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
45
+ arrayBuffer(): Promise<ArrayBuffer>;
46
+ text(): Promise<string>;
47
+ }
48
+ /** `R2Objects`: one page of a `list`. */
49
+ export interface R2ObjectsLike {
50
+ readonly objects: readonly R2ObjectLike[];
51
+ readonly truncated: boolean;
52
+ readonly cursor?: string;
53
+ }
54
+ /** `R2PutOptions`: the subset the stores set. */
55
+ export interface R2PutOptionsLike {
56
+ readonly onlyIf?: R2ConditionLike;
57
+ readonly httpMetadata?: {
58
+ readonly contentType?: string;
59
+ };
60
+ readonly customMetadata?: Record<string, string>;
61
+ }
62
+ /** `R2GetOptions`: declared for structural parity; the stores read plainly. */
63
+ export interface R2GetOptionsLike {
64
+ readonly onlyIf?: R2ConditionLike;
65
+ }
66
+ /**
67
+ * The `R2Bucket` binding surface the stores use
68
+ * (`wrangler [[r2_buckets]] binding = "BUCKET"` → `env.BUCKET`).
69
+ */
70
+ export interface R2BucketLike {
71
+ get(key: string, options?: R2GetOptionsLike): Promise<R2ObjectBodyLike | null>;
72
+ head(key: string): Promise<R2ObjectLike | null>;
73
+ /** `null` when `onlyIf` failed, exactly as the platform reports it. */
74
+ put(key: string, value: Uint8Array, options?: R2PutOptionsLike): Promise<R2ObjectLike | null>;
75
+ delete(key: string): Promise<void>;
76
+ list(options: {
77
+ readonly prefix: string;
78
+ readonly cursor?: string;
79
+ readonly limit?: number;
80
+ }): Promise<R2ObjectsLike>;
81
+ }
82
+ /**
83
+ * Segment store over an R2 binding. Same key layout, record CAS, reuse
84
+ * pointers, and approximate stats accumulator as `S3SegmentStore`.
85
+ *
86
+ * ```ts
87
+ * const segments = new R2SegmentStore(env.BUCKET);
88
+ * ```
89
+ */
90
+ export declare class R2SegmentStore extends BucketSegmentStore {
91
+ constructor(bucket: R2BucketLike, options?: BucketSegmentStoreOptions);
92
+ }
93
+ /**
94
+ * Blob store over an R2 binding. Same key layout, idempotent re-put, orphan
95
+ * sweep, and approximate stats accumulator as `S3BlobStore`. The sweep pages
96
+ * the binding's `list`, so no S3 credentials are needed for GC either.
97
+ *
98
+ * ```ts
99
+ * const blobs = new R2BlobStore(env.BUCKET);
100
+ * ```
101
+ */
102
+ export declare class R2BlobStore extends BucketBlobStore {
103
+ constructor(bucket: R2BucketLike, options?: BucketBlobStoreOptions);
104
+ }
@@ -0,0 +1,117 @@
1
+ /**
2
+ * R2-binding segment and blob stores (SPEC.md §5.1, §5.9.2) for Cloudflare
3
+ * Workers.
4
+ *
5
+ * `R2SegmentStore` and `R2BlobStore` run the same bucket-generic store logic
6
+ * as `S3SegmentStore` and `S3BlobStore` (`BucketSegmentStore` /
7
+ * `BucketBlobStore` in `@syncular/server`) over the Worker's `env.BUCKET`
8
+ * binding instead of the S3 REST API. No S3 credentials, no SigV4 signing, and
9
+ * no outbound request: every read and write is a binding call, which works the
10
+ * same under `wrangler dev --local`.
11
+ *
12
+ * The object key layout is identical to the S3 stores, so one bucket serves
13
+ * both access paths: a Bun or Node host can publish segments and blobs through
14
+ * the S3 API while the Worker reads them through the binding.
15
+ *
16
+ * There are no `presign*` methods here. A binding cannot mint a provider URL,
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.
21
+ *
22
+ * The binding surface is declared structurally below, so this package keeps
23
+ * taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
24
+ * is assignable to `R2BucketLike`.
25
+ */
26
+ import { BucketBlobStore, BucketSegmentStore, } from '@syncular/server';
27
+ function metadataOf(object) {
28
+ return object.customMetadata ?? {};
29
+ }
30
+ /**
31
+ * The `ObjectBucket` seam over one R2 binding. `etagMatches` /
32
+ * `etagDoesNotMatch: '*'` are the binding's spelling of the `If-Match` /
33
+ * `If-None-Match: *` preconditions the record and stats CAS depend on; a
34
+ * failed precondition is a `null` put result.
35
+ */
36
+ function r2ObjectBucket(bucket) {
37
+ return {
38
+ async get(key) {
39
+ const object = await bucket.get(key);
40
+ if (object === null)
41
+ return undefined;
42
+ return {
43
+ body: object.body,
44
+ etag: object.etag,
45
+ size: object.size,
46
+ metadata: metadataOf(object),
47
+ arrayBuffer: () => object.arrayBuffer(),
48
+ text: () => object.text(),
49
+ };
50
+ },
51
+ async head(key) {
52
+ const object = await bucket.head(key);
53
+ if (object === null)
54
+ return undefined;
55
+ return {
56
+ etag: object.etag,
57
+ size: object.size,
58
+ metadata: metadataOf(object),
59
+ };
60
+ },
61
+ async put(key, options) {
62
+ const onlyIf = options.createOnly === true
63
+ ? { etagDoesNotMatch: '*' }
64
+ : options.ifMatch !== undefined
65
+ ? { etagMatches: options.ifMatch }
66
+ : undefined;
67
+ const written = await bucket.put(key, options.body, {
68
+ ...(onlyIf !== undefined ? { onlyIf } : {}),
69
+ httpMetadata: { contentType: options.contentType },
70
+ ...(options.metadata !== undefined
71
+ ? { customMetadata: { ...options.metadata } }
72
+ : {}),
73
+ });
74
+ return written !== null;
75
+ },
76
+ async delete(key) {
77
+ await bucket.delete(key);
78
+ },
79
+ async list(prefix, cursor) {
80
+ const page = await bucket.list({
81
+ prefix,
82
+ ...(cursor !== undefined ? { cursor } : {}),
83
+ });
84
+ return {
85
+ keys: page.objects.map((object) => object.key),
86
+ cursor: page.truncated ? page.cursor : undefined,
87
+ };
88
+ },
89
+ };
90
+ }
91
+ /**
92
+ * Segment store over an R2 binding. Same key layout, record CAS, reuse
93
+ * pointers, and approximate stats accumulator as `S3SegmentStore`.
94
+ *
95
+ * ```ts
96
+ * const segments = new R2SegmentStore(env.BUCKET);
97
+ * ```
98
+ */
99
+ export class R2SegmentStore extends BucketSegmentStore {
100
+ constructor(bucket, options) {
101
+ super(r2ObjectBucket(bucket), options);
102
+ }
103
+ }
104
+ /**
105
+ * Blob store over an R2 binding. Same key layout, idempotent re-put, orphan
106
+ * sweep, and approximate stats accumulator as `S3BlobStore`. The sweep pages
107
+ * the binding's `list`, so no S3 credentials are needed for GC either.
108
+ *
109
+ * ```ts
110
+ * const blobs = new R2BlobStore(env.BUCKET);
111
+ * ```
112
+ */
113
+ export class R2BlobStore extends BucketBlobStore {
114
+ constructor(bucket, options) {
115
+ super(r2ObjectBucket(bucket), options);
116
+ }
117
+ }
@@ -45,10 +45,13 @@
45
45
  * an async generator draining over `ws.send`; while it is pending it holds
46
46
  * the DO's event loop, so the DO cannot be evicted mid-round. (This is the
47
47
  * same property the §8.7 "one round in flight" rule relies on.)
48
- * - **On the first message after a wake**, the socket has a serialized
49
- * attachment (`ws.serializeAttachment` — `{clientId, actorId, partition}`,
50
- * written at accept time) but no live session. We reconstruct the session
51
- * via `hub.connect(...)`, which reloads the registration list from the
48
+ * - **On the first serialized operation after a wake** (a socket frame, an
49
+ * HTTP sync round, a command, a wake), every accepted socket has a
50
+ * serialized attachment (`ws.serializeAttachment`, `{clientId, actorId,
51
+ * partition}`, written at accept time) but no live session. The host
52
+ * reconstructs the session of every socket in `getWebSockets()`, so
53
+ * sockets that stayed quiet through the hibernation keep receiving
54
+ * deltas. Each session is rebuilt via `hub.connect(...)`, which reloads the registration list from the
52
55
  * client record in D1 (the §8.1 load-at-upgrade rule — exactly what a
53
56
  * fresh upgrade does), then dispatch the message into it. Rehydration is
54
57
  * transparent to the client: it saw `hello` once at the real upgrade, so
@@ -62,12 +65,13 @@
62
65
  *
63
66
  * ## The wake path (external-command fan-out)
64
67
  *
65
- * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
68
+ * Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
69
+ * are forwarded into this DO and fan out in-process. An
66
70
  * external authoritative command host that already provides equivalent D1
67
71
  * partition serialization may call `/__wake` after its own commit so sockets
68
72
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
69
73
  */
70
- import { D1ServerStorage, type PruneOptions, type RealtimeHubConfig } from '@syncular/server';
74
+ import { D1ServerStorage, type PruneOptions, type RealtimeHubConfig, type RemoteOperationRegistry } from '@syncular/server';
71
75
  export interface DurableObjectStateLike {
72
76
  acceptWebSocket(ws: WebSocketLike, tags?: string[]): void;
73
77
  getWebSockets(tag?: string): WebSocketLike[];
@@ -113,6 +117,12 @@ export type RealtimeDOConfig = ({
113
117
  * partition's rounds.
114
118
  */
115
119
  readonly adminRingCapacity?: number;
120
+ /**
121
+ * Registered remote queries and commands (REMOTE.md). The Worker forwards
122
+ * `POST <mount>/operations` here, so a command applies on the partition
123
+ * FIFO and fans out to the partition's sockets like a pushed commit.
124
+ */
125
+ readonly operations?: RemoteOperationRegistry;
116
126
  };
117
127
  /**
118
128
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
@@ -129,6 +139,9 @@ export interface RealtimeUpgradeIdentity {
129
139
  export declare const REALTIME_DO_WAKE_PATH = "/__syncular_realtime/wake";
130
140
  export declare const REALTIME_DO_UPGRADE_PATH = "/__syncular_realtime/upgrade";
131
141
  export declare const SYNC_DO_REQUEST_PATH = "/__syncular_realtime/sync";
142
+ export declare const OPERATIONS_DO_REQUEST_PATH = "/__syncular_realtime/operations";
143
+ /** The remote operation protocol content type (REMOTE.md §5). */
144
+ export declare const OPERATIONS_CONTENT_TYPE = "application/vnd.syncular.operations.v1+json";
132
145
  /** Prefix of forwarded admin routes; the admin route path follows it. */
133
146
  export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
134
147
  /**
@@ -45,10 +45,13 @@
45
45
  * an async generator draining over `ws.send`; while it is pending it holds
46
46
  * the DO's event loop, so the DO cannot be evicted mid-round. (This is the
47
47
  * same property the §8.7 "one round in flight" rule relies on.)
48
- * - **On the first message after a wake**, the socket has a serialized
49
- * attachment (`ws.serializeAttachment` — `{clientId, actorId, partition}`,
50
- * written at accept time) but no live session. We reconstruct the session
51
- * via `hub.connect(...)`, which reloads the registration list from the
48
+ * - **On the first serialized operation after a wake** (a socket frame, an
49
+ * HTTP sync round, a command, a wake), every accepted socket has a
50
+ * serialized attachment (`ws.serializeAttachment`, `{clientId, actorId,
51
+ * partition}`, written at accept time) but no live session. The host
52
+ * reconstructs the session of every socket in `getWebSockets()`, so
53
+ * sockets that stayed quiet through the hibernation keep receiving
54
+ * deltas. Each session is rebuilt via `hub.connect(...)`, which reloads the registration list from the
52
55
  * client record in D1 (the §8.1 load-at-upgrade rule — exactly what a
53
56
  * fresh upgrade does), then dispatch the message into it. Rehydration is
54
57
  * transparent to the client: it saw `hello` once at the real upgrade, so
@@ -62,12 +65,13 @@
62
65
  *
63
66
  * ## The wake path (external-command fan-out)
64
67
  *
65
- * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
68
+ * Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
69
+ * are forwarded into this DO and fan out in-process. An
66
70
  * external authoritative command host that already provides equivalent D1
67
71
  * partition serialization may call `/__wake` after its own commit so sockets
68
72
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
69
73
  */
70
- import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
74
+ import { adapterSyncError, composeEvents, createRealtimeHub, D1ServerStorage, errorBody, handleRemoteOperation, handleSyncRequest, pruneCommitLog, RingBufferEvents, SSP2_CONTENT_TYPE, SyncError, SyncularAdmin, } from '@syncular/server';
71
75
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
72
76
  function isAttachment(value) {
73
77
  return (typeof value === 'object' &&
@@ -80,6 +84,9 @@ function isAttachment(value) {
80
84
  export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
81
85
  export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
82
86
  export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
87
+ export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
88
+ /** The remote operation protocol content type (REMOTE.md §5). */
89
+ export const OPERATIONS_CONTENT_TYPE = 'application/vnd.syncular.operations.v1+json';
83
90
  /** Prefix of forwarded admin routes; the admin route path follows it. */
84
91
  export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
85
92
  /**
@@ -112,12 +119,17 @@ export class SyncularRealtimeHost {
112
119
  #hub;
113
120
  #admin;
114
121
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
115
- * lazily rehydrated on the first message per socket (see the class doc). */
122
+ * rehydrated for every socket before the first serialized operation (see
123
+ * the class doc). */
116
124
  #sessions = new Map();
117
125
  /** Sockets whose rehydration `hello` must be swallowed (already greeted at
118
126
  * the real upgrade — rehydration is transparent to the client). */
119
127
  #swallowHello = new Set();
120
128
  #closedSockets = new WeakSet();
129
+ /** Accepted sockets whose upgrade is still building their session. */
130
+ #upgrading = new WeakSet();
131
+ /** Set once this instance rebuilt the sessions of hibernated sockets. */
132
+ #rehydrated = false;
121
133
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
122
134
  #partitionTail = Promise.resolve();
123
135
  constructor(state, db, config) {
@@ -166,8 +178,11 @@ export class SyncularRealtimeHost {
166
178
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
167
179
  return this.#serializePartition(() => this.#handleSync(request));
168
180
  }
181
+ if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
182
+ return this.#serializePartition(() => this.#handleOperation(request));
183
+ }
169
184
  if (url.pathname === REALTIME_DO_WAKE_PATH) {
170
- return this.#handleWake(request);
185
+ return this.#serializePartition(() => this.#handleWake(request));
171
186
  }
172
187
  if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
173
188
  return this.#handleUpgrade(request);
@@ -185,10 +200,76 @@ export class SyncularRealtimeHost {
185
200
  });
186
201
  }
187
202
  #serializePartition(operation) {
188
- const result = this.#partitionTail.then(operation, operation);
203
+ const run = async () => {
204
+ await this.#rehydrateSockets();
205
+ return operation();
206
+ };
207
+ const result = this.#partitionTail.then(run, run);
189
208
  this.#partitionTail = result.then(() => undefined, () => undefined);
190
209
  return result;
191
210
  }
211
+ /**
212
+ * After a hibernation wake the session map is empty while sockets stay
213
+ * open. Rebuild every socket's session before the first serialized
214
+ * operation, so a commit fans out to sockets that stayed quiet through
215
+ * the hibernation. A socket whose session cannot be rebuilt is closed;
216
+ * its client reconnects and catches up (§8.4).
217
+ */
218
+ async #rehydrateSockets() {
219
+ if (this.#rehydrated)
220
+ return;
221
+ this.#rehydrated = true;
222
+ for (const ws of this.#state.getWebSockets()) {
223
+ if (this.#upgrading.has(ws))
224
+ continue;
225
+ try {
226
+ await this.#sessionFor(ws);
227
+ }
228
+ catch (error) {
229
+ ws.close(1011, 'realtime rehydration failed');
230
+ this.#syncError(error, 'realtime');
231
+ }
232
+ }
233
+ }
234
+ /**
235
+ * Map a host failure to its catalog error. The reporters are read inside
236
+ * the callbacks so a failing accessor stays inside `adapterSyncError`.
237
+ */
238
+ #syncError(error, route) {
239
+ return adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), route, (error, context) => this.#getHub().mapError?.(error, context));
240
+ }
241
+ async #handleOperation(request) {
242
+ const contentType = request.headers
243
+ .get('content-type')
244
+ ?.split(';')[0]
245
+ ?.trim();
246
+ if (contentType !== OPERATIONS_CONTENT_TYPE) {
247
+ const error = new SyncError('operation.invalid_request');
248
+ return Response.json(errorBody(error), { status: 415 });
249
+ }
250
+ const registry = this.#config.operations;
251
+ if (registry === undefined) {
252
+ const error = new SyncError('operation.unknown');
253
+ return Response.json(errorBody(error), { status: error.httpStatus });
254
+ }
255
+ const identity = readRequestIdentityHeaders(request);
256
+ if (identity === undefined) {
257
+ const error = new SyncError('sync.auth_required');
258
+ return Response.json(errorBody(error), { status: error.httpStatus });
259
+ }
260
+ try {
261
+ const bytes = new Uint8Array(await request.arrayBuffer());
262
+ const out = await handleRemoteOperation(bytes, this.#getHub().requestContextFor(identity), registry);
263
+ return new Response(out.slice().buffer, {
264
+ status: 200,
265
+ headers: { 'content-type': OPERATIONS_CONTENT_TYPE },
266
+ });
267
+ }
268
+ catch (error) {
269
+ const sync = this.#syncError(error, 'operations');
270
+ return Response.json(errorBody(sync), { status: sync.httpStatus });
271
+ }
272
+ }
192
273
  async #handleSync(request) {
193
274
  const contentType = request.headers
194
275
  .get('content-type')
@@ -212,7 +293,7 @@ export class SyncularRealtimeHost {
212
293
  });
213
294
  }
214
295
  catch (error) {
215
- const sync = adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), 'sync', (error, context) => this.#getHub().mapError?.(error, context));
296
+ const sync = this.#syncError(error, 'sync');
216
297
  return Response.json(errorBody(sync), { status: sync.httpStatus });
217
298
  }
218
299
  }
@@ -276,16 +357,19 @@ export class SyncularRealtimeHost {
276
357
  clientId: identity.clientId,
277
358
  };
278
359
  server.serializeAttachment(attachment);
360
+ this.#upgrading.add(server);
279
361
  this.#state.acceptWebSocket(server);
280
362
  // Build the session now (first connect: hello IS delivered). Any failure
281
363
  // closes the socket loudly — never a half-open realtime connection.
282
364
  try {
283
365
  const session = await this.#connectSession(server, attachment, false);
284
366
  this.#sessions.set(server, session);
367
+ this.#upgrading.delete(server);
285
368
  }
286
369
  catch (error) {
370
+ this.#upgrading.delete(server);
287
371
  server.close(1011, 'realtime connect failed');
288
- const sync = adapterSyncError(error, (error, context) => this.#getHub().onError?.(error, context), 'realtime', (error, context) => this.#getHub().mapError?.(error, context));
372
+ const sync = this.#syncError(error, 'realtime');
289
373
  return Response.json(errorBody(sync), { status: sync.httpStatus });
290
374
  }
291
375
  // `webSocket` is a workerd-only ResponseInit field (the 101 upgrade
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.32.1",
3
+ "version": "0.33.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,11 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/server": "0.32.1",
49
- "@syncular/server-hono": "0.32.1"
48
+ "@syncular/server": "0.33.0",
49
+ "@syncular/server-hono": "0.33.0"
50
50
  },
51
51
  "devDependencies": {
52
- "@syncular/core": "0.32.1",
52
+ "@syncular/core": "0.33.0",
53
53
  "miniflare": "4.20260701.0"
54
54
  }
55
55
  }
package/src/index.ts CHANGED
@@ -9,9 +9,13 @@
9
9
  *
10
10
  * - **D1** → `D1ServerStorage` (the sqlite-family storage over the D1
11
11
  * binding, §4.2);
12
- * - **R2 / secrets** → the segment store, blob store, and signed-URL
13
- * config the host assembles from `env` (R2-as-S3 via `S3SegmentStore` +
14
- * `s3PresignedUrls`, or a memory store for tests);
12
+ * - **R2 / segments and blobs** → the segment store, blob store, and
13
+ * signed-URL config the host assembles from `env`. With a bucket binding
14
+ * (`env.BUCKET`), `R2SegmentStore` and `R2BlobStore` (`r2-stores.ts`) put
15
+ * the durable bytes in the same key layout as the S3 stores, with no S3
16
+ * credentials and no presign (bytes are served inline). With R2's S3
17
+ * endpoint, the S3 stores plus `s3PresignedUrls` give delegated presign
18
+ * (§5.4); a memory store serves tests;
15
19
  * - **secrets** → whatever `authenticate` needs.
16
20
  *
17
21
  * ## Realtime (§8): the Durable Object
@@ -43,6 +47,7 @@ import {
43
47
  } from '@syncular/server-hono';
44
48
  import {
45
49
  adminRequestForDurableObject,
50
+ OPERATIONS_DO_REQUEST_PATH,
46
51
  REALTIME_DO_UPGRADE_PATH,
47
52
  REALTIME_DO_WAKE_PATH,
48
53
  type RealtimeUpgradeIdentity,
@@ -52,6 +57,7 @@ import {
52
57
  } from './realtime-do';
53
58
 
54
59
  export { type D1Database, D1ServerStorage } from '@syncular/server';
60
+ export * from './r2-stores';
55
61
  export * from './realtime-do';
56
62
 
57
63
  /**
@@ -231,13 +237,30 @@ export function createWorkersFetchHandler<Env = unknown>(
231
237
  options.coordinator !== undefined
232
238
  ? await options.coordinator(env, ctx)
233
239
  : realtime;
234
- if (coordinator !== undefined && isSyncPost(request)) {
240
+ const partitionPath =
241
+ coordinator !== undefined ? partitionRequestPath(request) : undefined;
242
+ if (coordinator !== undefined && partitionPath !== undefined) {
243
+ if (
244
+ partitionPath === OPERATIONS_DO_REQUEST_PATH &&
245
+ honoOptions.operations !== undefined
246
+ ) {
247
+ // Commands must apply on the partition FIFO; a registry in the
248
+ // Worker would run them beside it.
249
+ throw new Error(
250
+ 'createWorkersFetchHandler: pass operations to the Durable Object config (RealtimeDOConfig.operations), not to the Worker config',
251
+ );
252
+ }
235
253
  const auth = await honoOptions.authenticate(request);
236
254
  if (auth === null) {
237
255
  const error = new SyncError('sync.auth_required');
238
256
  return Response.json(errorBody(error), { status: error.httpStatus });
239
257
  }
240
- return forwardSyncRequest(request, coordinator.namespace, auth);
258
+ return forwardSyncRequest(
259
+ request,
260
+ coordinator.namespace,
261
+ auth,
262
+ partitionPath,
263
+ );
241
264
  }
242
265
  if (options.admin !== undefined) {
243
266
  const admin = await options.admin(env, ctx);
@@ -283,34 +306,41 @@ export function createWorkersFetchHandler<Env = unknown>(
283
306
  };
284
307
  }
285
308
 
286
- function isSyncPost(request: Request): boolean {
287
- if (request.method !== 'POST') return false;
309
+ /**
310
+ * The Durable Object path for a request that must run on the partition FIFO:
311
+ * `POST /sync` with the SSP2 content type and `POST /operations` (the DO
312
+ * checks the operations content type). Exactly the routes
313
+ * `createSyncularHono` mounts at the app root; any other path, such as
314
+ * `/admin/sync`, stays with Hono routing.
315
+ */
316
+ function partitionRequestPath(request: Request): string | undefined {
317
+ if (request.method !== 'POST') return undefined;
318
+ const pathname = new URL(request.url).pathname;
319
+ if (pathname === '/operations') return OPERATIONS_DO_REQUEST_PATH;
288
320
  const contentType = request.headers
289
321
  .get('content-type')
290
322
  ?.split(';')[0]
291
323
  ?.trim();
292
- if (contentType !== SSP2_CONTENT_TYPE) return false;
293
- // Exactly the route `createSyncularHono` mounts (`POST /sync` at the app
294
- // root, which is where this handler serves the Hono app). Any other path —
295
- // e.g. `/admin/sync` — stays with Hono routing.
296
- return new URL(request.url).pathname === '/sync';
324
+ if (pathname === '/sync' && contentType === SSP2_CONTENT_TYPE)
325
+ return SYNC_DO_REQUEST_PATH;
326
+ return undefined;
297
327
  }
298
328
 
299
329
  /**
300
- * Forward an authenticated HTTP sync round to the partition's Durable Object.
301
- * Pulls and pushes share this path so client-record updates and push apply use
302
- * one ordered partition boundary. Other HTTP routes remain direct.
330
+ * Forward an authenticated HTTP sync round (or, with
331
+ * `OPERATIONS_DO_REQUEST_PATH`, a remote operation) to the partition's
332
+ * Durable Object. Pulls, pushes and commands share this boundary so
333
+ * client-record updates and commit apply use one ordered partition FIFO.
334
+ * Other HTTP routes remain direct.
303
335
  */
304
336
  export function forwardSyncRequest(
305
337
  request: Request,
306
338
  namespace: DurableObjectNamespaceLike,
307
339
  identity: { readonly partition: string; readonly actorId: string },
340
+ path: string = SYNC_DO_REQUEST_PATH,
308
341
  ): Promise<Response> {
309
342
  const stub = namespace.get(namespace.idFromName(identity.partition));
310
- const forwarded = new Request(
311
- new URL(SYNC_DO_REQUEST_PATH, request.url),
312
- request,
313
- );
343
+ const forwarded = new Request(new URL(path, request.url), request);
314
344
  writeRequestIdentityHeaders(forwarded.headers, identity);
315
345
  return stub.fetch(forwarded);
316
346
  }
@@ -0,0 +1,195 @@
1
+ /**
2
+ * R2-binding segment and blob stores (SPEC.md §5.1, §5.9.2) for Cloudflare
3
+ * Workers.
4
+ *
5
+ * `R2SegmentStore` and `R2BlobStore` run the same bucket-generic store logic
6
+ * as `S3SegmentStore` and `S3BlobStore` (`BucketSegmentStore` /
7
+ * `BucketBlobStore` in `@syncular/server`) over the Worker's `env.BUCKET`
8
+ * binding instead of the S3 REST API. No S3 credentials, no SigV4 signing, and
9
+ * no outbound request: every read and write is a binding call, which works the
10
+ * same under `wrangler dev --local`.
11
+ *
12
+ * The object key layout is identical to the S3 stores, so one bucket serves
13
+ * both access paths: a Bun or Node host can publish segments and blobs through
14
+ * the S3 API while the Worker reads them through the binding.
15
+ *
16
+ * There are no `presign*` methods here. A binding cannot mint a provider URL,
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.
21
+ *
22
+ * The binding surface is declared structurally below, so this package keeps
23
+ * taking no `@cloudflare/workers-types` dependency. Cloudflare's `R2Bucket`
24
+ * is assignable to `R2BucketLike`.
25
+ */
26
+ import {
27
+ BucketBlobStore,
28
+ type BucketBlobStoreOptions,
29
+ BucketSegmentStore,
30
+ type BucketSegmentStoreOptions,
31
+ type ObjectBucket,
32
+ } from '@syncular/server';
33
+
34
+ // -- R2 bindings (structural; no @cloudflare/workers-types dep) -------------
35
+
36
+ /** `R2Conditional`: the precondition R2 evaluates before it writes. */
37
+ export interface R2ConditionLike {
38
+ /** Write only if the stored ETag equals this one. */
39
+ readonly etagMatches?: string;
40
+ /** Write only if the stored ETag differs; `*` means "only when absent". */
41
+ readonly etagDoesNotMatch?: string;
42
+ }
43
+
44
+ /** `R2Object`: one stored object's description. */
45
+ export interface R2ObjectLike {
46
+ readonly key: string;
47
+ /** Unquoted object ETag (the CAS token; R2 also reports `httpEtag`). */
48
+ readonly etag: string;
49
+ readonly size: number;
50
+ readonly customMetadata?: Readonly<Record<string, string>>;
51
+ }
52
+
53
+ /** `R2ObjectBody`: the object plus its bytes. */
54
+ export interface R2ObjectBodyLike extends R2ObjectLike {
55
+ readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
56
+ arrayBuffer(): Promise<ArrayBuffer>;
57
+ text(): Promise<string>;
58
+ }
59
+
60
+ /** `R2Objects`: one page of a `list`. */
61
+ export interface R2ObjectsLike {
62
+ readonly objects: readonly R2ObjectLike[];
63
+ readonly truncated: boolean;
64
+ readonly cursor?: string;
65
+ }
66
+
67
+ /** `R2PutOptions`: the subset the stores set. */
68
+ export interface R2PutOptionsLike {
69
+ readonly onlyIf?: R2ConditionLike;
70
+ readonly httpMetadata?: { readonly contentType?: string };
71
+ readonly customMetadata?: Record<string, string>;
72
+ }
73
+
74
+ /** `R2GetOptions`: declared for structural parity; the stores read plainly. */
75
+ export interface R2GetOptionsLike {
76
+ readonly onlyIf?: R2ConditionLike;
77
+ }
78
+
79
+ /**
80
+ * The `R2Bucket` binding surface the stores use
81
+ * (`wrangler [[r2_buckets]] binding = "BUCKET"` → `env.BUCKET`).
82
+ */
83
+ export interface R2BucketLike {
84
+ get(
85
+ key: string,
86
+ options?: R2GetOptionsLike,
87
+ ): Promise<R2ObjectBodyLike | null>;
88
+ head(key: string): Promise<R2ObjectLike | null>;
89
+ /** `null` when `onlyIf` failed, exactly as the platform reports it. */
90
+ put(
91
+ key: string,
92
+ value: Uint8Array,
93
+ options?: R2PutOptionsLike,
94
+ ): Promise<R2ObjectLike | null>;
95
+ delete(key: string): Promise<void>;
96
+ list(options: {
97
+ readonly prefix: string;
98
+ readonly cursor?: string;
99
+ readonly limit?: number;
100
+ }): Promise<R2ObjectsLike>;
101
+ }
102
+
103
+ function metadataOf(object: R2ObjectLike): Readonly<Record<string, string>> {
104
+ return object.customMetadata ?? {};
105
+ }
106
+
107
+ /**
108
+ * The `ObjectBucket` seam over one R2 binding. `etagMatches` /
109
+ * `etagDoesNotMatch: '*'` are the binding's spelling of the `If-Match` /
110
+ * `If-None-Match: *` preconditions the record and stats CAS depend on; a
111
+ * failed precondition is a `null` put result.
112
+ */
113
+ function r2ObjectBucket(bucket: R2BucketLike): ObjectBucket {
114
+ return {
115
+ async get(key) {
116
+ const object = await bucket.get(key);
117
+ if (object === null) return undefined;
118
+ return {
119
+ body: object.body,
120
+ etag: object.etag,
121
+ size: object.size,
122
+ metadata: metadataOf(object),
123
+ arrayBuffer: () => object.arrayBuffer(),
124
+ text: () => object.text(),
125
+ };
126
+ },
127
+ async head(key) {
128
+ const object = await bucket.head(key);
129
+ if (object === null) return undefined;
130
+ return {
131
+ etag: object.etag,
132
+ size: object.size,
133
+ metadata: metadataOf(object),
134
+ };
135
+ },
136
+ async put(key, options) {
137
+ const onlyIf: R2ConditionLike | undefined =
138
+ options.createOnly === true
139
+ ? { etagDoesNotMatch: '*' }
140
+ : options.ifMatch !== undefined
141
+ ? { etagMatches: options.ifMatch }
142
+ : undefined;
143
+ const written = await bucket.put(key, options.body, {
144
+ ...(onlyIf !== undefined ? { onlyIf } : {}),
145
+ httpMetadata: { contentType: options.contentType },
146
+ ...(options.metadata !== undefined
147
+ ? { customMetadata: { ...options.metadata } }
148
+ : {}),
149
+ });
150
+ return written !== null;
151
+ },
152
+ async delete(key) {
153
+ await bucket.delete(key);
154
+ },
155
+ async list(prefix, cursor) {
156
+ const page = await bucket.list({
157
+ prefix,
158
+ ...(cursor !== undefined ? { cursor } : {}),
159
+ });
160
+ return {
161
+ keys: page.objects.map((object) => object.key),
162
+ cursor: page.truncated ? page.cursor : undefined,
163
+ };
164
+ },
165
+ };
166
+ }
167
+
168
+ /**
169
+ * Segment store over an R2 binding. Same key layout, record CAS, reuse
170
+ * pointers, and approximate stats accumulator as `S3SegmentStore`.
171
+ *
172
+ * ```ts
173
+ * const segments = new R2SegmentStore(env.BUCKET);
174
+ * ```
175
+ */
176
+ export class R2SegmentStore extends BucketSegmentStore {
177
+ constructor(bucket: R2BucketLike, options?: BucketSegmentStoreOptions) {
178
+ super(r2ObjectBucket(bucket), options);
179
+ }
180
+ }
181
+
182
+ /**
183
+ * Blob store over an R2 binding. Same key layout, idempotent re-put, orphan
184
+ * sweep, and approximate stats accumulator as `S3BlobStore`. The sweep pages
185
+ * the binding's `list`, so no S3 credentials are needed for GC either.
186
+ *
187
+ * ```ts
188
+ * const blobs = new R2BlobStore(env.BUCKET);
189
+ * ```
190
+ */
191
+ export class R2BlobStore extends BucketBlobStore {
192
+ constructor(bucket: R2BucketLike, options?: BucketBlobStoreOptions) {
193
+ super(r2ObjectBucket(bucket), options);
194
+ }
195
+ }
@@ -45,10 +45,13 @@
45
45
  * an async generator draining over `ws.send`; while it is pending it holds
46
46
  * the DO's event loop, so the DO cannot be evicted mid-round. (This is the
47
47
  * same property the §8.7 "one round in flight" rule relies on.)
48
- * - **On the first message after a wake**, the socket has a serialized
49
- * attachment (`ws.serializeAttachment` — `{clientId, actorId, partition}`,
50
- * written at accept time) but no live session. We reconstruct the session
51
- * via `hub.connect(...)`, which reloads the registration list from the
48
+ * - **On the first serialized operation after a wake** (a socket frame, an
49
+ * HTTP sync round, a command, a wake), every accepted socket has a
50
+ * serialized attachment (`ws.serializeAttachment`, `{clientId, actorId,
51
+ * partition}`, written at accept time) but no live session. The host
52
+ * reconstructs the session of every socket in `getWebSockets()`, so
53
+ * sockets that stayed quiet through the hibernation keep receiving
54
+ * deltas. Each session is rebuilt via `hub.connect(...)`, which reloads the registration list from the
52
55
  * client record in D1 (the §8.1 load-at-upgrade rule — exactly what a
53
56
  * fresh upgrade does), then dispatch the message into it. Rehydration is
54
57
  * transparent to the client: it saw `hello` once at the real upgrade, so
@@ -62,7 +65,8 @@
62
65
  *
63
66
  * ## The wake path (external-command fan-out)
64
67
  *
65
- * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
68
+ * Ordinary HTTP `/sync` and `/operations` (with `RealtimeDOConfig.operations`)
69
+ * are forwarded into this DO and fan out in-process. An
66
70
  * external authoritative command host that already provides equivalent D1
67
71
  * partition serialization may call `/__wake` after its own commit so sockets
68
72
  * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
@@ -73,16 +77,19 @@ import {
73
77
  createRealtimeHub,
74
78
  D1ServerStorage,
75
79
  errorBody,
80
+ handleRemoteOperation,
76
81
  handleSyncRequest,
77
82
  pruneCommitLog,
78
83
  type PruneOptions,
79
84
  type RealtimeHub,
80
85
  type RealtimeHubConfig,
81
86
  type RealtimeSession,
87
+ type RemoteOperationRegistry,
82
88
  RingBufferEvents,
83
89
  SSP2_CONTENT_TYPE,
84
90
  SyncError,
85
91
  SyncularAdmin,
92
+ type SyncularErrorRoute,
86
93
  } from '@syncular/server';
87
94
  import { createSyncularAdminRoutes } from '@syncular/server-hono';
88
95
 
@@ -139,6 +146,12 @@ export type RealtimeDOConfig = (
139
146
  * partition's rounds.
140
147
  */
141
148
  readonly adminRingCapacity?: number;
149
+ /**
150
+ * Registered remote queries and commands (REMOTE.md). The Worker forwards
151
+ * `POST <mount>/operations` here, so a command applies on the partition
152
+ * FIFO and fans out to the partition's sockets like a pushed commit.
153
+ */
154
+ readonly operations?: RemoteOperationRegistry;
142
155
  };
143
156
 
144
157
  /**
@@ -175,6 +188,10 @@ export interface RealtimeUpgradeIdentity {
175
188
  export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
176
189
  export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
177
190
  export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
191
+ export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
192
+ /** The remote operation protocol content type (REMOTE.md §5). */
193
+ export const OPERATIONS_CONTENT_TYPE =
194
+ 'application/vnd.syncular.operations.v1+json';
178
195
  /** Prefix of forwarded admin routes; the admin route path follows it. */
179
196
  export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
180
197
 
@@ -208,12 +225,17 @@ export class SyncularRealtimeHost {
208
225
  #hub: RealtimeHub | undefined;
209
226
  #admin: SyncularAdmin | undefined;
210
227
  /** Live sessions, keyed by their socket. Empty after a hibernation wake;
211
- * lazily rehydrated on the first message per socket (see the class doc). */
228
+ * rehydrated for every socket before the first serialized operation (see
229
+ * the class doc). */
212
230
  readonly #sessions = new Map<WebSocketLike, RealtimeSession>();
213
231
  /** Sockets whose rehydration `hello` must be swallowed (already greeted at
214
232
  * the real upgrade — rehydration is transparent to the client). */
215
233
  readonly #swallowHello = new Set<WebSocketLike>();
216
234
  readonly #closedSockets = new WeakSet<WebSocketLike>();
235
+ /** Accepted sockets whose upgrade is still building their session. */
236
+ readonly #upgrading = new WeakSet<WebSocketLike>();
237
+ /** Set once this instance rebuilt the sessions of hibernated sockets. */
238
+ #rehydrated = false;
217
239
  /** Explicit FIFO: Durable Object events may interleave at `await`. */
218
240
  #partitionTail: Promise<void> = Promise.resolve();
219
241
 
@@ -278,8 +300,11 @@ export class SyncularRealtimeHost {
278
300
  if (url.pathname === SYNC_DO_REQUEST_PATH) {
279
301
  return this.#serializePartition(() => this.#handleSync(request));
280
302
  }
303
+ if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
304
+ return this.#serializePartition(() => this.#handleOperation(request));
305
+ }
281
306
  if (url.pathname === REALTIME_DO_WAKE_PATH) {
282
- return this.#handleWake(request);
307
+ return this.#serializePartition(() => this.#handleWake(request));
283
308
  }
284
309
  if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
285
310
  return this.#handleUpgrade(request);
@@ -299,7 +324,11 @@ export class SyncularRealtimeHost {
299
324
  }
300
325
 
301
326
  #serializePartition<T>(operation: () => Promise<T>): Promise<T> {
302
- const result = this.#partitionTail.then(operation, operation);
327
+ const run = async (): Promise<T> => {
328
+ await this.#rehydrateSockets();
329
+ return operation();
330
+ };
331
+ const result = this.#partitionTail.then(run, run);
303
332
  this.#partitionTail = result.then(
304
333
  () => undefined,
305
334
  () => undefined,
@@ -307,6 +336,76 @@ export class SyncularRealtimeHost {
307
336
  return result;
308
337
  }
309
338
 
339
+ /**
340
+ * After a hibernation wake the session map is empty while sockets stay
341
+ * open. Rebuild every socket's session before the first serialized
342
+ * operation, so a commit fans out to sockets that stayed quiet through
343
+ * the hibernation. A socket whose session cannot be rebuilt is closed;
344
+ * its client reconnects and catches up (§8.4).
345
+ */
346
+ async #rehydrateSockets(): Promise<void> {
347
+ if (this.#rehydrated) return;
348
+ this.#rehydrated = true;
349
+ for (const ws of this.#state.getWebSockets()) {
350
+ if (this.#upgrading.has(ws)) continue;
351
+ try {
352
+ await this.#sessionFor(ws);
353
+ } catch (error) {
354
+ ws.close(1011, 'realtime rehydration failed');
355
+ this.#syncError(error, 'realtime');
356
+ }
357
+ }
358
+ }
359
+
360
+ /**
361
+ * Map a host failure to its catalog error. The reporters are read inside
362
+ * the callbacks so a failing accessor stays inside `adapterSyncError`.
363
+ */
364
+ #syncError(error: unknown, route: SyncularErrorRoute): SyncError {
365
+ return adapterSyncError(
366
+ error,
367
+ (error, context) => this.#getHub().onError?.(error, context),
368
+ route,
369
+ (error, context) => this.#getHub().mapError?.(error, context),
370
+ );
371
+ }
372
+
373
+ async #handleOperation(request: Request): Promise<Response> {
374
+ const contentType = request.headers
375
+ .get('content-type')
376
+ ?.split(';')[0]
377
+ ?.trim();
378
+ if (contentType !== OPERATIONS_CONTENT_TYPE) {
379
+ const error = new SyncError('operation.invalid_request');
380
+ return Response.json(errorBody(error), { status: 415 });
381
+ }
382
+ const registry = this.#config.operations;
383
+ if (registry === undefined) {
384
+ const error = new SyncError('operation.unknown');
385
+ return Response.json(errorBody(error), { status: error.httpStatus });
386
+ }
387
+ const identity = readRequestIdentityHeaders(request);
388
+ if (identity === undefined) {
389
+ const error = new SyncError('sync.auth_required');
390
+ return Response.json(errorBody(error), { status: error.httpStatus });
391
+ }
392
+ try {
393
+ const bytes = new Uint8Array(await request.arrayBuffer());
394
+ const out = await handleRemoteOperation(
395
+ bytes,
396
+ this.#getHub().requestContextFor(identity),
397
+ registry,
398
+ );
399
+ return new Response(out.slice().buffer as ArrayBuffer, {
400
+ status: 200,
401
+ headers: { 'content-type': OPERATIONS_CONTENT_TYPE },
402
+ });
403
+ } catch (error) {
404
+ const sync = this.#syncError(error, 'operations');
405
+ return Response.json(errorBody(sync), { status: sync.httpStatus });
406
+ }
407
+ }
408
+
310
409
  async #handleSync(request: Request): Promise<Response> {
311
410
  const contentType = request.headers
312
411
  .get('content-type')
@@ -335,12 +434,7 @@ export class SyncularRealtimeHost {
335
434
  headers: { 'content-type': SSP2_CONTENT_TYPE },
336
435
  });
337
436
  } catch (error) {
338
- const sync = adapterSyncError(
339
- error,
340
- (error, context) => this.#getHub().onError?.(error, context),
341
- 'sync',
342
- (error, context) => this.#getHub().mapError?.(error, context),
343
- );
437
+ const sync = this.#syncError(error, 'sync');
344
438
  return Response.json(errorBody(sync), { status: sync.httpStatus });
345
439
  }
346
440
  }
@@ -411,20 +505,18 @@ export class SyncularRealtimeHost {
411
505
  clientId: identity.clientId,
412
506
  };
413
507
  server.serializeAttachment(attachment);
508
+ this.#upgrading.add(server);
414
509
  this.#state.acceptWebSocket(server);
415
510
  // Build the session now (first connect: hello IS delivered). Any failure
416
511
  // closes the socket loudly — never a half-open realtime connection.
417
512
  try {
418
513
  const session = await this.#connectSession(server, attachment, false);
419
514
  this.#sessions.set(server, session);
515
+ this.#upgrading.delete(server);
420
516
  } catch (error) {
517
+ this.#upgrading.delete(server);
421
518
  server.close(1011, 'realtime connect failed');
422
- const sync = adapterSyncError(
423
- error,
424
- (error, context) => this.#getHub().onError?.(error, context),
425
- 'realtime',
426
- (error, context) => this.#getHub().mapError?.(error, context),
427
- );
519
+ const sync = this.#syncError(error, 'realtime');
428
520
  return Response.json(errorBody(sync), { status: sync.httpStatus });
429
521
  }
430
522
  // `webSocket` is a workerd-only ResponseInit field (the 101 upgrade