The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Effect workflows |
| 3 | description: Run Effect workflows on AWS Lambda durable functions. Host them in an AWS.Lambda.WorkflowFunction, start runs from other functions with AWS.Lambda.DurableFunctionEngine, and let them sleep and wait durably. |
| 4 | --- |
| 5 | |
| 6 | An Effect workflow is a durable process written with `effect/workflow`: a |
| 7 | series of steps whose results are stored, so a run that's interrupted |
| 8 | resumes after its last finished step, and a run can wait hours or days for |
| 9 | a timer or a signal. On AWS they run on Lambda durable functions: each run |
| 10 | is one durable execution. |
| 11 | |
| 12 | The same workflow code runs on Cloudflare too. See |
| 13 | [Effect workflows on Cloudflare](/cloudflare/compute/effect-workflows). |
| 14 | |
| 15 | ## Define a workflow |
| 16 | |
| 17 | `Workflow.make` declares the workflow, and `Workflows.layer` implements it. |
| 18 | Each step is an `Activity`: a named Effect whose result is stored the first |
| 19 | time it completes. |
| 20 | |
| 21 | ```typescript |
| 22 | // src/orders.ts |
| 23 | import * as Workflows from "alchemy/Workflows"; |
| 24 | import * as Effect from "effect/Effect"; |
| 25 | import * as Schema from "effect/Schema"; |
| 26 | import { Activity, Workflow } from "effect/workflow"; |
| 27 | |
| 28 | export const PlaceOrder = Workflow.make("PlaceOrder", { |
| 29 | payload: { orderId: Schema.String }, |
| 30 | success: Schema.String, |
| 31 | idempotencyKey: ({ orderId }) => orderId, |
| 32 | }); |
| 33 | |
| 34 | export const PlaceOrderLive = Workflows.layer( |
| 35 | PlaceOrder, |
| 36 | Effect.fn(function* ({ orderId }) { |
| 37 | return yield* Activity.make({ |
| 38 | name: "charge", |
| 39 | success: Schema.String, |
| 40 | execute: Effect.succeed(`charged ${orderId}`), |
| 41 | }); |
| 42 | }), |
| 43 | ); |
| 44 | ``` |
| 45 | |
| 46 | ## Use bindings in a step |
| 47 | |
| 48 | Pass `Workflows.layer` an Effect that returns the handler instead of the |
| 49 | handler itself. The Effect runs once, when the function starts, so resolve |
| 50 | bindings there and use them in the steps: |
| 51 | |
| 52 | ```typescript |
| 53 | // src/receipts.ts |
| 54 | import * as AWS from "@alchemy.run/aws"; |
| 55 | import * as Workflows from "alchemy/Workflows"; |
| 56 | import * as Effect from "effect/Effect"; |
| 57 | import * as Schema from "effect/Schema"; |
| 58 | import { Activity, Workflow } from "effect/workflow"; |
| 59 | |
| 60 | export const Receipts = AWS.S3.Bucket("Receipts"); |
| 61 | |
| 62 | export const SendReceipt = Workflow.make("SendReceipt", { |
| 63 | payload: { orderId: Schema.String }, |
| 64 | idempotencyKey: ({ orderId }) => orderId, |
| 65 | }); |
| 66 | |
| 67 | export const SendReceiptLive = Workflows.layer( |
| 68 | SendReceipt, |
| 69 | Effect.gen(function* () { |
| 70 | const putObject = yield* AWS.S3.PutObject(Receipts); |
| 71 | return Effect.fn(function* ({ orderId }) { |
| 72 | yield* Activity.make({ |
| 73 | name: "receipt", |
| 74 | execute: putObject({ |
| 75 | Key: `${orderId}.json`, |
| 76 | Body: JSON.stringify({ orderId }), |
| 77 | }).pipe(Effect.orDie), |
| 78 | }); |
| 79 | }); |
| 80 | }), |
| 81 | ); |
| 82 | ``` |
| 83 | |
| 84 | The binding grants the workflow function `s3:PutObject` on the bucket. |
| 85 | Provide its implementation on the Layer you deploy the function with: |
| 86 | `SendReceiptLive.pipe(Layer.provide(AWS.S3.PutObjectHttp))`. |
| 87 | |
| 88 | ## Host it in a workflow function |
| 89 | |
| 90 | `AWS.Lambda.WorkflowFunction` is a durable function that runs workflows. |
| 91 | Declare the workflows it runs, then deploy it with the Layer that |
| 92 | implements them: |
| 93 | |
| 94 | ```typescript |
| 95 | // src/OrderWorkflows.ts |
| 96 | import * as AWS from "@alchemy.run/aws"; |
| 97 | import { PlaceOrder, PlaceOrderLive } from "./orders.ts"; |
| 98 | |
| 99 | export class OrderWorkflows extends AWS.Lambda.WorkflowFunction<OrderWorkflows>()( |
| 100 | "OrderWorkflows", |
| 101 | { workflows: [PlaceOrder] }, |
| 102 | ) {} |
| 103 | |
| 104 | export default OrderWorkflows.make( |
| 105 | { main: import.meta.url, executionTimeout: "7 days" }, |
| 106 | PlaceOrderLive, |
| 107 | ); |
| 108 | ``` |
| 109 | |
| 110 | Each run is one durable execution of the function. `executionTimeout` caps |
| 111 | how long one run may take in total, waits included, up to a year. |
| 112 | |
| 113 | ## Host several workflows |
| 114 | |
| 115 | One function can run many workflows. List them all, and merge their Layers: |
| 116 | |
| 117 | ```typescript |
| 118 | // src/OrderWorkflows.ts |
| 119 | import * as AWS from "@alchemy.run/aws"; |
| 120 | import * as Layer from "effect/Layer"; |
| 121 | import { PlaceOrder, PlaceOrderLive, RefundOrder, RefundOrderLive } from "./orders.ts"; |
| 122 | |
| 123 | export class OrderWorkflows extends AWS.Lambda.WorkflowFunction<OrderWorkflows>()( |
| 124 | "OrderWorkflows", |
| 125 | { workflows: [PlaceOrder, RefundOrder] }, |
| 126 | ) {} |
| 127 | |
| 128 | export default OrderWorkflows.make( |
| 129 | { main: import.meta.url, executionTimeout: "7 days" }, |
| 130 | Layer.mergeAll(PlaceOrderLive, RefundOrderLive), |
| 131 | ); |
| 132 | ``` |
| 133 | |
| 134 | The Layer must implement every workflow the function lists: leaving one out |
| 135 | is a type error. A workflow's child workflows run in the same function, so |
| 136 | list them too. |
| 137 | |
| 138 | ## Start a run from another function |
| 139 | |
| 140 | `AWS.Lambda.DurableFunctionEngine` runs workflows on the functions that host |
| 141 | them. Provide it to the calling function, and get a client with |
| 142 | `Workflows.RunWorkflow`: |
| 143 | |
| 144 | ```typescript |
| 145 | // src/Api.ts |
| 146 | import * as AWS from "@alchemy.run/aws"; |
| 147 | import * as Workflows from "alchemy/Workflows"; |
| 148 | import * as Effect from "effect/Effect"; |
| 149 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 150 | import { OrderWorkflows } from "./OrderWorkflows.ts"; |
| 151 | import { PlaceOrder } from "./orders.ts"; |
| 152 | |
| 153 | export class Api extends AWS.Lambda.Function<Api>()("Api") {} |
| 154 | |
| 155 | export default Api.make( |
| 156 | { main: import.meta.url, functionUrl: true }, |
| 157 | Effect.gen(function* () { |
| 158 | const placeOrder = yield* Workflows.RunWorkflow(PlaceOrder); |
| 159 | return { |
| 160 | fetch: Effect.gen(function* () { |
| 161 | const run = yield* placeOrder.start({ orderId: "o-1" }); |
| 162 | return HttpServerResponse.text(run.executionId); |
| 163 | }), |
| 164 | }; |
| 165 | }).pipe(Effect.provide(AWS.Lambda.DurableFunctionEngine(OrderWorkflows))), |
| 166 | ); |
| 167 | ``` |
| 168 | |
| 169 | The engine grants the caller what it needs on `OrderWorkflows`: invoking it, |
| 170 | and reading and signalling its durable executions. `start` returns as soon |
| 171 | as the run is started. Starting again with the same key returns the run |
| 172 | already started, so a retried request never starts a second one. |
| 173 | |
| 174 | Running a workflow that none of the engine's functions list is a type error. |
| 175 | |
| 176 | ## Route across functions |
| 177 | |
| 178 | Pass every function whose workflows the caller runs. Each run goes to the |
| 179 | function that hosts its workflow: |
| 180 | |
| 181 | ```typescript |
| 182 | Effect.provide(AWS.Lambda.DurableFunctionEngine(OrderWorkflows, BillingWorkflows)) |
| 183 | ``` |
| 184 | |
| 185 | ## Read a run |
| 186 | |
| 187 | Store the run's `executionId`, and get the run back with `get`: |
| 188 | |
| 189 | ```typescript |
| 190 | const run = placeOrder.get(executionId); |
| 191 | const status = yield* run.status; |
| 192 | ``` |
| 193 | |
| 194 | `status` is `NotStarted`, `Running`, `Completed` with its result, `Failed` |
| 195 | with its error, `Interrupted`, or `Died` with a defect. `run.result` waits |
| 196 | for the run to finish, which suits tests and scripts more than requests. |
| 197 | |
| 198 | ## Sleep durably |
| 199 | |
| 200 | `DurableClock.sleep` is a durable wait: the invocation ends, nothing is |
| 201 | billed while it waits, and Lambda invokes the function again when it's due. |
| 202 | |
| 203 | ```typescript |
| 204 | yield* DurableClock.sleep({ name: "cool-off", duration: "1 hour" }); |
| 205 | ``` |
| 206 | |
| 207 | Sleeps of a minute or less run in memory by default. Pass |
| 208 | `inMemoryThreshold: 0` to make a short sleep durable too. Durable sleeps |
| 209 | round up to whole seconds. |
| 210 | |
| 211 | ## Wait for a signal |
| 212 | |
| 213 | A `DurableDeferred` is a value a run waits for, delivered from outside. The |
| 214 | run waits on a Lambda callback until it arrives. |
| 215 | |
| 216 | ```typescript |
| 217 | export const Approval = DurableDeferred.make("approval", { success: Schema.String }); |
| 218 | |
| 219 | const approvedBy = yield* DurableDeferred.await(Approval); |
| 220 | ``` |
| 221 | |
| 222 | Send it with the run's `signal`: |
| 223 | |
| 224 | ```typescript |
| 225 | yield* approve.get(executionId).signal(Approval, "agent-7"); |
| 226 | ``` |
| 227 | |
| 228 | The engine finds the run's callback in its execution history. A callback |
| 229 | only exists once the run reaches its wait, so `signal` retries for up to a |
| 230 | few minutes while the run gets there. |
| 231 | |
| 232 | ## Undo a step when a later one fails |
| 233 | |
| 234 | `withCompensation` attaches what to do if the run fails after the step |
| 235 | succeeded. Compensations run last step first. |
| 236 | |
| 237 | ```typescript |
| 238 | yield* Activity.make({ name: "reserve", execute: reserve(order) }).pipe( |
| 239 | Checkout.withCompensation(() => Activity.make({ name: "release", execute: release(order) })), |
| 240 | ); |
| 241 | ``` |
| 242 | |
| 243 | `run.interrupt` wakes a run that's waiting on a signal, which then |
| 244 | fails where it waits and runs its compensations. A run that's busy in a step |
| 245 | can only be stopped, with `StopDurableExecution`, and its compensations don't |
| 246 | run. |
| 247 | |
| 248 | ## See what a run did |
| 249 | |
| 250 | Every step is a named operation in the durable execution, so the Lambda |
| 251 | console and `GetDurableExecutionHistory` show which steps ran, with their |
| 252 | names (`charge/1`: the step and its attempt), results and timings. |