sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ StateStore/ State.ts

import crypto from "node:crypto";
import * as SecretsStore from "@distilled.cloud/cloudflare/secrets-store";
import * as workers from "@distilled.cloud/cloudflare/workers";
import { AuthError } from "alchemy/Auth/AuthProvider";
import { CredentialsStore } from "alchemy/Auth/Credentials";
import { currentProfileName } from "alchemy/Auth/Profile";
import { emit } from "alchemy/Events";
import * as Interaction from "alchemy/Interaction";
import { StateApi } from "alchemy/State/HttpStateApi";
import {
  checkHttpStateStoreAuth,
  makeHttpStateStore,
  type HttpStateStoreCredentials,
} from "alchemy/State/HttpStateStore";
import { makeLocalState } from "alchemy/State/LocalState";
import * as Provisioning from "alchemy/State/Provisioning";
import { State, StateStoreError } from "alchemy/State/State";
import { recordStateStoreInit, recordStateStoreOp } from "alchemy/Telemetry/Metrics";
import { globalLogs } from "alchemy/Util/LogRecord";
import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as HttpApiClient from "effect/http-api/HttpApiClient";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import * as Access from "../Access.ts";
import * as CloudflareEnvironment from "../CloudflareEnvironment.ts";
import { EdgeSessionError, createEdgeSession } from "../EdgeSession.ts";
import * as Cloudflare from "../Providers.ts";
import { STATE_STORE_SCRIPT_NAME, STATE_STORE_VERSION } from "./Api.ts";
import {
  deleteStoreCredentials,
  readStoreCredentials,
  writeStoreCredentials,
  isStateStoreCredentialsStale,
} from "./CredentialsFile.ts";
import {
  deployStateStoreWorker,
  encryptionKeyLost,
  findSecretSharingWorker,
  observeDeployedVersion,
  observeStateStoreDomain,
  stateStoreSecretsExist,
  stateStoreUrl,
  validateStateStoreWorkerName,
} from "./Deploy.ts";
import { AuthTokenSecretName, EncryptionKeySecretName, stateStoreSecretName } from "./Token.ts";

const CI = Config.Boolean("CI").pipe(Config.withDefault(false));

export type CloudflareStateOptions = {
  /**
   * The Cloudflare account the store lives in. Defaults to the account your
   * Alchemy profile resolves. Pin it when your credentials reach several
   * accounts, so a login against a different one can't read or deploy the
   * store somewhere else.
   */
  readonly accountId?: string;
  /**
   * Serve the store on this hostname in one of the account's zones instead of
   * its workers.dev URL, for networks that can't reach workers.dev. Bootstrap
   * attaches it to the store's Worker as a custom domain.
   */
  readonly domain?: string;
  /**
   * The store's Worker name, for a store other than the account's default
   * `alchemy-state-store`: 1-54 lowercase letters, digits, `-` and `_`,
   * starting with a letter or digit. Its secrets are named after it, e.g.
   * `acme-state` keeps its token in `AlchemyStateStoreToken_acme_state`.
   * @default "alchemy-state-store"
   */
  readonly workerName?: string;
};

