The best way to control Claude Code, Codex and more from any computer or phone
| 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 | ); |