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

main
mdx 276 lines 13.9 KB
Raw
1 ---
2 title: Saga
3 description: A process that spans several aggregates and takes time, run step by step as an Effect workflow, with steps that undo earlier ones when a later one fails.
4 ---
5
6 import DAG from "../../../components/DAG.astro";
7
8 A saga runs a process that spans several aggregates. An aggregate changes one instance at a time, and no transaction spans two, so a process that touches several runs as a series of steps, each committed on its own. When a step fails after earlier ones succeeded, the saga undoes them with compensations.
9
10 A saga is an [Effect workflow](https://effect.website/docs/workflow). Each step's result is stored, so a run that's interrupted resumes after its last finished step, and a run can wait hours or days for a signal or a timer. A policy usually decides when to start one.
11
12 In the example bank, a transfer is a saga: it debits one account, credits another, and refunds the debit if the credit fails.
13
14 <DAG
15 nodes={[
16 { id: "request", label: "RequestTransfer", type: "command", kind: "command", col: 0, row: 0 },
17 { id: "transfer", label: "Transfer", type: "records the request", kind: "aggregate", col: 1, row: 0 },
18 { id: "policy", label: "TransferExecution", type: "starts the saga", kind: "policy", col: 2, row: 0 },
19 { id: "saga", label: "ExecuteTransfer", type: "runs the steps", kind: "saga", col: 3, row: 0 },
20 { id: "debit", label: "DebitTransfer", type: "1 · source account", kind: "command", col: 3, row: 1 },
21 { id: "credit", label: "CreditTransfer", type: "2 · destination", kind: "command", col: 3, row: 2 },
22 ]}
23 edges={[
24 { from: "request", to: "transfer" },
25 { from: "transfer", to: "policy" },
26 { from: "policy", to: "saga" },
27 { from: "saga", to: "debit" },
28 { from: "saga", to: "credit" },
29 ]}
30 caption="A policy decides when the transfer runs; the saga carries it out, one step at a time."
31 />
32
33 This chapter starts with why a process across aggregates can't be one transaction, and what to do instead. Then it builds the transfer saga step by step.
34
35 ## No transaction spans two aggregates
36
37 Moving money between two accounts touches two aggregates, and each is its own consistency boundary. There's no step in which both change together. So a transfer can't be "debit and credit, or neither", the way a database transaction would make it.
38
39 Instead, it's a sequence of steps, each committed on its own: debit the source, then credit the destination. In between, the money is in flight. It has left one account and not yet reached the other, and anyone reading both balances at that moment sees it. That's not a bug to hide; it's how money moves in real banks too, and the `Transfer` aggregate records that the transfer is pending so screens can show it.
40
41 ## Undo with a new fact, not an erasure
42
43 When a later step fails, the earlier ones have already happened. Their events are facts and can't be erased. So the saga undoes them the way a business would, by recording another fact that reverses the effect: a debited transfer whose credit is refused is refunded, and the account's history shows the debit and the refund, one after the other.
44
45 <DAG
46 nodes={[
47 { id: "debited", label: "TransferDebited", type: "a-1 · −50", kind: "event", col: 0, row: 0 },
48 { id: "refused", label: "CreditTransfer", type: "a-2 is closed", kind: "rejection", col: 1, row: 0 },
49 { id: "refunded", label: "TransferRefunded", type: "a-1 · +50", kind: "event", col: 2, row: 0 },
50 ]}
51 edges={[
52 { from: "debited", to: "refused" },
53 { from: "refused", to: "refunded" },
54 ]}
55 caption="A compensation doesn't rewrite history. It adds the step that puts things right."
56 />
57
58 These undo steps are called **compensations**. Each step that can be undone declares its compensation next to it, and a saga that fails runs them in reverse order. A compensation must not be refused, or the process would be stuck halfway, so the command it sends records a fact in every state. See [Never refuse a compensation](/domain/aggregate#never-refuse-a-compensation).
59
60 ## Saga or policy?
61
62 A [policy](/domain/policy) is one reaction: an event arrives, the policy acts, and it's done. A saga is a process with memory. It knows which step it's on, waits between steps, and knows what to undo if something fails.
63
64 Reach for a saga when a process has more than one step, waits for something, a decision or a timer, or has to undo earlier steps on failure. A policy usually starts the saga, on the event that records the request.
65
66 ## Declare a saga
67
68 A saga has a key, the input it starts with, and every way it can be refused. The key identifies one run: starting the saga again with the same transfer id returns the same run.
69
70 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
71 export class ExecuteTransfer extends Domain.Saga("ExecuteTransfer", {
72 key: TransferId,
73 input: {
74 from: AccountId,
75 to: AccountId,
76 amount: Cents,
77 requestedBy: Actor,
78 needsApproval: Schema.Boolean,
79 },
80 rejects: [NotOpen, NotOwner, Frozen, InsufficientFunds, DestinationClosed],
81 }) {}
82 ```
83
84 ## Run its steps
85
86 Its Layer resolves the clients its steps use, then returns what each run does. Each step is an `Activity`: a named Effect whose result is stored. When the run replays, a finished step returns its stored result instead of running again.
87
88 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
89 yield* Activity.make({
90 name: "credit",
91 error: DestinationClosed,
92 execute: accounts
93 .send(to, new CreditTransfer({ transferId: key, amount }))
94 .pipe(Effect.catchTag("NotOpen", () => Effect.fail(new DestinationClosed()))),
95 });
96 ```
97
98 A step declares the errors it can fail with, so a refusal survives being stored. Here the destination account's `NotOpen` becomes the saga's own `DestinationClosed`.
99
100 A step that runs again is safe. A step can run twice: when it's retried, or when its run is cut short after the step's command committed but before its result was stored. The commands a step sends get ids derived from the run and the step, so the second run sends the same command ids, and the aggregate applies each command once. Keep each step to one command, so each stored result matches one fact.
101
102 ## Undo a step when a later one fails
103
104 A step can carry a compensation: what to do if the run fails after the step succeeded. The debit's compensation refunds it.
105
106 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
107 yield* Activity.make({
108 name: "debit",
109 error: Schema.Union([NotOpen, NotOwner, Frozen, InsufficientFunds]),
110 execute: accounts.send(from, new DebitTransfer({ transferId: key, amount, requestedBy })),
111 }).pipe(
112 ExecuteTransfer.withCompensation(() =>
113 Activity.make({
114 name: "refund",
115 execute: accounts.send(from, new RefundTransfer({ transferId: key, amount })),
116 }),
117 ),
118 );
119 ```
120
121 When the credit is refused, the run fails, and every compensation registered so far runs, last step first.
122
123 <DAG
124 nodes={[
125 { id: "debit", label: "DebitTransfer", type: "succeeded", kind: "command", col: 0, row: 0 },
126 { id: "credit", label: "CreditTransfer", type: "refused", kind: "command", col: 1, row: 0 },
127 { id: "closed", label: "DestinationClosed", type: "the saga fails", kind: "rejection", col: 2, row: 0 },
128 { id: "refund", label: "RefundTransfer", type: "undoes the debit", kind: "command", col: 2, row: 1 },
129 ]}
130 edges={[
131 { from: "debit", to: "credit" },
132 { from: "credit", to: "closed" },
133 { from: "closed", to: "refund" },
134 ]}
135 />
136
137 ## Take the step you can't undo first
138
139 Debit before you credit. If the credit then fails, the money is refunded, so it can be in flight but never created out of nothing. In the same way, registration claims the username before the customer counts as registered: see [Unique values](/domain/unique-values).
140
141 ## Record the outcome
142
143 The Transfer aggregate shows where every transfer stands, so the saga reports back to it. The last step completes the transfer:
144
145 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
146 yield* Activity.make({
147 name: "complete",
148 execute: transfers.send(key, new CompleteTransfer()),
149 });
150 ```
151
152 A failure is recorded by a finalizer. It's registered first, so it runs after every compensation:
153
154 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
155 yield* Workflow.addFinalizer((exit) =>
156 Exit.isSuccess(exit)
157 ? Effect.void
158 : Activity.make({
159 name: "record-failure",
160 execute: transfers.send(key, new FailTransfer({ reason: reasonOf(exit.cause) })),
161 }).pipe(Effect.orDie),
162 );
163 ```
164
165 ## Start it from a policy
166
167 Start a saga from a policy, on the event that records the request. The command that asked for the transfer commits `TransferRequested` and replies straight away; the policy starts the saga after that, and the saga runs on its own. Nobody waits for it.
168
169 <DAG
170 nodes={[
171 { id: "request", label: "RequestTransfer", type: "replies at once", kind: "command", col: 0, row: 0 },
172 { id: "transfer", label: "Transfer", type: "records the request", kind: "aggregate", col: 1, row: 0 },
173 { id: "requested", label: "TransferRequested", type: "the fact", kind: "event", col: 2, row: 0 },
174 { id: "policy", label: "TransferExecution", type: "starts it, later", kind: "policy", col: 2, row: 1 },
175 { id: "saga", label: "ExecuteTransfer", type: "runs on its own", kind: "saga", col: 1, row: 1 },
176 ]}
177 edges={[
178 { from: "request", to: "transfer" },
179 { from: "transfer", to: "requested" },
180 { from: "requested", to: "policy", dashed: true },
181 { from: "policy", to: "saga" },
182 ]}
183 caption="The request is a fact before the process starts, so it's never lost, and the caller never waits for the process."
184 />
185
186 `yield* ExecuteTransfer` gives the saga's client. `start` begins a run, or returns the one already started with that key, as a handle to the run. Policies run at least once, so key the saga by the aggregate it's about: a policy that runs twice still starts one transfer.
187
188 ```typescript title="packages/domain/src/Transfer/TransferExecution.policy.ts"
189 case "TransferRequested":
190 yield* executions.start(source, {
191 from: event.from,
192 to: event.to,
193 amount: event.amount,
194 requestedBy: event.requestedBy,
195 needsApproval: event.needsApproval,
196 });
197 return;
198 ```
199
200 List the saga on the model, next to its aggregates and policies, and its Layer with the other handlers.
201
202 ```typescript title="packages/domain/src/Bank.model.ts"
203 sagas: [ExecuteTransfer],
204 ```
205
206 ## Don't wait for it in a policy
207
208 `start` returns as soon as the run is recorded. Its run handle also has `result`, which waits for the run to finish, but a run can take days, and a policy that waits holds up every later event on its key. Use `result` in tests and scripts. Anything that needs to react to how a saga ends should react to the events it reports instead, like `TransferCompleted` or `TransferFailed`.
209
210 ## Wait for a decision
211
212 A run can wait as long as it needs to. A large transfer waits until the Transfer decides it: an agent approves it, or its approval window closes first. The saga waits on a `DurableDeferred`, and suspends until someone completes it.
213
214 ```typescript title="packages/domain/src/Transfer/ExecuteTransfer.saga.ts"
215 if (needsApproval) {
216 // The Transfer decides between approval and expiry; nothing to do if it expired.
217 if ((yield* DurableDeferred.await(Decision)) === "expired") return;
218 }
219 ```
220
221 The policy passes on the decision with the run's `signal`. `get` returns the run with a key:
222
223 ```typescript title="packages/domain/src/Transfer/TransferExecution.policy.ts"
224 case "TransferApproved":
225 return yield* executions.get(source).signal(Decision, "approved");
226 ```
227
228 The Transfer decides the race between approval and expiry, so there's one source of truth for it. See [Deadlines](/domain/deadlines).
229
230 ## Follow it
231
232 `TransferStatus` is a view of the transfer and both accounts. A client watches it to see the saga finish: the saga reports every step to the Transfer, so the view has everything a client should see.
233
234 ```typescript title="packages/server/test/followTransfer.ts"
235 export const followTransfer = Effect.fn(function* (bank: CustomerClient, transferId: string) {
236 yield* bank.TransferStatus.watch(TransferId.make(transferId)).pipe(
237 Stream.map(({ state }) => state),
238 Stream.takeUntil((status) => status?.completedAt !== null || status?.failedReason !== null),
239 Stream.runForEach((status) =>
240 Effect.log(status === null ? "pending" : TransferStatus.computed.status(status)),
241 ),
242 );
243 });
244 ```
245
246 The saga's own client reads a run too, which suits operators and tests more than apps. `get` returns the run with a key:
247
248 ```typescript
249 const run = executions.get(transferId);
250 const status = yield* run.status;
251 ```
252
253 `status` is `NotStarted`, `Running`, `Completed` with its result, `Rejected` with its rejection, `Interrupted`, or `Died` with a defect. Runs read the same as [Effect workflow runs](/cloudflare/compute/effect-workflows), on every engine.
254
255 ## Test it
256
257 A story runs the whole saga in memory: the request, every step, the compensations, and its status at the end.
258
259 Test what a saga does, not how it's built: the commands its steps send show up as events on the aggregates, and `Story.saga` checks how the run ended, with the same status its run handle reads.
260
261 ```typescript title="packages/domain/test/transfers.test.ts"
262 Story.saga(ExecuteTransfer, transfer, { _tag: "Rejected", rejection: new DestinationClosed() }),
263 ```
264
265 To test a saga on its own, complete what it waits for with `Story.signal`, and move its durable clocks with `Story.clock`:
266
267 ```typescript
268 Story.saga(ExecuteTransfer, transfer, { _tag: "Running" }),
269 Story.signal(ExecuteTransfer, transfer, Decision, "approved"),
270 ```
271
272 A step that calls an external system waits until the story answers the call, as a policy does. A run that dies fails the story, unless a step expects it with `Story.saga(ExecuteTransfer, transfer, { _tag: "Died" })`.
273
274 A saga runs wherever its model runs: in memory in a story, and on [Cloudflare Durable Objects](/domain/cloudflare) in production, with each run's steps stored durably.
275
276 Next, [External System](/domain/external-system): how the model talks to the world outside it.