export const state = (options: CloudflareStateOptions = {}) =>
  Layer.effect(
    State,
    Effect.gen(function* () {
      const isCI = yield* CI;
      const { workerName, domain } = options;
      const scriptName = workerName ?? STATE_STORE_SCRIPT_NAME;
      const profileName = yield* currentProfileName;
      const credStore = yield* CredentialsStore;
      const context = yield* Effect.context<Effect.Services<typeof init>>();
      const store: Provisioning.StoreRef = {
        backend: "cloudflare",
        name: workerName,
        label: `Cloudflare State Store '${scriptName}'`,
        configured: options.accountId !== undefined || domain !== undefined,
      };

      const init = Effect.gen(function* () {
        yield* validateStateStoreWorkerName(scriptName);
        const accountId = yield* resolveAccountId(options.accountId);
        const deployMissing = Provisioning.deployMissing(
          store,
          bootstrap({ workerName: scriptName, profile: profileName, accountId, domain }),
        );

        const ensureLatest = ({ url, authToken }: { url: string; authToken: string }) =>
          Effect.gen(function* () {
            const observed = yield* observeServedVersion(accountId, scriptName, domain);
            if (observed === undefined) return yield* deployMissing;
            const expected = STATE_STORE_VERSION;
            const matches = observed === expected;

            const httpState = yield* ensureAccess({ url, authToken });
            if (matches) return httpState;

            // The store is out of date. Upgrade it in place.
            const upgrade = Effect.gen(function* () {
              const interaction = yield* Interaction.Interaction;
              return yield* interaction.task(
                {
                  label: `Updating Cloudflare State Store '${scriptName}'`,
                  detail: `v${observed ?? "unknown"} → v${expected}`,
                },
                deployStateStore({
                  accountId,
                  scriptName,
                  domain,
                  profileName,
                  isCI,
                  force: false,
                }).pipe(Effect.flatMap(makeCloudflareStateStore)),
              );
            }).pipe(withStateBootstrapEvents(scriptName));
            return yield* Provisioning.upgradeOutdated({ ...store, observed, expected }, upgrade);
          });

        const ensureAccess = (credentials: HttpStateStoreCredentials) =>
          Effect.gen(function* () {
            if (yield* checkHttpStateStoreAuth(credentials)) {
              return yield* makeCloudflareStateStore(credentials);
            }
            // our token is wrong, force a refresh
            const refreshed = yield* loginWithCloudflare(
              profileName,
              true,
              scriptName,
              accountId,
              domain,
            );
            if (!(yield* checkHttpStateStoreAuth(refreshed))) {
              return yield* new StateStoreError({
                message: `${store.label} authentication failed, after refreshing credentials.`,
              });
            }
            return yield* makeCloudflareStateStore(refreshed);
          });

        const credentials = yield* readStoreCredentials(credStore, profileName, scriptName);
        if (credentials) {
          // The cached `url`/`authToken` are minted per-account (the `url`
          // encodes the account via its workers.dev subdomain). If the
          // active account changed since they were written — or the file
          // predates the `accountId` field — trusting the cache would
          // silently read/write state in the wrong account, so discard it
          // and fall through to re-derivation from the current account.
          if (isStateStoreCredentialsStale(credentials, accountId)) {
            yield* Interaction.info(
              `Cloudflare State Store credentials were minted for a different ` +
                `Cloudflare account; re-deriving for the current account.`,
            );
            yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);
          } else if (!servesOn(credentials.url, domain)) {
            // The store's `domain` changed since these were cached.
            yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);
          } else {
            return yield* ensureLatest(credentials);
          }
        }
        if ((yield* observeServedVersion(accountId, scriptName, domain)) !== undefined) {
          return yield* ensureLatest(
            yield* loginWithCloudflare(profileName, false, scriptName, accountId, domain),
          );
        }
        return yield* deployMissing;
        // Account-level: filed in the global run log, not the project's.
      }).pipe(recordStateStoreInit, globalLogs, Effect.orDie);

      return yield* Effect.cached(init.pipe(Effect.provideContext(context)));
    }),
  ).pipe(
    // The Cloudflare API foundation shared with `providers()` —
    // credentials, environment, auth/access, profile + credential
    // store, and the same blanket retry policy. Without the retry
    // policy the init-time subdomain/script/secrets probes run on the
    // SDK default and give up early under Cloudflare rate limiting.
    // `provide` (not `provideMerge`) so the distilled Retry tag stays
    // out of this layer's public type.
    Layer.provide(Cloudflare.CloudflareApiLive()),
    Layer.orDie,
  );

export interface BootstrapOptions {
  /** @default "alchemy-state-store" */
  workerName?: string;
  /** The account to deploy into. Defaults to the profile's account. */
  accountId?: string;
  /** A hostname to serve the store on, attached as a custom domain. */
  domain?: string;
  /** @default false */
  force?: boolean;
  /** @default "default" */
  profile?: string;
}

/**
 * Report `state.bootstrap.*` progress events around a state-store deploy or
 * upgrade. Bootstrap runs lazily inside the plan's "loading state" phase,
 * can take many seconds (it deploys a worker), and would otherwise be
 * invisible to non-interactive renderers and traces — the Interaction task only
 * paints the local terminal.
 */
const withStateBootstrapEvents =
  (store: string) =>
  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
    Effect.gen(function* () {
      yield* emit({ type: "state.bootstrap.started", store });
      const result = yield* effect;
      yield* emit({ type: "state.bootstrap.completed", store });
      return result;
    });

