sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workflows/ NativeEngine.ts

import {
  CurrentActivity,
  decodeExit,
  decodeResult,
  encodeExit,
  encodeResult,
  makeCurrentActivity,
  payloadCodec,
} from "alchemy/WorkflowEncoding";
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Schema from "effect/Schema";
import { Activity, Workflow as EffectWorkflow, WorkflowEngine } from "effect/workflow";
import type { Worker } from "../Workers/Worker.ts";
import { Workflow, type WorkflowHandle } from "./Workflow.ts";
import { WorkflowStep } from "./WorkflowRuntime.ts";

/** What each Cloudflare Workflow instance runs: one execution of one Effect workflow. */
interface Invocation {
  readonly workflow: string;
  readonly executionId: string;
  readonly payload: unknown;
}

type Execute = (
  payload: object,
  executionId: string,
) => Effect.Effect<
  unknown,
  unknown,
  WorkflowEngine.WorkflowInstance | WorkflowEngine.WorkflowEngine
>;

/** The run in progress: its step context, and the clocks it has scheduled. */
class CurrentRun extends Context.Service<
  CurrentRun,
  {
    readonly step: WorkflowStep["Service"];
    readonly context: Context.Context<never>;
    readonly clocks: Map<string, Duration.Duration>;
    readonly instance: WorkflowEngine.WorkflowInstance["Service"];
  }
>()("alchemy/Cloudflare/Workflows/NativeEngine/CurrentRun") {}

const currentRun = (operation: string) =>
  Effect.flatMap(Effect.serviceOption(CurrentRun), (run) =>
    Option.isSome(run)
      ? Effect.succeed(run.value)
      : Effect.die(new Error(`NativeEngine: ${operation} only runs inside a workflow run`)),
  );

/**
 * A name Cloudflare accepts for an instance id or event type: up to 100
 * letters, digits, `-` and `_`.
 */
const nameOf = (...parts: ReadonlyArray<string>) => {
  const name = parts.join("-").replace(/[^A-Za-z0-9_-]/g, "_");
  if (name.length <= 100) return name;
  let hash = 2166136261;
  for (const char of name) hash = Math.imul(hash ^ char.charCodeAt(0), 16777619) >>> 0;
  return `${name.slice(0, 91)}-${hash.toString(16).padStart(8, "0")}`;
};

/** Every wait for a signal also waits for this event, which interrupts the run. */
const INTERRUPT = "alchemy-interrupt";

/** A run suspended on a failure waits for this event, which resumes it. */
const RESUME = "alchemy-resume";

/** A defect the workflow doesn't capture, failing its activity's step so Cloudflare retries it. */
interface ActivityDefect {
  readonly _tag: "ActivityDefect";
  readonly message: string;
}

/** What an activity's step records when the activity suspends on a failure. */
const SUSPENDED = "alchemy-suspended";

/** How long a run waits for a signal; Cloudflare's limit for `waitForEvent`. */
const SIGNAL_TIMEOUT = "365 days";

/**
 * Retry a Workflows binding call while the Workflow class is still
 * propagating after a deploy, which Cloudflare reports as "Worker not found",
 * for about a minute.
 */
const inTransit = <A>(call: Effect.Effect<A>): Effect.Effect<A> =>
  call.pipe(
    Effect.catchDefect((defect) =>
      String(defect).includes("Worker not found") ? Effect.fail(defect) : Effect.die(defect),
    ),
    Effect.retry({
      schedule: Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("2 seconds")]),
      times: 35,
    }),
    Effect.orDie,
  ) as Effect.Effect<A>;

/**
 * Send an event to an instance, retrying any failure for about a minute: a run
 * takes each signal and interrupt at most once, so sending one again is safe.
 * A finished instance takes no more events, and needs none.
 */
const sendEvent = (
  handle: WorkflowHandle,
  id: string,
  event: { type: string; payload?: unknown },
) =>
  handle.get(id).pipe(
    Effect.flatMap((instance) => instance.sendEvent(event)),
    Effect.catchDefect((defect) => Effect.fail(defect)),
    Effect.catch((error) =>
      Effect.flatMap(statusOf(handle, id), (status) =>
        status?.status === "complete" ||
        status?.status === "errored" ||
        status?.status === "terminated"
          ? Effect.void
          : Effect.fail(error),
      ),
    ),
    Effect.retry({
      schedule: Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("2 seconds")]),
      times: 35,
    }),
    Effect.orDie,
  ) as Effect.Effect<void>;

