alchemy 0.6.0 → 0.7.1

package/src/cloudflare/queue.ts

@@ -0,0 +1,371 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+
+/**
+ * Settings for a Cloudflare Queue
+ */
+export interface QueueSettings {
+  /**
+   * Delay in seconds before message delivery
+   * Queue will not deliver messages until this time has elapsed
+   */
+  deliveryDelay?: number;
+
+  /**
+   * Whether delivery is paused
+   * If true, the queue will not deliver messages to consumers
+   */
+  deliveryPaused?: boolean;
+
+  /**
+   * Period in seconds to retain messages
+   * Messages will be automatically deleted after this time
+   */
+  messageRetentionPeriod?: number;
+}
+
+/**
+ * Properties for creating or updating a Cloudflare Queue
+ */
+export interface QueueProps extends CloudflareApiOptions {
+  /**
+   * Name of the queue
+   * Required during creation
+   * Cannot be changed after creation
+   */
+  name: string;
+
+  /**
+   * Settings for the queue
+   * These can be updated after queue creation
+   */
+  settings?: QueueSettings;
+
+  /**
+   * Whether to delete the queue.
+   * If set to false, the queue will remain but the resource will be removed from state
+   *
+   * @default true
+   */
+  delete?: boolean;
+}
+
+/**
+ * Output returned after Cloudflare Queue creation/update
+ */
+export interface Queue extends Resource<"cloudflare::Queue">, QueueProps {
+  /**
+   * Type identifier for Cloudflare Queue
+   */
+  type: "queue";
+
+  /**
+   * The unique ID of the queue
+   */
+  id: string;
+
+  /**
+   * Time when the queue was created
+   */
+  createdOn: string;
+
+  /**
+   * Modified timestamp
+   */
+  modifiedOn: string;
+}
+
+interface CloudflareQueueResponse {
+  result: {
+    queue_id?: string;
+    queue_name: string;
+    created_on?: string;
+    modified_on?: string;
+    settings?: {
+      delivery_delay?: number;
+      delivery_paused?: boolean;
+      message_retention_period?: number;
+    };
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Creates and manages Cloudflare Queues.
+ *
+ * Queues provide a managed queue system for reliable message delivery
+ * between workers and other systems.
+ *
+ * @example
+ * // Create a basic queue with default settings
+ * const basicQueue = await Queue("my-app-queue", {
+ *   name: "my-app-queue"
+ * });
+ *
+ * @example
+ * // Create a queue with custom settings
+ * const customQueue = await Queue("delayed-queue", {
+ *   name: "delayed-queue",
+ *   settings: {
+ *     deliveryDelay: 30, // 30 second delay before message delivery
+ *     messageRetentionPeriod: 86400 // Store messages for 1 day
+ *   }
+ * });
+ *
+ * @example
+ * // Create a paused queue for later activation
+ * const pausedQueue = await Queue("paused-queue", {
+ *   name: "paused-queue",
+ *   settings: {
+ *     deliveryPaused: true
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/queues/
+ */
+export const Queue = Resource(
+  "cloudflare::Queue",
+  async function (
+    this: Context<Queue>,
+    id: string,
+    props: QueueProps
+  ): Promise<Queue> {
+    const api = await createCloudflareApi(props);
+    const queueName = props.name || id;
+
+    if (this.phase === "delete") {
+      console.log("Deleting Cloudflare Queue:", queueName);
+      if (props.delete !== false) {
+        // Delete Queue
+        await deleteQueue(api, this.output?.id);
+      }
+
+      // Return void (a deleted queue has no content)
+      return this.destroy();
+    } else {
+      let queueData: CloudflareQueueResponse;
+
+      if (this.phase === "create") {
+        console.log("Creating Cloudflare Queue:", queueName);
+        queueData = await createQueue(api, queueName, props);
+      } else {
+        // Update operation
+        if (this.output?.id) {
+          console.log("Updating Cloudflare Queue:", queueName);
+
+          // Check if name is being changed, which is not allowed
+          if (props.name !== this.output.name) {
+            throw new Error(
+              "Cannot update Queue name after creation. Queue name is immutable."
+            );
+          }
+
+          // Update the queue with new settings
+          queueData = await updateQueue(api, this.output.id, props);
+        } else {
+          // If no ID exists, fall back to creating a new queue
+          console.log(
+            "No existing Queue ID found, creating new Cloudflare Queue:",
+            queueName
+          );
+          queueData = await createQueue(api, queueName, props);
+        }
+      }
+
+      return this({
+        type: "queue",
+        id: queueData.result.queue_id || "",
+        name: queueName,
+        settings: queueData.result.settings
+          ? {
+              deliveryDelay: queueData.result.settings.delivery_delay,
+              deliveryPaused: queueData.result.settings.delivery_paused,
+              messageRetentionPeriod:
+                queueData.result.settings.message_retention_period,
+            }
+          : undefined,
+        createdOn: queueData.result.created_on || new Date().toISOString(),
+        modifiedOn: queueData.result.modified_on || new Date().toISOString(),
+        accountId: api.accountId,
+      });
+    }
+  }
+);
+
+/**
+ * Create a new Cloudflare Queue
+ */
+export async function createQueue(
+  api: CloudflareApi,
+  queueName: string,
+  props: QueueProps
+): Promise<CloudflareQueueResponse> {
+  // Prepare the create payload
+  const createPayload: any = {
+    queue_name: queueName,
+  };
+
+  // Add settings if provided
+  if (props.settings) {
+    createPayload.settings = {};
+
+    if (props.settings.deliveryDelay !== undefined) {
+      createPayload.settings.delivery_delay = props.settings.deliveryDelay;
+    }
+
+    if (props.settings.deliveryPaused !== undefined) {
+      createPayload.settings.delivery_paused = props.settings.deliveryPaused;
+    }
+
+    if (props.settings.messageRetentionPeriod !== undefined) {
+      createPayload.settings.message_retention_period =
+        props.settings.messageRetentionPeriod;
+    }
+  }
+
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/queues`,
+    createPayload
+  );
+
+  if (!createResponse.ok) {
+    return await handleApiError(createResponse, "creating", "Queue", queueName);
+  }
+
+  return (await createResponse.json()) as CloudflareQueueResponse;
+}
+
+/**
+ * Get a Cloudflare Queue
+ */
+export async function getQueue(
+  api: CloudflareApi,
+  queueId: string
+): Promise<CloudflareQueueResponse> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/queues/${queueId}`
+  );
+
+  if (!response.ok) {
+    return await handleApiError(response, "getting", "Queue", queueId);
+  }
+
+  return (await response.json()) as CloudflareQueueResponse;
+}
+
+/**
+ * Delete a Cloudflare Queue
+ */
+export async function deleteQueue(
+  api: CloudflareApi,
+  queueId?: string
+): Promise<void> {
+  if (!queueId) {
+    console.log("No Queue ID provided, skipping delete");
+    return;
+  }
+
+  // Delete Queue
+  const deleteResponse = await api.delete(
+    `/accounts/${api.accountId}/queues/${queueId}`
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    const errorData: any = await deleteResponse.json().catch(() => ({
+      errors: [{ message: deleteResponse.statusText }],
+    }));
+    throw new CloudflareApiError(
+      `Error deleting Cloudflare Queue '${queueId}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+      deleteResponse
+    );
+  }
+}
+
+/**
+ * Update a Cloudflare Queue
+ *
+ * Note: According to Cloudflare API, the queue name cannot be changed after creation.
+ * Only the settings can be updated.
+ */
+export async function updateQueue(
+  api: CloudflareApi,
+  queueId: string,
+  props: QueueProps
+): Promise<CloudflareQueueResponse> {
+  // Prepare the update payload - only include settings
+  const updatePayload: any = {};
+
+  // Add settings if provided
+  if (props.settings) {
+    updatePayload.settings = {};
+
+    if (props.settings.deliveryDelay !== undefined) {
+      updatePayload.settings.delivery_delay = props.settings.deliveryDelay;
+    }
+
+    if (props.settings.deliveryPaused !== undefined) {
+      updatePayload.settings.delivery_paused = props.settings.deliveryPaused;
+    }
+
+    if (props.settings.messageRetentionPeriod !== undefined) {
+      updatePayload.settings.message_retention_period =
+        props.settings.messageRetentionPeriod;
+    }
+  }
+
+  // Use PATCH for partial updates (only settings can be updated)
+  const updateResponse = await api.patch(
+    `/accounts/${api.accountId}/queues/${queueId}`,
+    updatePayload
+  );
+
+  if (!updateResponse.ok) {
+    return await handleApiError(updateResponse, "updating", "Queue", queueId);
+  }
+
+  return (await updateResponse.json()) as CloudflareQueueResponse;
+}
+
+/**
+ * List all Cloudflare Queues in an account
+ */
+export async function listQueues(
+  api: CloudflareApi
+): Promise<{ name: string; id: string }[]> {
+  const response = await api.get(`/accounts/${api.accountId}/queues`);
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list queues: ${response.statusText}`,
+      response
+    );
+  }
+
+  const data = (await response.json()) as {
+    success: boolean;
+    errors?: Array<{ code: number; message: string }>;
+    result?: Array<{
+      queue_name: string;
+      queue_id: string;
+    }>;
+  };
+
+  if (!data.success) {
+    const errorMessage = data.errors?.[0]?.message || "Unknown error";
+    throw new Error(`Failed to list queues: ${errorMessage}`);
+  }
+
+  // Transform API response
+  return (data.result || []).map((queue) => ({
+    name: queue.queue_name,
+    id: queue.queue_id,
+  }));
+}

package/src/cloudflare/worker.ts

@@ -3,27 +3,21 @@ import * as fs from "fs/promises";
 import type { Context } from "../context";
 import { Bundle, type BundleProps } from "../esbuild/bundle";
 import { Resource } from "../resource";
-import { isSecret } from "../secret";
 import { getContentType } from "../util/content-type";
 import { withExponentialBackoff } from "../util/retry";
 import { slugify } from "../util/slugify";
 import {
+  createCloudflareApi,
   type CloudflareApi,
   type CloudflareApiOptions,
-  createCloudflareApi,
 } from "./api";
-import type { Assets } from "./assets";
-import {
-  type Bindings,
-  type WorkerBindingSpec,
-  isAssets,
-  isDurableObjectNamespace,
-} from "./bindings";
+import { type Assets } from "./assets";
+import { type Bindings, type WorkerBindingSpec } from "./bindings";
 import type { Bound } from "./bound";
-import type { DurableObjectNamespace } from "./durable-object-namespace";
-import { isKVNamespace } from "./kv-namespace";
+import { type DurableObjectNamespace } from "./durable-object-namespace";
 import type { WorkerScriptMetadata } from "./worker-metadata";
 import type { SingleStepMigration } from "./worker-migration";
+import { upsertWorkflow, type Workflow } from "./workflow";
 
 /**
  * Properties for creating or updating a Worker
@@ -261,10 +255,16 @@ export const Worker = Resource(
 
     // Find any assets bindings
     const assetsBindings: { name: string; assets: Assets }[] = [];
+    const workflowsBindings: Workflow[] = [];
+
     if (props.bindings) {
       for (const [bindingName, binding] of Object.entries(props.bindings)) {
-        if (isAssets(binding)) {
-          assetsBindings.push({ name: bindingName, assets: binding });
+        if (typeof binding === "object") {
+          if (binding.type === "assets") {
+            assetsBindings.push({ name: bindingName, assets: binding });
+          } else if (binding.type === "workflow") {
+            workflowsBindings.push(binding);
+          }
         }
       }
     }
@@ -292,9 +292,16 @@ export const Worker = Resource(
       assetUploadResult
     );
 
-    // Upload the worker script
     await putWorker(api, workerName, scriptContent, scriptMetadata);
 
+    for (const workflow of workflowsBindings) {
+      await upsertWorkflow(api, {
+        workflowName: workflow.workflowName,
+        className: workflow.className,
+        scriptName: workerName,
+      });
+    }
+
     // TODO: it is less than ideal that this can fail, resulting in state problem
     await this.set("bindings", props.bindings);
 
@@ -311,8 +318,10 @@ export const Worker = Resource(
 
     // Construct the output
     return this({
+      ...props,
       type: "service",
       id,
+      entrypoint: props.entrypoint,
       name: workerName,
       script: scriptContent,
       format: props.format || "esm", // Include format in the output
@@ -513,17 +522,23 @@ async function prepareWorkerMetadata<B extends Bindings>(
   for (const [bindingName, binding] of Object.entries(bindings)) {
     // Create a copy of the binding to avoid modifying the original
 
-    if (isKVNamespace(binding)) {
+    if (typeof binding === "string") {
       meta.bindings.push({
-        type: "kv_namespace",
+        type: "plain_text",
         name: bindingName,
-        namespace_id: binding.namespaceId,
+        text: binding,
       });
-    } else if (typeof binding === "string") {
+    } else if (binding.type === "d1") {
       meta.bindings.push({
-        type: "plain_text",
+        type: "d1",
         name: bindingName,
-        text: binding,
+        id: binding.id,
+      });
+    } else if (binding.type === "kv_namespace") {
+      meta.bindings.push({
+        type: "kv_namespace",
+        name: bindingName,
+        namespace_id: binding.namespaceId,
       });
     } else if (binding.type === "service") {
       meta.bindings.push({
@@ -532,60 +547,85 @@ async function prepareWorkerMetadata<B extends Bindings>(
         service: binding.id,
       });
     } else if (binding.type === "durable_object_namespace") {
-      const stableId = binding.id;
-      const className = binding.className;
-
       meta.bindings.push({
         type: "durable_object_namespace",
         name: bindingName,
-        class_name: className,
+        class_name: binding.className,
         script_name: binding.scriptName,
         environment: binding.environment,
         namespace_id: binding.namespaceId,
       });
-
-      const oldBinding: DurableObjectNamespace | undefined = Object.values(
-        oldBindings ?? {}
-      )
-        ?.filter(isDurableObjectNamespace)
-        ?.find((b) => b.id === stableId);
-
-      if (!oldBinding) {
-        if (binding.sqlite) {
-          meta.migrations!.new_sqlite_classes!.push(className);
-        } else {
-          meta.migrations!.new_classes!.push(className);
-        }
-      } else if (oldBinding.className !== className) {
-        meta.migrations!.renamed_classes!.push({
-          from: oldBinding.className,
-          to: className,
-        });
-      }
+      configureClassMigration(binding, binding.id, binding.className);
     } else if (binding.type === "r2_bucket") {
       meta.bindings.push({
         type: "r2_bucket",
         name: bindingName,
         bucket_name: binding.name,
       });
-    } else if (isAssets(binding)) {
+    } else if (binding.type === "assets") {
       meta.bindings.push({
         type: "assets",
         name: bindingName,
       });
-    } else if (isSecret(binding)) {
+    } else if (binding.type === "secret") {
       meta.bindings.push({
         type: "secret_text",
         name: bindingName,
         text: binding.unencrypted,
       });
+    } else if (binding.type === "workflow") {
+      meta.bindings.push({
+        type: "workflow",
+        name: bindingName,
+        workflow_name: binding.workflowName,
+        class_name: binding.className,
+        // this should be set if the Workflow is in another script ...
+        // script_name: ??,
+      });
+      // it's unclear whether this is needed, but it works both ways
+      configureClassMigration(binding, binding.id, binding.className);
+    } else if (binding.type === "queue") {
+      meta.bindings.push({
+        type: "queue",
+        name: bindingName,
+        queue_name: binding.name,
+      });
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);
     }
   }
 
+  function configureClassMigration(
+    binding: DurableObjectNamespace | Workflow,
+    stableId: string,
+    className: string
+  ) {
+    const oldBinding: DurableObjectNamespace | 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);
+      } else {
+        meta.migrations!.new_classes!.push(className);
+      }
+    } else if (oldBinding.className !== className) {
+      meta.migrations!.renamed_classes!.push({
+        from: oldBinding.className,
+        to: className,
+      });
+    }
+  }
+
   // Convert env variables to plain_text bindings
+  // TODO(sam): remove Worker.env in favor of always bindings
   if (props.env) {
     for (const [key, value] of Object.entries(props.env)) {
       meta.bindings.push({

package/src/cloudflare/workflow.ts

@@ -0,0 +1,79 @@
+import type { CloudflareApi } from "./api";
+import { handleApiError } from "./api-error";
+
+export interface WorkflowProps {
+  /**
+   * Name of the workflow
+   *
+   * @maxLength 64
+   * @minLength 1
+   * @default - className if provided, otherwise id
+   */
+  workflowName?: string;
+  /**
+   * Name of the class that implements the workflow
+   *
+   * @maxLength 255
+   * @minLength 1
+   * @default - workflowName if provided, otherwise id
+   */
+  className?: string;
+}
+
+export class Workflow<PARAMS = unknown> {
+  public readonly type: "workflow" = "workflow";
+  /**
+   * Phantom property to preserve workflow params at the type level.
+   *
+   * No value exists.
+   */
+  public readonly _PARAMS: PARAMS = undefined!;
+
+  public readonly workflowName: string;
+  public readonly className: string;
+
+  constructor(
+    public readonly id: string,
+    props: WorkflowProps = {}
+  ) {
+    this.workflowName = props.workflowName ?? props.className ?? id;
+    this.className = props.className ?? this.workflowName;
+  }
+}
+
+export interface WorkflowMetadata {
+  id: string; // uuid
+  class_name: string;
+  created_on: string; // date-time
+  modified_on: string; // date-time
+  name: string; // maxLength: 64, minLength: 1
+  script_name: string;
+  triggered_on: string; // date-time
+  version_id: string; // uuid
+}
+
+export async function upsertWorkflow(
+  api: CloudflareApi,
+  props: WorkflowProps & {
+    workflowName: string;
+    scriptName: string;
+  }
+) {
+  const response = await api.put(
+    `/accounts/${api.accountId}/workflows/${props.workflowName}`,
+    {
+      class_name: props.className,
+      script_name: props.scriptName,
+    }
+  );
+
+  if (!response.ok) {
+    await handleApiError(response, "create", "workflow", props.workflowName);
+  }
+
+  const body = (await response.json()) as {
+    result: WorkflowMetadata;
+  };
+
+  return body.result;
+}