The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: 2.0.0-beta.85 - Effect 4.1, Domain Replay & DynamoDB State |
| 3 | date: 2026-11-01T09:00:00Z |
| 4 | category: release |
| 5 | excerpt: Effect 4.1, Alchemy Domain deploys that backfill and rebuild views and projections, Domain models served over HTTP, MCP and the CLI, redesigned Cloud Run containers and keyless AWS↔GCP bindings, custom domains with any DNS provider, DynamoDB state, Alchemist, the @alchemy.run/test runner, and 95 bug fixes. |
| 6 | --- |
| 7 | |
| 8 | import BackfillFanout from "../../../components/blog/BackfillFanout.astro"; |
| 9 | import BoundedContext from "../../../components/blog/BoundedContext.astro"; |
| 10 | |
| 11 | beta.85 is 249 pull requests from 39 contributors: 84 features and 95 bug |
| 12 | fixes. |
| 13 | |
| 14 | It moves Alchemy to **Effect 4.1**. Alchemy Domain's deploys now **roll out |
| 15 | every model change** by replaying history, and one Domain model can be served |
| 16 | **over HTTP, MCP or the CLI**, so people and agents reach it however they |
| 17 | prefer. GCP gets **redesigned Cloud Run services and containers** and **connects to AWS |
| 18 | without keys**. Custom domains work with **any DNS provider**, the |
| 19 | **Cloudflare state store** takes its Worker name, account and domain, **AWS |
| 20 | state uses DynamoDB** and plans 270× faster, **Alchemist** exposes the whole CLI |
| 21 | as a programmatic API, and Alchemy's test runner ships as |
| 22 | **`@alchemy.run/test`**. |
| 23 | |
| 24 | :::danger |
| 25 | **Upgrade the Cloudflare state store to v8, and don't go back** |
| 26 | |
| 27 | Your next `alchemy deploy` asks to upgrade the store (pass `--yes` in CI). After |
| 28 | that, don't run an older Alchemy against it: you risk losing the encryption key, |
| 29 | which nothing can recover. Upgrade every machine and CI job together |
| 30 | ([below](#cloudflare-state-store-v8)). |
| 31 | ::: |
| 32 | |
| 33 | :::caution |
| 34 | **Breaking changes** |
| 35 | |
| 36 | - **Effect 4.1**: bump `effect` and `@effect/*` to `^4.1.0` ([below](#effect-41)). |
| 37 | - **`Cloudflare.state({ name })` is `workerName`**, the store's full Worker name, and `--name` takes the Worker name too: `name: "team-a"` becomes `workerName: "alchemy-state-store-team-a"`, the same Worker and secrets ([below](#choose-the-worker-name)). |
| 38 | - **`AWS.state()` uses DynamoDB**: run `alchemy state migrate`, or keep S3 with `AWS.state({ backend: "s3" })` ([below](#aws-state-now-uses-dynamodb-and-plans-270-faster)). |
| 39 | - **Lambda event-source handlers take the Lambda event** instead of a `Stream`, and can return a partial batch response ([below](#lambda-aliases-streaming-and-partial-batch-failures)): |
| 40 | |
| 41 | ```diff lang="typescript" |
| 42 | yield* AWS.SQS.consumeQueueMessages( |
| 43 | - queue, |
| 44 | - (records) => |
| 45 | - records.pipe(Stream.runForEach((record) => Effect.log(record.body))), |
| 46 | + queue, |
| 47 | + Effect.fn(function* (event) { |
| 48 | + for (const record of event.Records) yield* Effect.log(record.body); |
| 49 | + }), |
| 50 | ); |
| 51 | ``` |
| 52 | |
| 53 | - **`Test.make` moved to `@alchemy.run/test`**: `alchemy/Test/Alchemy` is now `@alchemy.run/test/Alchemy`, and the same for `Bun`, `Vitest`, `Core`, `Http` and `TestState` ([#2621](https://github.com/alchemy-run/alchemy/pull/2621)). |
| 54 | - **GCP profiles**: the `env` method is gone, and `gcloud` profiles name a configuration; run `alchemy profile edit --reconfigure GCP` ([#2680](https://github.com/alchemy-run/alchemy/pull/2680)). |
| 55 | - **`GCP.Run.Container` is now a resource**; the container-spec type it named is `GCP.Run.ContainerSpec` ([#2652](https://github.com/alchemy-run/alchemy/pull/2652)). |
| 56 | - **Domain models are upgraded on the next deploy**: their Durable Object classes are renamed after their model, and their data moves with them ([below](#alchemy-upgrades-your-deployed-model)). |
| 57 | - **The Durable Object Domain platform and workflow engine are factories**: `layerDurableObjects()` and `layerDurableObjectEngine()` ([#2601](https://github.com/alchemy-run/alchemy/pull/2601)). |
| 58 | - **Domain clients**: `bank.WithdrawMoney(target, input, options)` ([#2561](https://github.com/alchemy-run/alchemy/pull/2561)); `watch` streams `{ state, cursor }` and `events` ends with `CaughtUp` ([#2579](https://github.com/alchemy-run/alchemy/pull/2579)); `Domain.Api` takes `{ model }` and `api.entries` is `api.serves` ([#2820](https://github.com/alchemy-run/alchemy/pull/2820)); `testClient` is `clientInProcess` ([#2550](https://github.com/alchemy-run/alchemy/pull/2550)). |
| 59 | - **Domain stories**: `externalSystems` is `stub`, `expectCall` is `call`, `resolve` is `succeed`, every call needs a `call` step, and unasserted events fail the story ([how to update](#update-your-stories)). |
| 60 | - **Domain checks**: a command's `target` must be its aggregate's `id` schema ([#2563](https://github.com/alchemy-run/alchemy/pull/2563)), and an adapter returning a value its schema rejects now dies ([#2548](https://github.com/alchemy-run/alchemy/pull/2548)). |
| 61 | - **Cloudflare DNS**: `foundationDns: true` is `nameservers: { type: "cloudflare.advanced" }` ([#2501](https://github.com/alchemy-run/alchemy/pull/2501)). |
| 62 | - **`Cloudflare.Access.Organization`** resets settings your stack doesn't declare ([#2291](https://github.com/alchemy-run/alchemy/pull/2291)). |
| 63 | - **`GCP.SQL.Instance`**: `ipv4Enabled` is `ipConfiguration.ipv4Enabled`, `backupEnabled` is `backup.enabled` ([#2642](https://github.com/alchemy-run/alchemy/pull/2642)). |
| 64 | - **GitHub**: `Ruleset` rules are top-level props ([#2582](https://github.com/alchemy-run/alchemy/pull/2582)), and errors and credentials come from the distilled GitHub SDK ([#2530](https://github.com/alchemy-run/alchemy/pull/2530)). |
| 65 | - **Error fields named `name`** are renamed, mostly to `resourceName` ([#2689](https://github.com/alchemy-run/alchemy/pull/2689)). |
| 66 | - **`--log-ansi` is removed**, and telemetry no longer exports log records ([#2765](https://github.com/alchemy-run/alchemy/pull/2765)). |
| 67 | ::: |
| 68 | |
| 69 | ## Effect 4.1 |
| 70 | |
| 71 | Alchemy now runs on Effect 4.1 |
| 72 | ([#2754](https://github.com/alchemy-run/alchemy/pull/2754)): |
| 73 | |
| 74 | ```sh |
| 75 | bun add effect@^4.1.0 @effect/platform-node@^4.1.0 |
| 76 | ``` |
| 77 | |
| 78 | Effect 4.1 deletes `effect/Crypto`. Its `SecureRandom` and `Digest` services |
| 79 | replace it, and the platform layer provides them, so `StackServices` changes |
| 80 | with it: |
| 81 | |
| 82 | ```diff lang="typescript" |
| 83 | export type StackServices = |
| 84 | | FileSystem |
| 85 | - | Crypto |
| 86 | + | Digest |
| 87 | + | SecureRandom |
| 88 | | Path |
| 89 | ``` |
| 90 | |
| 91 | Foldkit projects need `foldkit@^0.170` and `@foldkit/vite-plugin@^0.29` |
| 92 | ([#2790](https://github.com/alchemy-run/alchemy/pull/2790)). |
| 93 | |
| 94 | ## Alchemy Domain |
| 95 | |
| 96 | Alchemy Domain shipped 30 features this release. Thanks |
| 97 | [Taras Kornichuk](https://github.com/artile), who built most of them! |
| 98 | |
| 99 | ### Deploys roll out every change to a model |
| 100 | |
| 101 | A Domain model's views and projections are derived from its events. Change |
| 102 | the model, and the deploy brings every consumer up to date from the history, |
| 103 | with no script to write |
| 104 | ([#2725](https://github.com/alchemy-run/alchemy/pull/2725), |
| 105 | [#2875](https://github.com/alchemy-run/alchemy/pull/2875)): |
| 106 | |
| 107 | | You change | The deploy | |
| 108 | | --- | --- | |
| 109 | | add a view or projection | feeds it every past event, in the order it was recorded | |
| 110 | | bump a view's `version` | recomputes it, and every view and projection that reads it | |
| 111 | | bump a projection's `version` | runs it again over the whole history | |
| 112 | | list a view as `lazy` | skips the backfill; each key fills itself on first read | |
| 113 | | add a policy | acts on new events only, so the past is never acted on twice | |
| 114 | | remove a view or projection | stops it | |
| 115 | |
| 116 | Adding a view is one line in the model: |
| 117 | |
| 118 | ```typescript |
| 119 | // deploy 1 |
| 120 | class Bank extends Domain.Model("Bank", { aggregates: [Account] }) {} |
| 121 | |
| 122 | // deploy 2: AccountSummary folds every earlier event |
| 123 | class Bank extends Domain.Model("Bank", { |
| 124 | aggregates: [Account], |
| 125 | views: [AccountSummary], |
| 126 | }) {} |
| 127 | ``` |
| 128 | |
| 129 | Changing what a view computes is a version bump: |
| 130 | |
| 131 | ```typescript |
| 132 | export class AccountSummary extends Domain.View("AccountSummary", { |
| 133 | from: [Account], |
| 134 | key: Account, |
| 135 | state: Schema.Struct({ net: Schema.Number }), |
| 136 | initial: { net: 0 }, |
| 137 | evolve: { |
| 138 | MoneyDeposited: (v, e) => ({ net: v.net + e.amount }), |
| 139 | // new: applied to every past withdrawal |
| 140 | MoneyWithdrawn: (v, e) => ({ net: v.net - e.amount }), |
| 141 | }, |
| 142 | version: 1, |
| 143 | }) {} |
| 144 | ``` |
| 145 | |
| 146 | The deploy picks the cheapest correct strategy. A view keyed by the one |
| 147 | aggregate it reads is rebuilt in place: each key re-reads its own |
| 148 | aggregate's events the first time it's touched, so the deploy waits for |
| 149 | nothing. Any other view, such as a total across every account, is rebuilt |
| 150 | from the history in new storage, and the deploy waits and reports progress: |
| 151 | |
| 152 | ```sh |
| 153 | [DomainBackfillRun] Backfilling view:Deposits reading history 41% (1,690/4,096 subtrees, 410,211 instances) (48s) ... |
| 154 | [DomainBackfillRun] Backfilled view:Deposits (112.4s) |
| 155 | ``` |
| 156 | |
| 157 | Reads stay correct while new code rolls out, `history.complete` tells a |
| 158 | screen when a view has caught up, and a deploy interrupted halfway picks up |
| 159 | where it stopped. |
| 160 | |
| 161 | #### How it scales |
| 162 | |
| 163 | On Cloudflare the replay runs as Durable Objects, not on the deploying |
| 164 | machine. Every aggregate instance lists itself in a directory on its first |
| 165 | commit: a tree where each node holds up to 256 instances and splits into 16 |
| 166 | children when it fills. A backfill's root splits that directory into a few |
| 167 | hundred subtrees and hands them to relays. A relay given more than six items |
| 168 | splits them among six child relays. Six because a Cloudflare Worker |
| 169 | invocation runs at most six outgoing calls at a time, so a seventh would only |
| 170 | wait in line. The tree grows deeper instead of wider, about log₆ of the |
| 171 | instance count: 6 levels for 10,000 instances, 8 for a million. |
| 172 | |
| 173 | <BackfillFanout /> |
| 174 | |
| 175 | At the bottom, a view keyed by its aggregate reads its own instance's events |
| 176 | and applies them. A view that many instances feed, like a timeline, gets a |
| 177 | scanner per instance that pushes each key its share; once every scanner has |
| 178 | pushed, each key applies its events in the order they were recorded. Every |
| 179 | part of the run is a class only the new code has, so nothing starts on the |
| 180 | old code while Cloudflare rolls the deploy out. |
| 181 | |
| 182 | We measured it on Cloudflare, rebuilding a view over accounts with 10 |
| 183 | deposits each: |
| 184 | |
| 185 | | Accounts | Events | The deploy waited | |
| 186 | | ---: | ---: | ---: | |
| 187 | | 10,000 | 100,000 | 13 s | |
| 188 | | 100,000 | 1,000,000 | 58 s | |
| 189 | | 1,000,000 | 10,000,000 | 8 min | |
| 190 | |
| 191 | Past about 100,000 accounts the limit isn't the tree but Cloudflare's cap on |
| 192 | how fast one account can create and call Durable Objects. The run paces |
| 193 | itself to that cap the way TCP does: it sends more while the account keeps |
| 194 | up, halves when Cloudflare refuses calls, and resends the refused work. The |
| 195 | million-account run held about 2,000 keys a second. |
| 196 | |
| 197 | Docs: [Consumers added later receive the history](/domain/model#consumers-added-later-receive-the-history) · |
| 198 | [Change a view: bump its version](/domain/model#change-a-view-bump-its-version) · |
| 199 | [Fill a view lazily](/domain/model#fill-a-view-lazily) · |
| 200 | [History at scale](/domain/backfill#width). |
| 201 | |
| 202 | ### Alchemy upgrades your deployed model |
| 203 | |
| 204 | A Domain model is more than code: on Cloudflare it is a set of Durable |
| 205 | Object classes holding every aggregate, view row and running saga. Changing |
| 206 | how those classes are laid out would normally mean a hand-written migration |
| 207 | and a careful cutover. In Alchemy it's part of the deploy. |
| 208 | |
| 209 | From this release, the deployed layout is versioned. Every Worker that hosts |
| 210 | a model records the Domain version it was deployed with, and the Worker's |
| 211 | reconciler upgrades older layouts on the next deploy, renaming classes in |
| 212 | place in the same upload, so no data is copied or lost |
| 213 | ([#2560](https://github.com/alchemy-run/alchemy/pull/2560)). Future layout |
| 214 | changes ship as new upgrade steps in Alchemy, and your deploy applies them. |
| 215 | A Worker deployed by a newer Alchemy is never moved back: an older one |
| 216 | refuses with `DomainVersionTooNew` before uploading anything. |
| 217 | |
| 218 | For the bank example, the first deploy with beta.85 changes the Worker like |
| 219 | this: |
| 220 | |
| 221 | ```diff lang="text" |
| 222 | Worker |
| 223 | - tag (none) |
| 224 | + tag alchemy:domain:v0 |
| 225 | - class AccountAggregate |
| 226 | + class Bank.AccountAggregate |
| 227 | - class OpenAccountWorkflow |
| 228 | + class Bank.OpenAccountWorkflow |
| 229 | ``` |
| 230 | |
| 231 | The renames ride in the same upload as the new code, as Cloudflare |
| 232 | `renamed_classes` migrations, so every account and running saga keeps its |
| 233 | storage and nothing is copied. |
| 234 | |
| 235 | This is what DDD buys you here. Because Alchemy knows the shape of your |
| 236 | model (its aggregates, views and sagas), it can own the infrastructure under |
| 237 | it, and evolve that infrastructure for you the same way it evolves a view. |
| 238 | |
| 239 | :::caution |
| 240 | The first deploy with beta.85 upgrades every Worker that hosts a Domain |
| 241 | model. Its Durable Object classes are renamed after their model, for example |
| 242 | `AccountAggregate` becomes `Bank.AccountAggregate`, and their data moves with |
| 243 | them. |
| 244 | |
| 245 | If two models in one Worker listed the same aggregate, they shared one class |
| 246 | and its data before this release, and the deploy fails with |
| 247 | `AmbiguousDomainLegacyData` until you pick the model that keeps it: |
| 248 | |
| 249 | ```typescript |
| 250 | export const BillingLive = Billing.layer(BillingHandlers, { |
| 251 | legacyData: true, // Billing keeps the shared data; Audit starts empty |
| 252 | }); |
| 253 | ``` |
| 254 | ::: |
| 255 | |
| 256 | Each model now owns its data, so two models that list the same aggregate get |
| 257 | separate instances, even in one Worker. And a model can keep all of it in a |
| 258 | Cloudflare jurisdiction ([#2601](https://github.com/alchemy-run/alchemy/pull/2601)): |
| 259 | |
| 260 | ```typescript |
| 261 | Layer.provide(DomainCloudflare.layerDurableObjects({ jurisdiction: "eu" })); |
| 262 | ``` |
| 263 | |
| 264 | A jurisdiction is part of an object's identity, so a model that already has |
| 265 | data starts empty in its new jurisdiction, and its old objects stay where |
| 266 | they were. |
| 267 | |
| 268 | Docs: [Upgrade without losing data](/domain/cloudflare#upgrade-without-losing-data) · |
| 269 | [Keep the model in a jurisdiction](/domain/cloudflare#keep-the-model-in-a-jurisdiction). |
| 270 | |
| 271 | ### Serve a Domain model over HTTP, MCP or the CLI |
| 272 | |
| 273 | A `Domain.Api` names the parts of a model a client may reach |
| 274 | ([#2820](https://github.com/alchemy-run/alchemy/pull/2820)): |
| 275 | |
| 276 | ```typescript |
| 277 | export class BankApi extends Domain.Api("BankApi", { |
| 278 | model: Bank, |
| 279 | commands: ["DepositMoney", "WithdrawMoney"], |
| 280 | views: ["AccountSummary"], |
| 281 | }) {} |
| 282 | ``` |
| 283 | |
| 284 | <BoundedContext /> |
| 285 | |
| 286 | The same Api can now be served to whoever needs it, through the same |
| 287 | middleware and rejections, so an agent can do exactly what a signed-in |
| 288 | client can and no more. |
| 289 | |
| 290 | As an HTTP JSON API with an OpenAPI document, with live reads as |
| 291 | Server-Sent Events, for partners, scripts and browsers |
| 292 | ([#2587](https://github.com/alchemy-run/alchemy/pull/2587)): |
| 293 | |
| 294 | ```typescript |
| 295 | const BankHttp = DomainHttp.toHttpApi(BankApi); |
| 296 | |
| 297 | export const BankHttpLive = HttpApiBuilder.layer(BankHttp.api, { |
| 298 | openapiPath: "/openapi.json", |
| 299 | }).pipe(Layer.provide(BankHttp.layer), Layer.provide(BankLive)); |
| 300 | ``` |
| 301 | |
| 302 | As an MCP server for agents, or as Effect AI tools for an agent inside your |
| 303 | app ([#2586](https://github.com/alchemy-run/alchemy/pull/2586)): |
| 304 | |
| 305 | ```typescript |
| 306 | export const BankMcp = DomainAi.toMcp(BankApi).pipe( |
| 307 | Layer.provide( |
| 308 | McpServer.layerHttp({ name: "bank", version: "1.0.0", path: "/mcp" }), |
| 309 | ), |
| 310 | Layer.provide(BankLive), |
| 311 | ); |
| 312 | ``` |
| 313 | |
| 314 | As a command-line tool, for people and agents in a terminal |
| 315 | ([#2588](https://github.com/alchemy-run/alchemy/pull/2588)): |
| 316 | |
| 317 | ```sh |
| 318 | $ bank deposit-money --target a-1 --amount 1000 |
| 319 | { "reply": { "balance": 1000 }, "stream": "Account/a-1", "version": 1 } |
| 320 | |
| 321 | $ bank withdraw-money --target a-1 --amount 5000 # exit code 1 |
| 322 | { "_tag": "InsufficientFunds", "balance": 1000, "requested": 5000 } |
| 323 | ``` |
| 324 | |
| 325 | And as Foldkit commands and subscriptions for a web app |
| 326 | ([#2700](https://github.com/alchemy-run/alchemy/pull/2700)). |
| 327 | |
| 328 | Docs: [HTTP API](/domain/http-api) · [MCP](/domain/mcp) · [CLI](/domain/cli) · |
| 329 | [Foldkit](/domain/foldkit). |
| 330 | |
| 331 | ### Stories run real adapters and show what went wrong |
| 332 | |
| 333 | A story tests a model as given, when, then. Stories now tell you exactly |
| 334 | what failed. A failing story prints every step, marked passed, failed or not |
| 335 | run, with the events committed so far |
| 336 | ([#2475](https://github.com/alchemy-run/alchemy/pull/2475)): |
| 337 | |
| 338 | ```typescript |
| 339 | yield* story( |
| 340 | Story.clock("2026-03-01T09:00:00Z"), |
| 341 | Story.given(c1, new Incremented({ by: 2, total: 2 })), |
| 342 | Story.when(c1, new Increment({ by: 3 })), |
| 343 | Story.then(c1, new Incremented({ by: 4, total: 6 })), |
| 344 | Story.replied({ total: 6 }), |
| 345 | ); |
| 346 | ``` |
| 347 | |
| 348 | ```text |
| 349 | StoryFailure: Then: on Counter/c-1 |
| 350 | |
| 351 | ✓ 1 Clock 2026-03-01T09:00:00.000Z |
| 352 | ✓ 2 Given Counter/c-1: Incremented { by: 2, total: 2 } |
| 353 | ✓ 3 When Counter/c-1: Increment { by: 3 } |
| 354 | ✗ 4 Then Counter/c-1: expected Incremented { by: 4, total: 6 } |
| 355 | got Incremented { by: 3, total: 5 } |
| 356 | 5 Replied { total: 6 } |
| 357 | events so far |
| 358 | Counter/c-1: Incremented → Incremented |
| 359 | ``` |
| 360 | |
| 361 | A story also fails on any event a command or policy committed that no step |
| 362 | asserts, on every stream, so a side effect can't slip past it |
| 363 | ([#2551](https://github.com/alchemy-run/alchemy/pull/2551)): |
| 364 | |
| 365 | ```text |
| 366 | StoryFailure: committed events no step asserts (assert them with then): |
| 367 | Counter/c-1: Capped (from step 4) |
| 368 | ``` |
| 369 | |
| 370 | Steps type-check against the last command, so a rejection it can't return, |
| 371 | or a reply it doesn't give, is a compile error instead of a failing run |
| 372 | ([#2559](https://github.com/alchemy-run/alchemy/pull/2559)): |
| 373 | |
| 374 | ```typescript |
| 375 | story( |
| 376 | Story.when(c1, new Increment({ by: 1 })), |
| 377 | Story.rejected(new NotAnOperator()), |
| 378 | // Type 'RejectedStep<NotAnOperator>' is not assignable to type |
| 379 | // '"Increment does not reject with NotAnOperator"'. |
| 380 | ); |
| 381 | ``` |
| 382 | |
| 383 | Time moves with `Story.advance`, and scheduled commands fire when they come |
| 384 | due ([#2629](https://github.com/alchemy-run/alchemy/pull/2629)): |
| 385 | |
| 386 | ```typescript |
| 387 | story( |
| 388 | Story.when(c1, new Cap()), |
| 389 | Story.then(c1, new Capped()), |
| 390 | Story.advance("1 hour"), |
| 391 | Story.then(c1, new Reminded()), // the scheduled reminder fired |
| 392 | ); |
| 393 | ``` |
| 394 | |
| 395 | Stories also changed how external systems are tested. Before, every |
| 396 | external system a story listed was scripted, and nothing outside the model |
| 397 | ran. Now you choose which systems to fake with `stub`, and the rest run for |
| 398 | real through the adapter Layers you provide |
| 399 | ([#2477](https://github.com/alchemy-run/alchemy/pull/2477), |
| 400 | [#2481](https://github.com/alchemy-run/alchemy/pull/2481)). |
| 401 | |
| 402 | Either way, every call is asserted. `Story.call` checks what the model sent, |
| 403 | and the next step settles how the call ended. For a stubbed system, that |
| 404 | step supplies the answer. For a real one, it checks the answer the adapter |
| 405 | gave: |
| 406 | |
| 407 | ```typescript |
| 408 | // FraudCheck is stubbed: the story supplies its answer |
| 409 | Story.call(FraudCheck.score, { accountId: account.id, amount: 60_000 }), |
| 410 | Story.succeed(FraudCheck.score, { risk: 0.95 }), |
| 411 | |
| 412 | // Payments runs for real: the story checks what the adapter returned |
| 413 | Story.call(Payments.refund, { settlementId: "st_1", amount: 500 }), |
| 414 | Story.returned(Payments.refund, { refundId: "re_st_1" }), |
| 415 | ``` |
| 416 | |
| 417 | | | Stubbed (`stub: [...]`) | Real (adapter Layer provided) | |
| 418 | | --- | --- | --- | |
| 419 | | what was sent | `Story.call` | `Story.call` | |
| 420 | | success | `Story.succeed` supplies the value | `Story.returned` asserts the value | |
| 421 | | declared error | `Story.fail` supplies it | `Story.failed` asserts it | |
| 422 | | defect | `Story.die` supplies it | `Story.died` asserts it | |
| 423 | |
| 424 | A real call that no step asserts fails the story, so nothing an adapter does |
| 425 | goes unchecked. Supplied answers are checked against the operation's schemas, like |
| 426 | a real adapter's ([#2548](https://github.com/alchemy-run/alchemy/pull/2548)), |
| 427 | and a story that leaves a system unstubbed requires its adapter Layer in its |
| 428 | type: |
| 429 | |
| 430 | ```typescript |
| 431 | const story = Story.make(Bank, { layer: BankHandlers, stub: [FraudCheck] }); |
| 432 | |
| 433 | it.effect("refunds through the real payments adapter", () => |
| 434 | story( |
| 435 | Story.when( |
| 436 | account, |
| 437 | new RecordSettlement({ settlementId: "st_1", amount: 500 }), |
| 438 | ), |
| 439 | Story.then( |
| 440 | account, |
| 441 | new SettlementOnClosedAccount({ settlementId: "st_1", amount: 500 }), |
| 442 | ), |
| 443 | Story.call(Payments.refund, { settlementId: "st_1", amount: 500 }), |
| 444 | Story.returned(Payments.refund, { refundId: "re_st_1" }), |
| 445 | ).pipe(Effect.provide(StripePayments)), // required: Payments isn't stubbed |
| 446 | ); |
| 447 | ``` |
| 448 | |
| 449 | #### Update your stories |
| 450 | |
| 451 | Rename the options and steps: |
| 452 | |
| 453 | ```diff lang="typescript" |
| 454 | const story = Story.make(Bank, { |
| 455 | layer: BankHandlers, |
| 456 | - externalSystems: [FraudCheck, Payments], |
| 457 | + stub: [FraudCheck, Payments], |
| 458 | }); |
| 459 | |
| 460 | story( |
| 461 | Story.when(account, new WithdrawMoney({ amount: 60_000 })), |
| 462 | - Story.expectCall(FraudCheck.score, { amount: 60_000 }), |
| 463 | - Story.resolve(FraudCheck.score, { risk: 0.95 }), |
| 464 | + Story.call(FraudCheck.score, { amount: 60_000 }), |
| 465 | + Story.succeed(FraudCheck.score, { risk: 0.95 }), |
| 466 | ); |
| 467 | ``` |
| 468 | |
| 469 | Then fix what the stricter checks now catch: |
| 470 | |
| 471 | - **Every call needs a `Story.call` step**, stubbed or real. Before, a bare `resolve` answered the only pending call; now each answer follows the `call` that checks what was sent. |
| 472 | - **List every system you want faked in `stub`.** A system left out runs for real, and the story's type requires its adapter Layer. |
| 473 | - **Assert every committed event.** A story fails on events no `then` asserts, including ones a policy writes on other instances. Add a `Story.then` for each. |
| 474 | - **Answer with values the schema accepts.** A stubbed answer the operation's success schema rejects now fails the policy. |
| 475 | - **Move the clock forward only.** A `Story.clock` earlier than the current time, or a string that isn't a time, now fails the story ([#2564](https://github.com/alchemy-run/alchemy/pull/2564)). |
| 476 | - **Use `clientInProcess` for Api tests.** `CustomerApi.testClient` is now `CustomerApi.clientInProcess` ([#2550](https://github.com/alchemy-run/alchemy/pull/2550)). |
| 477 | |
| 478 | Docs: [Story](/domain/story) · |
| 479 | [Answer outside systems](/domain/testing-models#answer-outside-systems) · |
| 480 | [Assert real calls](/domain/testing-models#assert-real-calls). |
| 481 | |
| 482 | ## GCP |
| 483 | |
| 484 | ### Cloud Run services and containers, redesigned |
| 485 | |
| 486 | A Cloud Run service runs one or more containers in each instance. The first |
| 487 | takes requests, and the rest run beside it on `localhost`. Cloud Run in |
| 488 | Alchemy was rebuilt around that model. Any container can be an image or your |
| 489 | own Effect program, and a container lists or binds the ones it needs |
| 490 | ([#2644](https://github.com/alchemy-run/alchemy/pull/2644), |
| 491 | [#2652](https://github.com/alchemy-run/alchemy/pull/2652), |
| 492 | [#2654](https://github.com/alchemy-run/alchemy/pull/2654), |
| 493 | [#2657](https://github.com/alchemy-run/alchemy/pull/2657)). |
| 494 | |
| 495 | #### One container |
| 496 | |
| 497 | A service starts as a single image: |
| 498 | |
| 499 | ```typescript |
| 500 | // alchemy.run.ts |
| 501 | import * as Alchemy from "alchemy"; |
| 502 | import * as GCP from "@alchemy.run/gcp"; |
| 503 | import * as Effect from "effect/Effect"; |
| 504 | |
| 505 | export default Alchemy.Stack( |
| 506 | "MyApp", |
| 507 | { providers: GCP.providers(), state: GCP.state() }, |
| 508 | Effect.gen(function* () { |
| 509 | const proxy = yield* GCP.Run.Service("Proxy", { |
| 510 | template: { |
| 511 | containers: [ |
| 512 | { |
| 513 | image: "us-docker.pkg.dev/cloudrun/container/hello", |
| 514 | ports: [{ containerPort: 8080 }], |
| 515 | }, |
| 516 | ], |
| 517 | }, |
| 518 | }); |
| 519 | return { url: proxy.uri }; |
| 520 | }), |
| 521 | ); |
| 522 | ``` |
| 523 | |
| 524 | #### Add a sidecar |
| 525 | |
| 526 | `GCP.Run.Container` declares a container as a resource. List it after the |
| 527 | first one, and `dependsOn` holds the proxy back until the cache passes its |
| 528 | startup probe: |
| 529 | |
| 530 | ```diff lang="typescript" |
| 531 | Effect.gen(function* () { |
| 532 | + const cache = yield* GCP.Run.Container("Cache", { |
| 533 | + image: "docker.io/library/redis:7-alpine", |
| 534 | + port: 6379, |
| 535 | + startupProbe: { tcpSocket: {} }, |
| 536 | + }); |
| 537 | const proxy = yield* GCP.Run.Service("Proxy", { |
| 538 | template: { |
| 539 | containers: [ |
| 540 | { |
| 541 | image: "us-docker.pkg.dev/cloudrun/container/hello", |
| 542 | ports: [{ containerPort: 8080 }], |
| 543 | + dependsOn: [cache.name], |
| 544 | }, |
| 545 | + cache, |
| 546 | ], |
| 547 | }, |
| 548 | }); |
| 549 | return { url: proxy.uri }; |
| 550 | }), |
| 551 | ``` |
| 552 | |
| 553 | A plain container spec works in the list too. Every container takes |
| 554 | `startupProbe`, `livenessProbe` and `dependsOn`. |
| 555 | |
| 556 | #### Run your own program |
| 557 | |
| 558 | Give the service `main` and an Effect, and Alchemy bundles your program into |
| 559 | the first container. An Effect service binds its sidecars instead of listing |
| 560 | them. `bindPort` adds the Cache to the revision, makes the service wait for |
| 561 | it, and returns its address: |
| 562 | |
| 563 | ```typescript |
| 564 | // src/api.ts |
| 565 | import * as GCP from "@alchemy.run/gcp"; |
| 566 | import * as Effect from "effect/Effect"; |
| 567 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 568 | |
| 569 | export const Cache = GCP.Run.Container("Cache", { |
| 570 | image: "docker.io/library/redis:7-alpine", |
| 571 | port: 6379, |
| 572 | startupProbe: { tcpSocket: {} }, |
| 573 | }); |
| 574 | |
| 575 | export default class Api extends GCP.Run.Service<Api>()( |
| 576 | "Api", |
| 577 | { main: import.meta.url }, |
| 578 | Effect.gen(function* () { |
| 579 | const cache = yield* GCP.Run.bindPort(Cache, 6379); |
| 580 | // cache.url === "http://localhost:6379" |
| 581 | return { |
| 582 | fetch: Effect.succeed(HttpServerResponse.text("hello")), |
| 583 | }; |
| 584 | }), |
| 585 | ) {} |
| 586 | ``` |
| 587 | |
| 588 | #### Run your own program in a sidecar |
| 589 | |
| 590 | A Container with `main` runs your Effect program in its own image. Its |
| 591 | methods become a typed client for whoever binds it, called over `localhost`, |
| 592 | streams included. A program Container binds sidecars of its own: |
| 593 | |
| 594 | ```typescript |
| 595 | // src/worker.ts |
| 596 | import * as GCP from "@alchemy.run/gcp"; |
| 597 | import * as Effect from "effect/Effect"; |
| 598 | import * as Stream from "effect/Stream"; |
| 599 | import * as HttpServerResponse from "effect/http/HttpServerResponse"; |
| 600 | import { Cache } from "./api.ts"; |
| 601 | |
| 602 | export default class Worker extends GCP.Run.Container<Worker>()( |
| 603 | "Worker", |
| 604 | { |
| 605 | main: import.meta.url, |
| 606 | port: 3000, |
| 607 | startupProbe: { httpGet: { path: "/health" } }, |
| 608 | }, |
| 609 | Effect.gen(function* () { |
| 610 | const cache = yield* GCP.Run.bindPort(Cache, 6379); |
| 611 | return { |
| 612 | greet: (name: string) => Effect.succeed(`hello ${name}`), |
| 613 | count: () => Stream.make(1, 2, 3), |
| 614 | fetch: Effect.succeed(HttpServerResponse.text("ok")), |
| 615 | }; |
| 616 | }), |
| 617 | ) {} |
| 618 | ``` |
| 619 | |
| 620 | The service binds the Worker with `bindContainer` and calls its methods: |
| 621 | |
| 622 | ```diff lang="typescript" |
| 623 | // src/api.ts |
| 624 | +import Worker from "./worker.ts"; |
| 625 | |
| 626 | export default class Api extends GCP.Run.Service<Api>()( |
| 627 | "Api", |
| 628 | { main: import.meta.url }, |
| 629 | Effect.gen(function* () { |
| 630 | - const cache = yield* GCP.Run.bindPort(Cache, 6379); |
| 631 | + const worker = yield* GCP.Run.bindContainer(Worker); |
| 632 | return { |
| 633 | - fetch: Effect.succeed(HttpServerResponse.text("hello")), |
| 634 | + fetch: worker.greet("sam").pipe(Effect.map(HttpServerResponse.text)), |
| 635 | }; |
| 636 | }), |
| 637 | ) {} |
| 638 | ``` |
| 639 | |
| 640 | Bindings chain, so one revision now runs three containers and starts them in |
| 641 | order: |
| 642 | |
| 643 | ```text |
| 644 | revision |
| 645 | ├── start Cache → TCP :6379 |
| 646 | ├── start Worker (dependsOn Cache) → GET :3000/health |
| 647 | ├── start Api (dependsOn Worker) → GET :8080/health |
| 648 | └── Ready → traffic to Api |
| 649 | ``` |
| 650 | |
| 651 | A service that runs an image lists its containers; a service or Container |
| 652 | that runs your program binds them, which gives it a client and orders startup |
| 653 | for it. |
| 654 | |
| 655 | Docs: [Sidecars](/gcp/compute/sidecars) · [Cloud Run](/gcp/compute/cloud-run). |
| 656 | |
| 657 | ### Call private Cloud Run services |
| 658 | |
| 659 | `InvokeService` calls the methods of a private Cloud Run service, signed with |
| 660 | the caller's ID token, with types taken from the service class |
| 661 | ([#2653](https://github.com/alchemy-run/alchemy/pull/2653)): |
| 662 | |
| 663 | ```typescript |
| 664 | export default class Quotes extends GCP.Run.Service<Quotes>()( |
| 665 | "Quotes", |
| 666 | { main: import.meta.url }, // the IAM invoker check stays on |
| 667 | Effect.gen(function* () { |
| 668 | return { |
| 669 | quote: (symbol: string) => Effect.succeed({ symbol, price: 42 }), |
| 670 | ticks: (symbol: string) => Stream.make(41, 42, 43), |
| 671 | }; |
| 672 | }), |
| 673 | ) {} |
| 674 | |
| 675 | // in another service |
| 676 | const quotes = yield* GCP.Run.InvokeService(Quotes); |
| 677 | const { price } = yield* quotes.quote("GOOG"); |
| 678 | ``` |
| 679 | |
| 680 | Pass an Effect RPC `schema` or an HttpApi `api` to `InvokeService` or |
| 681 | `bindContainer` for a client with typed errors, and serve it with |
| 682 | `ServeRpc` or `ServeHttpApi` |
| 683 | ([#2654](https://github.com/alchemy-run/alchemy/pull/2654)): |
| 684 | |
| 685 | ```typescript |
| 686 | const tasks = yield* GCP.Run.InvokeService(TaskBackend, { schema: TaskRpcs }); |
| 687 | // Effect<Task, TaskNotFound | …> |
| 688 | const task = yield* tasks.getTask({ id: "t1" }); |
| 689 | ``` |
| 690 | |
| 691 | A service that returns methods but turns off the invoker check fails to |
| 692 | deploy, so RPC methods are never public by accident. |
| 693 | |
| 694 | Docs: [Call it from another service](/gcp/apis/effect-rpc#call-it-from-another-service) · |
| 695 | [Run it as a sidecar](/gcp/apis/effect-rpc#run-it-as-a-sidecar). |
| 696 | |
| 697 | ### Connect AWS and GCP without keys |
| 698 | |
| 699 | A GCP binding on a Lambda, ECS task, EC2 instance or App Runner service no |
| 700 | longer creates a service account key. The host's IAM role impersonates the |
| 701 | service account through workload identity federation |
| 702 | ([#2648](https://github.com/alchemy-run/alchemy/pull/2648)). Your code |
| 703 | doesn't change: |
| 704 | |
| 705 | ```typescript |
| 706 | export default Worker.make( |
| 707 | { main: import.meta.url, functionUrl: true }, |
| 708 | Effect.gen(function* () { |
| 709 | const publish = yield* GCP.PubSub.Publish(yield* Events); |
| 710 | return { |
| 711 | fetch: publish({ body: { messages: [{ data: btoa("hello") }] } }).pipe( |
| 712 | Effect.as(HttpServerResponse.text("published")), |
| 713 | ), |
| 714 | }; |
| 715 | }).pipe(Effect.provide(GCP.PubSub.PublishHttp)), |
| 716 | ); |
| 717 | ``` |
| 718 | |
| 719 | ```diff lang="text" |
| 720 | WorkerServiceAccount GCP.IAM.ServiceAccount |
| 721 | -WorkerServiceAccountKey GCP.IAM.ServiceAccountKey |
| 722 | +AwsWorkloadIdentityPool GCP.IAM.WorkloadIdentityPool |
| 723 | +AwsWorkloadIdentityProvider GCP.IAM.WorkloadIdentityProvider |
| 724 | +WorkerWorkloadIdentityUser GCP.IAM.Member |
| 725 | ``` |
| 726 | |
| 727 | The other direction works the same way: Cloud Run and Cloud Functions assume |
| 728 | their AWS role with a Google ID token, with no IAM user or access key |
| 729 | ([#2645](https://github.com/alchemy-run/alchemy/pull/2645)). |
| 730 | `WorkloadIdentityPool` and `WorkloadIdentityProvider` are resources too, for |
| 731 | keyless CI from GitHub Actions or any OIDC issuer |
| 732 | ([#2130](https://github.com/alchemy-run/alchemy/pull/2130)). |
| 733 | |
| 734 | Docs: [GCP federated identity](/gcp/security/federated-identity) · |
| 735 | [AWS federated identity](/aws/security/federated-identity). |
| 736 | |
| 737 | ### Migrations on Cloud SQL, AlloyDB and Spanner |
| 738 | |
| 739 | Every GCP SQL database applies `migrations` on deploy, like D1, Neon, |
| 740 | PlanetScale, Turso, RDS and DSQL |
| 741 | ([#2651](https://github.com/alchemy-run/alchemy/pull/2651)): |
| 742 | |
| 743 | ```typescript |
| 744 | const db = yield* GCP.SQL.Database("App", { |
| 745 | instance: instance.instanceName, |
| 746 | migrations: "./migrations", |
| 747 | migrationsUser: user.userName, |
| 748 | migrationsPassword: password.text, |
| 749 | }); |
| 750 | ``` |
| 751 | |
| 752 | Cloud SQL runs them over its data API by default, which needs no network |
| 753 | route, or through the Cloud SQL connector. Spanner resumes a failed |
| 754 | migration at the statement that failed. `GCP.SQL.Instance` can now be |
| 755 | private-IP only, with SSL mode and backup retention in the stack |
| 756 | ([#2642](https://github.com/alchemy-run/alchemy/pull/2642)), and Pub/Sub |
| 757 | subscriptions write straight into BigQuery |
| 758 | ([#2213](https://github.com/alchemy-run/alchemy/pull/2213)). Thanks |
| 759 | [Lucas Duailibe](https://github.com/duailibe)! |
| 760 | |
| 761 | Docs: [Cloud SQL](/gcp/data/cloud-sql). |
| 762 | |
| 763 | ### Sign in with gcloud |
| 764 | |
| 765 | A GCP profile signs in through a named gcloud configuration, the way an AWS |
| 766 | profile uses `aws sso login` |
| 767 | ([#2635](https://github.com/alchemy-run/alchemy/pull/2635), |
| 768 | [#2680](https://github.com/alchemy-run/alchemy/pull/2680)): |
| 769 | |
| 770 | ```sh |
| 771 | gcloud auth login --configuration=work |
| 772 | alchemy profile edit --add GCP --method gcloud --set configuration=work |
| 773 | ``` |
| 774 | |
| 775 | `alchemy profile edit --add GCP` lists your configurations, or creates one |
| 776 | and opens the browser. Each run asks gcloud for a fresh token, and nothing is |
| 777 | copied into the profile. Signed in as yourself, you can also create projects |
| 778 | without an organization or folder |
| 779 | ([#2616](https://github.com/alchemy-run/alchemy/pull/2616)). |
| 780 | |
| 781 | Docs: [GCP credentials](/gcp/setup#credentials). |
| 782 | |
| 783 | ## Custom domains with any DNS provider |
| 784 | |
| 785 | A custom domain's DNS no longer has to live with the platform that serves |
| 786 | it. `domain.dns` names the DNS provider that holds the records, on every |
| 787 | platform ([#1888](https://github.com/alchemy-run/alchemy/pull/1888)): |
| 788 | |
| 789 | ```typescript |
| 790 | yield* AWS.Lambda.Function("Api", { |
| 791 | main: "./src/handler.ts", |
| 792 | domain: { |
| 793 | name: "api.example.com", |
| 794 | dns: Cloudflare.DNS.Adapter(), |
| 795 | }, |
| 796 | }); |
| 797 | |
| 798 | yield* Cloudflare.Worker("Web", { |
| 799 | main: "./src/web.ts", |
| 800 | domain: { |
| 801 | name: "app.example.com", |
| 802 | zoneId: saasZone.zoneId, |
| 803 | cnameTarget: fallback.origin, |
| 804 | dns: AWS.Route53.Adapter(), |
| 805 | }, |
| 806 | }); |
| 807 | |
| 808 | yield* Fly.Website.Vite("Docs", { |
| 809 | domain: { |
| 810 | name: "docs.example.com", |
| 811 | dns: Hetzner.DNS.Adapter(), |
| 812 | }, |
| 813 | }); |
| 814 | ``` |
| 815 | |
| 816 | Alchemy publishes whatever the platform asks for: certificate validation |
| 817 | records, ACME challenges, verification TXTs and aliases. Cloudflare, Route |
| 818 | 53 and Hetzner adapters ship today, and an adapter for another DNS provider |
| 819 | is three functions. Thanks [Dan Myles](https://github.com/dan-myles) and |
| 820 | [bjorntechTobbe](https://github.com/bjorntechTobbe)! |
| 821 | |
| 822 | Docs: [DNS adapters](/infrastructure-as-code/dns-adapters). |
| 823 | |
| 824 | ## Cloudflare State Store v8 |
| 825 | |
| 826 | The Cloudflare state store is now deployed with direct API calls instead of a |
| 827 | stack, as state store v8, and you choose its Worker name, account and domain |
| 828 | ([#2385](https://github.com/alchemy-run/alchemy/pull/2385)). |
| 829 | |
| 830 | ### Choose the Worker name |
| 831 | |
| 832 | `workerName` sets the store's Worker name. Without it, you get the same default |
| 833 | store as before: |
| 834 | |
| 835 | ```typescript |
| 836 | state: Cloudflare.state({ workerName: "team-a-state" }), |
| 837 | ``` |
| 838 | |
| 839 | It replaces `name`, which prefixed the Worker name with `alchemy-state-store-`. |
| 840 | A store you named that way keeps its Worker and secrets when you pass the full |
| 841 | name: |
| 842 | |
| 843 | ```diff lang="typescript" |
| 844 | Alchemy.Stack( |
| 845 | "MyApp", |
| 846 | { |
| 847 | providers: Cloudflare.providers(), |
| 848 | - state: Cloudflare.state({ name: "team-a" }), |
| 849 | + state: Cloudflare.state({ workerName: "alchemy-state-store-team-a" }), |
| 850 | }, |
| 851 | Effect.gen(function* () {}), |
| 852 | ); |
| 853 | ``` |
| 854 | |
| 855 | `--name` takes the Worker name too: |
| 856 | |
| 857 | ```sh |
| 858 | alchemy state list --backend cloudflare --name alchemy-state-store-team-a |
| 859 | ``` |
| 860 | |
| 861 | ### Pin the account and serve it on your domain |
| 862 | |
| 863 | Pin the account so a login against another one can't read or deploy the store |
| 864 | there, and serve it on a hostname in one of your zones for networks that can't |
| 865 | reach `workers.dev`: |
| 866 | |
| 867 | ```typescript |
| 868 | state: Cloudflare.state({ |
| 869 | accountId: "c8eeff0e...", |
| 870 | domain: "alchemy-state.example.com", |
| 871 | }), |
| 872 | ``` |
| 873 | |
| 874 | ### Upgrade from v7 |
| 875 | |
| 876 | Your next `alchemy deploy` asks to upgrade the store. In CI, pass `--yes`, or |
| 877 | upgrade it ahead of time: |
| 878 | |
| 879 | ```sh |
| 880 | alchemy state bootstrap |
| 881 | ``` |
| 882 | |
| 883 | The upgrade keeps the store's auth token, encryption key and state, and only |
| 884 | ever creates a secret that's missing, so a deploy can't rotate the token or |
| 885 | replace the key. A store that has lost its key isn't given a new one unless you |
| 886 | confirm. |
| 887 | |
| 888 | :::danger |
| 889 | The upgrade deletes the `CloudflareStateStore` stack that beta.84 and earlier |
| 890 | use to manage the store. Don't run an older Alchemy against the store after |
| 891 | upgrading: it can no longer manage it, and you risk losing the encryption key, |
| 892 | which nothing can recover. Upgrade every machine and CI job that uses the store |
| 893 | together. |
| 894 | ::: |
| 895 | |
| 896 | Docs: [Cloudflare state store](/state-store#cloudflare-state-store) · |
| 897 | [More than one store](/state-store#more-than-one-store-per-account). |
| 898 | |
| 899 | ## AWS state now uses DynamoDB and plans 270× faster |
| 900 | |
| 901 | `AWS.state()` keeps state in one on-demand DynamoDB table per account and |
| 902 | region, and a deploy loads the stage with one `Query` |
| 903 | ([#2683](https://github.com/alchemy-run/alchemy/pull/2683), |
| 904 | [#2691](https://github.com/alchemy-run/alchemy/pull/2691)): |
| 905 | |
| 906 | | | S3 | DynamoDB | |
| 907 | | --- | ---: | ---: | |
| 908 | | plan, 250 resources | 21.6 s | 0.08 s | |
| 909 | | unchanged redeploy, 1,000 resources | 195 s | 0.5 s | |
| 910 | | destroy, 1,000 resources | 162 s | 12.5 s | |
| 911 | |
| 912 | Existing stages move with one command. Older Alchemy versions are fenced |
| 913 | out of the S3 copy, and nothing in S3 is deleted: |
| 914 | |
| 915 | ```sh |
| 916 | $ alchemy state migrate |
| 917 | my-app/prod: migrated (42 records) |
| 918 | |
| 919 | $ alchemy state migrate --rollback # back to S3, before downgrading |
| 920 | ``` |
| 921 | |
| 922 | Docs: [AWS state store](/state-store#aws-state-store) · |
| 923 | [Migrating from S3](/state-store#migrating-from-the-s3-store). |
| 924 | |
| 925 | ## Alchemist: the Alchemy CLI as a programmatic API |
| 926 | |
| 927 | The `alchemy` CLI is now a thin layer over `alchemy/Alchemist`. Everything |
| 928 | it does (plan, apply, drift, nuke, logs, state) is one call you can make from |
| 929 | your own program, and every step is a typed event you can handle |
| 930 | ([#2765](https://github.com/alchemy-run/alchemy/pull/2765)): |
| 931 | |
| 932 | ```typescript |
| 933 | import * as Alchemist from "alchemy/Alchemist"; |
| 934 | |
| 935 | const program = Effect.gen(function* () { |
| 936 | const plan = yield* Alchemist.plan({ |
| 937 | stack: Stack, |
| 938 | operation: "deploy", |
| 939 | stage: "prod", |
| 940 | }); |
| 941 | if (Alchemist.hasChanges(plan)) yield* Alchemist.apply(plan); |
| 942 | |
| 943 | const scan = yield* Alchemist.Drift.scan({ stack: Stack, stage: "prod" }); |
| 944 | if (Alchemist.Drift.hasDrift(scan)) yield* Alchemist.Drift.execute(scan); |
| 945 | }).pipe( |
| 946 | Alchemist.onEvent((event) => Effect.log(event.type)), |
| 947 | Effect.provide(Alchemist.layer()), |
| 948 | Effect.scoped, |
| 949 | ); |
| 950 | ``` |
| 951 | |
| 952 | Build your own CLI, a deploy bot or a CI step on the same API the `alchemy` |
| 953 | command uses. Every run also writes one NDJSON log under `.alchemy/log/`, |
| 954 | child processes and sidecars included. Thanks |
| 955 | [Rahul Mishra](https://github.com/BlankParticle)! |
| 956 | |
| 957 | Docs: [CLI API](/cli/api). |
| 958 | |
| 959 | ## @alchemy.run/test: a test runner for Effect |
| 960 | |
| 961 | Alchemy's own test runner is now on npm as `@alchemy.run/test` |
| 962 | ([#2452](https://github.com/alchemy-run/alchemy/pull/2452)). It is small |
| 963 | and built only for Effect: tests are Effects, and every test file runs in |
| 964 | one bun process, with files and tests in flight at once. |
| 965 | |
| 966 | ```sh |
| 967 | bun add -d @alchemy.run/test effect |
| 968 | bunx alchemy-test |
| 969 | ``` |
| 970 | |
| 971 | ```typescript |
| 972 | import { describe, expect, it } from "@alchemy.run/test"; |
| 973 | import * as Effect from "effect/Effect"; |
| 974 | |
| 975 | const charge = (amount: number) => Effect.succeed(amount > 5000 ? 402 : 200); |
| 976 | |
| 977 | describe("Checkout", () => { |
| 978 | it.live("charges the card", () => |
| 979 | Effect.gen(function* () { |
| 980 | yield* Effect.log("POST /charges { amount: 9000 }"); |
| 981 | const status = yield* charge(9000); |
| 982 | if (status !== 200) { |
| 983 | yield* Effect.logError(`payment provider returned ${status}`); |
| 984 | } |
| 985 | expect(status).toBe(200); |
| 986 | }), |
| 987 | ); |
| 988 | }); |
| 989 | ``` |
| 990 | |
| 991 | It prints one line per test as it finishes, with a running count, so you can |
| 992 | follow a long run as it goes. Each test's stdout and stderr are buffered on |
| 993 | their own. A passing test's output stays quiet; a failing test prints its |
| 994 | error and its output at once, in one piece, never interleaved with tests |
| 995 | running beside it. The last line links one log file holding every test's |
| 996 | output, passes included: |
| 997 | |
| 998 | ```text |
| 999 | running 4 tests from 1 files |
| 1000 | |
| 1001 | [1/4 ✓1 ✗0] ✓ test/Checkout.test.ts > Checkout > adds an item to the cart (1ms) |
| 1002 | [2/4 ✓2 ✗0] ✓ test/Checkout.test.ts > Checkout > applies a discount (151ms) |
| 1003 | [3/4 ✓2 ✗1] ✗ test/Checkout.test.ts > Checkout > charges the card (0ms) |
| 1004 | AssertionError: expected 402 to be 200 |
| 1005 | at <anonymous> (test/Checkout.test.ts:21:42) |
| 1006 | --- captured output --- |
| 1007 | POST /charges { amount: 9000 } |
| 1008 | payment provider returned 402 |
| 1009 | --- end output --- |
| 1010 | [4/4 ✓3 ✗1] ✓ test/Checkout.test.ts > Checkout > sends a receipt (82ms) |
| 1011 | |
| 1012 | Tests: 1 failed | 3 passed (1 files, 250ms) |
| 1013 | |
| 1014 | Full log: .alchemy/log/test/2026-11-02T19-02-29-pid37920.log (2.6 KB) |
| 1015 | ``` |
| 1016 | |
| 1017 | That last line is there for agents. An agent running the suite reads the |
| 1018 | log to see what happened in any test, without piping output to a file or |
| 1019 | running the tests again. When nothing finishes for 10 s, the runner lists |
| 1020 | the tests still running and how long each has taken, so a hang names |
| 1021 | itself. |
| 1022 | |
| 1023 | `--stage <name>` gives each git worktree its own stage, so agents in |
| 1024 | parallel worktrees test against one cloud account without colliding |
| 1025 | ([#2613](https://github.com/alchemy-run/alchemy/pull/2613)). `Test.make`, |
| 1026 | which deploys a stack for a test file, lives in the same package and |
| 1027 | works with `bun test` and Vitest too. |
| 1028 | |
| 1029 | Docs: [Test harness](/testing/test-harness) · |
| 1030 | [Worktrees](/environments/worktrees). |
| 1031 | |
| 1032 | ## Lambda aliases, streaming and partial batch failures |
| 1033 | |
| 1034 | `alias` publishes a version on each deploy and routes every event source, |
| 1035 | URL and integration through it, so a rollback is one `update-alias` call |
| 1036 | ([#2504](https://github.com/alchemy-run/alchemy/pull/2504)): |
| 1037 | |
| 1038 | ```typescript |
| 1039 | export default class Api extends AWS.Lambda.Function<Api>()( |
| 1040 | "Api", |
| 1041 | { main: import.meta.url, alias: "live", functionUrl: true }, |
| 1042 | Effect.gen(function* () { |
| 1043 | yield* AWS.SQS.consumeQueueMessages(jobs, processJob); // → api:live |
| 1044 | return { fetch: handleHttp }; // URL on qualifier "live" |
| 1045 | }), |
| 1046 | ) {} |
| 1047 | ``` |
| 1048 | |
| 1049 | SQS, Kinesis and DynamoDB Streams handlers receive the Lambda event and can |
| 1050 | return its batch response, so only the failed records are retried |
| 1051 | ([#2508](https://github.com/alchemy-run/alchemy/pull/2508)): |
| 1052 | |
| 1053 | ```typescript |
| 1054 | yield* AWS.SQS.consumeQueueMessages( |
| 1055 | queue, |
| 1056 | Effect.fn(function* (event) { |
| 1057 | const failed = yield* Effect.filter(event.Records, (record) => |
| 1058 | handle(record.body).pipe( |
| 1059 | Effect.as(false), |
| 1060 | Effect.catchCause(() => Effect.succeed(true)), |
| 1061 | ), |
| 1062 | ); |
| 1063 | return { |
| 1064 | batchItemFailures: failed.map((r) => ({ itemIdentifier: r.messageId })), |
| 1065 | }; |
| 1066 | }), |
| 1067 | ); |
| 1068 | ``` |
| 1069 | |
| 1070 | A `RESPONSE_STREAM` Function URL streams an Effect response body instead of |
| 1071 | buffering it ([#2502](https://github.com/alchemy-run/alchemy/pull/2502)), and |
| 1072 | a handler that runs past its `timeout` is interrupted, so finalizers run and |
| 1073 | telemetry flushes before Lambda kills the sandbox |
| 1074 | ([#2682](https://github.com/alchemy-run/alchemy/pull/2682)): |
| 1075 | |
| 1076 | ```typescript |
| 1077 | timeout: Duration.seconds(30), // handler interrupted at 30 s |
| 1078 | timeoutMargin: Duration.seconds(2), // Lambda configured for 32 s |
| 1079 | ``` |
| 1080 | |
| 1081 | Docs: [Lambda](/aws/compute/lambda). |
| 1082 | |
| 1083 | ## 95 bug fixes |
| 1084 | |
| 1085 | Most of this release is fixes, many found by new test suites rather than by |
| 1086 | users. About 900 provider failures that were a plain `Error` are now tagged |
| 1087 | errors you can catch ([#2711](https://github.com/alchemy-run/alchemy/pull/2711)), |
| 1088 | and ECR images hash only what `.dockerignore` keeps, so hashing a large repo |
| 1089 | dropped from 344 s to 8 s |
| 1090 | ([#2351](https://github.com/alchemy-run/alchemy/pull/2351)). |
| 1091 | |
| 1092 | ### One conformance suite for every workflow engine |
| 1093 | |
| 1094 | Every `WorkflowEngine` implementation now runs the same 28-case conformance |
| 1095 | suite: the Durable Object engine, Cloudflare Workflows and Lambda durable |
| 1096 | functions ([#2916](https://github.com/alchemy-run/alchemy/pull/2916)). The |
| 1097 | cases cover results, idempotent starts, durable sleeps, signals, |
| 1098 | compensations, defects, retries, interrupts and child workflows. The suite |
| 1099 | found 12 of the 15 engine bugs fixed in this release, including: |
| 1100 | |
| 1101 | - Sleeps ran later on every hop, because wake-ups inherited the Durable |
| 1102 | Object alarm's retry backoff. Four one-second sleeps took over 45 s; they |
| 1103 | now take about 4 s. |
| 1104 | - A repeated or late signal hung for three minutes, then died. |
| 1105 | - An interrupt sent right after start was dropped, or stopped the run without |
| 1106 | running its compensations. |
| 1107 | - `Activity.retry` saw attempt 1 on every retry. |
| 1108 | - `Activity.raceAll` hung forever on the two engines that can't support it; |
| 1109 | it now fails at once and points to the Durable Object engine. |
| 1110 | |
| 1111 | ### Drift only reports real changes |
| 1112 | |
| 1113 | `alchemy drift` now sees every setting that Lambda, DynamoDB, S3, SQS, |
| 1114 | EventBridge, Step Functions, WAF, ELB, ECS and EC2 networking manage, so a |
| 1115 | change made in the console shows up |
| 1116 | ([#2661](https://github.com/alchemy-run/alchemy/pull/2661), |
| 1117 | [#2705](https://github.com/alchemy-run/alchemy/pull/2705)). Untouched |
| 1118 | resources no longer show up as drifted |
| 1119 | ([#2496](https://github.com/alchemy-run/alchemy/pull/2496), |
| 1120 | [#2169](https://github.com/alchemy-run/alchemy/pull/2169), |
| 1121 | [#2647](https://github.com/alchemy-run/alchemy/pull/2647)): |
| 1122 | |
| 1123 | ```diff lang="sh" |
| 1124 | $ alchemy deploy && alchemy drift |
| 1125 | -[Api] drifted |
| 1126 | -[Db] drifted |
| 1127 | +Plan: no changes |
| 1128 | ``` |
| 1129 | |
| 1130 | `--repair` recreates deleted resources in dependency order |
| 1131 | ([#2495](https://github.com/alchemy-run/alchemy/pull/2495)), and EC2 creates |
| 1132 | are idempotent, so a retry never launches a second instance |
| 1133 | ([#2598](https://github.com/alchemy-run/alchemy/pull/2598)). Thanks |
| 1134 | [DivMode](https://github.com/DivMode), |
| 1135 | [Gjermund Garaba](https://github.com/gjermundgaraba) and |
| 1136 | [Ahmed Hesham](https://github.com/ahmedhesham6)! |
| 1137 | |
| 1138 | ### Deploys never take over a resource they don't own |
| 1139 | |
| 1140 | - A resource in a dependency cycle checks ownership before it's created, so |
| 1141 | it can't overwrite a Worker or Lambda someone else owns |
| 1142 | ([#2195](https://github.com/alchemy-run/alchemy/pull/2195), |
| 1143 | [#2620](https://github.com/alchemy-run/alchemy/pull/2620)). |
| 1144 | - A replacement is refused before it touches anything when its new name |
| 1145 | belongs to someone else ([#2200](https://github.com/alchemy-run/alchemy/pull/2200)). |
| 1146 | - Recovering an interrupted create never deletes a same-named resource by |
| 1147 | guessing ([#2199](https://github.com/alchemy-run/alchemy/pull/2199), |
| 1148 | [#2534](https://github.com/alchemy-run/alchemy/pull/2534)). |
| 1149 | - A ref to a resource in the same stack is a dependency, so destroy no longer |
| 1150 | races it ([#2913](https://github.com/alchemy-run/alchemy/pull/2913)). |
| 1151 | - `alchemy destroy` plans from state without running your program, so a dev |
| 1152 | stage tears down without cloud credentials |
| 1153 | ([#2491](https://github.com/alchemy-run/alchemy/pull/2491)). |
| 1154 | |
| 1155 | Thanks [Nacho Vazquez](https://github.com/NachoVazquez)! |
| 1156 | |
| 1157 | ### Cloudflare |
| 1158 | |
| 1159 | - A secret removed from a Worker's `env` is unbound instead of staying live |
| 1160 | forever ([#2327](https://github.com/alchemy-run/alchemy/pull/2327)). |
| 1161 | - `forceDestroy` deletes an R2 bucket holding unfinished multipart uploads |
| 1162 | ([#2537](https://github.com/alchemy-run/alchemy/pull/2537)). |
| 1163 | - A new container-backed Durable Object deploys in one pass, and a |
| 1164 | local-only Container image works |
| 1165 | ([#2342](https://github.com/alchemy-run/alchemy/pull/2342), |
| 1166 | [#2922](https://github.com/alchemy-run/alchemy/pull/2922)). |
| 1167 | - Preview Workers keep `json` bindings and JWKs as written |
| 1168 | ([#2127](https://github.com/alchemy-run/alchemy/pull/2127)), and two async |
| 1169 | Workers can bind each other ([#2681](https://github.com/alchemy-run/alchemy/pull/2681)). |
| 1170 | - The login picker lists every account, not the first 20 |
| 1171 | ([#2902](https://github.com/alchemy-run/alchemy/pull/2902)), and a Secrets |
| 1172 | Store with more than 20 secrets finds them |
| 1173 | ([#2443](https://github.com/alchemy-run/alchemy/pull/2443)). |
| 1174 | |
| 1175 | Thanks [Patt O'Brien](https://github.com/pattobrien), |
| 1176 | [Drew Powers](https://github.com/drwpwrs), |
| 1177 | [Andoni Enriquez](https://github.com/andoni-enriquez) and |
| 1178 | [Harry Solovay](https://github.com/harrysolovay)! |
| 1179 | |
| 1180 | ### Local dev |
| 1181 | |
| 1182 | - A Vite app with `publicDir: false` no longer serves files from your |
| 1183 | machine through `ASSETS` ([#2615](https://github.com/alchemy-run/alchemy/pull/2615)), |
| 1184 | and the Bun RPC sidecar listens on loopback only |
| 1185 | ([#2845](https://github.com/alchemy-run/alchemy/pull/2845)). |
| 1186 | - Vite plugins and `server.proxy` keep their own WebSockets |
| 1187 | ([#2516](https://github.com/alchemy-run/alchemy/pull/2516)), and large |
| 1188 | responses behind a local reverse proxy aren't truncated |
| 1189 | ([#2841](https://github.com/alchemy-run/alchemy/pull/2841)). |
| 1190 | - `alchemy dev` runs on NixOS with `dev.workerd` or `ALCHEMY_WORKERD_PATH` |
| 1191 | ([#2791](https://github.com/alchemy-run/alchemy/pull/2791)), and Docker is |
| 1192 | contacted only for Workers with containers |
| 1193 | ([#2784](https://github.com/alchemy-run/alchemy/pull/2784)). |
| 1194 | - Concurrent processes on one OAuth profile no longer revoke it |
| 1195 | ([#1923](https://github.com/alchemy-run/alchemy/pull/1923)). |
| 1196 | |
| 1197 | Thanks [Yanqi Zong](https://github.com/xiaoyu2er) and |
| 1198 | [0xMilkEnjoyer](https://github.com/birbprophet)! |
| 1199 | |
| 1200 | ## Also in this release |
| 1201 | |
| 1202 | **Alchemy Domain** |
| 1203 | |
| 1204 | - `Aggregate.predict` runs a command's rules on the client, so a UI shows the outcome before the server answers ([#2568](https://github.com/alchemy-run/alchemy/pull/2568)), and `View.snapshot` returns state with the cursor to follow it live from ([#2567](https://github.com/alchemy-run/alchemy/pull/2567)). [Docs](/domain/optimistic-updates). |
| 1205 | - Views, projections and policies can be keyed by a Schema value instead of an aggregate ([#2554](https://github.com/alchemy-run/alchemy/pull/2554)), and a scheduled command can be cancelled with `unschedule` ([#2547](https://github.com/alchemy-run/alchemy/pull/2547)). |
| 1206 | - External system calls are checked against their schemas, and an operation can declare several errors ([#2548](https://github.com/alchemy-run/alchemy/pull/2548), [#2553](https://github.com/alchemy-run/alchemy/pull/2553)). |
| 1207 | |
| 1208 | **Cloudflare** |
| 1209 | |
| 1210 | - `codeUpdateStrategy` sets how running Durable Objects move onto new code ([#2863](https://github.com/alchemy-run/alchemy/pull/2863)). [Docs](/cloudflare/compute/code-updates). |
| 1211 | - Workers import any file through `rules` ([#2792](https://github.com/alchemy-run/alchemy/pull/2792)), and Flagship flags evaluate locally in `alchemy dev` ([#2746](https://github.com/alchemy-run/alchemy/pull/2746)). |
| 1212 | - `consumeNotifications` handles Cloudflare alerts in code, and Effect logs reach Workers Logs at their own level ([#2519](https://github.com/alchemy-run/alchemy/pull/2519)). |
| 1213 | - Workflows, Queues and R2 buckets take a `jurisdiction` ([#2734](https://github.com/alchemy-run/alchemy/pull/2734), [#2538](https://github.com/alchemy-run/alchemy/pull/2538), [#2758](https://github.com/alchemy-run/alchemy/pull/2758)), and Email Routing takes subdomains and subaddressing ([#2762](https://github.com/alchemy-run/alchemy/pull/2762)). |
| 1214 | |
| 1215 | **AWS** |
| 1216 | |
| 1217 | - Smaller runtime bundles: a Lambda ships 0.51 MB instead of 1.30 MB, minified with source maps ([#2492](https://github.com/alchemy-run/alchemy/pull/2492)). |
| 1218 | - `EventBridge.Endpoint` global endpoints, regional NAT gateways, and Auto Scaling by instance attributes ([#2507](https://github.com/alchemy-run/alchemy/pull/2507), [#2498](https://github.com/alchemy-run/alchemy/pull/2498), [#2817](https://github.com/alchemy-run/alchemy/pull/2817)). |
| 1219 | |
| 1220 | **Tooling** |
| 1221 | |
| 1222 | - Docker builds take args and BuildKit secrets, and `Docker.Container` takes hardening options ([#2225](https://github.com/alchemy-run/alchemy/pull/2225), [#2623](https://github.com/alchemy-run/alchemy/pull/2623)). |
| 1223 | - Drizzle 1.0 rc.5 asks rename-or-create questions during plan ([#2433](https://github.com/alchemy-run/alchemy/pull/2433)). |
| 1224 | - `Command.Dev` takes a `port` or waits for its URL ([#2750](https://github.com/alchemy-run/alchemy/pull/2750)). [Docs](/cli/dev). |
| 1225 | - A stack can declare its stages, so a misspelled stage is a type error ([#2131](https://github.com/alchemy-run/alchemy/pull/2131)). |
| 1226 | |
| 1227 | See the [CHANGELOG](https://github.com/alchemy-run/alchemy/blob/main/CHANGELOG.md#v200-beta85) for every other change, and thanks to everyone who contributed. |
| 1228 | |
| 1229 | ## Where to go next |
| 1230 | |
| 1231 | - [Alchemy Domain](/domain) · [Backfill](/domain/backfill) · [HTTP API](/domain/http-api) · [MCP](/domain/mcp) · [CLI](/domain/cli) |
| 1232 | - [Cloud Run](/gcp/compute/cloud-run) · [Sidecars](/gcp/compute/sidecars) · [GCP federated identity](/gcp/security/federated-identity) · [GCP credentials](/gcp/setup#credentials) |
| 1233 | - [DNS adapters](/infrastructure-as-code/dns-adapters) · [State stores](/state-store) · [Lambda](/aws/compute/lambda) · [CLI API](/cli/api) |
| 1234 | - [Compare v2.0.0-beta.84 → v2.0.0-beta.85](https://github.com/alchemy-run/alchemy/compare/v2.0.0-beta.84...v2.0.0-beta.85) |