/** An instance's status, or undefined if there's no such instance. */
const statusOf = (handle: WorkflowHandle, id: string) =>
  inTransit(handle.get(id).pipe(Effect.flatMap((instance) => instance.status()))).pipe(
    Effect.exit,
    Effect.map((exit) => (Exit.isSuccess(exit) ? exit.value : undefined)),
  );

/** An instance's result, or undefined while it runs. */
const resultOf = (
  handle: WorkflowHandle,
  workflow: EffectWorkflow.AnyWithProps,
  id: string,
): Effect.Effect<EffectWorkflow.Complete<unknown, unknown> | undefined | null> =>
  Effect.gen(function* () {
    const status = yield* statusOf(handle, id);
    if (status === undefined) return null;
    switch (status.status) {
      case "complete":
        return yield* decodeResult(workflow, status.output as string);
      case "terminated":
        return new EffectWorkflow.Complete({ exit: Exit.interrupt() });
      case "errored":
        return new EffectWorkflow.Complete({
          exit: Exit.die(new Error(status.error?.message ?? `Workflow instance ${id} errored`)),
        });
      default:
        return undefined;
    }
  });

/**
 * Run Effect workflows on Cloudflare Workflows. One Cloudflare Workflow class,
 * `NativeEngine`, runs every workflow the Worker implements; each execution is
 * one instance, named after the workflow and its execution id.
 *
 * Steps run with `step.do`, so a finished step is replayed rather than run
 * again. `DurableClock.sleep` is `step.sleep`, and `DurableDeferred.await`
 * waits for an event that a run's `signal` sends.
 *
 * ### Running workflows on Cloudflare Workflows
 * **Example:** Provide the engine to a Worker
 * ```typescript
 * import * as Cloudflare from "@alchemy.run/cloudflare";
 * import * as Workflows from "alchemy/Workflows";
 * import * as Effect from "effect/Effect";
 * import * as Layer from "effect/Layer";
 * import * as HttpServerResponse from "effect/http/HttpServerResponse";
 *
 * export default class AppWorker extends Cloudflare.Worker<AppWorker>()(
 *   "AppWorker",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const welcome = yield* Workflows.RunWorkflow(SendWelcome);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const run = yield* welcome.start({ userId: "u-1" });
 *         return HttpServerResponse.text(run.executionId);
 *       }),
 *     };
 *   }).pipe(
 *     Effect.provide(SendWelcomeLive.pipe(Layer.provideMerge(Cloudflare.Workflows.NativeEngine))),
 *   ),
 * ) {}
 * ```
 *
 * @layer
 * @provides WorkflowEngine
 * @product Workflows
 */