export const bootstrap = (options: BootstrapOptions = {}) =>
  withStateBootstrapEvents(options.workerName ?? STATE_STORE_SCRIPT_NAME)(
    Effect.gen(function* () {
      const interaction = yield* Interaction.Interaction;
      const isCI = yield* CI;
      const profileName = options.profile ?? (yield* currentProfileName);
      const scriptName = yield* validateStateStoreWorkerName(
        options.workerName ?? STATE_STORE_SCRIPT_NAME,
      );
      const force = options.force ?? false;
      const accountId = yield* resolveAccountId(options.accountId);
      const { domain } = options;
      yield* Effect.annotateCurrentSpan({
        "alchemy.state_store.script_name": scriptName,
        "alchemy.state_store.profile": profileName,
        "alchemy.state_store.force": force,
        "alchemy.state_store.ci": isCI,
      });
      yield* annotateAccountHash(accountId);

      const observed = yield* observeServedVersion(accountId, scriptName, domain);
      const serving = observed !== undefined;
      // A store missing a secret is redeployed, which creates only the missing one.
      if (serving && !force && (yield* stateStoreSecretsExist({ accountId, scriptName }))) {
        yield* Interaction.info(
          `Worker '${scriptName}' already exists; adopting and refreshing credentials. ` +
            `Use --force to redeploy.`,
        );
        const credentials = yield* loginWithCloudflare(
          profileName,
          true,
          scriptName,
          accountId,
          domain,
        );
        if (observed === STATE_STORE_VERSION) {
          yield* forgetLegacyBootstrapStack(credentials, scriptName);
          return yield* makeCloudflareStateStore(credentials);
        }
      }
      return yield* interaction.task(
        {
          label: `${serving ? "Updating" : "Deploying"} Cloudflare State Store '${scriptName}'`,
        },
        deployStateStore({ accountId, scriptName, domain, profileName, isCI, force }).pipe(
          Effect.flatMap(makeCloudflareStateStore),
        ),
      );
    }).pipe(
      Effect.withSpan("state_store.bootstrap", {
        attributes: {
          "alchemy.state_store.op": "bootstrap",
          "alchemy.state_store.script_name": options.workerName ?? STATE_STORE_SCRIPT_NAME,
        },
      }),
      // Account-level: filed in the global run log, not the project's.
      globalLogs,
    ),
  );

export interface TeardownOptions {
  /** @default "alchemy-state-store" */
  workerName?: string;
  /** The account the store lives in. Defaults to the profile's account. */
  accountId?: string;
  /** @default "default" */
  profile?: string;
  /**
   * Delete the account Secrets Store too, but only once the state-store
   * secrets have been removed and no other secrets remain in it. A store that
   * still holds foreign secrets is left in place.
   * @default true
   */
  deleteEmptySecretsStore?: boolean;
}

/**
 * The inverse of {@link bootstrap}: tear down the Cloudflare-deployed state
 * store. Deletes the state-store Worker and the secrets it created in the
 * account Secrets Store (the bearer token + the encryption key), then deletes
 * the Secrets Store itself if it is left empty, and drops the locally cached
 * state-store credentials for the profile.
 *
 * Idempotent — missing resources are treated as already-gone, so it is safe to
 * re-run. Intended for reclaiming a throwaway account after testing; on a
 * shared account it only removes resources alchemy created.
 */
export const teardownStateStore = (options: TeardownOptions = {}) =>
  Effect.gen(function* () {
    const interaction = yield* Interaction.Interaction;
    const profileName = options.profile ?? (yield* currentProfileName);
    const scriptName = options.workerName ?? STATE_STORE_SCRIPT_NAME;
    const deleteEmptyStore = options.deleteEmptySecretsStore ?? true;
    const accountId = yield* resolveAccountId(options.accountId);

    yield* annotateAccountHash(accountId);
    yield* Effect.annotateCurrentSpan({
      "alchemy.state_store.script_name": scriptName,
      "alchemy.state_store.profile": profileName,
    });

    // 1. Delete the state-store Worker.
    yield* Interaction.info(`Deleting state store worker '${scriptName}'...`);
    yield* workers.deleteScript({ accountId, scriptName, force: true }).pipe(
      Effect.asVoid,
      Effect.catchTag("WorkerNotFound", () =>
        interaction.output.info(`  Worker '${scriptName}' not found (already gone).`),
      ),
    );

    // 2. Delete the secrets the state store created, plus any now-empty store,
    // unless another store's Worker shares them.
    const sharing = yield* findSecretSharingWorker({ accountId, scriptName });
    if (sharing !== undefined) {
      yield* Interaction.info(
        `Keeping the secrets of '${scriptName}': Worker '${sharing}' uses the same secrets.`,
      );
    }
    const ourSecretNames = new Set<string>(
      sharing === undefined
        ? [
            stateStoreSecretName(AuthTokenSecretName, scriptName),
            stateStoreSecretName(EncryptionKeySecretName, scriptName),
          ]
        : [],
    );
    const stores = yield* SecretsStore.listStores.items({ accountId }).pipe(
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("InvalidAccountId", () => Effect.succeed([])),
    );
    for (const store of stores) {
      const secrets = yield* SecretsStore.listStoreSecrets
        .items({ accountId, storeId: store.id })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
          Effect.catchTag(["StoreNotFound", "InvalidAccountId"], () => Effect.succeed([])),
        );
      const ours = secrets.filter((s) => ourSecretNames.has(s.name));
      for (const secret of ours) {
        yield* Interaction.info(`Deleting secret '${secret.name}'...`);
        yield* SecretsStore.deleteStoreSecret({
          accountId,
          storeId: store.id,
          secretId: secret.id,
        }).pipe(
          Effect.asVoid,
          Effect.catchTag(
            ["SecretNotFound", "StoreNotFound", "NotFound", "InvalidAccountId"],
            () => Effect.void,
          ),
        );
      }
      const remaining = secrets.length - ours.length;
      if (deleteEmptyStore && remaining === 0) {
        yield* Interaction.info(`Deleting empty secrets store '${store.id}'...`);
        yield* SecretsStore.deleteStore({
          accountId,
          storeId: store.id,
          force: true,
        }).pipe(
          Effect.asVoid,
          Effect.catchTag(["StoreNotFound", "NotFound", "InvalidAccountId"], () => Effect.void),
        );
      } else if (remaining > 0) {
        yield* Interaction.info(
          `Secrets store '${store.id}' still has ${remaining} other ` +
            `secret(s); leaving it in place.`,
        );
      }
    }

    // 3. Drop the locally cached state-store credentials for this profile.
    const credStore = yield* CredentialsStore;
    yield* deleteStoreCredentials(credStore, profileName, scriptName).pipe(Effect.ignore);

    yield* Interaction.success(`Cloudflare State Store '${scriptName}' torn down.`);
  }).pipe(
    Effect.withSpan("state_store.teardown", {
      attributes: {
        "alchemy.state_store.op": "teardown",
        "alchemy.state_store.script_name": options.workerName ?? STATE_STORE_SCRIPT_NAME,
      },
    }),
  );

