alchemy 0.24.0 → 0.24.1

package/src/cloudflare/do-state-store/internal.ts

@@ -0,0 +1,215 @@
+import path from "node:path";
+import { bundle } from "../../esbuild/index.ts";
+import { withExponentialBackoff } from "../../util/retry.ts";
+import { handleApiError } from "../api-error.ts";
+import type { CloudflareApi } from "../api.ts";
+import { putWorker } from "../worker.ts";
+import type { DOStateStoreAPI } from "./types.ts";
+
+interface DOStateStoreClientOptions {
+  app: string;
+  stage: string;
+  url: string;
+  token: string;
+}
+
+class StateStoreError extends Error {
+  constructor(
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+  }
+}
+
+export class DOStateStoreClient {
+  constructor(private readonly options: DOStateStoreClientOptions) {}
+
+  async rpc<T extends keyof DOStateStoreAPI.API>(
+    method: T,
+    params: DOStateStoreAPI.API[T]["params"],
+  ): Promise<DOStateStoreAPI.API[T]["result"]> {
+    return await withExponentialBackoff(
+      async () => {
+        const res = await this.fetch("/rpc", {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            method,
+            params,
+          }),
+        });
+        if (!res.headers.get("Content-Type")?.includes("application/json")) {
+          throw new StateStoreError(
+            `Unexpected response of type "${res.headers.get("Content-Type")}" from state store: ${res.status} ${res.statusText} ${await res.text()}`,
+            true,
+          );
+        }
+        const body = await res.json<DOStateStoreAPI.Response>();
+        if (!body.success) {
+          throw new StateStoreError(
+            `State store "${method}" request failed with status ${res.status}: ${body.error}`,
+            res.status >= 500,
+          );
+        }
+        return body.result;
+      },
+      (error) => {
+        if (error instanceof StateStoreError) {
+          return error.retryable;
+        }
+        return true;
+      },
+      5,
+      500,
+    );
+  }
+
+  async validate(): Promise<Response> {
+    return await this.fetch("/rpc", {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        method: "validate",
+        params: null,
+      }),
+    });
+  }
+
+  async fetch(path: string, init: RequestInit = {}): Promise<Response> {
+    const url = new URL(path, this.options.url);
+    url.searchParams.set("app", this.options.app);
+    url.searchParams.set("stage", this.options.stage);
+    return await fetch(url, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${this.options.token}`,
+        ...init.headers,
+      },
+    });
+  }
+}
+
+const TAG = "alchemy-state-store:2025-06-03";
+
+const cache = new Map<string, string>();
+
+export async function upsertStateStoreWorker(
+  api: CloudflareApi,
+  workerName: string,
+  token: string,
+) {
+  const key = `worker:${workerName}`;
+  const cached = cache.get(key);
+  if (cached === TAG) {
+    return;
+  }
+  const { found, tag } = await getWorkerStatus(api, workerName);
+  if (found && tag === TAG) {
+    cache.set(key, TAG);
+    return;
+  }
+  const script = await bundleWorkerScript();
+  await putWorker(api, workerName, script, {
+    main_module: "worker.js",
+    compatibility_date: "2025-06-01",
+    compatibility_flags: ["nodejs_compat"],
+    bindings: [
+      {
+        name: "DOFS_STATE_STORE",
+        type: "durable_object_namespace",
+        class_name: "DOFSStateStore",
+      },
+      {
+        name: "DOFS_TOKEN",
+        type: "secret_text",
+        text: token,
+      },
+    ],
+    migrations: !found
+      ? {
+          new_sqlite_classes: ["DOFSStateStore"],
+        }
+      : undefined,
+    tags: [TAG],
+    observability: {
+      enabled: true,
+    },
+  });
+  const subdomainRes = await api.post(
+    `/accounts/${api.accountId}/workers/scripts/${workerName}/subdomain`,
+    { enabled: true, preview_enabled: false },
+    {
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+  if (!subdomainRes.ok) {
+    await handleApiError(
+      subdomainRes,
+      "creating worker subdomain",
+      "worker",
+      workerName,
+    );
+  }
+  cache.set(key, TAG);
+}
+
+async function getWorkerStatus(api: CloudflareApi, workerName: string) {
+  const res = await api.get(
+    `/accounts/${api.accountId}/workers/scripts/${workerName}/settings`,
+  );
+  if (!res.ok) {
+    return {
+      found: false,
+      tag: undefined,
+    };
+  }
+  const json: {
+    result: {
+      tags: string[];
+    };
+  } = await res.json();
+  return {
+    found: true,
+    tag: json.result.tags.find((tag) => tag.startsWith("alchemy-state-store:")),
+  };
+}
+
+export async function getAccountSubdomain(api: CloudflareApi) {
+  const key = `subdomain:${api.accountId}`;
+  const cached = cache.get(key);
+  if (cached) {
+    return cached;
+  }
+  const res = await api.get(`/accounts/${api.accountId}/workers/subdomain`);
+  if (!res.ok) {
+    throw new Error(
+      `Failed to get account subdomain: ${res.status} ${res.statusText}`,
+    );
+  }
+  const json: { result: { subdomain: string } } = await res.json();
+  const subdomain = json.result.subdomain;
+  cache.set(key, subdomain);
+  return subdomain;
+}
+
+async function bundleWorkerScript() {
+  const result = await bundle({
+    entryPoint: path.join(__dirname, "worker.ts"),
+    bundle: true,
+    format: "esm",
+    target: "es2022",
+    external: ["cloudflare:*", "node:crypto"],
+    write: false,
+  });
+  if (!result.outputFiles?.[0]) {
+    throw new Error("Failed to bundle worker.ts");
+  }
+  return result.outputFiles[0].text;
+}

package/src/cloudflare/do-state-store/store.ts

@@ -0,0 +1,188 @@
+import { alchemy } from "../../alchemy.ts";
+import { ResourceScope } from "../../resource.ts";
+import type { Scope } from "../../scope.ts";
+import type { State, StateStore } from "../../state.ts";
+import { deserializeState } from "../../state.ts";
+import { createCloudflareApi, type CloudflareApiOptions } from "../api.ts";
+import {
+  DOStateStoreClient,
+  getAccountSubdomain,
+  upsertStateStoreWorker,
+} from "./internal.ts";
+
+export interface DOStateStoreOptions extends CloudflareApiOptions {
+  /**
+   * The prefix to use for state keys.
+   * Each app and stage has its own state store, so this is primarily for testing.
+   * @default "alchemy"
+   */
+  prefix?: string;
+  worker?:
+    | {
+        /**
+         * The name of the worker to use
+         * @default "alchemy-state"
+         */
+        name?: string;
+        /**
+         * The token to use for the worker
+         * @default the value of the ALCHEMY_STATE_TOKEN environment variable
+         */
+        token?: string;
+        /**
+         * Whether to force the creation of a new worker
+         */
+        force?: boolean;
+      }
+    | {
+        /**
+         * The URL of an existing state store worker to use
+         */
+        url: string;
+        /**
+         * The token to use for the worker
+         * @default the value of the ALCHEMY_STATE_TOKEN environment variable
+         */
+        token?: string;
+      };
+}
+
+export class DOStateStore implements StateStore {
+  private prefix: string;
+  private client?: Promise<DOStateStoreClient>;
+
+  constructor(
+    private readonly scope: Scope,
+    private readonly options: DOStateStoreOptions = {},
+  ) {
+    this.prefix = [options.prefix ?? "alchemy", ...scope.chain, ""].join("/");
+  }
+
+  private async createClient() {
+    const token =
+      this.options.worker?.token ??
+      (await alchemy.secret.env.ALCHEMY_STATE_TOKEN).unencrypted;
+    if (this.options.worker && "url" in this.options.worker) {
+      const client = new DOStateStoreClient({
+        app: this.scope.appName ?? "alchemy",
+        stage: this.scope.stage,
+        url: this.options.worker.url,
+        token,
+      });
+      // The worker is already created and should be ready to use.
+      // If it's not, we'll fail fast with a helpful error message.
+      const res = await client.validate();
+      if (res.status === 200) {
+        return client;
+      }
+      if (res.status === 401) {
+        throw new Error(
+          "A worker URL was provided to DOStateStore, but the token is incorrect. Correct the token or remove the worker URL to create a new worker.",
+        );
+      }
+      throw new Error(
+        `A worker URL was provided to DOStateStore, but the worker status is ${res.status} ${res.statusText}.`,
+      );
+    }
+    const workerName = this.options.worker?.name ?? "alchemy-state";
+    const api = await createCloudflareApi(this.options);
+    const [subdomain, _] = await Promise.all([
+      getAccountSubdomain(api),
+      upsertStateStoreWorker(api, workerName, token),
+    ]);
+    const client = new DOStateStoreClient({
+      app: this.scope.appName ?? "alchemy",
+      stage: this.scope.stage,
+      url: `https://${workerName}.${subdomain}.workers.dev`,
+      token,
+    });
+    // This ensures the token is correct and the worker is ready to use.
+    // RPC methods are retried, which is what we want here in case the worker is not ready yet.
+    await client.rpc("validate", null);
+    return client;
+  }
+
+  private async getClient() {
+    this.client ??= this.createClient();
+    return await this.client;
+  }
+
+  async init() {
+    await this.getClient();
+  }
+
+  async list(): Promise<string[]> {
+    const client = await this.getClient();
+    const res = await client.rpc("list", { prefix: this.prefix });
+    return res.map((key) => this.deserializeKey(key));
+  }
+
+  async count(): Promise<number> {
+    const client = await this.getClient();
+    const res = await client.rpc("count", { prefix: this.prefix });
+    return res;
+  }
+
+  async get(key: string): Promise<State | undefined> {
+    const client = await this.getClient();
+    const res = await client.rpc("get", { key: this.serializeKey(key) });
+    if (res) {
+      return await this.deserializeState(res);
+    }
+    return undefined;
+  }
+
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    const client = await this.getClient();
+    const res = await client.rpc("getBatch", {
+      keys: ids.map((id) => this.serializeKey(id)),
+    });
+    return await this.deserializeStates(res);
+  }
+
+  async all(): Promise<Record<string, State>> {
+    const client = await this.getClient();
+    const res = await client.rpc("all", { prefix: this.prefix });
+    return await this.deserializeStates(res);
+  }
+
+  async set(key: string, value: State): Promise<void> {
+    const client = await this.getClient();
+    await client.rpc("set", { key: this.serializeKey(key), value });
+  }
+
+  async delete(key: string): Promise<void> {
+    const client = await this.getClient();
+    await client.rpc("delete", { key: this.serializeKey(key) });
+  }
+
+  private async deserializeStates(
+    input: Record<string, string>,
+  ): Promise<Record<string, State>> {
+    return Object.fromEntries(
+      await Promise.all(
+        Object.entries(input).map(async ([key, value]) => [
+          this.deserializeKey(key),
+          await this.deserializeState(value),
+        ]),
+      ),
+    );
+  }
+
+  private async deserializeState(input: string): Promise<State> {
+    const state = await deserializeState(this.scope, input);
+    if (state.output === undefined) {
+      state.output = {} as any;
+    }
+    state.output[ResourceScope] = this.scope;
+    return state;
+  }
+
+  private deserializeKey(key: string): string {
+    return key.replace(this.prefix, "").replaceAll(":", "/");
+  }
+
+  private serializeKey(key: string): string {
+    return `${this.prefix}${key.replaceAll("/", ":")}`;
+  }
+}