export const NativeEngine: Layer.Layer<WorkflowEngine.WorkflowEngine, never, Worker> = Layer.effect(
  WorkflowEngine.WorkflowEngine,
  Effect.gen(function* () {
    const handlers = new Map<
      string,
      { readonly workflow: EffectWorkflow.AnyWithProps; readonly execute: Execute }
    >();
    let engine: WorkflowEngine.WorkflowEngine["Service"];

    const handle = yield* Workflow(
      "NativeEngine",
      Effect.succeed((invocation: Invocation) =>
        Effect.gen(function* () {
          const registration = handlers.get(invocation.workflow);
          if (!registration) {
            return yield* Effect.die(
              new Error(`Workflow ${invocation.workflow} is not hosted here`),
            );
          }
          const step = yield* WorkflowStep;
          const context = yield* Effect.context<never>();
          const { workflow, execute } = registration;
          const payload = yield* Schema.decodeEffect(payloadCodec(workflow))(
            invocation.payload,
          ).pipe(Effect.orDie);
          const instance = WorkflowEngine.WorkflowInstance.initial(
            workflow,
            invocation.executionId,
          );
          const result = yield* execute(payload as object, invocation.executionId).pipe(
            EffectWorkflow.intoResult,
            Effect.provide(
              Layer.mergeAll(
                Layer.succeed(WorkflowEngine.WorkflowInstance, instance),
                Layer.succeed(WorkflowEngine.WorkflowEngine, engine),
                Layer.succeed(CurrentRun, { step, context, clocks: new Map(), instance }),
              ),
            ),
          );
          // Every wait blocks inside the instance, so a run always finishes.
          if (result._tag === "Suspended") {
            return yield* Effect.die(new Error(`Workflow ${workflow._tag} suspended unexpectedly`));
          }
          return yield* encodeResult(workflow, result.exit);
        }),
      ),
    ) as Effect.Effect<WorkflowHandle, never, Worker>;

    engine = WorkflowEngine.makeUnsafe({
      register: (workflow, execute) =>
        Effect.sync(
          () =>
            void handlers.set(workflow._tag, {
              workflow: workflow as EffectWorkflow.AnyWithProps,
              execute,
            }),
        ),

      execute: (workflow, opts) =>
        Effect.gen(function* () {
          const id = nameOf(workflow._tag, opts.executionId);
          const payload = yield* Schema.encodeEffect(
            payloadCodec(workflow as EffectWorkflow.AnyWithProps),
          )(opts.payload).pipe(Effect.orDie);
          // The same key always names the same run: create it only once.
          if ((yield* statusOf(handle, id)) === undefined) {
            yield* inTransit(
              handle.create({
                id,
                params: { workflow: workflow._tag, executionId: opts.executionId, payload },
              }),
            ).pipe(
              Effect.exit,
              Effect.flatMap((exit) =>
                Exit.isSuccess(exit)
                  ? Effect.void
                  : Effect.flatMap(statusOf(handle, id), (status) =>
                      status === undefined ? Effect.failCause(exit.cause) : Effect.void,
                    ),
              ),
            );
          }
          if (opts.discard) return undefined;
          const run = yield* Effect.serviceOption(CurrentRun);
          if (Option.isNone(run)) {
            const result = yield* resultOf(handle, workflow as EffectWorkflow.AnyWithProps, id);
            return result ?? EffectWorkflow.Suspended.make({});
          }
          // A child workflow: wait for it here, sleeping between checks.
          for (let check = 0; ; check++) {
            const text = yield* run.value.step.do({
              name: `child/${id}/${check}`,
              effect: resultOf(handle, workflow as EffectWorkflow.AnyWithProps, id).pipe(
                Effect.flatMap((result) =>
                  result
                    ? encodeResult(workflow as EffectWorkflow.AnyWithProps, result.exit)
                    : Effect.succeed(""),
                ),
              ),
            });
            if (text !== "") {
              return yield* decodeResult(workflow as EffectWorkflow.AnyWithProps, text);
            }
            yield* run.value.step.sleep(`child-wait/${id}/${check}`, "5 seconds");
          }
        }) as Effect.Effect<any>,

      poll: (workflow, executionId) =>
        Effect.map(
          resultOf(
            handle,
            workflow as EffectWorkflow.AnyWithProps,
            nameOf(workflow._tag, executionId),
          ),
          (result) =>
            result === null
              ? Option.none()
              : Option.some(result ?? EffectWorkflow.Suspended.make({})),
        ),

      // The run wakes from whatever it waits for, fails there, and runs
      // its compensations.
      interrupt: (workflow, executionId) =>
        sendEvent(handle, nameOf(workflow._tag, executionId), { type: INTERRUPT }),

      interruptUnsafe: (workflow, executionId) =>
        inTransit(
          handle
            .get(nameOf(workflow._tag, executionId))
            .pipe(Effect.flatMap((instance) => instance.terminate())),
        ),

      // Only a run suspended on a failure waits to be resumed.
      resume: (workflow, executionId) =>
        sendEvent(handle, nameOf(workflow._tag, executionId), { type: RESUME }),

      activityExecute: (activity, attempt) =>
        Effect.gen(function* () {
          const run = yield* currentRun("activity execution");
          const instance = yield* WorkflowEngine.WorkflowInstance;
          const activityInstance = WorkflowEngine.WorkflowInstance.initial(
            instance.workflow,
            instance.executionId,
          );
          activityInstance.interrupted = instance.interrupted;
          // The step's exit, failure or not, is its result. A defect the
          // workflow doesn't capture fails the step instead, so Cloudflare
          // retries it, and is a defect again once retries run out. An
          // activity that suspends on a failure records that, and a resume
          // runs it again under a new step name.
          for (let generation = 0; ; generation++) {
            const text = yield* run.step
              .do({
                name:
                  generation === 0
                    ? `${activity.name}/${attempt}`
                    : `${activity.name}/${attempt}/resumed-${generation}`,
                effect: activity.executeEncoded.pipe(
                  EffectWorkflow.intoResult,
                  Effect.catchCauseIf(
                    (cause) => !Cause.hasInterruptsOnly(cause),
                    (cause) =>
                      Effect.fail<ActivityDefect>({
                        _tag: "ActivityDefect",
                        message: Cause.pretty(cause),
                      }),
                  ),
                  Effect.flatMap((result) =>
                    result._tag === "Complete"
                      ? encodeExit(result.exit)
                      : Effect.succeed(SUSPENDED),
                  ),
                  // The run's services, with the step's own instance.
                  Effect.provide(
                    Layer.succeedContext(
                      run.context.pipe(
                        Context.add(WorkflowEngine.WorkflowInstance, activityInstance),
                        // The step runs on its own fiber: carry the attempt `Activity.retry` set.
                        Context.add(Activity.CurrentAttempt, attempt),
                        Context.add(
                          CurrentActivity,
                          makeCurrentActivity(
                            instance.workflow._tag,
                            instance.executionId,
                            activity.name,
                          ),
                        ),
                      ),
                    ),
                  ),
                ) as Effect.Effect<string, ActivityDefect>,
              })
              .pipe(
                Effect.catchTag("ActivityDefect", (defect) =>
                  Effect.die(new Error(defect.message)),
                ),
              );
            if (text !== SUSPENDED) {
              return new EffectWorkflow.Complete({ exit: yield* decodeExit(text) });
            }
            // Suspended on a failure: wait here for a resume, then run the
            // activity again, or for an interrupt.
            const waiting = `${activity.name}/${attempt}/suspended-${generation}`;
            const resumed = yield* run.step
              .waitForEvent(waiting, { type: RESUME, timeout: SIGNAL_TIMEOUT })
              .pipe(
                Effect.as(true),
                Effect.raceFirst(
                  run.step
                    .waitForEvent(`${waiting}/interrupt`, {
                      type: INTERRUPT,
                      timeout: SIGNAL_TIMEOUT,
                    })
                    .pipe(Effect.as(false)),
                ),
              );
            if (!resumed) {
              run.instance.interrupted = true;
              run.instance.suspended = false;
              return yield* Effect.interrupt;
            }
          }
        }),

      deferredResult: (deferred) =>
        Effect.gen(function* () {
          const run = yield* currentRun("DurableDeferred reads");
          // A race asks for its recorded winner before it runs. A step can only
          // be replayed by running it, so a winner can't be looked up first.
          if (deferred.name.startsWith("raceAll/")) {
            return yield* Effect.die(
              new Error(
                "Activity.raceAll and DurableDeferred.raceAll aren't supported on Cloudflare Workflows: a step's result can't be looked up before the step runs. Use the Durable Object engine.",
              ),
            );
          }
          const duration = run.clocks.get(deferred.name);
          // Every wait also waits for an interrupt.
          const interrupt = run.step
            .waitForEvent(`${deferred.name}/interrupt`, {
              type: INTERRUPT,
              timeout: SIGNAL_TIMEOUT,
            })
            .pipe(Effect.as({ interrupted: true, payload: "" }));
          const signal = yield* (
            duration !== undefined
              ? run.step
                  .sleep(deferred.name, Duration.toMillis(duration))
                  .pipe(Effect.as({ interrupted: false, payload: "" }))
              : run.step
                  .waitForEvent<string>(deferred.name, {
                    type: nameOf(deferred.name),
                    timeout: SIGNAL_TIMEOUT,
                  })
                  .pipe(Effect.map((event) => ({ interrupted: false, payload: event.payload })))
          ).pipe(Effect.raceFirst(interrupt));
          if (signal.interrupted) {
            run.instance.interrupted = true;
            run.instance.suspended = false;
            return yield* Effect.interrupt;
          }
          return Option.some(
            duration !== undefined ? Exit.void : yield* decodeExit(signal.payload),
          );
        }),

      deferredDone: (opts) =>
        Effect.gen(function* () {
          const payload = yield* encodeExit(opts.exit);
          yield* sendEvent(handle, nameOf(opts.workflowName, opts.executionId), {
            type: nameOf(opts.deferredName),
            payload,
          });
        }),

      scheduleClock: (_workflow, opts) =>
        Effect.flatMap(currentRun("DurableClock scheduling"), (run) =>
          Effect.sync(() => void run.clocks.set(opts.clock.deferred.name, opts.clock.duration)),
        ),
    });
    return engine;
  }),
);