/**
 * Deploy (or update) the store with direct API calls, wait until it serves
 * this CLI's version, and resolve its credentials. A token this deploy created
 * is returned directly; an existing one is read back through the Worker.
 */
const deployStateStore = ({
  accountId,
  scriptName,
  domain,
  profileName,
  isCI,
  force,
}: {
  accountId: string;
  scriptName: string;
  domain: string | undefined;
  profileName: string;
  isCI: boolean;
  /** Approves replacing a lost encryption key without asking. */
  force: boolean;
}) =>
  Effect.gen(function* () {
    if (
      (yield* encryptionKeyLost({ accountId, scriptName })) &&
      !(force || (yield* confirmNewEncryptionKey(scriptName, isCI)))
    ) {
      return yield* new StateStoreError({
        message:
          `Cloudflare State Store '${scriptName}' has lost its encryption key, so the state ` +
          `it holds can no longer be decrypted. Nothing was changed. To start over with a new ` +
          `key, which leaves that state unreadable, run 'alchemy state bootstrap' in a ` +
          `terminal and confirm, or pass --force with --backend.`,
      });
    }
    const { url, authToken } = yield* deployStateStoreWorker({ accountId, scriptName, domain });
    // Cloudflare's worker upload is eventually consistent: the edge can keep
    // serving the previous version for several seconds. Wait until `/version`
    // reports the version this CLI was built against before using it.
    yield* waitForStateStoreVersion(url, scriptName, accountId);
    const credentials =
      authToken === undefined
        ? yield* loginWithCloudflare(profileName, true, scriptName, accountId, domain)
        : { url, authToken, accountId };
    if (authToken !== undefined && !isCI) {
      // CI file systems are ephemeral; credentials are re-read each run.
      yield* writeStoreCredentials(yield* CredentialsStore, profileName, scriptName, credentials);
    }
    yield* forgetLegacyBootstrapStack(credentials, scriptName);
    return credentials;
  }).pipe(
    Effect.withSpan("state_store.deploy", {
      attributes: { "alchemy.state_store.op": "deploy" },
    }),
    recordStateStoreOp("deploy"),
  );

/** Ask before giving a store that lost its encryption key a new one. Never in CI. */
const confirmNewEncryptionKey = (scriptName: string, isCI: boolean) =>
  Effect.gen(function* () {
    const interaction = yield* Effect.serviceOption(Interaction.Interaction);
    if (isCI || Option.isNone(interaction)) return false;
    return yield* interaction.value.prompt
      .confirm({
        message:
          `Cloudflare State Store '${scriptName}' has lost its encryption key, so its state ` +
          `can't be decrypted. Create a new key and start with an empty store?`,
        initialValue: false,
      })
      .pipe(Effect.orElseSucceed(() => false));
  });

/** The stack Alchemy versions before direct deploys deployed the store through. */
const LEGACY_BOOTSTRAP_STACK = "CloudflareStateStore";

/**
 * Delete the records of the stack older versions deployed the store through:
 * the store's own, and those an interrupted bootstrap left in this project's
 * local state. Destroying that stack would delete the store's Worker and
 * secrets. A failure only warns: the store refuses that stack's reads and
 * writes either way, and the next bootstrap tries again.
 */
