@syncular/server-workers 0.32.1 → 0.34.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 +30 -25
- package/dist/index.d.ts +14 -7
- package/dist/index.js +40 -19
- package/dist/r2-stores.d.ts +104 -0
- package/dist/r2-stores.js +117 -0
- package/dist/realtime-do.d.ts +21 -6
- package/dist/realtime-do.js +95 -11
- package/package.json +4 -4
- package/src/index.ts +49 -19
- package/src/r2-stores.ts +195 -0
- package/src/realtime-do.ts +115 -20
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
|
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
|
-
//
|
|
78
|
-
|
|
79
|
-
//
|
|
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 /
|
|
13
|
-
* config the host assembles from `env
|
|
14
|
-
* `
|
|
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
|
|
158
|
-
*
|
|
159
|
-
*
|
|
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 /
|
|
13
|
-
* config the host assembles from `env
|
|
14
|
-
* `
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
140
|
-
return
|
|
141
|
-
|
|
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
|
|
148
|
-
*
|
|
149
|
-
*
|
|
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(
|
|
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
|
+
}
|
package/dist/realtime-do.d.ts
CHANGED
|
@@ -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
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
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`
|
|
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, type RemoteOperationResolver } 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,14 @@ 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. A
|
|
124
|
+
* `RemoteOperationResolver` chooses the registry, the commit actor, and
|
|
125
|
+
* the scope resolver per request (REMOTE.md §5.1).
|
|
126
|
+
*/
|
|
127
|
+
readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
|
|
116
128
|
};
|
|
117
129
|
/**
|
|
118
130
|
* The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
|
|
@@ -129,6 +141,9 @@ export interface RealtimeUpgradeIdentity {
|
|
|
129
141
|
export declare const REALTIME_DO_WAKE_PATH = "/__syncular_realtime/wake";
|
|
130
142
|
export declare const REALTIME_DO_UPGRADE_PATH = "/__syncular_realtime/upgrade";
|
|
131
143
|
export declare const SYNC_DO_REQUEST_PATH = "/__syncular_realtime/sync";
|
|
144
|
+
export declare const OPERATIONS_DO_REQUEST_PATH = "/__syncular_realtime/operations";
|
|
145
|
+
/** The remote operation protocol content type (REMOTE.md §5). */
|
|
146
|
+
export declare const OPERATIONS_CONTENT_TYPE = "application/vnd.syncular.operations.v1+json";
|
|
132
147
|
/** Prefix of forwarded admin routes; the admin route path follows it. */
|
|
133
148
|
export declare const ADMIN_DO_PATH = "/__syncular_realtime/admin";
|
|
134
149
|
/**
|
package/dist/realtime-do.js
CHANGED
|
@@ -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
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
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`
|
|
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
|
-
*
|
|
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
|
|
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 =
|
|
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 =
|
|
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.
|
|
3
|
+
"version": "0.34.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.
|
|
49
|
-
"@syncular/server-hono": "0.
|
|
48
|
+
"@syncular/server": "0.34.0",
|
|
49
|
+
"@syncular/server-hono": "0.34.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@syncular/core": "0.
|
|
52
|
+
"@syncular/core": "0.34.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 /
|
|
13
|
-
* config the host assembles from `env
|
|
14
|
-
* `
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
287
|
-
|
|
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
|
|
293
|
-
|
|
294
|
-
|
|
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
|
|
301
|
-
*
|
|
302
|
-
*
|
|
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
|
}
|
package/src/r2-stores.ts
ADDED
|
@@ -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
|
+
}
|
package/src/realtime-do.ts
CHANGED
|
@@ -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
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
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`
|
|
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,20 @@ 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,
|
|
88
|
+
type RemoteOperationResolver,
|
|
82
89
|
RingBufferEvents,
|
|
83
90
|
SSP2_CONTENT_TYPE,
|
|
84
91
|
SyncError,
|
|
85
92
|
SyncularAdmin,
|
|
93
|
+
type SyncularErrorRoute,
|
|
86
94
|
} from '@syncular/server';
|
|
87
95
|
import { createSyncularAdminRoutes } from '@syncular/server-hono';
|
|
88
96
|
|
|
@@ -139,6 +147,14 @@ export type RealtimeDOConfig = (
|
|
|
139
147
|
* partition's rounds.
|
|
140
148
|
*/
|
|
141
149
|
readonly adminRingCapacity?: number;
|
|
150
|
+
/**
|
|
151
|
+
* Registered remote queries and commands (REMOTE.md). The Worker forwards
|
|
152
|
+
* `POST <mount>/operations` here, so a command applies on the partition
|
|
153
|
+
* FIFO and fans out to the partition's sockets like a pushed commit. A
|
|
154
|
+
* `RemoteOperationResolver` chooses the registry, the commit actor, and
|
|
155
|
+
* the scope resolver per request (REMOTE.md §5.1).
|
|
156
|
+
*/
|
|
157
|
+
readonly operations?: RemoteOperationRegistry | RemoteOperationResolver;
|
|
142
158
|
};
|
|
143
159
|
|
|
144
160
|
/**
|
|
@@ -175,6 +191,10 @@ export interface RealtimeUpgradeIdentity {
|
|
|
175
191
|
export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
|
|
176
192
|
export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
|
|
177
193
|
export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
|
|
194
|
+
export const OPERATIONS_DO_REQUEST_PATH = '/__syncular_realtime/operations';
|
|
195
|
+
/** The remote operation protocol content type (REMOTE.md §5). */
|
|
196
|
+
export const OPERATIONS_CONTENT_TYPE =
|
|
197
|
+
'application/vnd.syncular.operations.v1+json';
|
|
178
198
|
/** Prefix of forwarded admin routes; the admin route path follows it. */
|
|
179
199
|
export const ADMIN_DO_PATH = '/__syncular_realtime/admin';
|
|
180
200
|
|
|
@@ -208,12 +228,17 @@ export class SyncularRealtimeHost {
|
|
|
208
228
|
#hub: RealtimeHub | undefined;
|
|
209
229
|
#admin: SyncularAdmin | undefined;
|
|
210
230
|
/** Live sessions, keyed by their socket. Empty after a hibernation wake;
|
|
211
|
-
*
|
|
231
|
+
* rehydrated for every socket before the first serialized operation (see
|
|
232
|
+
* the class doc). */
|
|
212
233
|
readonly #sessions = new Map<WebSocketLike, RealtimeSession>();
|
|
213
234
|
/** Sockets whose rehydration `hello` must be swallowed (already greeted at
|
|
214
235
|
* the real upgrade — rehydration is transparent to the client). */
|
|
215
236
|
readonly #swallowHello = new Set<WebSocketLike>();
|
|
216
237
|
readonly #closedSockets = new WeakSet<WebSocketLike>();
|
|
238
|
+
/** Accepted sockets whose upgrade is still building their session. */
|
|
239
|
+
readonly #upgrading = new WeakSet<WebSocketLike>();
|
|
240
|
+
/** Set once this instance rebuilt the sessions of hibernated sockets. */
|
|
241
|
+
#rehydrated = false;
|
|
217
242
|
/** Explicit FIFO: Durable Object events may interleave at `await`. */
|
|
218
243
|
#partitionTail: Promise<void> = Promise.resolve();
|
|
219
244
|
|
|
@@ -278,8 +303,11 @@ export class SyncularRealtimeHost {
|
|
|
278
303
|
if (url.pathname === SYNC_DO_REQUEST_PATH) {
|
|
279
304
|
return this.#serializePartition(() => this.#handleSync(request));
|
|
280
305
|
}
|
|
306
|
+
if (url.pathname === OPERATIONS_DO_REQUEST_PATH) {
|
|
307
|
+
return this.#serializePartition(() => this.#handleOperation(request));
|
|
308
|
+
}
|
|
281
309
|
if (url.pathname === REALTIME_DO_WAKE_PATH) {
|
|
282
|
-
return this.#handleWake(request);
|
|
310
|
+
return this.#serializePartition(() => this.#handleWake(request));
|
|
283
311
|
}
|
|
284
312
|
if (url.pathname === REALTIME_DO_UPGRADE_PATH) {
|
|
285
313
|
return this.#handleUpgrade(request);
|
|
@@ -299,7 +327,11 @@ export class SyncularRealtimeHost {
|
|
|
299
327
|
}
|
|
300
328
|
|
|
301
329
|
#serializePartition<T>(operation: () => Promise<T>): Promise<T> {
|
|
302
|
-
const
|
|
330
|
+
const run = async (): Promise<T> => {
|
|
331
|
+
await this.#rehydrateSockets();
|
|
332
|
+
return operation();
|
|
333
|
+
};
|
|
334
|
+
const result = this.#partitionTail.then(run, run);
|
|
303
335
|
this.#partitionTail = result.then(
|
|
304
336
|
() => undefined,
|
|
305
337
|
() => undefined,
|
|
@@ -307,6 +339,76 @@ export class SyncularRealtimeHost {
|
|
|
307
339
|
return result;
|
|
308
340
|
}
|
|
309
341
|
|
|
342
|
+
/**
|
|
343
|
+
* After a hibernation wake the session map is empty while sockets stay
|
|
344
|
+
* open. Rebuild every socket's session before the first serialized
|
|
345
|
+
* operation, so a commit fans out to sockets that stayed quiet through
|
|
346
|
+
* the hibernation. A socket whose session cannot be rebuilt is closed;
|
|
347
|
+
* its client reconnects and catches up (§8.4).
|
|
348
|
+
*/
|
|
349
|
+
async #rehydrateSockets(): Promise<void> {
|
|
350
|
+
if (this.#rehydrated) return;
|
|
351
|
+
this.#rehydrated = true;
|
|
352
|
+
for (const ws of this.#state.getWebSockets()) {
|
|
353
|
+
if (this.#upgrading.has(ws)) continue;
|
|
354
|
+
try {
|
|
355
|
+
await this.#sessionFor(ws);
|
|
356
|
+
} catch (error) {
|
|
357
|
+
ws.close(1011, 'realtime rehydration failed');
|
|
358
|
+
this.#syncError(error, 'realtime');
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
/**
|
|
364
|
+
* Map a host failure to its catalog error. The reporters are read inside
|
|
365
|
+
* the callbacks so a failing accessor stays inside `adapterSyncError`.
|
|
366
|
+
*/
|
|
367
|
+
#syncError(error: unknown, route: SyncularErrorRoute): SyncError {
|
|
368
|
+
return adapterSyncError(
|
|
369
|
+
error,
|
|
370
|
+
(error, context) => this.#getHub().onError?.(error, context),
|
|
371
|
+
route,
|
|
372
|
+
(error, context) => this.#getHub().mapError?.(error, context),
|
|
373
|
+
);
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
async #handleOperation(request: Request): Promise<Response> {
|
|
377
|
+
const contentType = request.headers
|
|
378
|
+
.get('content-type')
|
|
379
|
+
?.split(';')[0]
|
|
380
|
+
?.trim();
|
|
381
|
+
if (contentType !== OPERATIONS_CONTENT_TYPE) {
|
|
382
|
+
const error = new SyncError('operation.invalid_request');
|
|
383
|
+
return Response.json(errorBody(error), { status: 415 });
|
|
384
|
+
}
|
|
385
|
+
const registry = this.#config.operations;
|
|
386
|
+
if (registry === undefined) {
|
|
387
|
+
const error = new SyncError('operation.unknown');
|
|
388
|
+
return Response.json(errorBody(error), { status: error.httpStatus });
|
|
389
|
+
}
|
|
390
|
+
const identity = readRequestIdentityHeaders(request);
|
|
391
|
+
if (identity === undefined) {
|
|
392
|
+
const error = new SyncError('sync.auth_required');
|
|
393
|
+
return Response.json(errorBody(error), { status: error.httpStatus });
|
|
394
|
+
}
|
|
395
|
+
try {
|
|
396
|
+
const bytes = new Uint8Array(await request.arrayBuffer());
|
|
397
|
+
const out = await handleRemoteOperation(
|
|
398
|
+
bytes,
|
|
399
|
+
this.#getHub().requestContextFor(identity),
|
|
400
|
+
registry,
|
|
401
|
+
);
|
|
402
|
+
return new Response(out.slice().buffer as ArrayBuffer, {
|
|
403
|
+
status: 200,
|
|
404
|
+
headers: { 'content-type': OPERATIONS_CONTENT_TYPE },
|
|
405
|
+
});
|
|
406
|
+
} catch (error) {
|
|
407
|
+
const sync = this.#syncError(error, 'operations');
|
|
408
|
+
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
|
|
310
412
|
async #handleSync(request: Request): Promise<Response> {
|
|
311
413
|
const contentType = request.headers
|
|
312
414
|
.get('content-type')
|
|
@@ -335,12 +437,7 @@ export class SyncularRealtimeHost {
|
|
|
335
437
|
headers: { 'content-type': SSP2_CONTENT_TYPE },
|
|
336
438
|
});
|
|
337
439
|
} catch (error) {
|
|
338
|
-
const sync =
|
|
339
|
-
error,
|
|
340
|
-
(error, context) => this.#getHub().onError?.(error, context),
|
|
341
|
-
'sync',
|
|
342
|
-
(error, context) => this.#getHub().mapError?.(error, context),
|
|
343
|
-
);
|
|
440
|
+
const sync = this.#syncError(error, 'sync');
|
|
344
441
|
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
345
442
|
}
|
|
346
443
|
}
|
|
@@ -411,20 +508,18 @@ export class SyncularRealtimeHost {
|
|
|
411
508
|
clientId: identity.clientId,
|
|
412
509
|
};
|
|
413
510
|
server.serializeAttachment(attachment);
|
|
511
|
+
this.#upgrading.add(server);
|
|
414
512
|
this.#state.acceptWebSocket(server);
|
|
415
513
|
// Build the session now (first connect: hello IS delivered). Any failure
|
|
416
514
|
// closes the socket loudly — never a half-open realtime connection.
|
|
417
515
|
try {
|
|
418
516
|
const session = await this.#connectSession(server, attachment, false);
|
|
419
517
|
this.#sessions.set(server, session);
|
|
518
|
+
this.#upgrading.delete(server);
|
|
420
519
|
} catch (error) {
|
|
520
|
+
this.#upgrading.delete(server);
|
|
421
521
|
server.close(1011, 'realtime connect failed');
|
|
422
|
-
const sync =
|
|
423
|
-
error,
|
|
424
|
-
(error, context) => this.#getHub().onError?.(error, context),
|
|
425
|
-
'realtime',
|
|
426
|
-
(error, context) => this.#getHub().mapError?.(error, context),
|
|
427
|
-
);
|
|
522
|
+
const sync = this.#syncError(error, 'realtime');
|
|
428
523
|
return Response.json(errorBody(sync), { status: sync.httpStatus });
|
|
429
524
|
}
|
|
430
525
|
// `webSocket` is a workerd-only ResponseInit field (the 101 upgrade
|