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

import crypto from "node:crypto";
import * as dns from "node:dns/promises";
import { DEFAULT_COMPATIBILITY_DATE } from "@alchemy.run/cloudflare-runtime/core/internal/constants";
import * as durableObjects from "@distilled.cloud/cloudflare/durable-objects";
import * as secretsStore from "@distilled.cloud/cloudflare/secrets-store";
import * as workers from "@distilled.cloud/cloudflare/workers";
import * as zones from "@distilled.cloud/cloudflare/zones";
import { StateStoreError } from "alchemy/State/State";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { waitForSecretActive } from "../SecretsStore/Secret.ts";
import { getCompatibility } from "../Workers/Compatibility.ts";
import { WorkerBundle } from "../Workers/Sources/Rolldown.ts";
import { contentTypeForModule, putWorkerScript } from "../Workers/WorkerProvider.ts";
import { resolveZoneId } from "../Zone/lookup.ts";
import { API_MAIN, STATE_STORE_VERSION } from "./Api.ts";
import {
  AuthTokenBinding,
  AuthTokenSecretName,
  EncryptionKeyBinding,
  EncryptionKeySecretName,
  stateStoreSecretName,
} from "./Token.ts";

/** The Durable Object class holding every store's state. Its name must never change. */
const STORE_CLASS = "Store";

/** The stack name the Worker's runtime reports, kept from the stack-deployed era. */
const RUNTIME_STACK_NAME = "CloudflareStateStore";

/**
 * Deploy a Cloudflare State Store Worker with direct API calls.
 *
 * Every step is idempotent and only ever adds what is missing: the account's
 * Secrets Store and the two state-store secrets are created when absent and
 * never updated or deleted, so redeploying cannot rotate the auth token or
 * lose the encryption key. The Worker itself is re-uploaded on every call
 * with the same `Store` Durable Object class, keeping its stored state.
 *
 * With a `domain`, the Worker is also attached to that hostname as a custom
 * domain and served there.
 *
 * Returns the Worker's URL, and the auth token when this call created it
 * (an existing token can only be read back through a Worker binding).
 */
export const deployStateStoreWorker = Effect.fn("state_store.deploy_worker")(function* ({
  accountId,
  scriptName,
  domain,
}: {
  accountId: string;
  scriptName: string;
  domain: string | undefined;
}) {
  yield* Effect.annotateCurrentSpan({ "alchemy.state_store.script_name": scriptName });
  yield* validateStateStoreWorkerName(scriptName);
  // Fail on secrets or a hostname another Worker owns before changing anything.
  const sharing = yield* findSecretSharingWorker({ accountId, scriptName });
  if (sharing !== undefined) {
    return yield* new StateStoreError({
      message:
        `Cannot deploy the Cloudflare State Store '${scriptName}': its secrets would be shared ` +
        `with Worker '${sharing}', because secret names replace '-' with '_'. Choose a ` +
        `name that differs from '${sharing}' by more than '-' and '_'.`,
    });
  }
  if (domain !== undefined) yield* observeStateStoreDomain({ accountId, scriptName, domain });
  const storeId = yield* ensureSecretsStore(accountId);
  const authToken = yield* ensureSecret({
    accountId,
    storeId,
    name: stateStoreSecretName(AuthTokenSecretName, scriptName),
  });
  yield* ensureSecret({
    accountId,
    storeId,
    name: stateStoreSecretName(EncryptionKeySecretName, scriptName),
  });

  const compatibility = getCompatibility({
    main: API_MAIN,
    compatibility: { date: DEFAULT_COMPATIBILITY_DATE },
  });
  const bundler = yield* WorkerBundle;
  const bundle = yield* bundler.build({
    id: "Api",
    main: API_MAIN,
    compatibility,
    entry: {
      kind: "effect",
      // The entry only needs the class name to export the Durable Object bridge.
      exports: {
        [STORE_CLASS]: {
          kind: "durableObject",
          constructor: Effect.never,
          services: Context.empty(),
        },
      },
    },
    stack: { name: RUNTIME_STACK_NAME, stage: scriptName },
    extraOptions: undefined,
  });

  yield* putWorkerScript({
    accountId,
    scriptName,
    dispatchNamespace: undefined,
    metadata: {
      mainModule: bundle.files[0]!.path,
      compatibilityDate: compatibility.date,
      compatibilityFlags: compatibility.flags,
      bindings: [
        { type: "plain_text", name: "ALCHEMY_PHASE", text: "runtime" },
        { type: "plain_text", name: "ALCHEMY_WORKER_NAME", text: scriptName },
        { type: "plain_text", name: "ALCHEMY_STACK_NAME", text: RUNTIME_STACK_NAME },
        { type: "plain_text", name: "ALCHEMY_STAGE", text: scriptName },
        { type: "plain_text", name: "ALCHEMY_CLOUDFLARE_ACCOUNT_ID", text: accountId },
        {
          type: "plain_text",
          name: STATE_STORE_VERSION_BINDING,
          text: String(STATE_STORE_VERSION),
        },
        {
          type: "secrets_store_secret",
          name: AuthTokenBinding,
          storeId,
          secretName: stateStoreSecretName(AuthTokenSecretName, scriptName),
        },
        {
          type: "secrets_store_secret",
          name: EncryptionKeyBinding,
          storeId,
          secretName: stateStoreSecretName(EncryptionKeySecretName, scriptName),
        },
        { type: "durable_object_namespace", name: STORE_CLASS, className: STORE_CLASS },
      ],
      exports: {
        [STORE_CLASS]: {
          type: "durable-object",
          storage: yield* observedStoreStorage(accountId, scriptName),
        },
      },
      observability: { enabled: true, logs: { enabled: true, invocationLogs: true } },
    },
    files: bundle.files.map(
      (file) =>
        new File([file.content as BlobPart], file.path, {
          type: contentTypeForModule(file.path),
        }),
    ),
  });

  yield* workers.createScriptSubdomain({
    accountId,
    scriptName,
    enabled: true,
    previewsEnabled: true,
  });
  if (domain !== undefined) yield* attachDomain({ accountId, scriptName, domain });
  return { url: yield* stateStoreUrl({ accountId, scriptName, domain }), authToken };
});

