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, 06:00 UTC
| 1 | --- |
| 2 | title: Deadlines |
| 3 | description: Give a waiting process a time limit with a scheduled command, and let the aggregate decide whether the deadline or the action wins. |
| 4 | --- |
| 5 | |
| 6 | import DAG from "../../../components/DAG.astro"; |
| 7 | |
| 8 | A saga that waits needs a deadline. A large transfer waits for a support agent's approval, and expires if nobody approves it within 24 hours. Schedule a command for the deadline, and let the aggregate decide whichever comes first. |
| 9 | |
| 10 | ## Declare a command that reports the deadline |
| 11 | |
| 12 | A scheduled command fires when nobody is waiting for its answer, so it never rejects. It reports a fact, and records nothing when the fact no longer applies. |
| 13 | |
| 14 | ```typescript |
| 15 | // packages/domain/src/Transfer/ExpireTransfer.command.ts |
| 16 | import * as Domain from "@alchemy.run/domain"; |
| 17 | import { TransferFailed } from "./FailTransfer.command.ts"; |
| 18 | import { TransferId } from "./Transfer.id.ts"; |
| 19 | |
| 20 | /** |
| 21 | * The approval window closed. Scheduled by `TransferApprovalDeadline`; it |
| 22 | * reports a fact, so it never rejects, and it records nothing if the transfer |
| 23 | * was approved in time. |
| 24 | */ |
| 25 | export class ExpireTransfer extends Domain.Command("ExpireTransfer", { |
| 26 | target: TransferId, |
| 27 | events: [TransferFailed], |
| 28 | }) {} |
| 29 | ``` |
| 30 | |
| 31 | ## Schedule it |
| 32 | |
| 33 | A policy schedules the command when the waiting starts. |
| 34 | |
| 35 | ```typescript |
| 36 | // packages/domain/src/Transfer/TransferApprovalDeadline.policy.ts |
| 37 | import * as Domain from "@alchemy.run/domain"; |
| 38 | import * as Effect from "effect/Effect"; |
| 39 | import { ExpireTransfer } from "./ExpireTransfer.command.ts"; |
| 40 | import { TransferRequested } from "./RequestTransfer.command.ts"; |
| 41 | import { Transfer } from "./Transfer.aggregate.ts"; |
| 42 | |
| 43 | /** How long a support agent has to approve a large transfer. */ |
| 44 | export const APPROVAL_WINDOW = "24 hours"; |
| 45 | |
| 46 | /** |
| 47 | * Whenever a transfer needs approval, expire it if nobody approves it in time. |
| 48 | * The Transfer decides the race: approval and expiry are commands on the same |
| 49 | * instance, so exactly one of them wins. |
| 50 | */ |
| 51 | export class TransferApprovalDeadline extends Domain.Policy("TransferApprovalDeadline", { |
| 52 | from: Transfer, |
| 53 | on: [TransferRequested], |
| 54 | }) {} |
| 55 | |
| 56 | export const TransferApprovalDeadlineLive = TransferApprovalDeadline.toLayer( |
| 57 | Effect.gen(function* () { |
| 58 | const transfers = yield* Transfer; |
| 59 | return Effect.fn(function* ({ source, event }) { |
| 60 | if (!event.needsApproval) return; |
| 61 | yield* transfers.schedule(source, new ExpireTransfer(), { after: APPROVAL_WINDOW }).pipe( |
| 62 | // A redelivery after the window closed: the expiry already ran. |
| 63 | Effect.catchTag("AlreadyExecuted", () => Effect.void), |
| 64 | ); |
| 65 | }); |
| 66 | }), |
| 67 | ); |
| 68 | ``` |
| 69 | |
| 70 | The schedule is durable: it fires even if everything restarted in between. Scheduling again with the same command id replaces the earlier one. |
| 71 | |
| 72 | A scheduled command takes its command id like any other command, so it runs once. Scheduling an id the transfer already handled fails with `AlreadyExecuted`, because that command would never run again. Here it means the policy ran a second time for the same event, after the expiry fired, so there's nothing to do. |
| 73 | |
| 74 | ## Let the aggregate decide the race |
| 75 | |
| 76 | Approval and expiry are both commands to the same transfer. One may come from a support agent at any moment, the other from the schedule after 24 hours. |
| 77 | |
| 78 | <DAG |
| 79 | nodes={[ |
| 80 | { id: "agent", label: "Support agent", type: "approves", kind: "client", col: 0, row: 0 }, |
| 81 | { id: "schedule", label: "Schedule", type: "set by the policy", col: 0, row: 2 }, |
| 82 | { id: "approve", label: "ApproveTransfer", type: "any time", kind: "command", col: 1, row: 0 }, |
| 83 | { id: "expire", label: "ExpireTransfer", type: "after 24 hours", kind: "command", col: 1, row: 2 }, |
| 84 | { id: "transfer", label: "Transfer", type: "one at a time", kind: "aggregate", col: 2, row: 1 }, |
| 85 | ]} |
| 86 | edges={[ |
| 87 | { from: "agent", to: "approve" }, |
| 88 | { from: "schedule", to: "expire", dashed: true }, |
| 89 | { from: "approve", to: "transfer" }, |
| 90 | { from: "expire", to: "transfer" }, |
| 91 | ]} |
| 92 | caption="Both commands reach the same transfer, which handles one at a time." |
| 93 | /> |
| 94 | |
| 95 | The transfer handles one command at a time, so whichever arrives first changes its state, and its `decide` turns the other away. Approval is only accepted while the transfer is awaiting approval: |
| 96 | |
| 97 | ```typescript title="packages/domain/src/Transfer/Transfer.aggregate.ts" |
| 98 | ApproveTransfer: Effect.fn(function* (s, _, { id }) { |
| 99 | const approvedBy = yield* CurrentActor; |
| 100 | if (approvedBy._tag !== "Agent") return yield* new NotPermitted(); |
| 101 | if (s._tag !== "AwaitingApproval") return yield* new NotAwaitingApproval(); |
| 102 | ``` |
| 103 | |
| 104 | Expiry fails the transfer only if it's still waiting, and records nothing otherwise: |
| 105 | |
| 106 | ```typescript title="packages/domain/src/Transfer/Transfer.aggregate.ts" |
| 107 | ExpireTransfer: (s, _, { id }) => |
| 108 | s._tag === "AwaitingApproval" |
| 109 | ? [new TransferFailed({ transferId: id, reason: "not approved in time" })] |
| 110 | : [], |
| 111 | ``` |
| 112 | |
| 113 | So an approved transfer ignores its expiry, and an expired transfer rejects a late approval with `NotAwaitingApproval`. |
| 114 | |
| 115 | ## Cancel it |
| 116 | |
| 117 | When the deadline no longer applies, cancel it. Schedule the command with a command id you can name again, and unschedule it by that id: |
| 118 | |
| 119 | ```typescript |
| 120 | // when the waiting starts |
| 121 | yield* transfers.schedule(source, new ExpireTransfer(), { |
| 122 | after: APPROVAL_WINDOW, |
| 123 | commandId: `expire:${source.id}`, |
| 124 | }); |
| 125 | |
| 126 | // when the transfer is approved |
| 127 | yield* transfers.unschedule(source, `expire:${source.id}`); |
| 128 | ``` |
| 129 | |
| 130 | `schedule` returns a `ScheduleReceipt` with the command id and when the command is due (`at`), so code that schedules without its own id can still cancel by `receipt.commandId`. |
| 131 | |
| 132 | Unscheduling is durable, like scheduling. Once it succeeds, the command never fires, even when a story's clock passes its time. When there was nothing to cancel, it fails and says why: `AlreadyExecuted` when the command already ran, `AlreadyCancelled` when it was cancelled before, and `NotScheduled` when nothing was scheduled with that id. |
| 133 | |
| 134 | A policy cancels after the approval is recorded, so the expiry can still arrive in between. Keep the guard in `decide` for that case. A policy can also run again for the same event, and then finds the expiry already cancelled: |
| 135 | |
| 136 | ```typescript |
| 137 | yield* transfers.unschedule(source, `expire:${source.id}`).pipe( |
| 138 | Effect.catchTag(["AlreadyExecuted", "AlreadyCancelled"], () => Effect.void), |
| 139 | ); |
| 140 | ``` |
| 141 | |
| 142 | ## Test it with the clock |
| 143 | |
| 144 | A story has its own clock. `Story.clock` moves it, and any scheduled command that's now due fires. |
| 145 | |
| 146 | ```typescript title="packages/domain/test/deadlines.test.ts" |
| 147 | // A minute before the deadline, nothing has happened. |
| 148 | Story.clock("2026-01-02T08:59:00Z"), |
| 149 | Story.then(transfer), |
| 150 | // At the deadline, the transfer expires. |
| 151 | Story.clock("2026-01-02T09:00:00Z"), |
| 152 | Story.then(transfer, new TransferFailed({ transferId: transfer.id, reason: "not approved in time" })), |
| 153 | // Approval now comes too late. |
| 154 | Story.provide(CurrentActor, agent("support-7")), |
| 155 | Story.when(transfer, new ApproveTransfer()), |
| 156 | Story.rejected(new NotAwaitingApproval()), |
| 157 | ``` |
| 158 | |
| 159 | `Story.then(transfer)` with no events checks that nothing new was recorded. |
| 160 | |
| 161 | :::note |
| 162 | Scheduling is covered in [Command](/domain/command#send-it-later). A [saga](/domain/saga) waits for the decision. |
| 163 | ::: |