package/src/cloudflare/do-state-store/types.ts

@@ -0,0 +1,74 @@
+import type { State } from "../../state.ts";
+
+export namespace DOStateStoreAPI {
+  export type API = {
+    validate: {
+      method: "validate";
+      params: null;
+      result: null;
+    };
+    get: {
+      method: "get";
+      params: { key: string };
+      result: string | undefined;
+    };
+    getBatch: {
+      method: "getBatch";
+      params: { keys: string[] };
+      result: Record<string, string>;
+    };
+    all: {
+      method: "all";
+      params: { prefix: string };
+      result: Record<string, string>;
+    };
+    set: {
+      method: "set";
+      params: { key: string; value: State };
+      result: null;
+    };
+    delete: {
+      method: "delete";
+      params: { key: string };
+      result: null;
+    };
+    list: {
+      method: "list";
+      params: { prefix: string };
+      result: string[];
+    };
+    count: {
+      method: "count";
+      params: { prefix: string };
+      result: number;
+    };
+  };
+
+  export interface Context {
+    app: string;
+    stage: string;
+  }
+
+  export type Request = {
+    [K in keyof API]: {
+      method: K;
+      params: API[K]["params"];
+    };
+  }[keyof API];
+
+  export interface SuccessResponse<T extends keyof API = keyof API> {
+    success: true;
+    status: number;
+    result: API[T]["result"];
+  }
+
+  export interface ErrorResponse {
+    success: false;
+    status: number;
+    error: string;
+  }
+
+  export type Response<T extends keyof API = keyof API> =
+    | SuccessResponse<T>
+    | ErrorResponse;
+}