/**
 * A store's Worker name: lowercase letters, digits, `-` and `_`, starting with
 * a letter or digit, at most 54 characters. The store enables workers.dev
 * previews, and Cloudflare rejects a longer script name with previews enabled
 * (the preview hostname prefixes it); the cap also keeps its secret names well
 * under the Secrets Store's 255.
 */
export const validateStateStoreWorkerName = (scriptName: string) =>
  /^[a-z0-9][a-z0-9_-]{0,53}$/.test(scriptName)
    ? Effect.succeed(scriptName)
    : Effect.fail(
        new StateStoreError({
          message:
            `Invalid Cloudflare State Store Worker name '${scriptName}': use 1-54 lowercase ` +
            `letters, digits, '-' and '_', starting with a letter or digit.`,
        }),
      );

/**
 * Another Worker whose store's secrets have the same names as this store's.
 * Secret names replace every character other than a letter, digit or `_` with
 * `_`, so the stores `team-a` and `team_a` would share one token and key.
 */
export const findSecretSharingWorker = Effect.fn(function* ({
  accountId,
  scriptName,
}: {
  accountId: string;
  scriptName: string;
}) {
  const secretName = stateStoreSecretName(AuthTokenSecretName, scriptName);
  return yield* workers.listScripts.items({ accountId }).pipe(
    Stream.map((script) => script.id ?? undefined),
    Stream.filter(
      (name): name is string =>
        name !== undefined &&
        name !== scriptName &&
        stateStoreSecretName(AuthTokenSecretName, name) === secretName,
    ),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );
});

/** The binding each deployed store records its version in, read back through the API. */
const STATE_STORE_VERSION_BINDING = "ALCHEMY_STATE_STORE_VERSION";

/**
 * The store's version as Cloudflare's API reports it, `undefined` when it has
 * no Worker, or `"unrecorded"` for a Worker an older Alchemy deployed without
 * recording it. The edge can keep serving a deleted or replaced Worker for a
 * while, so decisions use this rather than what `/version` answers.
 */
export const observeDeployedVersion = Effect.fn(function* ({
  accountId,
  scriptName,
}: {
  accountId: string;
  scriptName: string;
}) {
  const settings = yield* workers
    .getScriptScriptAndVersionSetting({ accountId, scriptName })
    .pipe(Effect.catchTag(["WorkerNotFound", "WorkerHasNoVersions"], () => Effect.undefined));
  if (settings === undefined) return undefined;
  const binding = (settings.bindings ?? []).find(
    (binding) => binding.name === STATE_STORE_VERSION_BINDING,
  );
  const version = binding !== undefined && "text" in binding ? Number(binding.text) : Number.NaN;
  return Number.isInteger(version) ? version : ("unrecorded" as const);
});

