alchemy 0.20.1 → 0.22.0

package/src/cloudflare/worker-metadata.ts

@@ -1,11 +1,18 @@
-import type { Context } from "../context.js";
-import { slugify } from "../util/slugify.js";
-import { Self, type Bindings, type WorkerBindingSpec } from "./bindings.js";
-import type { DurableObjectNamespace } from "./durable-object-namespace.js";
-import { createAssetConfig, type AssetUploadResult } from "./worker-assets.js";
-import type { SingleStepMigration } from "./worker-migration.js";
-import type { AssetsConfig, Worker, WorkerProps } from "./worker.js";
-import type { Workflow } from "./workflow.js";
+import type { Context } from "../context.ts";
+import { slugify } from "../util/slugify.ts";
+import {
+  Self,
+  type Bindings,
+  type WorkerBindingDurableObjectNamespace,
+  type WorkerBindingSpec,
+} from "./bindings.ts";
+import {
+  isDurableObjectNamespace,
+  type DurableObjectNamespace,
+} from "./durable-object-namespace.ts";
+import { createAssetConfig, type AssetUploadResult } from "./worker-assets.ts";
+import type { SingleStepMigration } from "./worker-migration.ts";
+import type { AssetsConfig, Worker, WorkerProps } from "./worker.ts";
 
 /**
  * Metadata returned by Cloudflare API for a worker script
@@ -186,7 +193,8 @@ export interface WorkerMetadata {
 
 export async function prepareWorkerMetadata<B extends Bindings>(
   ctx: Context<Worker<B>>,
-  oldBindings: Bindings | undefined,
+  oldBindings: WorkerBindingSpec[] | undefined,
+  oldTags: string[] | undefined,
   props: WorkerProps & {
     compatibilityDate: string;
     compatibilityFlags: string[];
@@ -194,20 +202,75 @@ export async function prepareWorkerMetadata<B extends Bindings>(
   },
   assetUploadResult?: AssetUploadResult,
 ): Promise<WorkerMetadata> {
-  const deletedClasses = Object.entries(oldBindings ?? {})
-    .filter(([key]) => !props.bindings?.[key])
-    .flatMap(([_, binding]) => {
-      if (
-        binding &&
-        typeof binding === "object" &&
-        binding.type === "durable_object_namespace" &&
-        (binding.scriptName === undefined ||
-          binding.scriptName === props.workerName)
-      ) {
-        return [binding.className];
+  // we use Cloudflare Worker tags to store a mapping between Alchemy's stable identifier and the binding name
+  // e.g.
+  // {
+  //   BINDING_NAME: new DurableObjectNamespace("stable-id")
+  // }
+  // will be stored as alchemy:do:stable-id:BINDING_NAME
+  // TODO(sam): should we base64 encode to ensure no `:` collision risk?
+  const bindingNameToStableId = Object.fromEntries(
+    oldTags?.flatMap((tag) => {
+      // alchemy:do:{stableId}:{bindingName}
+      if (tag.startsWith("alchemy:do:")) {
+        const [, , stableId, bindingName] = tag.split(":");
+        return [[bindingName, stableId]];
       }
       return [];
-    });
+    }) ?? [],
+  );
+
+  const deletedClasses = oldBindings?.flatMap((oldBinding) => {
+    if (
+      oldBinding.type === "durable_object_namespace" &&
+      (oldBinding.script_name === undefined ||
+        // if this a cross-script binding, we don't need to do migrations in the remote worker
+        oldBinding.script_name === props.workerName)
+    ) {
+      // reverse the stableId from our tag-encoded metadata
+      const stableId = bindingNameToStableId[oldBinding.name];
+      if (stableId) {
+        if (props.bindings === undefined) {
+          // all classes are deleted
+          return [oldBinding.class_name];
+        }
+        // we created this worker on latest version, we can now intelligently determine migrations
+
+        // try and find the DO binding by stable id
+        const object = Object.values(props.bindings).find(
+          (binding): binding is DurableObjectNamespace<any> =>
+            isDurableObjectNamespace(binding) && binding.id === stableId,
+        );
+        if (object) {
+          // we found the corresponding object, it should not be deleted
+          return [];
+        } else {
+          // it was not found, we will now delete it
+          return [oldBinding.class_name];
+        }
+      } else {
+        // ok, we were unable to find the stableId, this worker must have been created by an old alchemy or outside of alchemy
+        // let's now apply a herusitic based on binding name (assume binding name is consistent)
+        // TODO(sam): this has a chance of being wrong, is that OK? Users should be encouraged to upgrade alchemy version and re-deploy
+        const object = props.bindings?.[oldBinding.name];
+        if (object && isDurableObjectNamespace(object)) {
+          if (object.className === oldBinding.class_name) {
+            // this is relatively safe to assume is the right match, do not delete
+            return [];
+          } else {
+            // the class name has changed, this could indicate one of:
+            // 1. the user has changed the class name and we should migrate it
+            // 2. the user deleted the DO a long time ago and this is unrelated (we should just create a new one)
+            return [oldBinding.class_name];
+          }
+        } else {
+          // we didn't find it, so delete it
+          return [oldBinding.class_name];
+        }
+      }
+    }
+    return [];
+  });
 
   // Prepare metadata with bindings
   const meta: WorkerMetadata = {
@@ -218,11 +281,22 @@ export async function prepareWorkerMetadata<B extends Bindings>(
       enabled: props.observability?.enabled !== false,
     },
     // TODO(sam): base64 encode instead? 0 collision risk vs readability.
-    tags: [`alchemy:id:${slugify(ctx.fqn)}`],
+    tags: [
+      `alchemy:id:${slugify(ctx.fqn)}`,
+      // encode a mapping table of Durable Object stable ID -> binding name
+      // we use this to reliably compute class migrations based on server-side state
+      ...Object.entries(props.bindings ?? {}).flatMap(
+        ([bindingName, binding]) =>
+          isDurableObjectNamespace(binding)
+            ? // TODO(sam): base64 encode if contains `:`?
+              [`alchemy:do:${binding.id}:${bindingName}`]
+            : [],
+      ),
+    ],
     migrations: {
       new_classes: props.migrations?.new_classes ?? [],
       deleted_classes: [
-        ...deletedClasses,
+        ...(deletedClasses ?? []),
         ...(props.migrations?.deleted_classes ?? []),
       ],
       renamed_classes: props.migrations?.renamed_classes ?? [],
@@ -303,7 +377,7 @@ export async function prepareWorkerMetadata<B extends Bindings>(
         binding.scriptName === props.workerName
       ) {
         // we do not need configure class migrations for cross-script bindings
-        configureClassMigration(binding, binding.id, binding.className);
+        configureClassMigration(bindingName, binding);
       }
     } else if (binding.type === "r2_bucket") {
       meta.bindings.push({
@@ -393,29 +467,46 @@ export async function prepareWorkerMetadata<B extends Bindings>(
   }
 
   function configureClassMigration(
-    binding: DurableObjectNamespace<any> | Workflow,
-    stableId: string,
-    className: string,
+    bindingName: string,
+    newBinding: DurableObjectNamespace<any>,
   ) {
-    const oldBinding: DurableObjectNamespace<any> | Workflow | undefined =
-      Object.values(oldBindings ?? {})
-        ?.filter(
-          (b) =>
-            typeof b === "object" &&
-            (b.type === "durable_object_namespace" || b.type === "workflow"),
-        )
-        ?.find((b) => b.id === stableId);
-
-    if (!oldBinding) {
-      if (binding.type === "durable_object_namespace" && binding.sqlite) {
-        meta.migrations!.new_sqlite_classes!.push(className);
+    let prevBinding: WorkerBindingDurableObjectNamespace | undefined;
+    if (oldBindings) {
+      // try and find the prev binding for this
+      for (const oldBinding of oldBindings) {
+        if (oldBinding.type === "durable_object_namespace") {
+          const stableId = bindingNameToStableId[oldBinding.name];
+          if (stableId) {
+            // (happy case)
+            // great, this Worker was created with Alchemy and we can map stable ids
+            if (stableId === newBinding.id) {
+              prevBinding = oldBinding;
+              break;
+            }
+          } else {
+            // (heuristic case)
+            // we were unable to find the stableId, this Worker must not have been created with Alchemy
+            // now, try and resolve by assuming 1:1 binding name correspondence
+            // WARNING: this is an imperfect assumption. Users are advised to upgrade alchemy and re-deploy
+            if (oldBinding.name === bindingName) {
+              prevBinding = oldBinding;
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    if (!prevBinding) {
+      if (newBinding.sqlite) {
+        meta.migrations!.new_sqlite_classes!.push(newBinding.className);
       } else {
-        meta.migrations!.new_classes!.push(className);
+        meta.migrations!.new_classes!.push(newBinding.className);
       }
-    } else if (oldBinding.className !== className) {
+    } else if (prevBinding.class_name !== newBinding.className) {
       meta.migrations!.renamed_classes!.push({
-        from: oldBinding.className,
-        to: className,
+        from: prevBinding.class_name,
+        to: newBinding.className,
       });
     }
   }

package/src/cloudflare/worker-stub.ts

@@ -1,11 +1,11 @@
-import type { Context } from "../context.js";
-import { Resource, ResourceKind } from "../resource.js";
-import { handleApiError } from "./api-error.js";
+import type { Context } from "../context.ts";
+import { Resource, ResourceKind } from "../resource.ts";
+import { handleApiError } from "./api-error.ts";
 import {
   createCloudflareApi,
   type CloudflareApi,
   type CloudflareApiOptions,
-} from "./api.js";
+} from "./api.ts";
 
 /**
  * Properties for creating a Worker stub

package/src/cloudflare/worker.ts

@@ -1,54 +1,60 @@
 import path from "node:path";
-import type { Context } from "../context.js";
-import type { BundleProps } from "../esbuild/bundle.js";
-import { InnerResourceScope, Resource, ResourceKind } from "../resource.js";
-import { getBindKey, tryGetBinding } from "../runtime/bind.js";
-import { isRuntime } from "../runtime/global.js";
-import { bootstrapPlugin } from "../runtime/plugin.js";
-import { Scope } from "../scope.js";
-import { Secret, secret } from "../secret.js";
-import { serializeScope } from "../serde.js";
-import { withExponentialBackoff } from "../util/retry.js";
-import { slugify } from "../util/slugify.js";
-import { CloudflareApiError, handleApiError } from "./api-error.js";
+import type { Context } from "../context.ts";
+import type { BundleProps } from "../esbuild/bundle.ts";
+import { InnerResourceScope, Resource, ResourceKind } from "../resource.ts";
+import { getBindKey, tryGetBinding } from "../runtime/bind.ts";
+import { isRuntime } from "../runtime/global.ts";
+import { bootstrapPlugin } from "../runtime/plugin.ts";
+import { Scope } from "../scope.ts";
+import { Secret, secret } from "../secret.ts";
+import { serializeScope } from "../serde.ts";
+import type { type } from "../type.ts";
+import { withExponentialBackoff } from "../util/retry.ts";
+import { slugify } from "../util/slugify.ts";
+import { CloudflareApiError, handleApiError } from "./api-error.ts";
 import {
   type CloudflareApi,
   type CloudflareApiOptions,
   createCloudflareApi,
-} from "./api.js";
-import type { Assets } from "./assets.js";
-import { type Binding, type Bindings, Json } from "./bindings.js";
-import type { Bound } from "./bound.js";
-import { isBucket } from "./bucket.js";
-import { bundleWorkerScript } from "./bundle/bundle-worker.js";
-import { isD1Database } from "./d1-database.js";
+} from "./api.ts";
+import type { Assets } from "./assets.ts";
+import {
+  type Binding,
+  type Bindings,
+  Json,
+  type WorkerBindingSpec,
+} from "./bindings.ts";
+import type { Bound } from "./bound.ts";
+import { isBucket } from "./bucket.ts";
+import { bundleWorkerScript } from "./bundle/bundle-worker.ts";
+import { isD1Database } from "./d1-database.ts";
 import {
   DurableObjectNamespace,
   isDurableObjectNamespace,
-} from "./durable-object-namespace.js";
+} from "./durable-object-namespace.ts";
 import {
   type EventSource,
   type QueueEventSource,
   isQueueEventSource,
-} from "./event-source.js";
-import { isKVNamespace } from "./kv-namespace.js";
-import { isPipeline } from "./pipeline.js";
+} from "./event-source.ts";
+import { isKVNamespace } from "./kv-namespace.ts";
+import { isPipeline } from "./pipeline.ts";
 import {
   QueueConsumer,
   deleteQueueConsumer,
   listQueueConsumers,
-} from "./queue-consumer.js";
-import { type QueueResource, isQueue } from "./queue.js";
-import { isVectorizeIndex } from "./vectorize-index.js";
-import { type AssetUploadResult, uploadAssets } from "./worker-assets.js";
+} from "./queue-consumer.ts";
+import { type QueueResource, isQueue } from "./queue.ts";
+import { isVectorizeIndex } from "./vectorize-index.ts";
+import { type AssetUploadResult, uploadAssets } from "./worker-assets.ts";
 import {
   type WorkerMetadata,
   type WorkerScriptMetadata,
   prepareWorkerMetadata,
-} from "./worker-metadata.js";
-import type { SingleStepMigration } from "./worker-migration.js";
-import { WorkerStub, isWorkerStub } from "./worker-stub.js";
-import { type Workflow, upsertWorkflow } from "./workflow.js";
+} from "./worker-metadata.ts";
+import type { SingleStepMigration } from "./worker-migration.ts";
+import { WorkerStub, isWorkerStub } from "./worker-stub.ts";
+import { type Workflow, upsertWorkflow } from "./workflow.ts";
 
 /**
  * Configuration options for static assets
@@ -94,8 +100,10 @@ export interface AssetsConfig {
   serve_directly?: boolean;
 }
 
-export interface BaseWorkerProps<B extends Bindings | undefined = undefined>
-  extends CloudflareApiOptions {
+export interface BaseWorkerProps<
+  B extends Bindings | undefined = undefined,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends CloudflareApiOptions {
   /**
    * Bundle options when using entryPoint
    *
@@ -202,17 +210,27 @@ export interface BaseWorkerProps<B extends Bindings | undefined = undefined>
    * Can include queues, streams, or other event sources.
    */
   eventSources?: EventSource[];
