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

main
ts 1,014 lines 39.8 KB
Raw
1 import crypto from "node:crypto";
2 import * as SecretsStore from "@distilled.cloud/cloudflare/secrets-store";
3 import * as workers from "@distilled.cloud/cloudflare/workers";
4 import { AuthError } from "alchemy/Auth/AuthProvider";
5 import { CredentialsStore } from "alchemy/Auth/Credentials";
6 import { currentProfileName } from "alchemy/Auth/Profile";
7 import { emit } from "alchemy/Events";
8 import * as Interaction from "alchemy/Interaction";
9 import { StateApi } from "alchemy/State/HttpStateApi";
10 import {
11 checkHttpStateStoreAuth,
12 makeHttpStateStore,
13 type HttpStateStoreCredentials,
14 } from "alchemy/State/HttpStateStore";
15 import { makeLocalState } from "alchemy/State/LocalState";
16 import * as Provisioning from "alchemy/State/Provisioning";
17 import { State, StateStoreError } from "alchemy/State/State";
18 import { recordStateStoreInit, recordStateStoreOp } from "alchemy/Telemetry/Metrics";
19 import { globalLogs } from "alchemy/Util/LogRecord";
20 import * as Config from "effect/Config";
21 import * as Data from "effect/Data";
22 import * as Effect from "effect/Effect";
23 import * as HttpApiClient from "effect/http-api/HttpApiClient";
24 import * as HttpClient from "effect/http/HttpClient";
25 import * as HttpClientRequest from "effect/http/HttpClientRequest";
26 import * as Layer from "effect/Layer";
27 import * as Option from "effect/Option";
28 import * as Schedule from "effect/Schedule";
29 import * as Stream from "effect/Stream";
30 import * as Access from "../Access.ts";
31 import * as CloudflareEnvironment from "../CloudflareEnvironment.ts";
32 import { EdgeSessionError, createEdgeSession } from "../EdgeSession.ts";
33 import * as Cloudflare from "../Providers.ts";
34 import { STATE_STORE_SCRIPT_NAME, STATE_STORE_VERSION } from "./Api.ts";
35 import {
36 deleteStoreCredentials,
37 readStoreCredentials,
38 writeStoreCredentials,
39 isStateStoreCredentialsStale,
40 } from "./CredentialsFile.ts";
41 import {
42 deployStateStoreWorker,
43 encryptionKeyLost,
44 findSecretSharingWorker,
45 observeDeployedVersion,
46 observeStateStoreDomain,
47 stateStoreSecretsExist,
48 stateStoreUrl,
49 validateStateStoreWorkerName,
50 } from "./Deploy.ts";
51 import { AuthTokenSecretName, EncryptionKeySecretName, stateStoreSecretName } from "./Token.ts";
52
53 const CI = Config.Boolean("CI").pipe(Config.withDefault(false));
54
55 export type CloudflareStateOptions = {
56 /**
57 * The Cloudflare account the store lives in. Defaults to the account your
58 * Alchemy profile resolves. Pin it when your credentials reach several
59 * accounts, so a login against a different one can't read or deploy the
60 * store somewhere else.
61 */
62 readonly accountId?: string;
63 /**
64 * Serve the store on this hostname in one of the account's zones instead of
65 * its workers.dev URL, for networks that can't reach workers.dev. Bootstrap
66 * attaches it to the store's Worker as a custom domain.
67 */
68 readonly domain?: string;
69 /**
70 * The store's Worker name, for a store other than the account's default
71 * `alchemy-state-store`: 1-54 lowercase letters, digits, `-` and `_`,
72 * starting with a letter or digit. Its secrets are named after it, e.g.
73 * `acme-state` keeps its token in `AlchemyStateStoreToken_acme_state`.
74 * @default "alchemy-state-store"
75 */
76 readonly workerName?: string;
77 };
78
79 export const state = (options: CloudflareStateOptions = {}) =>
80 Layer.effect(
81 State,
82 Effect.gen(function* () {
83 const isCI = yield* CI;
84 const { workerName, domain } = options;
85 const scriptName = workerName ?? STATE_STORE_SCRIPT_NAME;
86 const profileName = yield* currentProfileName;
87 const credStore = yield* CredentialsStore;
88 const context = yield* Effect.context<Effect.Services<typeof init>>();
89 const store: Provisioning.StoreRef = {
90 backend: "cloudflare",
91 name: workerName,
92 label: `Cloudflare State Store '${scriptName}'`,
93 configured: options.accountId !== undefined || domain !== undefined,
94 };
95
96 const init = Effect.gen(function* () {
97 yield* validateStateStoreWorkerName(scriptName);
98 const accountId = yield* resolveAccountId(options.accountId);
99 const deployMissing = Provisioning.deployMissing(
100 store,
101 bootstrap({ workerName: scriptName, profile: profileName, accountId, domain }),
102 );
103
104 const ensureLatest = ({ url, authToken }: { url: string; authToken: string }) =>
105 Effect.gen(function* () {
106 const observed = yield* observeServedVersion(accountId, scriptName, domain);
107 if (observed === undefined) return yield* deployMissing;
108 const expected = STATE_STORE_VERSION;
109 const matches = observed === expected;
110
111 const httpState = yield* ensureAccess({ url, authToken });
112 if (matches) return httpState;
113
114 // The store is out of date. Upgrade it in place.
115 const upgrade = Effect.gen(function* () {
116 const interaction = yield* Interaction.Interaction;
117 return yield* interaction.task(
118 {
119 label: `Updating Cloudflare State Store '${scriptName}'`,
120 detail: `v${observed ?? "unknown"} → v${expected}`,
121 },
122 deployStateStore({
123 accountId,
124 scriptName,
125 domain,
126 profileName,
127 isCI,
128 force: false,
129 }).pipe(Effect.flatMap(makeCloudflareStateStore)),
130 );
131 }).pipe(withStateBootstrapEvents(scriptName));
132 return yield* Provisioning.upgradeOutdated({ ...store, observed, expected }, upgrade);
133 });
134
135 const ensureAccess = (credentials: HttpStateStoreCredentials) =>
136 Effect.gen(function* () {
137 if (yield* checkHttpStateStoreAuth(credentials)) {
138 return yield* makeCloudflareStateStore(credentials);
139 }
140 // our token is wrong, force a refresh
141 const refreshed = yield* loginWithCloudflare(
142 profileName,
143 true,
144 scriptName,
145 accountId,
146 domain,
147 );
148 if (!(yield* checkHttpStateStoreAuth(refreshed))) {
149 return yield* new StateStoreError({
150 message: `${store.label} authentication failed, after refreshing credentials.`,
151 });
152 }
153 return yield* makeCloudflareStateStore(refreshed);
154 });
155
156 const credentials = yield* readStoreCredentials(credStore, profileName, scriptName);
157 if (credentials) {
158 // The cached `url`/`authToken` are minted per-account (the `url`
159 // encodes the account via its workers.dev subdomain). If the
160 // active account changed since they were written — or the file
161 // predates the `accountId` field — trusting the cache would
162 // silently read/write state in the wrong account, so discard it
163 // and fall through to re-derivation from the current account.
164 if (isStateStoreCredentialsStale(credentials, accountId)) {
165 yield* Interaction.info(
166 `Cloudflare State Store credentials were minted for a different ` +
167 `Cloudflare account; re-deriving for the current account.`,
168 );
169 yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);
170 } else if (!servesOn(credentials.url, domain)) {
171 // The store's `domain` changed since these were cached.
172 yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);
173 } else {
174 return yield* ensureLatest(credentials);
175 }
176 }
177 if ((yield* observeServedVersion(accountId, scriptName, domain)) !== undefined) {
178 return yield* ensureLatest(
179 yield* loginWithCloudflare(profileName, false, scriptName, accountId, domain),
180 );
181 }
182 return yield* deployMissing;
183 // Account-level: filed in the global run log, not the project's.
184 }).pipe(recordStateStoreInit, globalLogs, Effect.orDie);
185
186 return yield* Effect.cached(init.pipe(Effect.provideContext(context)));
187 }),
188 ).pipe(
189 // The Cloudflare API foundation shared with `providers()` —
190 // credentials, environment, auth/access, profile + credential
191 // store, and the same blanket retry policy. Without the retry
192 // policy the init-time subdomain/script/secrets probes run on the
193 // SDK default and give up early under Cloudflare rate limiting.
194 // `provide` (not `provideMerge`) so the distilled Retry tag stays
195 // out of this layer's public type.
196 Layer.provide(Cloudflare.CloudflareApiLive()),
197 Layer.orDie,
198 );
199
200 export interface BootstrapOptions {
201 /** @default "alchemy-state-store" */
202 workerName?: string;
203 /** The account to deploy into. Defaults to the profile's account. */
204 accountId?: string;
205 /** A hostname to serve the store on, attached as a custom domain. */
206 domain?: string;
207 /** @default false */
208 force?: boolean;
209 /** @default "default" */
210 profile?: string;
211 }
212
213 /**
214 * Report `state.bootstrap.*` progress events around a state-store deploy or
215 * upgrade. Bootstrap runs lazily inside the plan's "loading state" phase,
216 * can take many seconds (it deploys a worker), and would otherwise be
217 * invisible to non-interactive renderers and traces — the Interaction task only
218 * paints the local terminal.
219 */
220 const withStateBootstrapEvents =
221 (store: string) =>
222 <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
223 Effect.gen(function* () {
224 yield* emit({ type: "state.bootstrap.started", store });
225 const result = yield* effect;
226 yield* emit({ type: "state.bootstrap.completed", store });
227 return result;
228 });
229
230 export const bootstrap = (options: BootstrapOptions = {}) =>
231 withStateBootstrapEvents(options.workerName ?? STATE_STORE_SCRIPT_NAME)(
232 Effect.gen(function* () {
233 const interaction = yield* Interaction.Interaction;
234 const isCI = yield* CI;
235 const profileName = options.profile ?? (yield* currentProfileName);
236 const scriptName = yield* validateStateStoreWorkerName(
237 options.workerName ?? STATE_STORE_SCRIPT_NAME,
238 );
239 const force = options.force ?? false;
240 const accountId = yield* resolveAccountId(options.accountId);
241 const { domain } = options;
242 yield* Effect.annotateCurrentSpan({
243 "alchemy.state_store.script_name": scriptName,
244 "alchemy.state_store.profile": profileName,
245 "alchemy.state_store.force": force,
246 "alchemy.state_store.ci": isCI,
247 });
248 yield* annotateAccountHash(accountId);
249
250 const observed = yield* observeServedVersion(accountId, scriptName, domain);
251 const serving = observed !== undefined;
252 // A store missing a secret is redeployed, which creates only the missing one.
253 if (serving && !force && (yield* stateStoreSecretsExist({ accountId, scriptName }))) {
254 yield* Interaction.info(
255 `Worker '${scriptName}' already exists; adopting and refreshing credentials. ` +
256 `Use --force to redeploy.`,
257 );
258 const credentials = yield* loginWithCloudflare(
259 profileName,
260 true,
261 scriptName,
262 accountId,
263 domain,
264 );
265 if (observed === STATE_STORE_VERSION) {
266 yield* forgetLegacyBootstrapStack(credentials, scriptName);
267 return yield* makeCloudflareStateStore(credentials);
268 }
269 }
270 return yield* interaction.task(
271 {
272 label: `${serving ? "Updating" : "Deploying"} Cloudflare State Store '${scriptName}'`,
273 },
274 deployStateStore({ accountId, scriptName, domain, profileName, isCI, force }).pipe(
275 Effect.flatMap(makeCloudflareStateStore),
276 ),
277 );
278 }).pipe(
279 Effect.withSpan("state_store.bootstrap", {
280 attributes: {
281 "alchemy.state_store.op": "bootstrap",
282 "alchemy.state_store.script_name": options.workerName ?? STATE_STORE_SCRIPT_NAME,
283 },
284 }),
285 // Account-level: filed in the global run log, not the project's.
286 globalLogs,
287 ),
288 );
289
290 export interface TeardownOptions {
291 /** @default "alchemy-state-store" */
292 workerName?: string;
293 /** The account the store lives in. Defaults to the profile's account. */
294 accountId?: string;
295 /** @default "default" */
296 profile?: string;
297 /**
298 * Delete the account Secrets Store too, but only once the state-store
299 * secrets have been removed and no other secrets remain in it. A store that
300 * still holds foreign secrets is left in place.
301 * @default true
302 */
303 deleteEmptySecretsStore?: boolean;
304 }
305
306 /**
307 * The inverse of {@link bootstrap}: tear down the Cloudflare-deployed state
308 * store. Deletes the state-store Worker and the secrets it created in the
309 * account Secrets Store (the bearer token + the encryption key), then deletes
310 * the Secrets Store itself if it is left empty, and drops the locally cached
311 * state-store credentials for the profile.
312 *
313 * Idempotent — missing resources are treated as already-gone, so it is safe to
314 * re-run. Intended for reclaiming a throwaway account after testing; on a
315 * shared account it only removes resources alchemy created.
316 */
317 export const teardownStateStore = (options: TeardownOptions = {}) =>
318 Effect.gen(function* () {
319 const interaction = yield* Interaction.Interaction;
320 const profileName = options.profile ?? (yield* currentProfileName);
321 const scriptName = options.workerName ?? STATE_STORE_SCRIPT_NAME;
322 const deleteEmptyStore = options.deleteEmptySecretsStore ?? true;
323 const accountId = yield* resolveAccountId(options.accountId);
324
325 yield* annotateAccountHash(accountId);
326 yield* Effect.annotateCurrentSpan({
327 "alchemy.state_store.script_name": scriptName,
328 "alchemy.state_store.profile": profileName,
329 });
330
331 // 1. Delete the state-store Worker.
332 yield* Interaction.info(`Deleting state store worker '${scriptName}'...`);
333 yield* workers.deleteScript({ accountId, scriptName, force: true }).pipe(
334 Effect.asVoid,
335 Effect.catchTag("WorkerNotFound", () =>
336 interaction.output.info(` Worker '${scriptName}' not found (already gone).`),
337 ),
338 );
339
340 // 2. Delete the secrets the state store created, plus any now-empty store,
341 // unless another store's Worker shares them.
342 const sharing = yield* findSecretSharingWorker({ accountId, scriptName });
343 if (sharing !== undefined) {
344 yield* Interaction.info(
345 `Keeping the secrets of '${scriptName}': Worker '${sharing}' uses the same secrets.`,
346 );
347 }
348 const ourSecretNames = new Set<string>(
349 sharing === undefined
350 ? [
351 stateStoreSecretName(AuthTokenSecretName, scriptName),
352 stateStoreSecretName(EncryptionKeySecretName, scriptName),
353 ]
354 : [],
355 );
356 const stores = yield* SecretsStore.listStores.items({ accountId }).pipe(
357 Stream.runCollect,
358 Effect.map((chunk) => Array.from(chunk)),
359 Effect.catchTag("InvalidAccountId", () => Effect.succeed([])),
360 );
361 for (const store of stores) {
362 const secrets = yield* SecretsStore.listStoreSecrets
363 .items({ accountId, storeId: store.id })
364 .pipe(
365 Stream.runCollect,
366 Effect.map((chunk) => Array.from(chunk)),
367 Effect.catchTag(["StoreNotFound", "InvalidAccountId"], () => Effect.succeed([])),
368 );
369 const ours = secrets.filter((s) => ourSecretNames.has(s.name));
370 for (const secret of ours) {
371 yield* Interaction.info(`Deleting secret '${secret.name}'...`);
372 yield* SecretsStore.deleteStoreSecret({
373 accountId,
374 storeId: store.id,
375 secretId: secret.id,
376 }).pipe(
377 Effect.asVoid,
378 Effect.catchTag(
379 ["SecretNotFound", "StoreNotFound", "NotFound", "InvalidAccountId"],
380 () => Effect.void,
381 ),
382 );
383 }
384 const remaining = secrets.length - ours.length;
385 if (deleteEmptyStore && remaining === 0) {
386 yield* Interaction.info(`Deleting empty secrets store '${store.id}'...`);
387 yield* SecretsStore.deleteStore({
388 accountId,
389 storeId: store.id,
390 force: true,
391 }).pipe(
392 Effect.asVoid,
393 Effect.catchTag(["StoreNotFound", "NotFound", "InvalidAccountId"], () => Effect.void),
394 );
395 } else if (remaining > 0) {
396 yield* Interaction.info(
397 `Secrets store '${store.id}' still has ${remaining} other ` +
398 `secret(s); leaving it in place.`,
399 );
400 }
401 }
402
403 // 3. Drop the locally cached state-store credentials for this profile.
404 const credStore = yield* CredentialsStore;
405 yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);
406
407 yield* Interaction.success(`Cloudflare State Store '${scriptName}' torn down.`);
408 }).pipe(
409 Effect.withSpan("state_store.teardown", {
410 attributes: {
411 "alchemy.state_store.op": "teardown",
412 "alchemy.state_store.script_name": options.workerName ?? STATE_STORE_SCRIPT_NAME,
413 },
414 }),
415 );
416
417 /**
418 * Deploy (or update) the store with direct API calls, wait until it serves
419 * this CLI's version, and resolve its credentials. A token this deploy created
420 * is returned directly; an existing one is read back through the Worker.
421 */
422 const deployStateStore = ({
423 accountId,
424 scriptName,
425 domain,
426 profileName,
427 isCI,
428 force,
429 }: {
430 accountId: string;
431 scriptName: string;
432 domain: string | undefined;
433 profileName: string;
434 isCI: boolean;
435 /** Approves replacing a lost encryption key without asking. */
436 force: boolean;
437 }) =>
438 Effect.gen(function* () {
439 if (
440 (yield* encryptionKeyLost({ accountId, scriptName })) &&
441 !(force || (yield* confirmNewEncryptionKey(scriptName, isCI)))
442 ) {
443 return yield* new StateStoreError({
444 message:
445 `Cloudflare State Store '${scriptName}' has lost its encryption key, so the state ` +
446 `it holds can no longer be decrypted. Nothing was changed. To start over with a new ` +
447 `key, which leaves that state unreadable, run 'alchemy state bootstrap' in a ` +
448 `terminal and confirm, or pass --force with --backend.`,
449 });
450 }
451 const { url, authToken } = yield* deployStateStoreWorker({ accountId, scriptName, domain });
452 // Cloudflare's worker upload is eventually consistent: the edge can keep
453 // serving the previous version for several seconds. Wait until `/version`
454 // reports the version this CLI was built against before using it.
455 yield* waitForStateStoreVersion(url, scriptName, accountId);
456 const credentials =
457 authToken === undefined
458 ? yield* loginWithCloudflare(profileName, true, scriptName, accountId, domain)
459 : { url, authToken, accountId };
460 if (authToken !== undefined && !isCI) {
461 // CI file systems are ephemeral; credentials are re-read each run.
462 yield* writeStoreCredentials(yield* CredentialsStore, profileName, scriptName, credentials);
463 }
464 yield* forgetLegacyBootstrapStack(credentials, scriptName);
465 return credentials;
466 }).pipe(
467 Effect.withSpan("state_store.deploy", {
468 attributes: { "alchemy.state_store.op": "deploy" },
469 }),
470 recordStateStoreOp("deploy"),
471 );
472
473 /** Ask before giving a store that lost its encryption key a new one. Never in CI. */
474 const confirmNewEncryptionKey = (scriptName: string, isCI: boolean) =>
475 Effect.gen(function* () {
476 const interaction = yield* Effect.serviceOption(Interaction.Interaction);
477 if (isCI || Option.isNone(interaction)) return false;
478 return yield* interaction.value.prompt
479 .confirm({
480 message:
481 `Cloudflare State Store '${scriptName}' has lost its encryption key, so its state ` +
482 `can't be decrypted. Create a new key and start with an empty store?`,
483 initialValue: false,
484 })
485 .pipe(Effect.orElseSucceed(() => false));
486 });
487
488 /** The stack Alchemy versions before direct deploys deployed the store through. */
489 const LEGACY_BOOTSTRAP_STACK = "CloudflareStateStore";
490
491 /**
492 * Delete the records of the stack older versions deployed the store through:
493 * the store's own, and those an interrupted bootstrap left in this project's
494 * local state. Destroying that stack would delete the store's Worker and
495 * secrets. A failure only warns: the store refuses that stack's reads and
496 * writes either way, and the next bootstrap tries again.
497 */
498 const forgetLegacyBootstrapStack = Effect.fn("state_store.forget_legacy_stack")(
499 function* (credentials: HttpStateStoreCredentials, scriptName: string) {
500 const remote = yield* makeCloudflareStateStore(credentials);
501 yield* remote.deleteStack({ stack: LEGACY_BOOTSTRAP_STACK });
502 // An interrupted bootstrap left its stage as `<profile>_<worker>`.
503 const local = yield* makeLocalState();
504 const stages = yield* local.listStages(LEGACY_BOOTSTRAP_STACK);
505 yield* Effect.forEach(
506 stages.filter((stage) => stage.endsWith(`_${scriptName}`)),
507 (stage) => local.deleteStack({ stack: LEGACY_BOOTSTRAP_STACK, stage }),
508 { discard: true },
509 );
510 },
511 (effect, _credentials, scriptName) =>
512 effect.pipe(
513 Effect.catch((error) =>
514 Interaction.warning(
515 `Couldn't delete the old '${LEGACY_BOOTSTRAP_STACK}' records of Cloudflare State ` +
516 `Store '${scriptName}': ${error.message}`,
517 ),
518 ),
519 ),
520 );
521
522 /**
523 * The account a store lives in: the pinned one, or the profile's. Fails when
524 * the credentials can't reach a pinned account, before anything is read or
525 * deployed.
526 */
527 const resolveAccountId = (pinned: string | undefined) =>
528 Effect.gen(function* () {
529 if (pinned === undefined) {
530 return (yield* yield* CloudflareEnvironment.CloudflareEnvironment).accountId;
531 }
532 yield* workers.getSubdomain({ accountId: pinned }).pipe(
533 Effect.mapError(
534 (cause) =>
535 new StateStoreError({
536 message:
537 `The Cloudflare State Store is pinned to account ${pinned}, but the current ` +
538 `credentials can't access it. Log in to that account or change \`accountId\`.`,
539 cause,
540 }),
541 ),
542 );
543 return pinned;
544 });
545
546 /**
547 * Log in to a Cloudflare-deployed HTTP state-store.
548 *
549 * 1. Find the single account-wide Secrets Store.
550 * 2. Upload a short-lived edge-preview worker that binds the
551 * auth-token secret and returns its value.
552 * 3. Derive the state-store worker URL: its custom `domain`, or its
553 * workers.dev URL.
554 * 4. Persist `{ url, token }` under the `http-state-store`
555 * credentials file.
556 *
557 * Requirements are covered by the Cloudflare provider stack —
558 * `CloudflareEnvironment`, `Credentials`, `HttpClient`, and
559 * `FileSystem`.
560 */
561 export const loginWithCloudflare = Effect.fn("state_store.login", {
562 attributes: {
563 "alchemy.state_store.op": "login",
564 },
565 })(
566 function* (
567 profileName: string,
568 force: boolean,
569 scriptName: string = STATE_STORE_SCRIPT_NAME,
570 pinnedAccountId?: string,
571 domain?: string,
572 ) {
573 yield* Effect.annotateCurrentSpan({ "alchemy.state_store.script_name": scriptName });
574 const credStore = yield* CredentialsStore;
575 const isCI = yield* CI;
576 const accountId = yield* resolveAccountId(pinnedAccountId);
577
578 if (!force) {
579 // try and read from the cached credentials first if not forcing (force will always refresh)
580 const credentials = yield* readStoreCredentials(credStore, profileName, scriptName);
581 // Ignore a cache minted for a different account (or a legacy file with
582 // no `accountId`) — reusing it would hand back the wrong account's
583 // state-store URL. Fall through to re-derive against `accountId`.
584 if (
585 credentials &&
586 !isStateStoreCredentialsStale(credentials, accountId) &&
587 servesOn(credentials.url, domain)
588 ) {
589 return credentials;
590 }
591 }
592
593 const interaction = yield* Interaction.Interaction;
594 const credentials = yield* interaction.task(
595 { label: "Refreshing Cloudflare State Store credentials" },
596 Effect.gen(function* () {
597 // 1. Locate the single Secrets Store on the account.
598 const store = yield* SecretsStore.listStores
599 .items({ accountId })
600 .pipe(Stream.runHead, Effect.map(Option.getOrUndefined));
601 if (!store) {
602 return yield* AuthError.make({
603 message: "No Secrets Store found on this account. Deploy the state store first.",
604 });
605 }
606
607 // 2. Fetch the auth-token from Secrets Store with a temporary edge-preview
608 // worker, served on the custom domain when the store has one attached.
609 const zoneId =
610 domain === undefined
611 ? undefined
612 : yield* observeStateStoreDomain({ accountId, scriptName, domain });
613 const authToken = yield* readSecretViaEdge(
614 accountId,
615 scriptName,
616 store.id,
617 stateStoreSecretName(AuthTokenSecretName, scriptName),
618 domain !== undefined && zoneId !== undefined ? { zoneId, host: domain } : undefined,
619 ).pipe(
620 Effect.retry({
621 while: (error) =>
622 isWorkersPreviewConfigurationError(error) || isTransientEdgeSessionError(error),
623 // Cap the exponential delay at 2s so 15 retries stay within
624 // ~30s instead of doubling unboundedly.
625 schedule: Schedule.max([
626 Schedule.min([Schedule.exponential(200), Schedule.spaced("2 seconds")]),
627 Schedule.recurs(15),
628 ]),
629 }),
630 );
631
632 // 3. Derive the deployed worker URL.
633 const url = yield* stateStoreUrl({ accountId, scriptName, domain });
634 const credentials = {
635 url,
636 authToken: authToken.trim(),
637 accountId,
638 };
639
640 if (!isCI) {
641 // 4. Persist credentials for subsequent invocations.
642 yield* writeStoreCredentials(credStore, profileName, scriptName, credentials).pipe(
643 Effect.mapError((e) =>
644 AuthError.make({
645 message: "Failed to write credentials",
646 cause: e,
647 }),
648 ),
649 );
650 }
651
652 return credentials;
653 }),
654 );
655 if (!isCI) yield* interaction.output.info(` url: ${credentials.url}`);
656 return credentials;
657 },
658 Effect.catchTag("EdgeSessionError", (e) =>
659 Effect.fail(
660 AuthError.make({
661 message: `Edge-preview secret read failed: ${e.message}`,
662 cause: e.cause,
663 }),
664 ),
665 ),
666 );
667
668 const isStateStoreAvailable = (accountId: string, scriptName: string) =>
669 workers.getScriptSetting({ accountId, scriptName }).pipe(
670 Effect.map((setting) => setting !== undefined),
671 Effect.catchTags({
672 WorkerNotFound: () => Effect.succeed(false),
673 InvalidRoute: () => Effect.succeed(false),
674 // A worker that exists but has no versions (a previous deploy was
675 // interrupted before any content upload) can't serve — treat it
676 // as absent so bootstrap redeploys it.
677 WorkerHasNoVersions: () => Effect.succeed(false),
678 }),
679 );
680
681 /**
682 * Whether cached credentials point at where the store serves now: its
683 * custom `domain`, or workers.dev without one.
684 */
685 const servesOn = (url: string, domain: string | undefined) =>
686 domain === undefined
687 ? new URL(url).hostname.endsWith(".workers.dev")
688 : url === `https://${domain}`;
689
690 /**
691 * Does this account have a *functioning* state-store worker,
692 * verified by checking the /version endpoint
693 *
694 * `false` means the lookups succeeded and found no store. A lookup that
695 * fails, such as one the credentials aren't permitted to make, fails this
696 * check: a missing store is bootstrapped, and bootstrapping over a live
697 * store replaces its auth token and encryption key.
698 */
699 const observeServedVersion = (accountId: string, scriptName: string, domain?: string) =>
700 Effect.gen(function* () {
701 // Ask the API whether the domain is attached before resolving it, so a
702 // lookup before the first deploy can't leave a cached NXDOMAIN behind.
703 const attached =
704 domain === undefined ||
705 (yield* observeStateStoreDomain({ accountId, scriptName, domain }).pipe(
706 // Another Worker owning the domain fails as itself, not as an unknown.
707 Effect.mapError((e) =>
708 e._tag === "StateStoreError" ? e : existenceUnknown(scriptName)(e),
709 ),
710 )) !== undefined;
711 if (!attached) return undefined;
712 const observed = yield* Effect.gen(function* () {
713 const deployed = yield* observeDeployedVersion({ accountId, scriptName });
714 if (deployed !== "unrecorded") return deployed;
715 // An older Alchemy deployed it without recording its version: ask the
716 // Worker, which the API says exists.
717 const url = yield* stateStoreUrl({ accountId, scriptName, domain }).pipe(
718 // Without a workers.dev subdomain, nothing can serve the store.
719 Effect.catchTag("SubdomainNotFound", () => Effect.undefined),
720 );
721 if (url === undefined) return undefined;
722 return (yield* checkStateStoreVersion(url, scriptName, accountId)).observed;
723 }).pipe(Effect.mapError(existenceUnknown(scriptName)));
724 return yield* refuseNewerStore(scriptName, observed);
725 });
726
727 /**
728 * Fail on a store a newer Alchemy deployed: redeploying this version's Worker
729 * over it could leave its state in a format this version doesn't know.
730 */
731 const refuseNewerStore = (scriptName: string, observed: number | undefined) =>
732 observed !== undefined && observed > STATE_STORE_VERSION
733 ? Effect.fail(
734 new StateStoreError({
735 message:
736 `Cloudflare State Store '${scriptName}' runs v${observed}, newer than this ` +
737 `Alchemy's v${STATE_STORE_VERSION}, so it was left untouched. Upgrade alchemy to use it.`,
738 }),
739 )
740 : Effect.succeed(observed);
741
742 const existenceUnknown =
743 (scriptName: string) =>
744 (cause: Error & { readonly _tag: string }): StateStoreError =>
745 new StateStoreError({
746 message:
747 `Could not determine whether Cloudflare State Store '${scriptName}' exists, ` +
748 `so it was left untouched: ${cause.message}. ` +
749 (cause._tag === "Forbidden"
750 ? `Check that the Cloudflare credentials can read Workers scripts (Workers Scripts Read).`
751 : `Run the command again.`),
752 cause,
753 });
754
755 const makeCloudflareStateStore = Effect.fn(function* ({
756 url,
757 authToken,
758 }: {
759 url: string;
760 authToken: string;
761 }) {
762 const access = yield* Access.Access;
763 const accessHeaders = yield* access.getAccessHeaders(new URL(url).host);
764 return yield* makeHttpStateStore({
765 url,
766 authToken,
767 transformClient: HttpClientRequest.setHeaders(accessHeaders),
768 id: "cloudflare-http",
769 });
770 });
771
772 export class StateStoreVersionNotReady extends Data.TaggedError("StateStoreVersionNotReady")<{
773 readonly expected: number;
774 readonly observed: number | undefined;
775 }> {
776 override get message() {
777 return `Cloudflare State Store version not ready (expected v${this.expected}, observed v${this.observed ?? "unknown"}).`;
778 }
779 }
780
781 const waitForStateStoreVersion = (url: string, scriptName: string, accountId: string) =>
782 Effect.gen(function* () {
783 // Right after a deploy the store may not answer yet: keep polling.
784 const { matches, expected, observed } = yield* checkStateStoreVersion(
785 url,
786 scriptName,
787 accountId,
788 ).pipe(Effect.orElseSucceed(() => unknownVersion));
789 if (!matches) {
790 return yield* new StateStoreVersionNotReady({ expected, observed });
791 }
792 }).pipe(
793 Effect.retry({
794 while: (error) => error instanceof StateStoreVersionNotReady,
795 // Edge propagation is usually sub-second but production traces
796 // show redeploys occasionally serving the old version for well
797 // over 10s. Poll for ~30s before failing loudly.
798 schedule: Schedule.max([Schedule.spaced("500 millis"), Schedule.recurs(60)]),
799 }),
800 // Each poll retries on its own, so bound the whole wait.
801 Effect.timeoutOrElse({
802 duration: "2 minutes",
803 orElse: () =>
804 Effect.fail(
805 new StateStoreError({
806 message:
807 `Cloudflare State Store '${scriptName}' was deployed but ${url} did not serve ` +
808 `v${STATE_STORE_VERSION} within 2 minutes. Its secrets and state are unchanged; ` +
809 `run the command again.`,
810 }),
811 ),
812 }),
813 Effect.withSpan("state_store.wait_for_version", {
814 attributes: {
815 "alchemy.state_store.op": "wait_for_version",
816 "alchemy.state_store.url": url,
817 "alchemy.state_store.expected_version": STATE_STORE_VERSION,
818 },
819 }),
820 );
821
822 const checkStateStoreVersion = Effect.fn("state_store.check_version", {
823 attributes: { "alchemy.state_store.op": "check_version" },
824 })(function* (url: string, scriptName: string, accountId: string) {
825 const client = yield* HttpApiClient.make(StateApi, { baseUrl: url });
826 const isAvailable = yield* Effect.cached(isStateStoreAvailable(accountId, scriptName));
827 // The /version route may 404 transiently after a fresh deploy
828 // while Cloudflare propagates the new script to the edge, and may
829 // also surface transport-level blips on cold workers.dev hosts.
830 // Retry the probe itself for ~10s before giving up. `observed` is
831 // `undefined` only when the worker is confirmed absent; a probe that
832 // still fails after that budget fails the check.
833 const result = yield* client.version.getVersion().pipe(
834 Effect.catchTag("HttpClientError", (e) =>
835 // if we get a 404 here, it means we assumed the worker shoudl exist, but it does not
836 // we should do a check to see if it does
837 e.response?.status === 404
838 ? isAvailable.pipe(
839 Effect.flatMap((isAvailable) =>
840 // if the worker is available, then we should assume it was recently created and retry by propagating the error
841 // otherwise, return undefined (we don't know the version, there is no worker)
842 isAvailable ? Effect.fail(e) : Effect.undefined,
843 ),
844 )
845 : Effect.fail(e),
846 ),
847 Effect.retry({
848 schedule: Schedule.max([Schedule.spaced("250 millis"), Schedule.recurs(40)]),
849 }),
850 );
851 const matches = result?.version === STATE_STORE_VERSION;
852 yield* Effect.annotateCurrentSpan({
853 "alchemy.state_store.expected_version": STATE_STORE_VERSION,
854 "alchemy.state_store.observed_version": result?.version ?? -1,
855 "alchemy.state_store.version_match": matches,
856 });
857 return {
858 matches,
859 expected: STATE_STORE_VERSION,
860 observed: result?.version,
861 };
862 });
863
864 /** A version check that failed, for callers that read it as an outdated store. */
865 const unknownVersion = {
866 matches: false,
867 expected: STATE_STORE_VERSION,
868 observed: undefined,
869 } as const;
870
871 /**
872 * Tiny ES-module worker that reads `env.SECRET.get()` and echoes it
873 * back. Uploaded as an ephemeral edge-preview, called once, then
874 * discarded — see {@link readSecretViaEdge}.
875 */
876 const SECRET_PROBE_SOURCE = `export default {
877 async fetch(_request, env) {
878 try {
879 const value = await env.SECRET.get();
880 return new Response(value ?? "", { status: 200, headers: { "content-type": "text/plain" } });
881 } catch (e) {
882 return new Response("Error: " + (e && e.message ? e.message : String(e)), { status: 500 });
883 }
884 },
885 };`;
886
887 /**
888 * Upload an ephemeral edge-preview build of the given (already
889 * deployed) script that binds the requested Secrets Store secret,
890 * call it once with the preview token, and return the decoded value.
891 * The Cloudflare REST API deliberately hides secret values; only
892 * worker bindings can resolve them, so this is the out-of-band path.
893 *
894 * `scriptName` MUST be a script that is already deployed on the
895 * account with workers.dev enabled — the `cf-workers-preview-token`
896 * header swaps our probe code in for an existing route, it does not
897 * create one. Using an undeployed name (or a deployed script that
898 * doesn't have workers.dev enabled) makes the workers.dev edge serve
899 * a generic Cloudflare 400 HTML error page instead of routing to the
900 * preview. The state-store script itself satisfies both conditions.
901 */
902 const readSecretViaEdge = (
903 accountId: string,
904 scriptName: string,
905 storeId: string,
906 secretName: string,
907 route?: { readonly zoneId: string; readonly host: string },
908 ) =>
909 Effect.gen(function* () {
910 const http = yield* HttpClient.HttpClient;
911 const file = new File([SECRET_PROBE_SOURCE], "worker.js", {
912 type: "application/javascript+module",
913 });
914 // The preview runs in the store's account, which a pin may set apart
915 // from the profile's.
916 const environment = yield* CloudflareEnvironment.CloudflareEnvironment;
917 const session = yield* createEdgeSession({
918 scriptName,
919 files: [file],
920 bindings: [{ type: "secrets_store_secret", name: "SECRET", secretName, storeId }],
921 route,
922 }).pipe(
923 Effect.provideService(
924 CloudflareEnvironment.CloudflareEnvironment,
925 Effect.map(environment, (credentials) => ({ ...credentials, accountId })),
926 ),
927 );
928 const response = yield* http.get(session.url, {
929 headers: session.headers,
930 });
931 if (response.status !== 200) {
932 const body = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
933 // TEMP(sam): dump the full body so we can capture the exact
934 // Cloudflare error page when the probe fails in the wild. Drop
935 // this once we've confirmed the routing fix covers all the
936 // observed failure modes.
937 yield* Effect.logWarning(
938 `Secret probe failed (${response.status}) at ${session.url}\n${body}`,
939 );
940 return yield* new EdgeSessionError({
941 message: `Secret probe returned ${response.status}: ${body.slice(0, 200)}`,
942 });
943 }
944 return yield* response.text;
945 }).pipe(
946 Effect.mapError((cause) =>
947 cause instanceof EdgeSessionError
948 ? cause
949 : new EdgeSessionError({ message: "Failed to read secret", cause }),
950 ),
951 Effect.withSpan("state_store.read_secret_via_edge", {
952 attributes: {
953 "alchemy.state_store.op": "read_secret_via_edge",
954 "alchemy.state_store.script_name": scriptName,
955 "alchemy.state_store.secret_name": secretName,
956 },
957 }),
958 );
959
960 const isWorkersPreviewConfigurationError = (error: unknown) =>
961 error instanceof EdgeSessionError &&
962 (error.message.includes("Invalid Workers Preview configuration") ||
963 error.message.includes("Error 1031"));
964
965 /**
966 * Edge-preview reads are flaky in ways that clear up on their own:
967 * the workers.dev edge can serve a generic Cloudflare 400/502 HTML
968 * page while preview routing propagates ("Secret probe returned
969 * ..."), the session-create call can hit transient API blips, and the
970 * probe fetch can fail at the transport level ("fetch failed").
971 * Retry everything except causes that are clearly permanent
972 * (bad credentials, invalid routes).
973 *
974 * @internal exported for unit testing.
975 */
976 export const isTransientEdgeSessionError = (error: unknown): boolean => {
977 if (!(error instanceof EdgeSessionError)) return false;
978 // Non-200 probe responses are edge-propagation flakes, not client bugs.
979 if (error.message.startsWith("Secret probe returned")) return true;
980 const tag = (error.cause as { _tag?: unknown } | undefined)?._tag;
981 if (
982 typeof tag === "string" &&
983 (tag.startsWith("Unauthorized") ||
984 tag === "Forbidden" ||
985 tag === "InvalidRoute" ||
986 tag === "AuthError")
987 ) {
988 return false;
989 }
990 return true;
991 };
992
993 /**
994 * SHA-256 hex digest of the Cloudflare account ID. Used as a stable
995 * pseudonymous identifier on telemetry spans so the dashboard can
996 * count distinct state-store deployments without leaking the raw
997 * accountId. Mirrors the `alchemy.git.origin_hash` pattern in
998 * `Telemetry/Attributes.ts`.
999 */
1000 const hashAccountId = (accountId: string) =>
1001 Effect.sync(() => crypto.createHash("sha256").update(accountId).digest("hex"));
1002
1003 /**
1004 * Best-effort Cloudflare-account-hash annotation on the current span, unless
1005 * the `NO_TRACK` env var opts out.
1006 */
1007 const annotateAccountHash = (accountId: string) =>
1008 Effect.gen(function* () {
1009 if (yield* Config.Boolean("NO_TRACK").pipe(Config.withDefault(false))) return;
1010 yield* Effect.annotateCurrentSpan(
1011 "alchemy.cloudflare.account_hash",
1012 yield* hashAccountId(accountId),
1013 );
1014 }).pipe(Effect.ignore);