const forgetLegacyBootstrapStack = Effect.fn("state_store.forget_legacy_stack")(
  function* (credentials: HttpStateStoreCredentials, scriptName: string) {
    const remote = yield* makeCloudflareStateStore(credentials);
    yield* remote.deleteStack({ stack: LEGACY_BOOTSTRAP_STACK });
    // An interrupted bootstrap left its stage as `<profile>_<worker>`.
    const local = yield* makeLocalState();
    const stages = yield* local.listStages(LEGACY_BOOTSTRAP_STACK);
    yield* Effect.forEach(
      stages.filter((stage) => stage.endsWith(`_${scriptName}`)),
      (stage) => local.deleteStack({ stack: LEGACY_BOOTSTRAP_STACK, stage }),
      { discard: true },
    );
  },
  (effect, _credentials, scriptName) =>
    effect.pipe(
      Effect.catch((error) =>
        Interaction.warning(
          `Couldn't delete the old '${LEGACY_BOOTSTRAP_STACK}' records of Cloudflare State ` +
            `Store '${scriptName}': ${error.message}`,
        ),
      ),
    ),
);

/**
 * The account a store lives in: the pinned one, or the profile's. Fails when
 * the credentials can't reach a pinned account, before anything is read or
 * deployed.
 */
const resolveAccountId = (pinned: string | undefined) =>
  Effect.gen(function* () {
    if (pinned === undefined) {
      return (yield* yield* CloudflareEnvironment.CloudflareEnvironment).accountId;
    }
    yield* workers.getSubdomain({ accountId: pinned }).pipe(
      Effect.mapError(
        (cause) =>
          new StateStoreError({
            message:
              `The Cloudflare State Store is pinned to account ${pinned}, but the current ` +
              `credentials can't access it. Log in to that account or change \`accountId\`.`,
            cause,
          }),
      ),
    );
    return pinned;
  });

/**
 * Log in to a Cloudflare-deployed HTTP state-store.
 *
 * 1. Find the single account-wide Secrets Store.
 * 2. Upload a short-lived edge-preview worker that binds the
 *    auth-token secret and returns its value.
 * 3. Derive the state-store worker URL: its custom `domain`, or its
 *    workers.dev URL.
 * 4. Persist `{ url, token }` under the `http-state-store`
 *    credentials file.
 *
 * Requirements are covered by the Cloudflare provider stack —
 * `CloudflareEnvironment`, `Credentials`, `HttpClient`, and
 * `FileSystem`.
 */
export const loginWithCloudflare = Effect.fn("state_store.login", {
  attributes: {
    "alchemy.state_store.op": "login",
  },
})(
  function* (
    profileName: string,
    force: boolean,
    scriptName: string = STATE_STORE_SCRIPT_NAME,
    pinnedAccountId?: string,
    domain?: string,
  ) {
    yield* Effect.annotateCurrentSpan({ "alchemy.state_store.script_name": scriptName });
    const credStore = yield* CredentialsStore;
    const isCI = yield* CI;
    const accountId = yield* resolveAccountId(pinnedAccountId);

    if (!force) {
      // try and read from the cached credentials first if not forcing (force will always refresh)
      const credentials = yield* readStoreCredentials(credStore, profileName, scriptName);
      // Ignore a cache minted for a different account (or a legacy file with
      // no `accountId`) — reusing it would hand back the wrong account's
      // state-store URL. Fall through to re-derive against `accountId`.
      if (
        credentials &&
        !isStateStoreCredentialsStale(credentials, accountId) &&
        servesOn(credentials.url, domain)
      ) {
        return credentials;
      }
    }

    const interaction = yield* Interaction.Interaction;
    const credentials = yield* interaction.task(
      { label: "Refreshing Cloudflare State Store credentials" },
      Effect.gen(function* () {
        // 1. Locate the single Secrets Store on the account.
        const store = yield* SecretsStore.listStores
          .items({ accountId })
          .pipe(Stream.runHead, Effect.map(Option.getOrUndefined));
        if (!store) {
          return yield* AuthError.make({
            message: "No Secrets Store found on this account. Deploy the state store first.",
          });
        }

        // 2. Fetch the auth-token from Secrets Store with a temporary edge-preview
        // worker, served on the custom domain when the store has one attached.
        const zoneId =
          domain === undefined
            ? undefined
            : yield* observeStateStoreDomain({ accountId, scriptName, domain });
        const authToken = yield* readSecretViaEdge(
          accountId,
          scriptName,
          store.id,
          stateStoreSecretName(AuthTokenSecretName, scriptName),
          domain !== undefined && zoneId !== undefined ? { zoneId, host: domain } : undefined,
        ).pipe(
          Effect.retry({
            while: (error) =>
              isWorkersPreviewConfigurationError(error) || isTransientEdgeSessionError(error),
            // Cap the exponential delay at 2s so 15 retries stay within
            // ~30s instead of doubling unboundedly.
            schedule: Schedule.max([
              Schedule.min([Schedule.exponential(200), Schedule.spaced("2 seconds")]),
              Schedule.recurs(15),
            ]),
          }),
        );

        // 3. Derive the deployed worker URL.
        const url = yield* stateStoreUrl({ accountId, scriptName, domain });
        const credentials = {
          url,
          authToken: authToken.trim(),
          accountId,
        };

        if (!isCI) {
          // 4. Persist credentials for subsequent invocations.
          yield* writeStoreCredentials(credStore, profileName, scriptName, credentials).pipe(
            Effect.mapError((e) =>
              AuthError.make({
                message: "Failed to write credentials",
                cause: e,
              }),
            ),
          );
        }

        return credentials;
      }),
    );
    if (!isCI) yield* interaction.output.info(`  url:     ${credentials.url}`);
    return credentials;
  },
  Effect.catchTag("EdgeSessionError", (e) =>
    Effect.fail(
      AuthError.make({
        message: `Edge-preview secret read failed: ${e.message}`,
        cause: e.cause,
      }),
    ),
  ),
);

