@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 252 lines 8.04 KB
Raw
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.