package/src/cloudflare/do-state-store/worker.ts

@@ -0,0 +1,199 @@
+import { DurableObject, WorkerEntrypoint } from "cloudflare:workers";
+import { Fs } from "dofs";
+import { timingSafeEqual } from "node:crypto";
+import type { State } from "../../state.ts";
+import type { DOStateStoreAPI } from "./types.ts";
+
+interface Env {
+  DOFS_STATE_STORE: DurableObjectNamespace<DOFSStateStore>;
+  DOFS_TOKEN: string;
+}
+
+export default class extends WorkerEntrypoint<Env> {
+  override async fetch(request: Request) {
+    try {
+      const result = await this.handle(request);
+      const body: DOStateStoreAPI.Response = {
+        success: true,
+        status: 200,
+        result: result ?? undefined,
+      };
+      return Response.json(body, { status: body.status });
+    } catch (error) {
+      return APIError.fromUnknown(error).toResponse();
+    }
+  }
+
+  private async handle(request: Request) {
+    if (!this.authorize(request)) {
+      throw new APIError("Unauthorized", 401);
+    }
+    const stub = this.getStub(request);
+    const body = await this.parseBody(request);
+    switch (body.method) {
+      case "validate":
+        return null;
+      case "all":
+        return await stub.all(body.params.prefix);
+      case "count":
+        return await stub.count(body.params.prefix);
+      case "delete":
+        return await stub.delete(body.params.key);
+      case "get":
+        return await stub.get(body.params.key);
+      case "getBatch":
+        return await stub.getBatch(body.params.keys);
+      case "list":
+        return await stub.list(body.params.prefix);
+      case "set":
+        return await stub.set(body.params.key, body.params.value);
+      default: {
+        const _: never = body;
+        throw new APIError("Method not found", 404);
+      }
+    }
+  }
+
+  private authorize(request: Request): boolean {
+    const token = request.headers.get("Authorization")?.split(" ")[1];
+    if (!token) {
+      return false;
+    }
+    return timingSafeEqual(
+      new TextEncoder().encode(token),
+      new TextEncoder().encode(this.env.DOFS_TOKEN),
+    );
+  }
+
+  private getStub(request: Request): DurableObjectStub<DOFSStateStore> {
+    const url = new URL(request.url);
+    const app = url.searchParams.get("app");
+    const stage = url.searchParams.get("stage");
+    if (!app || !stage) {
+      throw new APIError("Missing app or stage", 400);
+    }
+    return this.env.DOFS_STATE_STORE.get(
+      this.env.DOFS_STATE_STORE.idFromName(`${app}/${stage}`),
+    );
+  }
+
+  private async parseBody(request: Request): Promise<DOStateStoreAPI.Request> {
+    try {
+      return await request.json<DOStateStoreAPI.Request>();
+    } catch {
+      throw new APIError("Invalid JSON", 400);
+    }
+  }
+}
+
+class APIError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+  ) {
+    super(message);
+  }
+
+  toResponse(): Response {
+    return Response.json(
+      {
+        success: false,
+        status: this.status,
+        error: this.message,
+      },
+      { status: this.status },
+    );
+  }
+
+  static fromUnknown(error: unknown): APIError {
+    if (error instanceof APIError) {
+      return error;
+    }
+    if (error instanceof Error) {
+      return new APIError(error.message, 500);
+    }
+    return new APIError("An unknown error occurred.", 500);
+  }
+}
+
+export class DOFSStateStore extends DurableObject<Env> {
+  fs = new Fs(this.ctx, this.env, {
+    chunkSize: 256 * 1024,
+  });
+
+  async all(prefix: string): Promise<Record<string, string>> {
+    const keys = this.list(prefix);
+    return await this.getBatch(keys);
+  }
+
+  count(prefix: string): number {
+    return this.list(prefix).length;
+  }
+
+  delete(key: string): void {
+    try {
+      this.fs.unlink(key);
+    } catch (error) {
+      if (isErrorCode(error, "ENOENT")) {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    try {
+      const file = this.fs.readFile(key);
+      return new Response(file).text();
+    } catch (error) {
+      if (isErrorCode(error, "ENOENT")) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async getBatch(keys: string[]): Promise<Record<string, string>> {
+    const result: Record<string, string> = {};
+    await Promise.all(
+      keys.map(async (key) => {
+        const value = await this.get(key);
+        if (value) {
+          result[key] = value;
+        }
+      }),
+    );
+    return result;
+  }
+
+  list(prefix: string): string[] {
+    try {
+      return this.fs
+        .listDir(prefix, { recursive: true })
+        .filter((item) => item !== "." && item !== "..");
+    } catch (error) {
+      if (isErrorCode(error, "ENOENT")) {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  async set(key: string, value: State): Promise<void> {
+    this.ensureDir(key);
+    await this.fs.writeFile(key, JSON.stringify(value));
+  }
+
+  private ensureDir(path: string): void {
+    const dir = path.split("/").slice(0, -1).join("/");
+    try {
+      this.fs.mkdir(dir, { recursive: true });
+    } catch {
+      // directory already exists, ignore
+    }
+  }
+}
+
+const isErrorCode = (error: unknown, code: string) => {
+  return error instanceof Error && "message" in error && error.message === code;
+};

package/src/cloudflare/index.ts

@@ -18,6 +18,7 @@ export * from "./d1-database.ts";
 export * from "./d1-export.ts";
 export * from "./d1-import.ts";
 export * from "./dns-records.ts";
+export * from "./do-state-store/index.ts";
 export * from "./durable-object-namespace.ts";
 export * from "./hyperdrive.ts";
 export * from "./kv-namespace.ts";

package/src/cloudflare/pipeline.ts

@@ -364,7 +364,7 @@ const PipelineResource = Resource("cloudflare::Pipeline", async function <
     // Update operation
     if (this.output?.id) {
       // Check if name is being changed, which is not allowed
-      if (props.name !== this.output.name) {
+      if (pipelineName !== this.output.name) {
         throw new Error(
           "Cannot update Pipeline name after creation. Pipeline name is immutable.",
         );