const isStateStoreAvailable = (accountId: string, scriptName: string) =>
  workers.getScriptSetting({ accountId, scriptName }).pipe(
    Effect.map((setting) => setting !== undefined),
    Effect.catchTags({
      WorkerNotFound: () => Effect.succeed(false),
      InvalidRoute: () => Effect.succeed(false),
      // A worker that exists but has no versions (a previous deploy was
      // interrupted before any content upload) can't serve — treat it
      // as absent so bootstrap redeploys it.
      WorkerHasNoVersions: () => Effect.succeed(false),
    }),
  );

/**
 * Whether cached credentials point at where the store serves now: its
 * custom `domain`, or workers.dev without one.
 */
const servesOn = (url: string, domain: string | undefined) =>
  domain === undefined
    ? new URL(url).hostname.endsWith(".workers.dev")
    : url === `https://${domain}`;

/**
 * Does this account have a *functioning* state-store worker,
 * verified by checking the /version endpoint
 *
 * `false` means the lookups succeeded and found no store. A lookup that
 * fails, such as one the credentials aren't permitted to make, fails this
 * check: a missing store is bootstrapped, and bootstrapping over a live
 * store replaces its auth token and encryption key.
 */
const observeServedVersion = (accountId: string, scriptName: string, domain?: string) =>
  Effect.gen(function* () {
    // Ask the API whether the domain is attached before resolving it, so a
    // lookup before the first deploy can't leave a cached NXDOMAIN behind.
    const attached =
      domain === undefined ||
      (yield* observeStateStoreDomain({ accountId, scriptName, domain }).pipe(
        // Another Worker owning the domain fails as itself, not as an unknown.
        Effect.mapError((e) =>
          e._tag === "StateStoreError" ? e : existenceUnknown(scriptName)(e),
        ),
      )) !== undefined;
    if (!attached) return undefined;
    const observed = yield* Effect.gen(function* () {
      const deployed = yield* observeDeployedVersion({ accountId, scriptName });
      if (deployed !== "unrecorded") return deployed;
      // An older Alchemy deployed it without recording its version: ask the
      // Worker, which the API says exists.
      const url = yield* stateStoreUrl({ accountId, scriptName, domain }).pipe(
        // Without a workers.dev subdomain, nothing can serve the store.
        Effect.catchTag("SubdomainNotFound", () => Effect.undefined),
      );
      if (url === undefined) return undefined;
      return (yield* checkStateStoreVersion(url, scriptName, accountId)).observed;
    }).pipe(Effect.mapError(existenceUnknown(scriptName)));
    return yield* refuseNewerStore(scriptName, observed);
  });

/**
 * Fail on a store a newer Alchemy deployed: redeploying this version's Worker
 * over it could leave its state in a format this version doesn't know.
 */
const refuseNewerStore = (scriptName: string, observed: number | undefined) =>
  observed !== undefined && observed > STATE_STORE_VERSION
    ? Effect.fail(
        new StateStoreError({
          message:
            `Cloudflare State Store '${scriptName}' runs v${observed}, newer than this ` +
            `Alchemy's v${STATE_STORE_VERSION}, so it was left untouched. Upgrade alchemy to use it.`,
        }),
      )
    : Effect.succeed(observed);

const existenceUnknown =
  (scriptName: string) =>
  (cause: Error & { readonly _tag: string }): StateStoreError =>
    new StateStoreError({
      message:
        `Could not determine whether Cloudflare State Store '${scriptName}' exists, ` +
        `so it was left untouched: ${cause.message}. ` +
        (cause._tag === "Forbidden"
          ? `Check that the Cloudflare credentials can read Workers scripts (Workers Scripts Read).`
          : `Run the command again.`),
      cause,
    });

const makeCloudflareStateStore = Effect.fn(function* ({
  url,
  authToken,
}: {
  url: string;
  authToken: string;
}) {
  const access = yield* Access.Access;
  const accessHeaders = yield* access.getAccessHeaders(new URL(url).host);
  return yield* makeHttpStateStore({
    url,
    authToken,
    transformClient: HttpClientRequest.setHeaders(accessHeaders),
    id: "cloudflare-http",
  });
});