/** The origin a store serves on: its custom domain, or its workers.dev URL. */
export const stateStoreUrl = Effect.fn(function* ({
  accountId,
  scriptName,
  domain,
}: {
  accountId: string;
  scriptName: string;
  domain: string | undefined;
}) {
  if (domain !== undefined) return `https://${domain}`;
  const { subdomain } = yield* workers.getSubdomain({ accountId });
  return `https://${scriptName}.${subdomain}.workers.dev`;
});

/**
 * The zone of the custom domain `domain` when it is attached to this Worker,
 * or `undefined`. Fails when another Worker owns the hostname.
 */
export const observeStateStoreDomain = Effect.fn(function* ({
  accountId,
  scriptName,
  domain,
}: {
  accountId: string;
  scriptName: string;
  domain: string;
}) {
  const { result } = yield* workers.listDomains({ accountId, hostname: domain });
  const attached = (result ?? []).find((d) => d.hostname === domain);
  if (attached === undefined) return undefined;
  if (attached.service !== scriptName) {
    return yield* new StateStoreError({
      message:
        `Cannot serve the Cloudflare State Store '${scriptName}' on '${domain}': it is ` +
        `already attached to Worker '${attached.service ?? "<unknown>"}'.`,
    });
  }
  return attached.zoneId ?? undefined;
});

/** Attach `domain` to the Worker as a custom domain, unless it already is. */
const attachDomain = Effect.fn(function* ({
  accountId,
  scriptName,
  domain,
}: {
  accountId: string;
  scriptName: string;
  domain: string;
}) {
  if ((yield* observeStateStoreDomain({ accountId, scriptName, domain })) !== undefined) return;
  const zoneId = yield* resolveZoneId({ accountId, zone: undefined, hostname: domain }).pipe(
    Effect.mapError(
      (cause) =>
        new StateStoreError({
          message: `Couldn't find the Cloudflare zone of '${domain}' on account ${accountId}.`,
          cause,
        }),
    ),
  );
  yield* workers.putDomain({ accountId, hostname: domain, service: scriptName, zoneId }).pipe(
    // The script registry can lag the upload by a few seconds.
    Effect.retry({
      while: (error) => error._tag === "WorkerNotFound",
      schedule: Schedule.max([Schedule.exponential(200), Schedule.recurs(15)]),
    }),
  );
  yield* waitForAuthoritativeDns(zoneId, domain);
});

/**
 * Wait until the zone's nameservers answer for a newly attached `domain`.
 * Resolving it any earlier caches NXDOMAIN in the local resolver for the
 * zone's negative TTL (30 minutes on Cloudflare), and the store would be
 * unreachable from this machine for that long.
 */
const waitForAuthoritativeDns = Effect.fn(function* (zoneId: string, domain: string) {
  const { nameServers } = yield* zones.getZone({ zoneId });
  const servers = yield* Effect.forEach(nameServers, (ns) =>
    Effect.tryPromise(() => dns.resolve4(ns)).pipe(Effect.orElseSucceed(() => [])),
  ).pipe(Effect.map((ips) => ips.flat()));
  if (servers.length === 0) return;
  // A fresh resolver per attempt: one caches the NXDOMAIN it got first.
  const resolver = Effect.sync(() => {
    const resolver = new dns.Resolver({ timeout: 2_000, tries: 1 });
    resolver.setServers(servers);
    return resolver;
  });
  yield* resolver.pipe(
    Effect.flatMap((resolver) => Effect.tryPromise(() => resolver.resolve4(domain))),
    Effect.filterOrFail((addresses) => addresses.length > 0),
    // Cloudflare can take a minute to publish a re-attached custom domain.
    Effect.retry({ schedule: Schedule.spaced("2 seconds"), times: 45 }),
    Effect.mapError(
      (cause) =>
        new StateStoreError({
          message: `'${domain}' was attached to the State Store but its DNS record never appeared.`,
          cause,
        }),
    ),
  );
});

