@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 274 lines 9.1 KB
Raw
1 ---
2 title: Effect workflows
3 description: Run Effect workflows on Cloudflare, on Durable Objects or Cloudflare Workflows. Declare a workflow with effect/workflow, implement it with Workflows.layer, start runs with Workflows.RunWorkflow, and let them sleep, wait for signals and undo steps 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 Cloudflare they run on Durable Objects
10 (`Cloudflare.Workflows.layerDurableObjectEngine()`) or on Cloudflare Workflows
11 (`Cloudflare.Workflows.NativeEngine`), with the same workflow code.
12
13 Reach for Effect workflows when you want the same workflow code to run
14 anywhere Effect's `WorkflowEngine` does: on Cloudflare, on
15 [AWS Lambda](/aws/compute/effect-workflows), or in memory in tests. To write
16 against Cloudflare Workflows' own step API instead, see
17 [Workflows](/cloudflare/compute/workflows).
18
19 ## Define a workflow
20
21 `Workflow.make` declares the workflow: its name, the payload it starts
22 with, its result, and the key that identifies one run.
23
24 ```typescript
25 // src/Greet.ts
26 import * as Schema from "effect/Schema";
27 import { Workflow } from "effect/workflow";
28
29 export const Greet = Workflow.make("Greet", {
30 payload: { id: Schema.String, name: Schema.String },
31 success: Schema.String,
32 idempotencyKey: ({ id }) => id,
33 });
34 ```
35
36 Starting a workflow again with the same key returns the run already
37 started, so a retried request never starts a second one.
38
39 ## Implement its steps
40
41 `Workflows.layer` implements the workflow. Each step is an `Activity`: a
42 named Effect whose result is stored the first time it completes. When the
43 run replays, a finished step returns its stored result instead of running
44 again.
45
46 ```typescript
47 // src/Greet.ts
48 import * as Workflows from "alchemy/Workflows";
49 import * as Effect from "effect/Effect";
50 import { Activity } from "effect/workflow";
51
52 export const GreetLive = Workflows.layer(
53 Greet,
54 Effect.fn(function* ({ name }) {
55 return yield* Activity.make({
56 name: "greet",
57 success: Schema.String,
58 execute: Effect.succeed(`hello ${name}`),
59 });
60 }),
61 );
62 ```
63
64 A step that returns a value or fails with a typed error declares `success`
65 and `error` schemas, because its result is stored as JSON.
66
67 ## Run it on Durable Objects
68
69 `Cloudflare.Workflows.layerDurableObjectEngine()` is the engine. Provide it under
70 the workflow Layers, and provide both to the Worker:
71
72 ```typescript
73 // src/worker.ts
74 import * as Cloudflare from "@alchemy.run/cloudflare";
75 import * as Effect from "effect/Effect";
76 import * as Layer from "effect/Layer";
77 import { GreetLive } from "./Greet.ts";
78
79 export default class AppWorker extends Cloudflare.Worker<AppWorker>()(
80 "AppWorker",
81 { main: import.meta.url },
82 Effect.gen(function* () {
83 return {};
84 }).pipe(
85 Effect.provide(GreetLive.pipe(Layer.provideMerge(Cloudflare.Workflows.layerDurableObjectEngine()))),
86 ),
87 ) {}
88 ```
89
90 Each workflow gets its own Durable Object class on the Worker, named after
91 it (`GreetWorkflow`), and deploying the Worker deploys them.
92
93 Pass `{ jurisdiction: "eu" }` to `layerDurableObjectEngine` to create and
94 store every run's Durable Object only inside that jurisdiction. Runs that
95 already exist stay where they were, and `alchemy dev` runs it unrestricted,
96 since local workerd doesn't emulate jurisdictions.
97
98 ## Start a run
99
100 `Workflows.RunWorkflow` gives you a client for the workflow. Resolve it
101 during init, and start runs from your handlers:
102
103 ```typescript
104 // src/worker.ts
105 import * as Cloudflare from "@alchemy.run/cloudflare";
106 import * as Workflows from "alchemy/Workflows";
107 import * as Effect from "effect/Effect";
108 import * as HttpServerResponse from "effect/http/HttpServerResponse";
109 import * as Layer from "effect/Layer";
110 import { Greet, GreetLive } from "./Greet.ts";
111
112 export default class AppWorker extends Cloudflare.Worker<AppWorker>()(
113 "AppWorker",
114 { main: import.meta.url },
115 Effect.gen(function* () {
116 const greet = yield* Workflows.RunWorkflow(Greet);
117 return {
118 fetch: Effect.gen(function* () {
119 const run = yield* greet.start({ id: "g-1", name: "sam" });
120 return HttpServerResponse.text(run.executionId);
121 }),
122 };
123 }).pipe(
124 Effect.provide(GreetLive.pipe(Layer.provideMerge(Cloudflare.Workflows.layerDurableObjectEngine()))),
125 ),
126 ) {}
127 ```
128
129 `start` returns as soon as the run is started, with a handle to it.
130 Starting again with the same key returns the run already started, so a
131 retried request never starts a second one.
132
133 `RunWorkflow` only compiles where the workflow is implemented: running a
134 workflow with no `Workflows.layer` in the Worker is a type error.
135
136 ## Read a run
137
138 Store the run's `executionId`, and get the run back with `get`:
139
140 ```typescript
141 const run = greet.get(executionId);
142 const status = yield* run.status;
143 ```
144
145 `status` is `NotStarted`, `Running`, `Completed` with its result, `Failed`
146 with its error, `Interrupted`, or `Died` with a defect. `run.result` waits
147 for the run to finish, which suits tests and scripts more than requests.
148
149 ## Or run it on Cloudflare Workflows
150
151 `Cloudflare.Workflows.NativeEngine` runs the same workflow Layers on
152 Cloudflare Workflows instead: one Workflow class, `NativeEngine`, runs them
153 all, and each run is one Workflow instance. Swap the engine and nothing else
154 changes:
155
156 ```typescript
157 Effect.provide(GreetLive.pipe(Layer.provideMerge(Cloudflare.Workflows.NativeEngine)))
158 ```
159
160 Steps run with `step.do`, sleeps with `step.sleep`, and signals are
161 Workflow events, so runs show up in the Cloudflare dashboard step by step.
162 Cloudflare's limits apply: steps per instance, the size of each step's
163 result, and a year at most for a wait.
164
165 ## Sleep durably
166
167 `DurableClock.sleep` waits on a Durable Object alarm or a Workflow sleep, so
168 the wait survives restarts and costs nothing while it lasts:
169
170 ```typescript
171 yield* DurableClock.sleep({ name: "cool-off", duration: "1 hour" });
172 ```
173
174 Sleeps of a minute or less run in memory by default. Pass
175 `inMemoryThreshold: 0` to make a short sleep durable too.
176
177 ## Wait for a signal
178
179 A `DurableDeferred` is a value a run waits for, delivered from outside:
180 an approval, a webhook, a person clicking a link. The run suspends until
181 it arrives.
182
183 ```typescript
184 export const Approval = DurableDeferred.make("approval", { success: Schema.String });
185
186 const approvedBy = yield* DurableDeferred.await(Approval);
187 ```
188
189 Send it with the run's `signal`:
190
191 ```typescript
192 yield* greet.get(executionId).signal(Approval, "agent-7");
193 ```
194
195 ## Undo a step when a later one fails
196
197 `withCompensation` attaches what to do if the run fails after the step
198 succeeded. Compensations run last step first.
199
200 ```typescript
201 yield* Activity.make({ name: "reserve", execute: reserve(order) }).pipe(
202 Checkout.withCompensation(() => Activity.make({ name: "release", execute: release(order) })),
203 );
204 ```
205
206 `run.interrupt` stops a run where it waits, and its compensations run too.
207
208 ## Use bindings in a step
209
210 Pass `Workflows.layer` an Effect that returns the handler instead of the
211 handler itself. The Effect runs once, when the Worker starts, so resolve
212 bindings there, the same way a Worker's init does, and use them in the
213 steps:
214
215 ```typescript
216 // src/Checkout.ts
217 import * as Cloudflare from "@alchemy.run/cloudflare";
218 import * as Workflows from "alchemy/Workflows";
219 import * as Effect from "effect/Effect";
220 import * as Schema from "effect/Schema";
221 import { Activity, Workflow } from "effect/workflow";
222
223 export const Receipts = Cloudflare.R2.Bucket("Receipts");
224
225 export const Checkout = Workflow.make("Checkout", {
226 payload: { orderId: Schema.String },
227 idempotencyKey: ({ orderId }) => orderId,
228 });
229
230 export const CheckoutLive = Workflows.layer(
231 Checkout,
232 Effect.gen(function* () {
233 const receipts = yield* Cloudflare.R2.WriteBucket(Receipts);
234 return Effect.fn(function* ({ orderId }) {
235 yield* Activity.make({
236 name: "receipt",
237 execute: receipts
238 .put(`${orderId}.json`, JSON.stringify({ orderId }))
239 .pipe(Effect.orDie),
240 });
241 });
242 }),
243 );
244 ```
245
246 Provide the binding's implementation with the engine:
247
248 ```typescript
249 Effect.provide(
250 CheckoutLive.pipe(
251 Layer.provideMerge(Cloudflare.Workflows.layerDurableObjectEngine()),
252 Layer.provide(Cloudflare.R2.WriteBucketBinding),
253 ),
254 )
255 ```
256
257 A Durable Object namespace works the same way: `yield* Journal` in the
258 Effect, and call `journals.getByName(id).append(...)` from a step.
259
260 The bucket's methods are runtime-only: they need `RuntimeContext`, which
261 init doesn't have. Steps only run inside a run, which has one, so
262 `Workflows.layer` doesn't pass that requirement on to the Worker.
263
264 ## How a run executes on Durable Objects
265
266 A run is one Durable Object instance, named by its execution id, with its
267 journal in that instance's SQLite: the payload, each finished step's
268 result, completed signals and pending timers. Every wake-up (a start, a
269 signal, a timer, an interrupt) schedules one durable alarm callback that
270 replays the run, so runs never overlap, and a run that fails or is cut
271 short is retried.
272
273 Under `alchemy dev` the same Durable Objects run locally in workerd, so
274 workflows, sleeps and signals behave as they do when deployed.