export class StateStoreVersionNotReady extends Data.TaggedError("StateStoreVersionNotReady")<{
  readonly expected: number;
  readonly observed: number | undefined;
}> {
  override get message() {
    return `Cloudflare State Store version not ready (expected v${this.expected}, observed v${this.observed ?? "unknown"}).`;
  }
}

const waitForStateStoreVersion = (url: string, scriptName: string, accountId: string) =>
  Effect.gen(function* () {
    // Right after a deploy the store may not answer yet: keep polling.
    const { matches, expected, observed } = yield* checkStateStoreVersion(
      url,
      scriptName,
      accountId,
    ).pipe(Effect.orElseSucceed(() => unknownVersion));
    if (!matches) {
      return yield* new StateStoreVersionNotReady({ expected, observed });
    }
  }).pipe(
    Effect.retry({
      while: (error) => error instanceof StateStoreVersionNotReady,
      // Edge propagation is usually sub-second but production traces
      // show redeploys occasionally serving the old version for well
      // over 10s. Poll for ~30s before failing loudly.
      schedule: Schedule.max([Schedule.spaced("500 millis"), Schedule.recurs(60)]),
    }),
    // Each poll retries on its own, so bound the whole wait.
    Effect.timeoutOrElse({
      duration: "2 minutes",
      orElse: () =>
        Effect.fail(
          new StateStoreError({
            message:
              `Cloudflare State Store '${scriptName}' was deployed but ${url} did not serve ` +
              `v${STATE_STORE_VERSION} within 2 minutes. Its secrets and state are unchanged; ` +
              `run the command again.`,
          }),
        ),
    }),
    Effect.withSpan("state_store.wait_for_version", {
      attributes: {
        "alchemy.state_store.op": "wait_for_version",
        "alchemy.state_store.url": url,
        "alchemy.state_store.expected_version": STATE_STORE_VERSION,
      },
    }),
  );

const checkStateStoreVersion = Effect.fn("state_store.check_version", {
  attributes: { "alchemy.state_store.op": "check_version" },
})(function* (url: string, scriptName: string, accountId: string) {
  const client = yield* HttpApiClient.make(StateApi, { baseUrl: url });
  const isAvailable = yield* Effect.cached(isStateStoreAvailable(accountId, scriptName));
  // The /version route may 404 transiently after a fresh deploy
  // while Cloudflare propagates the new script to the edge, and may
  // also surface transport-level blips on cold workers.dev hosts.
  // Retry the probe itself for ~10s before giving up. `observed` is
  // `undefined` only when the worker is confirmed absent; a probe that
  // still fails after that budget fails the check.
  const result = yield* client.version.getVersion().pipe(
    Effect.catchTag("HttpClientError", (e) =>
      // if we get a 404 here, it means we assumed the worker shoudl exist, but it does not
      // we should do a check to see if it does
      e.response?.status === 404
        ? isAvailable.pipe(
            Effect.flatMap((isAvailable) =>
              // if the worker is available, then we should assume it was recently created and retry by propagating the error
              // otherwise, return undefined (we don't know the version, there is no worker)
              isAvailable ? Effect.fail(e) : Effect.undefined,
            ),
          )
        : Effect.fail(e),
    ),
    Effect.retry({
      schedule: Schedule.max([Schedule.spaced("250 millis"), Schedule.recurs(40)]),
    }),
  );
  const matches = result?.version === STATE_STORE_VERSION;
  yield* Effect.annotateCurrentSpan({
    "alchemy.state_store.expected_version": STATE_STORE_VERSION,
    "alchemy.state_store.observed_version": result?.version ?? -1,
    "alchemy.state_store.version_match": matches,
  });
  return {
    matches,
    expected: STATE_STORE_VERSION,
    observed: result?.version,
  };
});

/** A version check that failed, for callers that read it as an outdated store. */
const unknownVersion = {
  matches: false,
  expected: STATE_STORE_VERSION,
  observed: undefined,
} as const;

/**
 * Tiny ES-module worker that reads `env.SECRET.get()` and echoes it
 * back. Uploaded as an ephemeral edge-preview, called once, then
 * discarded — see {@link readSecretViaEdge}.
 */
const SECRET_PROBE_SOURCE = `export default {
  async fetch(_request, env) {
    try {
      const value = await env.SECRET.get();
      return new Response(value ?? "", { status: 200, headers: { "content-type": "text/plain" } });
    } catch (e) {
      return new Response("Error: " + (e && e.message ? e.message : String(e)), { status: 500 });
    }
  },
};`;