+
+  /**
+   * The RPC class to use for the worker.
+   *
+   * This is only used when using the rpc property.
+   */
+  rpc?: (new (...args: any[]) => RPC) | type<RPC>;
 }
 
-export interface InlineWorkerProps<B extends Bindings | undefined = Bindings>
-  extends BaseWorkerProps<B> {
+export interface InlineWorkerProps<
+  B extends Bindings | undefined = Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends BaseWorkerProps<B, RPC> {
   script: string;
   entrypoint?: undefined;
 }
 
 export interface EntrypointWorkerProps<
   B extends Bindings | undefined = Bindings,
-> extends BaseWorkerProps<B> {
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends BaseWorkerProps<B, RPC> {
   entrypoint: string;
   script?: undefined;
 }
@@ -220,9 +238,10 @@ export interface EntrypointWorkerProps<
 /**
  * Properties for creating or updating a Worker
  */
-export type WorkerProps<B extends Bindings | undefined = Bindings> =
-  | InlineWorkerProps<B>
-  | EntrypointWorkerProps<B>;
+export type WorkerProps<
+  B extends Bindings | undefined = Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> = InlineWorkerProps<B, RPC> | EntrypointWorkerProps<B, RPC>;
 
 export type FetchWorkerProps<
   B extends Bindings = Bindings,
@@ -270,65 +289,70 @@ export function isWorker(resource: Resource): resource is Worker<any> {
 /**
  * Output returned after Worker creation/update
  */
-export type Worker<B extends Bindings | undefined = Bindings | undefined> =
-  Resource<"cloudflare::Worker"> &
-    Omit<WorkerProps<B>, "url" | "script"> &
-    globalThis.Service & {
-      type: "service";
-
-      /**
-       * The ID of the worker
-       */
-      id: string;
-
-      /**
-       * The name of the worker
-       */
-      name: string;
-
-      /**
-       * Time at which the worker was created
-       */
-      createdAt: number;
-
-      /**
-       * Time at which the worker was last updated
-       */
-      updatedAt: number;
-
-      /**
-       * The worker's URL if enabled
-       * Format: {name}.{subdomain}.workers.dev
-       */
-      url?: string;
-
-      /**
-       * The bindings that were created
-       */
-      bindings: B;
-
-      /**
-       * Configuration for static assets
-       */
-      assets?: AssetsConfig;
-
-      // phantom property (for typeof myWorker.Env)
-      Env: B extends Bindings
-        ? {
-            [bindingName in keyof B]: Bound<B[bindingName]>;
-          }
-        : undefined;
+export type Worker<
+  B extends Bindings | undefined = Bindings | undefined,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> = Resource<"cloudflare::Worker"> &
+  Omit<WorkerProps<B>, "url" | "script"> &
+  globalThis.Service & {
+    /** @internal phantom property */
+    __rpc__?: RPC;
 
-      /**
-       * The compatibility date for the worker
-       */
-      compatibilityDate: string;
+    type: "service";
 
-      /**
-       * The compatibility flags for the worker
-       */
-      compatibilityFlags: string[];
-    };
+    /**
+     * The ID of the worker
+     */
+    id: string;
+
+    /**
+     * The name of the worker
+     */
+    name: string;
+
+    /**
+     * Time at which the worker was created
+     */
+    createdAt: number;
+
+    /**
+     * Time at which the worker was last updated
+     */
+    updatedAt: number;
+
+    /**
+     * The worker's URL if enabled
+     * Format: {name}.{subdomain}.workers.dev
+     */
+    url?: string;
+
+    /**
+     * The bindings that were created
+     */
+    bindings: B;
+
+    /**
+     * Configuration for static assets
+     */
+    assets?: AssetsConfig;
+
+    // phantom property (for typeof myWorker.Env)
+    Env: B extends Bindings
+      ? {
+          [bindingName in keyof B]: Bound<B[bindingName]>;
+        }
+      : undefined;
+
+    /**
+     * The compatibility date for the worker
+     */
+    compatibilityDate: string;
+
+    /**
+     * The compatibility flags for the worker
+     */
+    compatibilityFlags: string[];
+  };
 
 /**
  * A Cloudflare Worker is a serverless function that can be deployed to the Cloudflare network.
@@ -445,10 +469,10 @@ export type Worker<B extends Bindings | undefined = Bindings | undefined> =
  * @see
  * https://developers.cloudflare.com/workers/
  */
-export function Worker<const B extends Bindings>(
-  id: string,
-  props: WorkerProps<B>,
-): Promise<Worker<B>>;
+export function Worker<
+  const B extends Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded,
+>(id: string, props: WorkerProps<B, RPC>): Promise<Worker<B, RPC>>;
 export function Worker<const B extends Bindings, const E extends EventSource[]>(
   id: string,
   meta: ImportMeta,
@@ -461,6 +485,7 @@ export function Worker<const B extends Bindings>(
 ): Promise<Worker<B>> {
   const [id, meta, props] =
     args.length === 2 ? [args[0], undefined, args[1]] : args;
+
   if (("fetch" in props && props.fetch) || ("queue" in props && props.queue)) {
     const scope = Scope.current;
 
@@ -658,6 +683,8 @@ export function Worker<const B extends Bindings>(
   });
 }
 
+export const DEFAULT_COMPATIBILITY_DATE = "2025-04-20";
+
 export const _Worker = Resource(
   "cloudflare::Worker",
   {
@@ -674,11 +701,16 @@ export const _Worker = Resource(
     // Use the provided name
     const workerName = props.name ?? id;
 
-    const compatibilityDate = props.compatibilityDate ?? "2025-04-20";
+    const compatibilityDate =
+      props.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE;
     const compatibilityFlags = props.compatibilityFlags ?? [];
 
     const uploadWorkerScript = async (props: WorkerProps<B>) => {
-      const oldBindings = await this.get<Bindings>("bindings");
+      const [oldBindings, oldMetadata] = await Promise.all([
+        getWorkerBindings(api, workerName),
+        getWorkerScriptMetadata(api, workerName),
+      ]);
+      const oldTags = oldMetadata?.default_environment?.script?.tags;
 
       // Get the script content - either from props.script, or by bundling
       const scriptContent =
@@ -725,6 +757,7 @@ export const _Worker = Resource(
       const scriptMetadata = await prepareWorkerMetadata(
         this,
         oldBindings,
+        oldTags,
         {
           ...props,
           compatibilityDate,
@@ -736,9 +769,6 @@ export const _Worker = Resource(
 
       await putWorker(api, workerName, scriptContent, scriptMetadata);
 
-      // TODO: it is less than ideal that this can fail, resulting in state problem
-      await this.set("bindings", props.bindings);
-
       for (const workflow of workflowsBindings) {
         await upsertWorkflow(api, {
           workflowName: workflow.workflowName,
@@ -1106,34 +1136,49 @@ export async function getWorkerScriptMetadata(
   return ((await response.json()) as any).result as WorkerScriptMetadata;
 }
 
-export async function _getWorkerBindings(
-  api: CloudflareApi,
-  workerName: string,
-  environment = "production",
-) {
+async function getWorkerBindings(api: CloudflareApi, workerName: string) {
+  // Fetch the bindings for a worker by calling the Cloudflare API endpoint:
+  // GET /accounts/:account_id/workers/scripts/:script_name/bindings
+  // See: https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/script_and_version_settings/methods/get/
   const response = await api.get(
-    `/accounts/${api.accountId}/workers/services/${workerName}/environments/${environment}/bindings`,
-    {
-      headers: {
-        Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
-        "Content-Type": "application/json",
-      },
-    },
+    `/accounts/${api.accountId}/workers/scripts/${workerName}/settings`,
   );
-
   if (response.status === 404) {
     return undefined;
   }
-
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch bindings: ${response.status} ${response.statusText}`,
+      `Error getting worker bindings: ${response.status} ${response.statusText}`,
     );
   }
-
-  const data: any = await response.json();
-
-  return data.result;
+  // The result is an object with a "result" property containing the bindings array
+  const { result, success, errors } = (await response.json()) as {
+    result: {
+      bindings: WorkerBindingSpec[];
+      compatibility_date: string;
+      compatibility_flags: string[];
+      [key: string]: any;
+    };
+    success: boolean;
+    errors: Array<{
+      code: number;
+      message: string;
+      documentation_url: string;
+      [key: string]: any;
+    }>;
+    messages: Array<{
+      code: number;
+      message: string;
+      documentation_url: string;
+      [key: string]: any;
+    }>;
+  };
+  if (!success) {
+    throw new Error(
+      `Error getting worker bindings: ${response.status} ${response.statusText}\nErrors:\n${errors.map((e) => `- [${e.code}] ${e.message} (${e.documentation_url})`).join("\n")}`,
+    );
+  }
+  return result.bindings;
 }
 
 /**

package/src/cloudflare/workflow.ts

@@ -1,5 +1,6 @@
-import { handleApiError } from "./api-error.js";
-import type { CloudflareApi } from "./api.js";
+import { handleApiError } from "./api-error.ts";
+import type { CloudflareApi } from "./api.ts";
+import type { Binding } from "./bindings.ts";
 
 export interface WorkflowProps {
   /**
@@ -20,6 +21,10 @@ export interface WorkflowProps {
   className?: string;
 }
 
+export function isWorkflow(binding: Binding): binding is Workflow {
+  return typeof binding === "object" && binding.type === "workflow";
+}
+
 export class Workflow<PARAMS = unknown> {
   public readonly type = "workflow";
   /**