alchemy 2.0.0-beta.60 → 2.0.0-beta.62

package/src/Cloudflare/Workflows/Workflow.ts

@@ -2,9 +2,9 @@ import * as workflows from "@distilled.cloud/cloudflare/workflows";
 import type { ConfigError } from "effect/Config";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import type { Scope } from "effect/Scope";
 import * as Stream from "effect/Stream";
 import { AlchemyContext } from "../../AlchemyContext.ts";
-import { ExecutionContext } from "../../ExecutionContext.ts";
 import type { Input } from "../../Input.ts";
 import { ALCHEMY_PHASE } from "../../Phase.ts";
 import type { PlatformServices } from "../../Platform.ts";
@@ -18,6 +18,7 @@ import {
   WorkerEnvironment,
   type WorkerServices,
 } from "../Workers/Worker.ts";
+import { makeWorkflowName } from "./WorkflowName.ts";
 
 type TypeId = "Cloudflare.Workflow";
 const TypeId = "Cloudflare.Workflow" as const;
@@ -36,19 +37,119 @@ export class WorkflowEvent extends Context.Service<
     payload: unknown;
     timestamp: Date;
     instanceId: string;
+    workflowName: string;
+    schedule?: WorkflowCronSchedule;
   }
 >()("Cloudflare.Workflows.WorkflowEvent") {}
 
+export interface WorkflowCronSchedule {
+  cron: string;
+  scheduledTime: number;
+}
+
+export type WorkflowBackoff = "constant" | "linear" | "exponential";
+
+export interface WorkflowStepConfig {
+  retries?: {
+    limit: number;
+    delay: string | number;
+    backoff?: WorkflowBackoff;
+  };
+  timeout?: string | number;
+}
+
+export interface WorkflowStepContextData {
+  step: {
+    name: string;
+    count: number;
+  };
+  attempt: number;
+  config: WorkflowStepConfig;
+}
+
+/**
+ * Runtime information for the current `task` attempt.
+ */
+export class WorkflowStepContext extends Context.Service<
+  WorkflowStepContext,
+  WorkflowStepContextData
+>()("Cloudflare.WorkflowStepContext") {}
+
+export interface WorkflowRollbackContext<Output = unknown> {
+  error: Error;
+  output: Output | undefined;
+}
+
+export interface WorkflowRollbackOptions<Output = unknown, R = never> {
+  rollback: (
+    context: WorkflowRollbackContext<Output>,
+  ) => Effect.Effect<void, never, R>;
+  rollbackConfig?: WorkflowStepConfig;
+}
+
+/**
+ * Optional configuration for a `task` step: retry policy, timeout, and a
+ * rollback handler with its own retry config.
+ */
+export interface WorkflowTaskConfig<
+  Output = unknown,
+  RollbackReq = never,
+> extends WorkflowStepConfig {
+  rollback?: (
+    context: WorkflowRollbackContext<Output>,
+  ) => Effect.Effect<void, never, RollbackReq>;
+  rollbackConfig?: WorkflowStepConfig;
+}
+
+/**
+ * Internal step descriptor passed from `task` to the bridge. Bundles the step
+ * name and Effect together with the `WorkflowTaskConfig` fields.
+ */
+export interface WorkflowTaskOptions<
+  Output = unknown,
+  R = never,
+  RollbackReq = never,
+> extends WorkflowTaskConfig<Output, RollbackReq> {
+  name: string;
+  effect: Effect.Effect<Output, never, R>;
+}
+
+export interface WorkflowWaitForEventOptions {
+  type: string;
+  timeout?: string | number;
+}
+
+/**
+ * The event delivered to a `waitForEvent` step. Mirrors the native
+ * `WorkflowStepEvent` shape from `cloudflare:workers` 1:1.
+ */
+export interface WorkflowStepEvent<Payload = unknown> {
+  payload: Payload;
+  timestamp: Date;
+  type: string;
+}
+
+type ExcludeWorkflowStepContext<R> = R extends {
+  readonly key: "Cloudflare.WorkflowStepContext";
+}
+  ? never
+  : R;
+
 /**
  * Internal service that wraps the Cloudflare `WorkflowStep` object.
- * Not accessed directly by users -- use `task`, `sleep`, `sleepUntil` instead.
+ * Not accessed directly by users -- use `task`, `sleep`, `sleepUntil`, and
+ * `waitForEvent` instead.
  */
 export class WorkflowStep extends Context.Service<
   WorkflowStep,
   {
-    do<T>(name: string, effect: Effect.Effect<T>): Effect.Effect<T>;
+    do<T>(options: WorkflowTaskOptions<T, any, any>): Effect.Effect<T>;
     sleep(name: string, duration: string | number): Effect.Effect<void>;
     sleepUntil(name: string, timestamp: Date | number): Effect.Effect<void>;
+    waitForEvent<T>(
+      name: string,
+      options: WorkflowWaitForEventOptions,
+    ): Effect.Effect<WorkflowStepEvent<T>>;
   }
 >()("Cloudflare.Workflows.WorkflowStep") {}
 