/**
 * Upload an ephemeral edge-preview build of the given (already
 * deployed) script that binds the requested Secrets Store secret,
 * call it once with the preview token, and return the decoded value.
 * The Cloudflare REST API deliberately hides secret values; only
 * worker bindings can resolve them, so this is the out-of-band path.
 *
 * `scriptName` MUST be a script that is already deployed on the
 * account with workers.dev enabled — the `cf-workers-preview-token`
 * header swaps our probe code in for an existing route, it does not
 * create one. Using an undeployed name (or a deployed script that
 * doesn't have workers.dev enabled) makes the workers.dev edge serve
 * a generic Cloudflare 400 HTML error page instead of routing to the
 * preview. The state-store script itself satisfies both conditions.
 */
const readSecretViaEdge = (
  accountId: string,
  scriptName: string,
  storeId: string,
  secretName: string,
  route?: { readonly zoneId: string; readonly host: string },
) =>
  Effect.gen(function* () {
    const http = yield* HttpClient.HttpClient;
    const file = new File([SECRET_PROBE_SOURCE], "worker.js", {
      type: "application/javascript+module",
    });
    // The preview runs in the store's account, which a pin may set apart
    // from the profile's.
    const environment = yield* CloudflareEnvironment.CloudflareEnvironment;
    const session = yield* createEdgeSession({
      scriptName,
      files: [file],
      bindings: [{ type: "secrets_store_secret", name: "SECRET", secretName, storeId }],
      route,
    }).pipe(
      Effect.provideService(
        CloudflareEnvironment.CloudflareEnvironment,
        Effect.map(environment, (credentials) => ({ ...credentials, accountId })),
      ),
    );
    const response = yield* http.get(session.url, {
      headers: session.headers,
    });
    if (response.status !== 200) {
      const body = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
      // TEMP(sam): dump the full body so we can capture the exact
      // Cloudflare error page when the probe fails in the wild. Drop
      // this once we've confirmed the routing fix covers all the
      // observed failure modes.
      yield* Effect.logWarning(
        `Secret probe failed (${response.status}) at ${session.url}\n${body}`,
      );
      return yield* new EdgeSessionError({
        message: `Secret probe returned ${response.status}: ${body.slice(0, 200)}`,
      });
    }
    return yield* response.text;
  }).pipe(
    Effect.mapError((cause) =>
      cause instanceof EdgeSessionError
        ? cause
        : new EdgeSessionError({ message: "Failed to read secret", cause }),
    ),
    Effect.withSpan("state_store.read_secret_via_edge", {
      attributes: {
        "alchemy.state_store.op": "read_secret_via_edge",
        "alchemy.state_store.script_name": scriptName,
        "alchemy.state_store.secret_name": secretName,
      },
    }),
  );

const isWorkersPreviewConfigurationError = (error: unknown) =>
  error instanceof EdgeSessionError &&
  (error.message.includes("Invalid Workers Preview configuration") ||
    error.message.includes("Error 1031"));

/**
 * Edge-preview reads are flaky in ways that clear up on their own:
 * the workers.dev edge can serve a generic Cloudflare 400/502 HTML
 * page while preview routing propagates ("Secret probe returned
 * ..."), the session-create call can hit transient API blips, and the
 * probe fetch can fail at the transport level ("fetch failed").
 * Retry everything except causes that are clearly permanent
 * (bad credentials, invalid routes).
 *
 * @internal exported for unit testing.
 */
export const isTransientEdgeSessionError = (error: unknown): boolean => {
  if (!(error instanceof EdgeSessionError)) return false;
  // Non-200 probe responses are edge-propagation flakes, not client bugs.
  if (error.message.startsWith("Secret probe returned")) return true;
  const tag = (error.cause as { _tag?: unknown } | undefined)?._tag;
  if (
    typeof tag === "string" &&
    (tag.startsWith("Unauthorized") ||
      tag === "Forbidden" ||
      tag === "InvalidRoute" ||
      tag === "AuthError")
  ) {
    return false;
  }
  return true;
};

/**
 * SHA-256 hex digest of the Cloudflare account ID. Used as a stable
 * pseudonymous identifier on telemetry spans so the dashboard can
 * count distinct state-store deployments without leaking the raw
 * accountId. Mirrors the `alchemy.git.origin_hash` pattern in
 * `Telemetry/Attributes.ts`.
 */
const hashAccountId = (accountId: string) =>
  Effect.sync(() => crypto.createHash("sha256").update(accountId).digest("hex"));

/**
 * Best-effort Cloudflare-account-hash annotation on the current span, unless
 * the `NO_TRACK` env var opts out.
 */
const annotateAccountHash = (accountId: string) =>
  Effect.gen(function* () {
    if (yield* Config.Boolean("NO_TRACK").pipe(Config.withDefault(false))) return;
    yield* Effect.annotateCurrentSpan(
      "alchemy.cloudflare.account_hash",
      yield* hashAccountId(accountId),
    );
  }).pipe(Effect.ignore);