/** Whether the store's auth token and encryption key both exist. */
export const stateStoreSecretsExist = Effect.fn(function* ({
  accountId,
  scriptName,
}: {
  accountId: string;
  scriptName: string;
}) {
  const names = new Set([
    stateStoreSecretName(AuthTokenSecretName, scriptName),
    stateStoreSecretName(EncryptionKeySecretName, scriptName),
  ]);
  const store = yield* secretsStore.listStores.items({ accountId }).pipe(Stream.runHead);
  if (Option.isNone(store)) return false;
  const found = yield* secretsStore.listStoreSecrets
    .items({ accountId, storeId: store.value.id })
    .pipe(
      Stream.filter((secret) => names.has(secret.name)),
      Stream.runCollect,
    );
  return new Set(Array.from(found, (secret) => secret.name)).size === names.size;
});

/**
 * Whether a store that may hold state has lost its encryption key: its Worker
 * exists, so it served state encrypted with a key, but the key is gone. A
 * listing can lag a create, so the key must be missing from several reads.
 */
export const encryptionKeyLost = Effect.fn(function* ({
  accountId,
  scriptName,
}: {
  accountId: string;
  scriptName: string;
}) {
  const hasWorker = yield* workers.getScriptSetting({ accountId, scriptName }).pipe(
    Effect.as(true),
    Effect.catchTag(["WorkerNotFound", "InvalidRoute", "WorkerHasNoVersions"], () =>
      Effect.succeed(false),
    ),
  );
  if (!hasWorker) return false;
  const name = stateStoreSecretName(EncryptionKeySecretName, scriptName);
  const listed = Effect.gen(function* () {
    const store = yield* secretsStore.listStores.items({ accountId }).pipe(Stream.runHead);
    if (Option.isNone(store)) return false;
    return yield* secretsStore.listStoreSecrets.items({ accountId, storeId: store.value.id }).pipe(
      Stream.filter((secret) => secret.name === name),
      Stream.runHead,
      Effect.map(Option.isSome),
    );
  });
  const found = yield* listed.pipe(
    Effect.repeat({ until: (found) => found, schedule: Schedule.spaced("2 seconds"), times: 3 }),
  );
  return !found;
});

/** The account's Secrets Store (Cloudflare allows one), created when missing. */
const ensureSecretsStore = Effect.fn(function* (accountId: string) {
  const first = secretsStore.listStores
    .items({ accountId })
    .pipe(Stream.runHead, Effect.map(Option.getOrUndefined));
  const existing = yield* first;
  if (existing) return existing.id;
  const created = yield* secretsStore
    .createStore({ accountId, name: "default_secrets_store" })
    .pipe(
      // A concurrent bootstrap created it first.
      Effect.catchTag("MaximumStoresExceeded", () => Effect.undefined),
    );
  if (created) return created.id;
  const raced = yield* first;
  if (raced) return raced.id;
  return yield* Effect.die(
    new Error(`Cloudflare reports a Secrets Store on account ${accountId} but lists none.`),
  );
});

/**
 * Create a secret holding 32 random hex-encoded bytes, unless one with this
 * name exists. Returns the value only when this call created it; an existing
 * secret is left exactly as it is.
 */
const ensureSecret = Effect.fn(function* ({
  accountId,
  storeId,
  name,
}: {
  accountId: string;
  storeId: string;
  name: string;
}) {
  const exists = yield* secretsStore.listStoreSecrets.items({ accountId, storeId }).pipe(
    Stream.filter((secret) => secret.name === name),
    Stream.runHead,
    Effect.map(Option.isSome),
  );
  if (exists) return undefined;
  const value = yield* Effect.sync(() => crypto.randomBytes(32).toString("hex"));
  const created = yield* secretsStore
    .createStoreSecret({
      accountId,
      storeId,
      body: [{ name, scopes: ["workers"], value, comment: "Alchemy Cloudflare State Store" }],
    })
    .pipe(
      // A concurrent bootstrap created it first; keep theirs.
      Effect.catchTag("SecretNameAlreadyExists", () => Effect.undefined),
    );
  if (!created) return undefined;
  const secret = created.result[0]!;
  yield* waitForSecretActive({ accountId, storeId, secretId: secret.id }, "pending");
  return value;
});

/** The `Store` class's storage backend as deployed; SQLite for a new store. */
const observedStoreStorage = (accountId: string, scriptName: string) =>
  durableObjects.listNamespaces.items({ accountId }).pipe(
    Stream.filter((ns) => ns.script === scriptName && ns.class === STORE_CLASS),
    Stream.runHead,
    Effect.map((ns) =>
      Option.isSome(ns) && ns.value.useSqlite === false
        ? ("legacy-kv" as const)
        : ("sqlite" as const),
    ),
  );