The best way to control Claude Code, Codex and more from any computer or phone

main
ts 467 lines 16.8 KB
Raw
1 import crypto from "node:crypto";
2 import * as dns from "node:dns/promises";
3 import { DEFAULT_COMPATIBILITY_DATE } from "@alchemy.run/cloudflare-runtime/core/internal/constants";
4 import * as durableObjects from "@distilled.cloud/cloudflare/durable-objects";
5 import * as secretsStore from "@distilled.cloud/cloudflare/secrets-store";
6 import * as workers from "@distilled.cloud/cloudflare/workers";
7 import * as zones from "@distilled.cloud/cloudflare/zones";
8 import { StateStoreError } from "alchemy/State/State";
9 import * as Context from "effect/Context";
10 import * as Effect from "effect/Effect";
11 import * as Option from "effect/Option";
12 import * as Schedule from "effect/Schedule";
13 import * as Stream from "effect/Stream";
14 import { waitForSecretActive } from "../SecretsStore/Secret.ts";
15 import { getCompatibility } from "../Workers/Compatibility.ts";
16 import { WorkerBundle } from "../Workers/Sources/Rolldown.ts";
17 import { contentTypeForModule, putWorkerScript } from "../Workers/WorkerProvider.ts";
18 import { resolveZoneId } from "../Zone/lookup.ts";
19 import { API_MAIN, STATE_STORE_VERSION } from "./Api.ts";
20 import {
21 AuthTokenBinding,
22 AuthTokenSecretName,
23 EncryptionKeyBinding,
24 EncryptionKeySecretName,
25 stateStoreSecretName,
26 } from "./Token.ts";
27
28 /** The Durable Object class holding every store's state. Its name must never change. */
29 const STORE_CLASS = "Store";
30
31 /** The stack name the Worker's runtime reports, kept from the stack-deployed era. */
32 const RUNTIME_STACK_NAME = "CloudflareStateStore";
33
34 /**
35 * Deploy a Cloudflare State Store Worker with direct API calls.
36 *
37 * Every step is idempotent and only ever adds what is missing: the account's
38 * Secrets Store and the two state-store secrets are created when absent and
39 * never updated or deleted, so redeploying cannot rotate the auth token or
40 * lose the encryption key. The Worker itself is re-uploaded on every call
41 * with the same `Store` Durable Object class, keeping its stored state.
42 *
43 * With a `domain`, the Worker is also attached to that hostname as a custom
44 * domain and served there.
45 *
46 * Returns the Worker's URL, and the auth token when this call created it
47 * (an existing token can only be read back through a Worker binding).
48 */
49 export const deployStateStoreWorker = Effect.fn("state_store.deploy_worker")(function* ({
50 accountId,
51 scriptName,
52 domain,
53 }: {
54 accountId: string;
55 scriptName: string;
56 domain: string | undefined;
57 }) {
58 yield* Effect.annotateCurrentSpan({ "alchemy.state_store.script_name": scriptName });
59 yield* validateStateStoreWorkerName(scriptName);
60 // Fail on secrets or a hostname another Worker owns before changing anything.
61 const sharing = yield* findSecretSharingWorker({ accountId, scriptName });
62 if (sharing !== undefined) {
63 return yield* new StateStoreError({
64 message:
65 `Cannot deploy the Cloudflare State Store '${scriptName}': its secrets would be shared ` +
66 `with Worker '${sharing}', because secret names replace '-' with '_'. Choose a ` +
67 `name that differs from '${sharing}' by more than '-' and '_'.`,
68 });
69 }
70 if (domain !== undefined) yield* observeStateStoreDomain({ accountId, scriptName, domain });
71 const storeId = yield* ensureSecretsStore(accountId);
72 const authToken = yield* ensureSecret({
73 accountId,
74 storeId,
75 name: stateStoreSecretName(AuthTokenSecretName, scriptName),
76 });
77 yield* ensureSecret({
78 accountId,
79 storeId,
80 name: stateStoreSecretName(EncryptionKeySecretName, scriptName),
81 });
82
83 const compatibility = getCompatibility({
84 main: API_MAIN,
85 compatibility: { date: DEFAULT_COMPATIBILITY_DATE },
86 });
87 const bundler = yield* WorkerBundle;
88 const bundle = yield* bundler.build({
89 id: "Api",
90 main: API_MAIN,
91 compatibility,
92 entry: {
93 kind: "effect",
94 // The entry only needs the class name to export the Durable Object bridge.
95 exports: {
96 [STORE_CLASS]: {
97 kind: "durableObject",
98 constructor: Effect.never,
99 services: Context.empty(),
100 },
101 },
102 },
103 stack: { name: RUNTIME_STACK_NAME, stage: scriptName },
104 extraOptions: undefined,
105 });
106
107 yield* putWorkerScript({
108 accountId,
109 scriptName,
110 dispatchNamespace: undefined,
111 metadata: {
112 mainModule: bundle.files[0]!.path,
113 compatibilityDate: compatibility.date,
114 compatibilityFlags: compatibility.flags,
115 bindings: [
116 { type: "plain_text", name: "ALCHEMY_PHASE", text: "runtime" },
117 { type: "plain_text", name: "ALCHEMY_WORKER_NAME", text: scriptName },
118 { type: "plain_text", name: "ALCHEMY_STACK_NAME", text: RUNTIME_STACK_NAME },
119 { type: "plain_text", name: "ALCHEMY_STAGE", text: scriptName },
120 { type: "plain_text", name: "ALCHEMY_CLOUDFLARE_ACCOUNT_ID", text: accountId },
121 {
122 type: "plain_text",
123 name: STATE_STORE_VERSION_BINDING,
124 text: String(STATE_STORE_VERSION),
125 },
126 {
127 type: "secrets_store_secret",
128 name: AuthTokenBinding,
129 storeId,
130 secretName: stateStoreSecretName(AuthTokenSecretName, scriptName),
131 },
132 {
133 type: "secrets_store_secret",
134 name: EncryptionKeyBinding,
135 storeId,
136 secretName: stateStoreSecretName(EncryptionKeySecretName, scriptName),
137 },
138 { type: "durable_object_namespace", name: STORE_CLASS, className: STORE_CLASS },
139 ],
140 exports: {
141 [STORE_CLASS]: {
142 type: "durable-object",
143 storage: yield* observedStoreStorage(accountId, scriptName),
144 },
145 },
146 observability: { enabled: true, logs: { enabled: true, invocationLogs: true } },
147 },
148 files: bundle.files.map(
149 (file) =>
150 new File([file.content as BlobPart], file.path, {
151 type: contentTypeForModule(file.path),
152 }),
153 ),
154 });
155
156 yield* workers.createScriptSubdomain({
157 accountId,
158 scriptName,
159 enabled: true,
160 previewsEnabled: true,
161 });
162 if (domain !== undefined) yield* attachDomain({ accountId, scriptName, domain });
163 return { url: yield* stateStoreUrl({ accountId, scriptName, domain }), authToken };
164 });
165
166 /**
167 * A store's Worker name: lowercase letters, digits, `-` and `_`, starting with
168 * a letter or digit, at most 54 characters. The store enables workers.dev
169 * previews, and Cloudflare rejects a longer script name with previews enabled
170 * (the preview hostname prefixes it); the cap also keeps its secret names well
171 * under the Secrets Store's 255.
172 */
173 export const validateStateStoreWorkerName = (scriptName: string) =>
174 /^[a-z0-9][a-z0-9_-]{0,53}$/.test(scriptName)
175 ? Effect.succeed(scriptName)
176 : Effect.fail(
177 new StateStoreError({
178 message:
179 `Invalid Cloudflare State Store Worker name '${scriptName}': use 1-54 lowercase ` +
180 `letters, digits, '-' and '_', starting with a letter or digit.`,
181 }),
182 );
183
184 /**
185 * Another Worker whose store's secrets have the same names as this store's.
186 * Secret names replace every character other than a letter, digit or `_` with
187 * `_`, so the stores `team-a` and `team_a` would share one token and key.
188 */
189 export const findSecretSharingWorker = Effect.fn(function* ({
190 accountId,
191 scriptName,
192 }: {
193 accountId: string;
194 scriptName: string;
195 }) {
196 const secretName = stateStoreSecretName(AuthTokenSecretName, scriptName);
197 return yield* workers.listScripts.items({ accountId }).pipe(
198 Stream.map((script) => script.id ?? undefined),
199 Stream.filter(
200 (name): name is string =>
201 name !== undefined &&
202 name !== scriptName &&
203 stateStoreSecretName(AuthTokenSecretName, name) === secretName,
204 ),
205 Stream.runHead,
206 Effect.map(Option.getOrUndefined),
207 );
208 });
209
210 /** The binding each deployed store records its version in, read back through the API. */
211 const STATE_STORE_VERSION_BINDING = "ALCHEMY_STATE_STORE_VERSION";
212
213 /**
214 * The store's version as Cloudflare's API reports it, `undefined` when it has
215 * no Worker, or `"unrecorded"` for a Worker an older Alchemy deployed without
216 * recording it. The edge can keep serving a deleted or replaced Worker for a
217 * while, so decisions use this rather than what `/version` answers.
218 */
219 export const observeDeployedVersion = Effect.fn(function* ({
220 accountId,
221 scriptName,
222 }: {
223 accountId: string;
224 scriptName: string;
225 }) {
226 const settings = yield* workers
227 .getScriptScriptAndVersionSetting({ accountId, scriptName })
228 .pipe(Effect.catchTag(["WorkerNotFound", "WorkerHasNoVersions"], () => Effect.undefined));
229 if (settings === undefined) return undefined;
230 const binding = (settings.bindings ?? []).find(
231 (binding) => binding.name === STATE_STORE_VERSION_BINDING,
232 );
233 const version = binding !== undefined && "text" in binding ? Number(binding.text) : Number.NaN;
234 return Number.isInteger(version) ? version : ("unrecorded" as const);
235 });
236
237 /** The origin a store serves on: its custom domain, or its workers.dev URL. */
238 export const stateStoreUrl = Effect.fn(function* ({
239 accountId,
240 scriptName,
241 domain,
242 }: {
243 accountId: string;
244 scriptName: string;
245 domain: string | undefined;
246 }) {
247 if (domain !== undefined) return `https://${domain}`;
248 const { subdomain } = yield* workers.getSubdomain({ accountId });
249 return `https://${scriptName}.${subdomain}.workers.dev`;
250 });
251
252 /**
253 * The zone of the custom domain `domain` when it is attached to this Worker,
254 * or `undefined`. Fails when another Worker owns the hostname.
255 */
256 export const observeStateStoreDomain = Effect.fn(function* ({
257 accountId,
258 scriptName,
259 domain,
260 }: {
261 accountId: string;
262 scriptName: string;
263 domain: string;
264 }) {
265 const { result } = yield* workers.listDomains({ accountId, hostname: domain });
266 const attached = (result ?? []).find((d) => d.hostname === domain);
267 if (attached === undefined) return undefined;
268 if (attached.service !== scriptName) {
269 return yield* new StateStoreError({
270 message:
271 `Cannot serve the Cloudflare State Store '${scriptName}' on '${domain}': it is ` +
272 `already attached to Worker '${attached.service ?? "<unknown>"}'.`,
273 });
274 }
275 return attached.zoneId ?? undefined;
276 });
277
278 /** Attach `domain` to the Worker as a custom domain, unless it already is. */
279 const attachDomain = Effect.fn(function* ({
280 accountId,
281 scriptName,
282 domain,
283 }: {
284 accountId: string;
285 scriptName: string;
286 domain: string;
287 }) {
288 if ((yield* observeStateStoreDomain({ accountId, scriptName, domain })) !== undefined) return;
289 const zoneId = yield* resolveZoneId({ accountId, zone: undefined, hostname: domain }).pipe(
290 Effect.mapError(
291 (cause) =>
292 new StateStoreError({
293 message: `Couldn't find the Cloudflare zone of '${domain}' on account ${accountId}.`,
294 cause,
295 }),
296 ),
297 );
298 yield* workers.putDomain({ accountId, hostname: domain, service: scriptName, zoneId }).pipe(
299 // The script registry can lag the upload by a few seconds.
300 Effect.retry({
301 while: (error) => error._tag === "WorkerNotFound",
302 schedule: Schedule.max([Schedule.exponential(200), Schedule.recurs(15)]),
303 }),
304 );
305 yield* waitForAuthoritativeDns(zoneId, domain);
306 });
307
308 /**
309 * Wait until the zone's nameservers answer for a newly attached `domain`.
310 * Resolving it any earlier caches NXDOMAIN in the local resolver for the
311 * zone's negative TTL (30 minutes on Cloudflare), and the store would be
312 * unreachable from this machine for that long.
313 */
314 const waitForAuthoritativeDns = Effect.fn(function* (zoneId: string, domain: string) {
315 const { nameServers } = yield* zones.getZone({ zoneId });
316 const servers = yield* Effect.forEach(nameServers, (ns) =>
317 Effect.tryPromise(() => dns.resolve4(ns)).pipe(Effect.orElseSucceed(() => [])),
318 ).pipe(Effect.map((ips) => ips.flat()));
319 if (servers.length === 0) return;
320 // A fresh resolver per attempt: one caches the NXDOMAIN it got first.
321 const resolver = Effect.sync(() => {
322 const resolver = new dns.Resolver({ timeout: 2_000, tries: 1 });
323 resolver.setServers(servers);
324 return resolver;
325 });
326 yield* resolver.pipe(
327 Effect.flatMap((resolver) => Effect.tryPromise(() => resolver.resolve4(domain))),
328 Effect.filterOrFail((addresses) => addresses.length > 0),
329 // Cloudflare can take a minute to publish a re-attached custom domain.
330 Effect.retry({ schedule: Schedule.spaced("2 seconds"), times: 45 }),
331 Effect.mapError(
332 (cause) =>
333 new StateStoreError({
334 message: `'${domain}' was attached to the State Store but its DNS record never appeared.`,
335 cause,
336 }),
337 ),
338 );
339 });
340
341 /** Whether the store's auth token and encryption key both exist. */
342 export const stateStoreSecretsExist = Effect.fn(function* ({
343 accountId,
344 scriptName,
345 }: {
346 accountId: string;
347 scriptName: string;
348 }) {
349 const names = new Set([
350 stateStoreSecretName(AuthTokenSecretName, scriptName),
351 stateStoreSecretName(EncryptionKeySecretName, scriptName),
352 ]);
353 const store = yield* secretsStore.listStores.items({ accountId }).pipe(Stream.runHead);
354 if (Option.isNone(store)) return false;
355 const found = yield* secretsStore.listStoreSecrets
356 .items({ accountId, storeId: store.value.id })
357 .pipe(
358 Stream.filter((secret) => names.has(secret.name)),
359 Stream.runCollect,
360 );
361 return new Set(Array.from(found, (secret) => secret.name)).size === names.size;
362 });
363
364 /**
365 * Whether a store that may hold state has lost its encryption key: its Worker
366 * exists, so it served state encrypted with a key, but the key is gone. A
367 * listing can lag a create, so the key must be missing from several reads.
368 */
369 export const encryptionKeyLost = Effect.fn(function* ({
370 accountId,
371 scriptName,
372 }: {
373 accountId: string;
374 scriptName: string;
375 }) {
376 const hasWorker = yield* workers.getScriptSetting({ accountId, scriptName }).pipe(
377 Effect.as(true),
378 Effect.catchTag(["WorkerNotFound", "InvalidRoute", "WorkerHasNoVersions"], () =>
379 Effect.succeed(false),
380 ),
381 );
382 if (!hasWorker) return false;
383 const name = stateStoreSecretName(EncryptionKeySecretName, scriptName);
384 const listed = Effect.gen(function* () {
385 const store = yield* secretsStore.listStores.items({ accountId }).pipe(Stream.runHead);
386 if (Option.isNone(store)) return false;
387 return yield* secretsStore.listStoreSecrets.items({ accountId, storeId: store.value.id }).pipe(
388 Stream.filter((secret) => secret.name === name),
389 Stream.runHead,
390 Effect.map(Option.isSome),
391 );
392 });
393 const found = yield* listed.pipe(
394 Effect.repeat({ until: (found) => found, schedule: Schedule.spaced("2 seconds"), times: 3 }),
395 );
396 return !found;
397 });
398
399 /** The account's Secrets Store (Cloudflare allows one), created when missing. */
400 const ensureSecretsStore = Effect.fn(function* (accountId: string) {
401 const first = secretsStore.listStores
402 .items({ accountId })
403 .pipe(Stream.runHead, Effect.map(Option.getOrUndefined));
404 const existing = yield* first;
405 if (existing) return existing.id;
406 const created = yield* secretsStore
407 .createStore({ accountId, name: "default_secrets_store" })
408 .pipe(
409 // A concurrent bootstrap created it first.
410 Effect.catchTag("MaximumStoresExceeded", () => Effect.undefined),
411 );
412 if (created) return created.id;
413 const raced = yield* first;
414 if (raced) return raced.id;
415 return yield* Effect.die(
416 new Error(`Cloudflare reports a Secrets Store on account ${accountId} but lists none.`),
417 );
418 });
419
420 /**
421 * Create a secret holding 32 random hex-encoded bytes, unless one with this
422 * name exists. Returns the value only when this call created it; an existing
423 * secret is left exactly as it is.
424 */
425 const ensureSecret = Effect.fn(function* ({
426 accountId,
427 storeId,
428 name,
429 }: {
430 accountId: string;
431 storeId: string;
432 name: string;
433 }) {
434 const exists = yield* secretsStore.listStoreSecrets.items({ accountId, storeId }).pipe(
435 Stream.filter((secret) => secret.name === name),
436 Stream.runHead,
437 Effect.map(Option.isSome),
438 );
439 if (exists) return undefined;
440 const value = yield* Effect.sync(() => crypto.randomBytes(32).toString("hex"));
441 const created = yield* secretsStore
442 .createStoreSecret({
443 accountId,
444 storeId,
445 body: [{ name, scopes: ["workers"], value, comment: "Alchemy Cloudflare State Store" }],
446 })
447 .pipe(
448 // A concurrent bootstrap created it first; keep theirs.
449 Effect.catchTag("SecretNameAlreadyExists", () => Effect.undefined),
450 );
451 if (!created) return undefined;
452 const secret = created.result[0]!;
453 yield* waitForSecretActive({ accountId, storeId, secretId: secret.id }, "pending");
454 return value;
455 });
456
457 /** The `Store` class's storage backend as deployed; SQLite for a new store. */
458 const observedStoreStorage = (accountId: string, scriptName: string) =>
459 durableObjects.listNamespaces.items({ accountId }).pipe(
460 Stream.filter((ns) => ns.script === scriptName && ns.class === STORE_CLASS),
461 Stream.runHead,
462 Effect.map((ns) =>
463 Option.isSome(ns) && ns.value.useSqlite === false
464 ? ("legacy-kv" as const)
465 : ("sqlite" as const),
466 ),
467 );