/** * Runs durable workflows on the dedicated workflow Durable Object class. * * On this path one workflow execution is one Durable Object: the engine * encodes `(workflowName, executionId)` into a Durable Object name with the * same length-prefix scheme as entities and resolves the object through the * workflow namespace binding. Execution state, activity results keyed * `${name}/${attempt}`, durable deferred exits, and the clock due table all * live on the object's SQLite storage behind its single alarm. * * Every `DurableClock` is durable on this engine: the in-memory short-sleep * path is disabled, so even sub-minute sleeps persist a due row and arm the * alarm. * * @stability experimental * @since 4.1.3 */ import { Clock } from "effect/Clock" import * as Context from "effect/Context" import * as Duration from "effect/Duration" import * as Effect from "effect/Effect" import * as Layer from "effect/Layer" import * as Option from "effect/Option" import * as Schedule from "effect/Schedule" import * as Workflow from "effect/workflow/Workflow" import * as WorkflowEngine from "effect/workflow/WorkflowEngine" import { encodeName } from "./internal/clusterName.ts" import { callDurableObject } from "./internal/transport.ts" import { CurrentExecutionHandle, registerWorkflow, unregisterWorkflow, type WorkflowRegistration, type WorkflowStub } from "./internal/workflowRegistry.ts" import { InterruptSignalName } from "./internal/workflowRuntime.ts" import { decodeExit, decodeResult, encodeExit, encodePayload } from "./internal/workflowWire.ts" /** * The workflow Durable Object namespace binding the engine is built from. * * @stability experimental * @category layers * @since 4.1.3 */ export interface LayerOptions { readonly workflowNamespace: DurableObjectNamespace } const retryPolicy = Schedule.min([ Schedule.exponential(200, 1.5), Schedule.spaced("1 minute") ]) /** * Creates the `WorkflowEngine` service backed by the workflow Durable Object * namespace binding. * * **Details** * * Inside a workflow Durable Object the engine operates on the local execution * handle, so activities and deferred reads never leave the object. Everywhere * else it resolves the target execution's object with `getByName` and drives * it over the same-Worker binding. * * @stability experimental * @category constructors * @since 4.1.3 */ export const make = Effect.fnUntraced(function*(options: LayerOptions) { const clock = yield* Clock // Inside a run the execution's own handle avoids a self-RPC; every other // target resolves to its Durable Object stub through the namespace binding. // // As in `ClusterWorkflowEngine`, a transport failure is retried on an // exponential schedule capped at one minute and only then becomes a defect: // every call here is idempotent by key, and a permanently unreachable object // stalls the caller instead of failing a workflow for good. The object never // rejects for application reasons, so a child's own defect arrives as its // stored `Complete` result and is never retried. const callExecution = ( workflowName: string, executionId: string, call: (stub: WorkflowStub) => Promise ): Effect.Effect => Effect.flatMap(Effect.serviceOption(CurrentExecutionHandle), (handle) => { if (Option.isSome(handle) && handle.value.executionId === executionId) { const local = handle.value as WorkflowStub return Effect.promise(() => call(local)) } const name = encodeName(workflowName, executionId) return callDurableObject({ resolve: () => options.workflowNamespace.getByName(name) as unknown as WorkflowStub, call, retry: retryPolicy }).pipe(Effect.orDie) }) const localHandle = Effect.fnUntraced(function*(operation: string) { const instance = yield* WorkflowEngine.WorkflowInstance const handle = yield* Effect.serviceOption(CurrentExecutionHandle) if (Option.isNone(handle)) { return yield* Effect.die( `CloudflareWorkflowEngine: ${operation} is only available inside a workflow Durable Object execution` ) } return { instance, handle: handle.value } as const }) return WorkflowEngine.makeUnsafe({ register: Effect.fnUntraced(function*(workflow, execute) { const context = yield* Effect.context() const registration: WorkflowRegistration = { workflow, execute, context } if (!registerWorkflow(workflow._tag, registration)) return yield* Effect.addFinalizer(() => Effect.sync(() => { unregisterWorkflow(workflow._tag, registration) }) ) }), execute: Effect.fnUntraced(function*(workflow, opts) { const context = yield* Effect.context() const payload = yield* encodePayload(workflow, opts.payload, context) // A detached child keeps no parent, so neither its completion nor a // failed run wakes the parent. const parent = opts.parent === undefined || opts.detached ? undefined : { workflowName: opts.parent.workflow._tag, executionId: opts.parent.executionId } const text = yield* callExecution( workflow._tag, opts.executionId, (stub) => stub.run(payload, { discard: opts.discard, parent }) ) if (opts.discard) return undefined return yield* decodeResult(workflow, text, context) }) as WorkflowEngine.Encoded["execute"], poll: Effect.fnUntraced(function*(workflow, executionId) { const context = yield* Effect.context() const text = yield* callExecution(workflow._tag, executionId, (stub) => stub.poll()) if (text === undefined) return Option.none() return Option.some(yield* decodeResult(workflow, text, context)) }), interrupt: (workflow, executionId) => callExecution(workflow._tag, executionId, (stub) => stub.interrupt()), interruptUnsafe: (workflow, executionId) => callExecution(workflow._tag, executionId, (stub) => stub.interruptUnsafe()), resume: (workflow, executionId) => callExecution(workflow._tag, executionId, (stub) => stub.resume()), activityExecute: Effect.fnUntraced(function*(activity, attempt) { const { handle, instance } = yield* localHandle("Activity execution") const key = `${activity.name}/${attempt}` const stored = handle.loadActivity(key) if (stored !== undefined) { return new Workflow.Complete({ exit: yield* decodeExit(stored, Context.empty()) }) } // A pending interrupt replays only to rebuild compensations, so it must // not start new activities. Suspending lets the run apply the interrupt. if (!instance.interrupted && handle.loadDeferred(InterruptSignalName) !== undefined) { instance.suspended = true return new Workflow.Suspended({}) } const activityInstance = WorkflowEngine.WorkflowInstance.initial(instance.workflow, instance.executionId) activityInstance.interrupted = instance.interrupted const result = yield* activity.executeEncoded.pipe( Workflow.intoResult, Effect.provideService(WorkflowEngine.WorkflowInstance, activityInstance) ) if (result._tag === "Complete") { handle.saveActivity(key, yield* encodeExit(result.exit, Context.empty())) } return result }), deferredResult: Effect.fnUntraced(function*(deferred) { const { handle } = yield* localHandle("DurableDeferred reads") const stored = handle.loadDeferred(deferred.name) if (stored === undefined) return Option.none() return Option.some(yield* decodeExit(stored, Context.empty())) }), deferredDone: Effect.fnUntraced(function*({ deferredName, executionId, exit, workflowName }) { const text = yield* encodeExit(exit, Context.empty()) const handle = yield* Effect.serviceOption(CurrentExecutionHandle) if (Option.isSome(handle) && handle.value.executionId === executionId) { return yield* handle.value.completeOwnDeferred(deferredName, text) } yield* callExecution(workflowName, executionId, (stub) => stub.deferredDone(deferredName, text)) }), scheduleClock: Effect.fnUntraced(function*(workflow, opts) { const wakeUp = clock.currentTimeMillisUnsafe() + Math.ceil(Duration.toMillis(opts.clock.duration)) yield* callExecution( workflow._tag, opts.executionId, (stub) => stub.scheduleClock(opts.clock.name, opts.clock.deferred.name, wakeUp) ) }) }) }) /** * Layer that provides the `WorkflowEngine` backed by the workflow Durable * Object namespace binding. * * **Details** * * `CloudflareCluster.layer` already includes this layer; use it directly only * when the workflow engine is needed without the rest of the cluster. * * @stability experimental * @category layers * @since 4.1.3 */ export const layer = (options: LayerOptions): Layer.Layer => Layer.effect(WorkflowEngine.WorkflowEngine)(make(options))