@@ -65,16 +166,35 @@ export class WorkflowStep extends Context.Service<
  * binding like `kv.put` / `kv.get`) are threaded through automatically by
  * capturing the surrounding workflow body's context and providing it to
  * the inner effect before it runs inside `step.do`.
+ *
+ * The step name comes first, followed by the Effect. Retry config, timeout,
+ * and a rollback handler can be passed in the optional third `options` arg.
  */
-export const task = <T, R = never>(
+export function task<T, R = never, RollbackReq = never>(
   name: string,
   effect: Effect.Effect<T, never, R>,
-): Effect.Effect<T, never, WorkflowStep | R> =>
-  Effect.gen(function* () {
+  options?: WorkflowTaskConfig<T, RollbackReq>,
+): Effect.Effect<
+  T,
+  never,
+  WorkflowStep | ExcludeWorkflowStepContext<R | RollbackReq>
+> {
+  return Effect.gen(function* () {
     const step = yield* WorkflowStep;
-    const context = yield* Effect.context<R>();
-    return yield* step.do(name, effect.pipe(Effect.provide(context)));
+    const context =
+      yield* Effect.context<ExcludeWorkflowStepContext<R | RollbackReq>>();
+    const rollbackEffect = options?.rollback;
+    return yield* step.do({
+      ...options,
+      name,
+      effect: effect.pipe(Effect.provide(context)),
+      rollback: rollbackEffect
+        ? (rollbackContext: WorkflowRollbackContext<T>) =>
+            rollbackEffect(rollbackContext).pipe(Effect.provide(context))
+        : undefined,
+    } as WorkflowTaskOptions<T, any, any>);
   });
+}
 
 /**
  * Pause the workflow for the given duration.
@@ -83,10 +203,10 @@ export const sleep = (
   name: string,
   duration: string | number,
 ): Effect.Effect<void, never, WorkflowStep> =>
-  WorkflowStep.pipe(
-    Effect.flatMap((step) => step.sleep(name, duration)),
-    Effect.orDie,
-  );
+  Effect.gen(function* () {
+    const step = yield* WorkflowStep;
+    yield* step.sleep(name, duration);
+  }).pipe(Effect.orDie);
 
 /**
  * Pause the workflow until the given timestamp.
@@ -95,10 +215,25 @@ export const sleepUntil = (
   name: string,
   timestamp: Date | number,
 ): Effect.Effect<void, never, WorkflowStep> =>
-  WorkflowStep.pipe(
-    Effect.flatMap((step) => step.sleepUntil(name, timestamp)),
-    Effect.orDie,
-  );
+  Effect.gen(function* () {
+    const step = yield* WorkflowStep;
+    yield* step.sleepUntil(name, timestamp);
+  }).pipe(Effect.orDie);
+
+/**
+ * Pause the workflow until an external event is delivered with
+ * `WorkflowInstance.sendEvent`. Resolves with the full
+ * {@link WorkflowStepEvent} (`{ payload, timestamp, type }`), exactly like
+ * the native `step.waitForEvent`.
+ */
+export const waitForEvent = <T = unknown>(
+  name: string,
+  options: WorkflowWaitForEventOptions,
+): Effect.Effect<WorkflowStepEvent<T>, never, WorkflowStep> =>
+  Effect.gen(function* () {
+    const step = yield* WorkflowStep;
+    return yield* step.waitForEvent<T>(name, options);
+  }).pipe(Effect.orDie);
 
 /**
  * The services available inside a workflow run body.
@@ -109,17 +244,17 @@ export const sleepUntil = (
  * reflect that or `yield* WorkerEnvironment` fails to type-check inside a
  * body even though it succeeds at runtime.
  *
- * `ExecutionContext` (scope + cache) is provided per run-invocation by
- * `WorkflowBridge.run` and threaded into every `task` via the surrounding
- * body context, so `@binding` helpers that need it (e.g. `Drizzle.postgres`)
- * resolve their per-run resources inside workflow steps just as they do in a
- * Worker `fetch`/`queue` handler.
+ * A fresh `Scope` is provided per run-invocation by `WorkflowBridge.run` and
+ * threaded into every `task` via the surrounding body context, so `@binding`
+ * helpers that acquire per-run resources against the ambient scope (e.g.
+ * `Drizzle.postgres`) resolve them inside workflow steps just as they do in
+ * a Worker `fetch`/`queue` handler.
  */
 export type WorkflowRunServices =
   | WorkflowEvent
   | WorkflowStep
   | WorkerServices
-  | ExecutionContext;
+  | Scope;
 
 export type WorkflowServices =
   | WorkflowRunServices
@@ -216,22 +351,75 @@ export const isWorkflowBinding = (binding: {
 export interface WorkflowHandle<Input = unknown, Result = unknown> {
   Type: TypeId;
   name: string;
-  create(input: Input): Effect.Effect<WorkflowInstance<Result>>;
+  /**
+   * Start a workflow instance. Pass payload through `params`; omit `id` to let
+   * Cloudflare generate an instance ID.
+   */
+  create(
+    options?: WorkflowInstanceCreateOptions<Input>,
+  ): Effect.Effect<WorkflowInstance<Result>>;
+  createBatch(
+    batch: WorkflowInstanceCreateOptions<Input>[],
+  ): Effect.Effect<WorkflowInstance<Result>[]>;
   get(instanceId: string): Effect.Effect<WorkflowInstance<Result>>;
 }
 
+/** Options for starting a workflow instance. */
+export interface WorkflowInstanceCreateOptions<Input = unknown> {
+  id?: string;
+  params?: Input;
+  retention?: WorkflowInstanceRetention;
+}
+
+export interface WorkflowInstanceRetention {
+  successRetention?: string | number;
+  errorRetention?: string | number;
+}
+
+/** Handle for a single Cloudflare workflow instance. */
 export interface WorkflowInstance<Result = unknown> {
   id: string;
   status(): Effect.Effect<WorkflowInstanceStatus<Result>>;
   pause(): Effect.Effect<void>;
   resume(): Effect.Effect<void>;
+  restart(options?: WorkflowInstanceRestartOptions): Effect.Effect<void>;
   terminate(): Effect.Effect<void>;
+  sendEvent<Event = unknown>(
+    event: WorkflowInstanceEvent<Event>,
+  ): Effect.Effect<void>;
+}
+
+export interface WorkflowInstanceRestartOptions {
+  from?: {
+    name: string;
+    count?: number;
+    type?: "do" | "sleep" | "waitForEvent";
+  };
+}
+
+export interface WorkflowInstanceEvent<Payload = unknown> {
+  type: string;
+  payload?: Payload;
 }
 
 export interface WorkflowInstanceStatus<Result = unknown> {
-  status: string;
+  status:
+    | "queued"
+    | "running"
+    | "paused"
+    | "errored"
+    | "terminated"
+    | "complete"
+    | "waiting"
+    | "waitingForPause"
+    | "unknown"
+    | (string & {});
   output?: Result;
   error?: { name: string; message: string } | null;
+  rollback?: {
+    outcome: "complete" | "failed";
+    error: { name: string; message: string } | null;
+  } | null;
 }
 
 export interface WorkflowClass extends Effect.Effect<
@@ -278,7 +466,8 @@ export class WorkflowScope extends Context.Service<
  * Objects. The outer `Effect.gen` resolves shared dependencies. The inner
  * `Effect.fn` is the workflow body — a function from a typed `input`
  * payload to an Effect that runs steps using `task`, `sleep`, and
- * `sleepUntil`.
+ * `sleepUntil`. `task` takes the step name and Effect, plus an optional
+ * config object for retries, timeout, and a rollback handler.
  *
  * ```typescript
  * Effect.gen(function* () {
@@ -320,11 +509,42 @@ export class WorkflowScope extends Context.Service<
  * );
  * ```
  *
+ * @example Configuring retries and reading step context
+ * ```typescript
+ * const result = yield* Cloudflare.Workflows.task(
+ *   "call-api",
+ *   Effect.gen(function* () {
+ *     const context = yield* Cloudflare.Workflows.WorkflowStepContext;
+ *     return { attempt: context.attempt };
+ *   }),
+ *   { retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
+ * );
+ * ```
+ *
+ * @example Registering rollback
+ * ```typescript
+ * yield* Cloudflare.Workflows.task("reserve-inventory", reserveInventory, {
+ *   rollback: ({ output }) =>
+ *     output ? releaseInventory(output.reservationId) : Effect.void,
+ *   rollbackConfig: { retries: { limit: 3, delay: "10 seconds" } },
+ * });
+ * ```
+ *
  * @example Sleeping between steps
  * ```typescript
  * yield* Cloudflare.Workflows.sleep("cooldown", "30 seconds");
  * ```
  *
+ * @example Waiting for an external event
+ * ```typescript
+ * const event = yield* Cloudflare.Workflows.waitForEvent<{ approved: boolean }>(
+ *   "approval",
+ *   { type: "approval", timeout: "1 day" },
+ * );
+ * // Same shape as the native step.waitForEvent result:
+ * event.payload.approved;
+ * ```
+ *
  * @example Accessing env bindings inside a task
  * Bind a resource (e.g. `Namespace`, `Bucket`) in the workflow's
  * outer init phase to get a typed Effect-native client, then use it
@@ -354,10 +574,31 @@ export class WorkflowScope extends Context.Service<
  * ```
  *
  * @section Starting and Monitoring Instances
+ * `create` mirrors Cloudflare's native Workflow API: pass workflow input in
+ * `params`, pass `id` only when you need a deterministic instance ID, and omit
+ * `id` to let Cloudflare generate one.
+ *
  * @example Creating an instance from a Worker
  * ```typescript
  * const workflow = yield* MyWorkflow;
- * const instance = yield* workflow.create({ orderId: "abc" });
+ * const instance = yield* workflow.create({ params: { orderId: "abc" } });
+ * ```
+ *
+ * @example Creating an instance with id and retention
+ * ```typescript
+ * const instance = yield* workflow.create({
+ *   id: "order-abc",
+ *   params: { orderId: "abc" },
+ *   retention: { successRetention: "1 day", errorRetention: "7 days" },
+ * });
+ * ```
+ *
+ * @example Creating a batch
+ * ```typescript
+ * const instances = yield* workflow.createBatch([
+ *   { id: "order-a", params: { orderId: "a" } },
+ *   { id: "order-b", params: { orderId: "b" } },
+ * ]);
  * ```
  *
  * @example Checking instance status
@@ -367,6 +608,13 @@ export class WorkflowScope extends Context.Service<
  * const status = yield* handle.status();
  * ```
  *
+ * @example Sending events and restarting instances
+ * ```typescript
+ * const instance = yield* workflow.get(instanceId);
+ * yield* instance.sendEvent({ type: "approval", payload: { approved: true } });
+ * yield* instance.restart({ from: { name: "approval", type: "waitForEvent" } });
+ * ```
+ *
  * @section Triggering from a Worker
  * Wire the workflow into HTTP routes so callers can fire instances
  * and poll for completion.
@@ -382,7 +630,7 @@ export class WorkflowScope extends Context.Service<
  *
  *     if (request.url.startsWith("/workflow/start/")) {
  *       const id = request.url.split("/").pop()!;
- *       const instance = yield* notifier.create({ id });
+ *       const instance = yield* notifier.create({ params: { orderId: id } });
  *       return HttpServerResponse.json({ instanceId: instance.id });
  *     }
  *
@@ -462,9 +710,8 @@ export class WorkflowScope extends Context.Service<
  * ```
  *
  * @section Testing Workflows
- * Workflows run asynchronously, so tests start an instance and
- * poll until it reaches a terminal status. A simple recipe with
- * `alchemy/Test/Bun`:
+ * Workflows run asynchronously, so tests start an instance and poll until it
+ * reaches a terminal status. Keep polling bounded with `Effect.repeat`.
  *
  * @example Polling for workflow completion
  * ```typescript
@@ -476,20 +723,20 @@ export class WorkflowScope extends Context.Service<
  *     const start = yield* HttpClient.post(`${url}/workflow/start/x`);
  *     const { instanceId } = (yield* start.json) as { instanceId: string };
  *
- *     let status: { status: string } | undefined;
- *     const deadline = Date.now() + 60_000;
- *     while (Date.now() < deadline) {
- *       const res = yield* HttpClient.get(
- *         `${url}/workflow/status/${instanceId}`,
- *       );
- *       status = (yield* res.json) as { status: string };
- *       if (status.status === "complete" || status.status === "errored") {
- *         break;
- *       }
- *       yield* Effect.sleep("2 seconds");
- *     }
+ *     const status = yield* HttpClient.get(
+ *       `${url}/workflow/status/${instanceId}`,
+ *     ).pipe(
+ *       Effect.flatMap((res) => res.json),
+ *       Effect.map((json) => json as { status: string }),
+ *       Effect.repeat({
+ *         schedule: Schedule.spaced("2 seconds"),
+ *         until: (status) =>
+ *           status.status === "complete" || status.status === "errored",
+ *         times: 30,
+ *       }),
+ *     );
  *
- *     expect(status?.status).toBe("complete");
+ *     expect(status.status).toBe("complete");
  *   }),
  *   { timeout: 120_000 },
  * );
@@ -513,7 +760,6 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
     return {
       kind: TypeId,
       name,
-      workflowName: name,
       className: props?.className ?? name,
       scriptName: props?.scriptName,
     } satisfies WorkflowLike;
@@ -523,25 +769,27 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
     Effect.gen(function* () {
       const worker = yield* Worker;
 
+      // Workflow names are account-global, so derive the physical name from
+      // the already-unique host Worker name and exported class name.
+      const workflowName = makeWorkflowName(worker.workerName, name);
+      const workflow = yield* WorkflowResource(name, {
+        workflowName,
+        className: name,
+        scriptName: worker.workerName,
+      });
+
       // Add the workflow binding to the Worker metadata
       yield* worker.bind`${name}`({
         bindings: [
           {
             type: "workflow",
             name,
-            workflowName: name,
+            workflowName: workflow.workflowName,
             className: name,
           },
         ],
       });
 
-      // Create the Workflow API resource (putWorkflow / deleteWorkflow)
-      yield* WorkflowResource(name, {
-        workflowName: name,
-        className: name,
-        scriptName: worker.workerName,
-      });
-
       const services = yield* Effect.context<Effect.Services<typeof impl>>();
 
       const binding = yield* Effect.all([
@@ -563,11 +811,18 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
       const self: WorkflowHandle<any, any> = {
         Type: TypeId,
         name,
-        create: (input: unknown) =>
-          Effect.tryPromise(() => binding.create({ params: input })).pipe(
+        create: (options?: WorkflowInstanceCreateOptions<any>) =>
+          Effect.tryPromise(() => binding.create(options)).pipe(
             Effect.map(wrapInstance),
             Effect.orDie,
           ),
+        createBatch: (batch: WorkflowInstanceCreateOptions<any>[]) =>
+          Effect.tryPromise(
+            () => binding.createBatch(batch) as Promise<any[]>,
+          ).pipe(
+            Effect.map((instances: any[]) => instances.map(wrapInstance)),
+            Effect.orDie,
+          ),
         get: (instanceId: string) =>
           Effect.tryPromise(() => binding.get(instanceId)).pipe(
             Effect.map(wrapInstance),
@@ -601,6 +856,9 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
 // ---------------------------------------------------------------------------
 
 export interface WorkflowResourceProps {
+  /**
+   * Account-global Workflow name.
+   */
   workflowName: string;
   className: string;
   scriptName: string;
@@ -634,7 +892,7 @@ export const WorkflowProvider = () =>
 
       return WorkflowResource.Provider.of({
         // The `workflowId` is no longer marked as stable because if you start in dev mode, the ID will change on first deploy.
-        stables: ["accountId"],
+        stables: ["accountId", "workflowName"],
         // Workflows are account-scoped. Enumerate every workflow in the account
         // via the paginated list API and hydrate each into the same Attributes
         // shape `reconcile` returns (id/name/className/scriptName are all on the
@@ -665,17 +923,46 @@ export const WorkflowProvider = () =>
             return { action: "update" };
           }
         }),
+        read: Effect.fn(function* ({ output, olds }) {
+          // Dev workflows only exist in local state; there is no account-level
+          // Workflow API resource to observe until the first real deploy.
+          if (ctx.dev) return output;
+
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          const workflowName = output?.workflowName ?? olds?.workflowName;
+          if (workflowName === undefined) return undefined;
+
+          const acct = output?.accountId ?? accountId;
+          return yield* workflows
+            .getWorkflow({
+              accountId: acct,
+              workflowName,
+            })
+            .pipe(
+              Effect.map((workflow) => ({
+                workflowId: workflow.id,
+                workflowName: workflow.name,
+                className: workflow.className,
+                scriptName: workflow.scriptName,
+                accountId: acct,
+              })),
+              Effect.catchTag("WorkflowNotFound", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+        }),
         reconcile: Effect.fn(function* ({ news, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
           const acct = output?.accountId ?? accountId;
+          const workflowName = news.workflowName;
           yield* Effect.logInfo(
-            `Cloudflare Workflow reconcile: ${news.workflowName}`,
+            `Cloudflare Workflow reconcile: ${workflowName}`,
           );
           if (ctx.dev) {
             return {
               workflowId: output?.workflowId ?? `dev:${crypto.randomUUID()}`,
               accountId,
-              workflowName: news.workflowName,
+              workflowName,
               className: news.className,
               scriptName: news.scriptName,
             };
@@ -686,7 +973,7 @@ export const WorkflowProvider = () =>
           // — the API is naturally reconciler-shaped.
           const result = yield* workflows.putWorkflow({
             accountId: acct,
-            workflowName: news.workflowName,
+            workflowName,
             className: news.className,
             scriptName: news.scriptName,
           });
@@ -725,10 +1012,15 @@ const wrapInstance = <Result>(raw: any): WorkflowInstance<Result> => ({
         status: s.status as string,
         output: s.output as Result,
         error: s.error,
+        rollback: s.rollback,
       })),
       Effect.orDie,
     ),
   pause: () => Effect.tryPromise(() => raw.pause()).pipe(Effect.orDie),
   resume: () => Effect.tryPromise(() => raw.resume()).pipe(Effect.orDie),
+  restart: (options?: WorkflowInstanceRestartOptions) =>
+    Effect.tryPromise(() => raw.restart(options)).pipe(Effect.orDie),
   terminate: () => Effect.tryPromise(() => raw.terminate()).pipe(Effect.orDie),
+  sendEvent: <Event = unknown>(event: WorkflowInstanceEvent<Event>) =>
+    Effect.tryPromise(() => raw.sendEvent(event)).pipe(Effect.orDie),
 });