From e63356f33b53925816d2acff0b53c4ab813f1758 Mon Sep 17 00:00:00 2001 From: Marcos Oliveira Date: Tue, 17 Nov 2026 07:46:54 -0500 Subject: [PATCH] =?UTF-8?q?feat(demo13):=20saga=20under=20a=20slow=20payme?= =?UTF-8?q?nt=20=E2=80=94=20idempotency=20key,=20void=20before=20undo,=20p?= =?UTF-8?q?ending=20orders?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A LinkedIn reader pointed out the saga's dangerous case: a charge that times out may have gone through, and releasing the stock then leaves a customer charged with no order. - Every charge carries the saga id as its idempotency key; a retry returns the first charge, and a reused key with a different amount answers 409. - Payment records PROCESSING before the slow part. After a timeout the saga voids the key (POST /api/payment/charges//void): an unseen key becomes VOIDED, so a late charge is refused; a charge stuck in PROCESSING for 30 s is voided; anything else is returned as it stands. - APPROVED confirms the order, DECLINED (402) or VOIDED (503) releases the stock, PROCESSING or no answer leaves the order pending with the stock held. reconcile.py settles pending orders every 5 s. - Demo page /patterns/slow-payment, Pact contract updated, smoke tests for both outcomes. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 10 +- README.md | 28 ++- contracts/pacts/order-payment.json | 183 ++++++++++++++++++ docs/screenshots/p13-slow-payment.jpg | Bin 0 -> 55548 bytes frontend/src/api/gatewayClient.ts | 19 +- frontend/src/pages/Home.tsx | 2 +- frontend/src/pages/PatternPage.tsx | 2 + frontend/src/pages/Patterns.tsx | 7 +- frontend/src/pages/Shop.tsx | 8 +- frontend/src/patterns/content.ts | 24 +++ frontend/src/patterns/demos/SagaDemo.tsx | 7 +- .../src/patterns/demos/SlowPaymentDemo.tsx | 171 ++++++++++++++++ services/order/application/__init__.py | 5 + services/order/application/models.py | 14 ++ .../application/order_api/api/clients.py | 21 +- .../order/application/order_api/routes.py | 2 + services/order/application/reconcile.py | 65 +++++++ services/order/application/saga.py | 90 +++++++-- .../order/tests/test_checkout_and_breaker.py | 13 +- .../order/tests/test_contracts_consumer.py | 28 ++- services/order/tests/test_saga_and_outbox.py | 2 +- services/order/tests/test_slow_payment.py | 158 +++++++++++++++ services/payment/application/__init__.py | 4 + services/payment/application/models.py | 6 +- services/payment/application/routes.py | 76 +++++++- .../payment/tests/test_contract_provider.py | 18 +- services/payment/tests/test_payment.py | 167 +++++++++++++++- shared/shop_common/db_setup.py | 37 ++++ tests/smoke/test_post_run.py | 46 +++++ 29 files changed, 1152 insertions(+), 61 deletions(-) create mode 100644 docs/screenshots/p13-slow-payment.jpg create mode 100644 frontend/src/patterns/demos/SlowPaymentDemo.tsx create mode 100644 services/order/application/reconcile.py create mode 100644 services/order/tests/test_slow_payment.py diff --git a/CLAUDE.md b/CLAUDE.md index 3d52db5..242b334 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA - Name prefix: `ms12p` (parent uses `flaskms`). Teardown deletes the whole resource group, so a shared name would delete the other project. -## Current state (complete: 12 of 12 live; one Azure run done and torn down, #11) +## Current state (complete: 12 of 12 live, plus demo 13; one Azure run done and torn down, #11) - Folders: `services/{user,catalog,order,payment,inventory}/` (Flask, one DB each), `gateway/` (FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`, `scripts/`, `tests/`. @@ -41,6 +41,14 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA charge_payment, confirm; compensation releases the hold (or emits StockReleaseRequested). Steps in `saga_step`; holds keyed by saga id in inventory's `reservation`. `{"simulate_decline": true}` on checkout makes payment answer DECLINED (200, not a breaker failure). +- Demo 13 (slow payment, from a LinkedIn comment): every charge carries `idempotency_key` = saga id + (payment's `payment.idempotency_key`, unique; old DBs gain it via `shop_common.db_setup.add_missing_columns`). + Payment records PROCESSING before the slow part; a reused key with another amount answers 409. + After a timeout the saga calls `POST /api/payment/charges//void` (exempt from chaos): an unseen key + becomes VOIDED (a late charge then gets VOIDED back), PROCESSING older than 30 s is voided, others + are returned as they are. `saga.settle_charge`: APPROVED confirms, DECLINED 402, VOIDED 503 (both + release), PROCESSING/no answer writes `pending_payment` (checkout and add-item answer 409) and returns 202; + `reconcile.py` settles pending rows every 5 s (deleting and committing the row is the claim). Page `/patterns/slow-payment`. - Events (pattern 7): `shop_common/events.py` (Redis Stream `shop.events`, consumer groups, at least once). Order writes `outbox_event` in the same transaction; `outbox.py` relays every 1 s; inventory's `consumer.py` commits the hold on OrderConfirmed and dedupes via `consumed_event`. `POST /debug/bus` diff --git a/README.md b/README.md index 31c9a1d..eef5009 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,8 @@ can click. > **Status: complete.** All 12 patterns are live, each with a working demo, locally and in one > real Azure run: provision, deploy through GitHub Actions with OIDC, smoke tests, screenshots, -> teardown. The foundation is copied from +> teardown. Demo 13, a slow payment in the middle of checkout, came from a reader's comment on +> the project's LinkedIn post. The foundation is copied from > [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration). ## Project summary @@ -25,15 +26,16 @@ React frontend with one page per pattern. Every demo calls the real services: no | M2: resilience and independence | 4, 10, 11, 12 | [#3](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/3) | | M3a: async and packaging | 7, 8, 9 | [#4](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/4) | | M3b: delivery and the Azure run | 3 | [#12](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/12), [#13](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/13), [#14](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/14) | +| Demo 13: a slow payment mid-checkout | 4 and 8, under a timeout | [#16](https://github.com/MAOFILHO/Microservices-12-Patterns/pull/16) | M3b was planned as 7 GitHub issues ([#5 to #11](https://github.com/MAOFILHO/Microservices-12-Patterns/issues?q=is%3Aissue)), all closed. **How it was checked.** -- **155 unit tests** across 8 suites, each in its own virtualenv, built test-first from M3a on. +- **181 unit tests** across 8 suites, each in its own virtualenv, built test-first from M3a on. - **Pact contract tests**: the order service's contracts with payment, catalog and inventory, verified against the real providers in CI. -- **23 local smoke tests** against the running stack, and **4 Azure smoke tests** against the real +- **25 local smoke tests** against the running stack, and **4 Azure smoke tests** against the real deployment. - **CI on every pull request** runs only what the change touches; every image is built for linux/amd64, started, and rejected if it runs as root. `main` requires the "CI ok" check. @@ -59,6 +61,7 @@ or the cheapest SKUs, with a $25/month budget alert, then torn down and verified | 10 | [Stateless Services](#10-stateless-services) | Stores session data outside the service | M2 | | 11 | [Contract Testing](#11-contract-testing) | Checks that APIs stay compatible across services | M2 | | 12 | [Service Discovery](#12-service-discovery) | Finds service instances automatically at runtime | M2 | +| 13 | [Saga under a slow payment](#13-saga-under-a-slow-payment) | Follows the money and the stock when payment times out mid-checkout | Demo 13 | ## Architecture @@ -191,6 +194,25 @@ The live registry. Stop an instance: its heartbeat stops, the registry expires i Service Discovery demo: registry table and an expired then re-registered order replica +### 13. Saga under a slow payment +A declined card is the easy case. The hard one is a timeout: the charge call runs long, the +breaker counts a failure, and a saga that releases the stock now may leave a customer charged +with no order, or charged twice by the retry. Two fixes, both suggested by a reader: + +- **An idempotency key on every charge** (the saga id). The retry sends the same key, so payment + returns the first charge instead of making a second one. +- **A status check before any undo.** The saga voids the key with payment, which answers how the + charge stands. APPROVED confirms the order; DECLINED releases the stock; a charge payment never + saw becomes VOIDED, so a late copy of it is refused. PROCESSING or no answer leaves the order + **pending**, stock held, until a background check (every 5 s) settles it. A charge stuck in + PROCESSING for 30 s is voided, so no order waits forever. + +Make payment slow, buy 2 mugs, and follow the money and the stock. Here the charge call timed out, +payment still said PROCESSING, so the order waited; 5 s later it settled as 1 charge, 1 order, +2 mugs sold. + +Demo 13: payment slowed mid-checkout; the order waits as pending, then settles as 1 charge, 1 order, 2 mugs sold + ## Run locally (no Docker) ```bash diff --git a/contracts/pacts/order-payment.json b/contracts/pacts/order-payment.json index 64303f3..22f3111 100644 --- a/contracts/pacts/order-payment.json +++ b/contracts/pacts/order-payment.json @@ -15,6 +15,7 @@ "body": { "content": { "amount_cents": 2598, + "idempotency_key": "saga-42", "order_id": 42 }, "contentType": "application/json", @@ -35,6 +36,14 @@ } ] }, + "$.idempotency_key": { + "combine": "AND", + "matchers": [ + { + "match": "type" + } + ] + }, "$.order_id": { "combine": "AND", "matchers": [ @@ -110,6 +119,7 @@ "body": { "content": { "amount_cents": 899, + "idempotency_key": "saga-43", "order_id": 43, "simulate": "decline" }, @@ -131,6 +141,14 @@ } ] }, + "$.idempotency_key": { + "combine": "AND", + "matchers": [ + { + "match": "type" + } + ] + }, "$.order_id": { "combine": "AND", "matchers": [ @@ -204,6 +222,171 @@ "status": 200 }, "type": "Synchronous/HTTP" + }, + { + "description": "a void for a charge payment never saw", + "pending": false, + "providerStates": [ + { + "name": "payment is healthy" + } + ], + "request": { + "body": { + "content": { + "amount_cents": 500, + "order_id": 44 + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.amount_cents": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.order_id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "method": "POST", + "path": "/api/payment/charges/saga-never-sent/void" + }, + "response": { + "body": { + "content": { + "result": { + "id": 3, + "status": "VOIDED" + } + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.result.id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + }, + { + "description": "a void for a charge that went through", + "pending": false, + "providerStates": [ + { + "name": "a charge exists", + "params": { + "idempotency_key": "saga-42" + } + } + ], + "request": { + "body": { + "content": { + "amount_cents": 2598, + "order_id": 42 + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.amount_cents": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.order_id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "method": "POST", + "path": "/api/payment/charges/saga-42/void" + }, + "response": { + "body": { + "content": { + "result": { + "id": 1, + "status": "APPROVED" + } + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.result.id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.result.status": { + "combine": "AND", + "matchers": [ + { + "match": "type" + } + ] + } + } + }, + "status": 200 + }, + "type": "Synchronous/HTTP" } ], "metadata": { diff --git a/docs/screenshots/p13-slow-payment.jpg b/docs/screenshots/p13-slow-payment.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d7c478b3ff7d5870fff55137f9deb01b1bcc162c GIT binary patch literal 55548 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�nimtAk5iOLG`H(8Iw9Mp`NlUjv>%he; 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 - request<{ result: Order }>(`/api/shop/order/checkout`, { + request<{ result?: Order; pending?: boolean; message?: string }>(`/api/shop/order/checkout`, { method: "POST", headers: authHeaders(token), }), @@ -249,7 +250,7 @@ export interface SagaStep { export interface SagaRun { saga_id: string; order_id: number; - outcome: "completed" | "compensated" | "failed"; + outcome: "completed" | "compensated" | "failed" | "pending"; steps: SagaStep[]; } @@ -295,7 +296,7 @@ export interface RuntimeInfo { export const asyncApi = { checkout: (token: string, simulateDecline: boolean) => - getAny<{ message?: string; saga_id?: string; failed_step?: string }>("/api/shop/order/checkout", { + getAny<{ message?: string; saga_id?: string; failed_step?: string; pending?: boolean }>("/api/shop/order/checkout", { method: "POST", headers: { ...authHeaders(token), "Content-Type": "application/json" }, body: JSON.stringify({ simulate_decline: simulateDecline }), @@ -310,8 +311,20 @@ export const asyncApi = { body: JSON.stringify({ connected }), }), runtime: () => request<{ processes: RuntimeInfo[] }>("/api/patterns/runtime"), + payments: () => request<{ results: PaymentRow[] }>("/api/shop/payments"), }; +// --- Demo 13: a slow payment mid-checkout -------------------------------------------------------- + +export interface PaymentRow { + id: number; + order_id: number; + amount_cents: number; + status: "PROCESSING" | "APPROVED" | "DECLINED" | "VOIDED" | string; + idempotency_key: string | null; + created_at: string | null; +} + // --- M3b demo endpoint (pattern 3) --------------------------------------------------------------- export interface WorkflowRun { diff --git a/frontend/src/pages/Home.tsx b/frontend/src/pages/Home.tsx index 03f6e1f..96c0256 100644 --- a/frontend/src/pages/Home.tsx +++ b/frontend/src/pages/Home.tsx @@ -18,7 +18,7 @@ export default function Home() {

Patterns

-

The 12 patterns. All 12 are live, each with a working demo.

+

The 12 patterns. All 12 are live, each with a working demo, plus demo 13: a slow payment in the middle of checkout.

diff --git a/frontend/src/pages/PatternPage.tsx b/frontend/src/pages/PatternPage.tsx index a15224c..8a951be 100644 --- a/frontend/src/pages/PatternPage.tsx +++ b/frontend/src/pages/PatternPage.tsx @@ -11,6 +11,7 @@ import DatabasePerServiceDemo from "../patterns/demos/DatabasePerServiceDemo"; import ObservabilityDemo from "../patterns/demos/ObservabilityDemo"; import SagaDemo from "../patterns/demos/SagaDemo"; import ServiceDiscoveryDemo from "../patterns/demos/ServiceDiscoveryDemo"; +import SlowPaymentDemo from "../patterns/demos/SlowPaymentDemo"; import StatelessDemo from "../patterns/demos/StatelessDemo"; import { PATTERNS } from "../patterns/content"; @@ -27,6 +28,7 @@ const DEMOS: Record ReactNode> = { saga: () => , containerization: () => , "ci-cd-pipeline": () => , + "slow-payment": () => , }; export default function PatternPage() { diff --git a/frontend/src/pages/Patterns.tsx b/frontend/src/pages/Patterns.tsx index 4a0afbe..fb59885 100644 --- a/frontend/src/pages/Patterns.tsx +++ b/frontend/src/pages/Patterns.tsx @@ -2,14 +2,15 @@ import { Link } from "react-router-dom"; import { PATTERNS } from "../patterns/content"; export default function Patterns() { - const liveCount = PATTERNS.filter((p) => p.live).length; + const patterns = PATTERNS.filter((p) => p.n <= 12); // demo 13 is a bonus, not a 13th pattern + const liveCount = patterns.filter((p) => p.live).length; return (
-

The 12 patterns

+

The 12 patterns, plus demo 13

Each pattern has a page that explains it, says when not to use it, and runs a live demo against the real - services. {liveCount} of 12 are live; every one has a working demo. + services. {liveCount} of {patterns.length} are live. Demo 13 puts patterns 4 and 8 under a slow payment.

diff --git a/frontend/src/pages/Shop.tsx b/frontend/src/pages/Shop.tsx index 1936082..fef323c 100644 --- a/frontend/src/pages/Shop.tsx +++ b/frontend/src/pages/Shop.tsx @@ -121,8 +121,12 @@ export default function Shop() { setCartError(null); setCheckoutMessage(null); try { - const { result } = await shopApi.checkout(auth.token); - setCart(result); + const answer = await shopApi.checkout(auth.token); + if (answer.pending || !answer.result) { + setCheckoutMessage(answer.message ?? "Your order is pending."); + return; + } + setCart(answer.result); setCheckoutMessage("Order placed! Thank you."); } catch (err) { setCartError(String(err)); diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts index 8169dba..9b31e12 100644 --- a/frontend/src/patterns/content.ts +++ b/frontend/src/patterns/content.ts @@ -279,6 +279,30 @@ export const PATTERNS: PatternInfo[] = [ ], source: { label: "microservices.io — Client-side service discovery", url: "https://microservices.io/patterns/client-side-discovery.html" }, }, + { + n: 13, + slug: "slow-payment", + name: "Saga under a slow payment", + what: "Follows the money and the stock when payment times out mid-checkout.", + milestone: "M3", + live: true, + problem: + "A declined card is the easy case: the answer is clear and the stock goes back. A timeout is the hard one. The charge call runs long, the breaker counts a failure, the saga releases the stock, and the customer was charged anyway. A retry can even charge them twice.", + inThisProject: [ + "Every charge carries an idempotency key: the saga id, one per checkout attempt. The retry sends the same key, so payment returns the first charge instead of making a second one.", + "Payment records a charge as PROCESSING when it arrives, before the slow part, so a check made meanwhile sees it in flight. A reused key with a different amount is refused.", + "Before any undo, the saga voids the key with payment, which answers how the charge stands. APPROVED confirms the order. DECLINED releases the stock. A charge payment never saw is recorded as VOIDED, so a late copy of it can never be charged.", + "PROCESSING or no answer: the order waits as pending, with the stock held. It cannot be checked out again or changed, so a second attempt cannot charge.", + "Every 5 s, each order replica asks payment about pending orders and settles them by the same rules. Deleting the pending row is the claim, so 2 replicas cannot settle one twice. A charge stuck in PROCESSING for 30 s lost its process, so payment voids it and no order waits forever.", + "Raised by a reader of the project's LinkedIn post, who named both fixes.", + ], + whenNotToUse: [ + "Idempotency keys are not optional for anything that moves money. What varies is the key: one per attempt (as here) lets a declined card be retried.", + "A pending state is honest but costs the shopper a wait. Use it only where guessing is worse, as with money.", + "\"Never seen\" is final only because payment records a charge on arrival. A provider that does not must also offer a way to refuse a key before the saga releases the stock.", + ], + source: { label: "Stripe — Idempotent requests", url: "https://docs.stripe.com/api/idempotent_requests" }, + }, ]; export const SERVICE_NAMES = ["gateway", "user", "catalog", "order", "payment", "inventory"] as const; diff --git a/frontend/src/patterns/demos/SagaDemo.tsx b/frontend/src/patterns/demos/SagaDemo.tsx index f0b8f71..4089308 100644 --- a/frontend/src/patterns/demos/SagaDemo.tsx +++ b/frontend/src/patterns/demos/SagaDemo.tsx @@ -2,15 +2,16 @@ import { useEffect, useState } from "react"; import { Link } from "react-router-dom"; import { SagaRun, StockRow, asyncApi, savedToken } from "../../api/gatewayClient"; -const STEP_LABEL: Record = { +export const STEP_LABEL: Record = { price: "1. Price the cart (catalog)", reserve_stock: "2. Hold the stock (inventory)", charge_payment: "3. Charge the card (payment)", + check_payment: "3b. Ask payment what happened (demo 13)", confirm: "4. Confirm the order", release_stock: "Undo step 2: release the stock", }; -const PILL: Record = { done: "done", failed: "failed", compensated: "running" }; +export const PILL: Record = { done: "done", failed: "failed", compensated: "running", timed_out: "failed" }; const DEMO_PRODUCT = 1; export default function SagaDemo() { @@ -115,7 +116,7 @@ export default function SagaDemo() {

Step 2. What the saga did

Saga {latest.saga_id.slice(0, 8)} for order #{latest.order_id}:{" "} - + {latest.outcome}

diff --git a/frontend/src/patterns/demos/SlowPaymentDemo.tsx b/frontend/src/patterns/demos/SlowPaymentDemo.tsx new file mode 100644 index 0000000..9a8fefa --- /dev/null +++ b/frontend/src/patterns/demos/SlowPaymentDemo.tsx @@ -0,0 +1,171 @@ +import { useEffect, useState } from "react"; +import { Link } from "react-router-dom"; +import { PaymentRow, SagaRun, StockRow, asyncApi, resilienceApi, savedToken } from "../../api/gatewayClient"; +import { PILL, STEP_LABEL } from "./SagaDemo"; + +const DEMO_PRODUCT = 1; +const POLL_MS = 2000; + +/** Demo 13: slow payment down mid-checkout, then follow where the money and the stock end up. */ +export default function SlowPaymentDemo() { + const token = savedToken(); + const [mode, setMode] = useState("unknown"); + const [modeError, setModeError] = useState(null); + const [busy, setBusy] = useState(false); + const [result, setResult] = useState<{ kind: "done" | "running" | "failed"; label: string; message: string } | null>(null); + const [saga, setSaga] = useState(null); + const [charges, setCharges] = useState([]); + const [stock, setStock] = useState(null); + + async function refresh() { + if (!token) return; + const [history, payments, view, breaker] = await Promise.all([ + asyncApi.sagas(token).catch(() => null), + asyncApi.payments().catch(() => null), + asyncApi.events().catch(() => null), + resilienceApi.breakerState().catch(() => null), + ]); + const latest = history?.results[0] ?? null; + setSaga(latest); + setCharges(latest && payments ? payments.results.filter((p) => p.idempotency_key === latest.saga_id) : []); + setStock(view?.stock?.find((s) => s.product_id === DEMO_PRODUCT) ?? null); + if (breaker) setMode(breaker.payment.mode); + } + + useEffect(() => { + refresh(); + const timer = setInterval(refresh, POLL_MS); // the reconciler settles pending orders every 5 s + return () => clearInterval(timer); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, []); + + if (!token) { + return ( +

+ This demo checks out a real cart, so it needs a signed-in user. Register or log in on the Shop + page, then come back. +

+ ); + } + + async function switchPayment(next: string) { + setModeError(null); + const { status, body } = await resilienceApi.setPaymentMode(next); + if (status === 200 && body.mode) setMode(body.mode); + else setModeError(body.message ?? `HTTP ${status}`); + } + + async function buy() { + if (!token) return; + setBusy(true); + setResult(null); + try { + await asyncApi.addToCart(token, DEMO_PRODUCT, 2); + const { status, body } = await asyncApi.checkout(token, false); + if (status === 200) setResult({ kind: "done", label: "Completed", message: "Order placed. Payment approved." }); + else if (status === 202) setResult({ kind: "running", label: "Pending", message: body.message ?? "Waiting for payment." }); + else setResult({ kind: "failed", label: "Not placed", message: body.message ?? `HTTP ${status}` }); + } catch (err) { + setResult({ kind: "failed", label: "Error", message: String(err) }); + } finally { + await refresh(); + setBusy(false); + } + } + + // A pending answer goes stale once the reconciler settles the order: show what it settled to. + const shown = + result?.kind === "running" && saga && saga.outcome !== "pending" + ? saga.outcome === "completed" + ? { kind: "done" as const, label: "Confirmed", message: "Payment answered APPROVED, so the order was confirmed." } + : { kind: "failed" as const, label: "Released", message: "Payment declined or voided the charge, so the stock went back." } + : result; + const approved = charges.filter((c) => c.status === "APPROVED").length; + const verdict = !saga + ? null + : saga.outcome === "pending" + ? "Waiting: payment has not said yet. The mugs stay held, and the order cannot be paid for again." + : saga.outcome === "completed" + ? `Settled: ${approved} charge, 1 order, 2 mugs sold.` + : `Settled: ${approved} charges, no order, the mugs went back to stock.`; + + return ( +
+
+
+

Step 1. Slow payment down

+

+ Payment now answers {mode === "slow" ? "after 3 s" : "at once"}. The order service waits 1 s, retries once, + then gives up on the call. +

+
+ + +
+ {modeError &&

{modeError}

} + +

Step 2. Buy 2 Contoso Mugs

+ + {shown && ( +

+ {shown.label} {shown.message} +

+ )} +
+ +
+

Step 3. Where the money and the stock are

+ + + + + + + + + + + + + + + + + + + +
Charges for this checkout + {charges.length === 0 + ? "none" + : charges.map((c) => `#${c.id} ${c.status} ${(c.amount_cents / 100).toFixed(2)}`).join(", ")} +
Mugs on hand{stock?.on_hand ?? "?"}
Mugs held for checkouts{stock?.reserved ?? "?"}
Order{saga ? `#${saga.order_id} ${saga.outcome}` : "–"}
+ {verdict &&

{verdict}

} +

+ Refreshes every 2 s. A pending order settles within about 5 s of payment finishing. +

+
+
+ + {saga && ( +
+

What the saga did

+
    + {saga.steps.map((s, i) => ( +
  1. + {s.status} + {STEP_LABEL[s.step] ?? s.step} + {s.detail && · {s.detail}} +
  2. + ))} +
+
+ )} +
+ ); +} diff --git a/services/order/application/__init__.py b/services/order/application/__init__.py index 047f088..59a296b 100644 --- a/services/order/application/__init__.py +++ b/services/order/application/__init__.py @@ -48,4 +48,9 @@ def create_app(config_name: str | None = None) -> Flask: from .outbox import start as start_outbox_relay start_outbox_relay(app, instance_id("order")) + + # Demo 13: settle checkouts left pending by a slow payment. + from .reconcile import start as start_reconciler + + start_reconciler(app) return app diff --git a/services/order/application/models.py b/services/order/application/models.py index 7eafd49..1355ac9 100644 --- a/services/order/application/models.py +++ b/services/order/application/models.py @@ -93,3 +93,17 @@ class CheckoutLock(db.Model): order_id = db.Column(db.Integer, primary_key=True, autoincrement=False) saga_id = db.Column(db.String(36), nullable=False) started_at = db.Column(db.DateTime, nullable=False, default=_utcnow) + + +class PendingPayment(db.Model): + """Demo 13: a checkout whose charge timed out and whose outcome payment could not yet tell. + The stock stays held and the order cannot be checked out or changed until reconcile.py settles + it. A row is deleted by whoever settles it, so two replicas cannot settle it twice.""" + + __tablename__ = "pending_payment" + + saga_id = db.Column(db.String(36), primary_key=True) # also the charge's idempotency key + order_id = db.Column(db.Integer, nullable=False, unique=True) + user_id = db.Column(db.Integer, nullable=False) + amount_cents = db.Column(db.Integer, nullable=False) + since = db.Column(db.DateTime, nullable=False, default=_utcnow) diff --git a/services/order/application/order_api/api/clients.py b/services/order/application/order_api/api/clients.py index 9be3984..3145eb2 100644 --- a/services/order/application/order_api/api/clients.py +++ b/services/order/application/order_api/api/clients.py @@ -108,8 +108,9 @@ def attempt() -> requests.Response: raise PaymentUnavailable("failed") -def charge(order_id: int, amount_cents: int, simulate: str = "approve") -> dict: - body = {"order_id": order_id, "amount_cents": amount_cents} +def charge(order_id: int, amount_cents: int, simulate: str = "approve", *, idempotency_key: str) -> dict: + """The retry above resends this same body, key included, so payment charges at most once (demo 13).""" + body = {"order_id": order_id, "amount_cents": amount_cents, "idempotency_key": idempotency_key} if simulate != "approve": body["simulate"] = simulate response = call_payment("POST", "/api/payment/charge", body) @@ -117,6 +118,22 @@ def charge(order_id: int, amount_cents: int, simulate: str = "approve") -> dict: return response.json()["result"] +VOID_TIMEOUT_SECONDS = 2.0 + + +def void_charge(idempotency_key: str, order_id: int, amount_cents: int) -> dict: + """Demo 13: cancels this key unless the charge went through, and returns the charge as it now + stands (status APPROVED, DECLINED, VOIDED or PROCESSING). Once VOIDED, a late copy of the + charge is refused. Raises requests.RequestException when payment does not answer. + + Not behind the breaker: it is one light call, and its answer is what lets the saga undo safely. + """ + response = requests.post(f"{base_url('payment')}/api/payment/charges/{idempotency_key}/void", + json={"order_id": order_id, "amount_cents": amount_cents}, timeout=VOID_TIMEOUT_SECONDS) + response.raise_for_status() + return response.json()["result"] + + def breaker_state() -> dict: retry_in = None opened_at = BREAKER._state_storage.opened_at # pybreaker keeps no public accessor for this diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index f4e0002..0cf12ad 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -37,6 +37,8 @@ def order_add_item(): # The cart lives in the order database, not in this process (pattern 10): any replica sees it. known_order = Order.query.filter_by(user_id=u_id, is_open=True).first() + if known_order is not None and saga.is_pending(known_order.id): # demo 13: the charge may have happened + return make_response(jsonify({"message": saga.PENDING_MESSAGE, "pending": True}), 409) if known_order is None: known_order = Order(user_id=u_id, is_open=True) known_order.items.append(OrderItem(data.product_id, data.qty)) diff --git a/services/order/application/reconcile.py b/services/order/application/reconcile.py new file mode 100644 index 0000000..0bc6950 --- /dev/null +++ b/services/order/application/reconcile.py @@ -0,0 +1,65 @@ +"""Settles checkouts left pending by a slow payment (demo 13). + +Every RECONCILE_SECONDS, each order replica voids every pending charge's key with payment, which +answers how the charge stands: APPROVED confirms the order, DECLINED or VOIDED releases the stock, +and PROCESSING or no answer leaves it pending for the next pass. Payment voids a charge stuck in +PROCESSING once its process is surely gone, so no order waits forever while payment answers. +The rules are the saga's own (saga.settle_charge). +""" +import logging +import threading +import time + +import requests + +from . import db, saga +from .models import Order, PendingPayment +from .order_api.api import clients + +RECONCILE_SECONDS = 5 +log = logging.getLogger(__name__) + + +def resolve_pending() -> int: + """One pass. Returns how many pending checkouts it settled.""" + settled = 0 + for row in PendingPayment.query.order_by(PendingPayment.since).all(): + saga_id, order_id, user_id, amount = row.saga_id, row.order_id, row.user_id, row.amount_cents + try: + charge = clients.void_charge(saga_id, order_id, amount) + except requests.RequestException: + continue # still no answer: ask again next pass + if charge["status"] == "PROCESSING": + continue + # Claim it by deleting the row, and commit at once: settling calls inventory, and the other + # replica must not wait on this database lock meanwhile. If the other replica already took + # it, nothing is deleted and this replica leaves it alone. + claimed = PendingPayment.query.filter_by(saga_id=saga_id).delete() == 1 + db.session.commit() + if not claimed: + continue + checkout = saga.Saga(db.session.get(Order, order_id), user_id, saga_id=saga_id) + saga.settle_charge(checkout, amount, charge) + settled += 1 + return settled + + +def start(app) -> None: + from shop_common.flask_support import is_serving_process + + if not is_serving_process(app): + return # unit tests and the reloader's watcher land here + + def loop() -> None: + while True: + time.sleep(RECONCILE_SECONDS) + with app.app_context(): + try: + resolve_pending() + except Exception: + log.exception("reconcile pass failed; the next pass retries") + db.session.rollback() + finally: + db.session.remove() + + threading.Thread(target=loop, name="payment-reconciler", daemon=True).start() diff --git a/services/order/application/saga.py b/services/order/application/saga.py index f098815..9de1084 100644 --- a/services/order/application/saga.py +++ b/services/order/application/saga.py @@ -7,6 +7,12 @@ outbox. Inventory turns the hold into a sale when it reads that event (7). Any failure: event CheckoutFailed. One checkout per order at a time (checkout_lock). +Demo 13, a charge that times out: the customer may have been charged. The charge carries the saga +id as its idempotency key, so the retry cannot charge twice. Before it undoes anything, the saga +voids that key with payment, which answers how the charge stands (settle_charge). APPROVED +confirms the order; DECLINED or VOIDED (never arrived, and now never will) releases the stock; +PROCESSING or no answer leaves the order pending, with the stock held, until reconcile.py settles it. + If a later step fails, the earlier steps are undone in reverse order. Only step 2 changes another service's data, so the only compensation is releasing the stock. If that direct call fails too, a StockReleaseRequested event goes to the outbox, so inventory releases it once it can. @@ -21,13 +27,13 @@ from sqlalchemy.exc import IntegrityError from . import db -from .models import CheckoutLock, Order, OutboxEvent, SagaStep +from .models import CheckoutLock, Order, OutboxEvent, PendingPayment, SagaStep from .order_api.api import clients class Saga: - def __init__(self, order: Order, user_id: int): - self.id = str(uuid.uuid4()) + def __init__(self, order: Order, user_id: int, saga_id: str | None = None): + self.id = saga_id or str(uuid.uuid4()) self.order = order self.user_id = user_id @@ -85,11 +91,17 @@ def _release_lock(order_id: int) -> None: db.session.commit() +PENDING_MESSAGE = ("Your last checkout is still waiting for payment. It is confirmed, or the stock released, " + "as soon as payment answers.") + + def run_checkout(order: Order, user_id: int, simulate: str = "approve") -> tuple[int, dict]: saga = Saga(order, user_id) if not _acquire_lock(order, saga.id): return 409, {"message": "A checkout for this order is already in progress."} try: + if is_pending(order.id): + return 409, {"message": PENDING_MESSAGE, "pending": True} return _run_steps(saga, simulate) finally: _release_lock(order.id) @@ -128,36 +140,77 @@ def _run_steps(saga: Saga, simulate: str) -> tuple[int, dict]: saga.log("reserve_stock", "done", f"held {units} unit(s)", event="StockReserved", payload={"reservation_id": saga.id, "items": items}) - # 3. charge payment (behind the M2 circuit breaker) + # 3. charge payment (behind the M2 circuit breaker), keyed by the saga id (demo 13) try: - payment = clients.charge(order.id, amount, simulate) + payment = clients.charge(order.id, amount, simulate, idempotency_key=saga.id) except clients.PaymentUnavailable as exc: - breaker = clients.breaker_state() if exc.reason == "open": # the breaker refused the call: payment was never contacted + breaker = clients.breaker_state() wait = f" Try again in {breaker['retry_in_seconds']:.0f} s." if breaker["retry_in_seconds"] else "" - message = f"Payment is unavailable right now, so nothing was charged; the stock was released. {kept}{wait}" - else: # timeout or 5xx: the charge may or may not have happened - message = f"Payment could not be confirmed, so the order was not placed and the stock was released. {kept}" - return saga.fail("charge_payment", f"payment unavailable ({exc.reason})", 503, message, - compensate=True, breaker=breaker) + return saga.fail("charge_payment", "payment unavailable (open)", 503, + f"Payment is unavailable right now, so nothing was charged; the stock was released. {kept}{wait}", + compensate=True, breaker=breaker) + return _charge_unknown(saga, amount, f"payment unavailable ({exc.reason})") except requests.RequestException as exc: - return saga.fail("charge_payment", f"payment error: {exc.__class__.__name__}", 502, - f"Payment could not be confirmed, so the order was not placed and the stock was released. {kept}", - compensate=True) + return _charge_unknown(saga, amount, f"payment error: {exc.__class__.__name__}") + if payment["status"] == "PROCESSING": # a retry answered while the first try is still running + return _charge_unknown(saga, amount, "payment still processing") if payment["status"] != "APPROVED": return saga.fail("charge_payment", "declined", 402, f"Your payment was declined. Nothing was charged; the stock was released. {kept}", compensate=True) - saga.log("charge_payment", "done", f"payment {payment['id']} APPROVED, {amount} cents", event="PaymentCharged", - payload={"payment_id": payment["id"], "amount_cents": amount}) + return _confirm(saga, amount, payment, "charge_payment") + - # 4. confirm: the order change, its log line and its event commit together, or not at all +def _confirm(saga: Saga, amount: int, payment: dict, step: str) -> tuple[int, dict]: + """The charge went through: record it, then 4. confirm. The order change, its log line and its + event commit together, or not at all.""" + order = saga.order + items = [{"product_id": i.product_id, "quantity": i.quantity} for i in order.items] + saga.log(step, "done", f"payment {payment['id']} APPROVED, {amount} cents", event="PaymentCharged", + payload={"payment_id": payment["id"], "amount_cents": amount}) order.is_open = False saga.log("confirm", "done", "order closed; OrderConfirmed in the outbox", event="OrderConfirmed", payload={"reservation_id": saga.id, "amount_cents": amount, "items": items}) return 200, {"result": order.to_json(), "payment": payment, "saga_id": saga.id} +def _charge_unknown(saga: Saga, amount: int, detail: str) -> tuple[int, dict]: + """Demo 13: the charge call failed after it may have reached payment, so the customer may have + been charged. Void the key first: payment then says how the charge stands.""" + saga.log("charge_payment", "timed_out", f"{detail}; asking payment what happened") + try: + charge = clients.void_charge(saga.id, saga.order.id, amount) + except requests.RequestException as exc: + charge = {"status": f"no answer ({exc.__class__.__name__})"} + return settle_charge(saga, amount, charge) + + +def settle_charge(saga: Saga, amount: int, charge: dict) -> tuple[int, dict]: + """How payment says the saga's charge stands decides the outcome (also used by reconcile.py).""" + status = charge["status"] + kept = "Your cart is kept." + if status == "APPROVED": + return _confirm(saga, amount, charge, "check_payment") + if status == "DECLINED": + return saga.fail("check_payment", "payment says DECLINED", 402, + f"Your payment was declined. Nothing was charged; the stock was released. {kept}", + compensate=True) + if status == "VOIDED": + return saga.fail("check_payment", "payment never took the charge; its key is now void", 503, + f"Payment did not go through. Nothing was charged; the stock was released. {kept}", + compensate=True) + db.session.add(PendingPayment(saga_id=saga.id, order_id=saga.order.id, user_id=saga.user_id, amount_cents=amount)) + saga.log("check_payment", "pending", f"payment says {status}; the order waits, the stock stays held") + return 202, {"message": "Payment is taking longer than usual. Your order is pending: it is confirmed, or the " + "stock released, as soon as payment answers. You cannot be charged twice.", + "saga_id": saga.id, "pending": True} + + +def is_pending(order_id: int) -> bool: + return PendingPayment.query.filter_by(order_id=order_id).first() is not None + + def _compensate(saga: Saga) -> None: try: clients.release_stock(saga.id) @@ -176,7 +229,8 @@ def recent_sagas(user_id: int, limit: int = 5) -> list[dict]: for saga_id in saga_ids: steps = SagaStep.query.filter_by(saga_id=saga_id).order_by(SagaStep.id).all() statuses = {s.status for s in steps} - outcome = "compensated" if "compensated" in statuses else "failed" if "failed" in statuses else "completed" + outcome = ("compensated" if "compensated" in statuses else "failed" if "failed" in statuses + else "pending" if steps[-1].status == "pending" else "completed") result.append({"saga_id": saga_id, "order_id": steps[0].order_id, "outcome": outcome, "steps": [s.to_json() for s in steps]}) return result diff --git a/services/order/tests/test_checkout_and_breaker.py b/services/order/tests/test_checkout_and_breaker.py index fd485ae..a52a1a8 100644 --- a/services/order/tests/test_checkout_and_breaker.py +++ b/services/order/tests/test_checkout_and_breaker.py @@ -46,18 +46,19 @@ def test_breaker_opens_after_three_failures_then_fails_fast(client): assert 0 < body["breaker"]["retry_in_seconds"] <= clients.RESET_SECONDS -def test_checkout_keeps_the_cart_when_payment_is_down(client): +def test_checkout_waits_as_pending_when_payment_is_down(client): + """Payment at :9 refuses the charge and the void: nobody can say whether it was charged.""" _cart(client) r = client.post("/api/order/checkout", headers=AUTH) - assert r.status_code == 503 - assert "Your cart is kept" in r.get_json()["message"] + assert r.status_code == 202 + assert r.get_json()["pending"] is True assert client.get("/api/order", headers=AUTH).get_json()["result"]["is_open"] is True def test_checkout_charges_the_catalog_price_and_closes_the_order(client, monkeypatch): charged = {} - def fake_charge(order_id, amount_cents, simulate="approve"): + def fake_charge(order_id, amount_cents, simulate="approve", *, idempotency_key): charged.update(order_id=order_id, amount_cents=amount_cents) return {"id": 1, "order_id": order_id, "amount_cents": amount_cents, "status": "APPROVED"} @@ -92,8 +93,8 @@ def test_a_payment_timeout_never_claims_nothing_was_charged(client): """Payment at :9 refuses the call, which looks like a timeout: the charge state is unknown.""" _cart(client) message = client.post("/api/order/checkout", headers=AUTH).get_json()["message"] - assert "could not be confirmed" in message - assert "nothing was charged" not in message + assert "pending" in message + assert "nothing was charged" not in message.lower() def test_an_open_breaker_does_say_nothing_was_charged(client): diff --git a/services/order/tests/test_contracts_consumer.py b/services/order/tests/test_contracts_consumer.py index 1159a16..bfea820 100644 --- a/services/order/tests/test_contracts_consumer.py +++ b/services/order/tests/test_contracts_consumer.py @@ -28,7 +28,8 @@ def test_order_to_payment_contract(monkeypatch): pact.upon_receiving("a charge for an order") .given("payment is healthy") .with_request("POST", "/api/payment/charge") - .with_body({"order_id": match.int(42), "amount_cents": match.int(2598)}, "application/json") + .with_body({"order_id": match.int(42), "amount_cents": match.int(2598), "idempotency_key": match.str("saga-42")}, + "application/json") .will_respond_with(200) .with_body({"result": { "id": match.int(1), @@ -41,10 +42,27 @@ def test_order_to_payment_contract(monkeypatch): pact.upon_receiving("a charge the bank declines") .given("payment is healthy") .with_request("POST", "/api/payment/charge") - .with_body({"order_id": match.int(43), "amount_cents": match.int(899), "simulate": "decline"}, "application/json") + .with_body({"order_id": match.int(43), "amount_cents": match.int(899), "simulate": "decline", + "idempotency_key": match.str("saga-43")}, "application/json") .will_respond_with(200) .with_body({"result": {"id": match.int(2), "status": "DECLINED"}}, "application/json") ) + ( + pact.upon_receiving("a void for a charge that went through") + .given("a charge exists", idempotency_key="saga-42") + .with_request("POST", "/api/payment/charges/saga-42/void") + .with_body({"order_id": match.int(42), "amount_cents": match.int(2598)}, "application/json") + .will_respond_with(200) + .with_body({"result": {"id": match.int(1), "status": match.str("APPROVED")}}, "application/json") + ) + ( + pact.upon_receiving("a void for a charge payment never saw") + .given("payment is healthy") + .with_request("POST", "/api/payment/charges/saga-never-sent/void") + .with_body({"order_id": match.int(44), "amount_cents": match.int(500)}, "application/json") + .will_respond_with(200) + .with_body({"result": {"id": match.int(3), "status": "VOIDED"}}, "application/json") + ) ( pact.upon_receiving("a health check through the circuit breaker") .given("payment is healthy") @@ -54,10 +72,12 @@ def test_order_to_payment_contract(monkeypatch): ) with pact.serve() as server: monkeypatch.setitem(clients.STATIC_URLS, "payment", str(server.url).rstrip("/")) - payment = clients.charge(42, 2598) + payment = clients.charge(42, 2598, idempotency_key="saga-42") assert payment["status"] == "APPROVED" assert payment["amount_cents"] == 2598 - assert clients.charge(43, 899, "decline")["status"] == "DECLINED" + assert clients.charge(43, 899, "decline", idempotency_key="saga-43")["status"] == "DECLINED" + assert clients.void_charge("saga-42", 42, 2598)["status"] == "APPROVED" + assert clients.void_charge("saga-never-sent", 44, 500)["status"] == "VOIDED" assert clients.call_payment("GET", "/api/payment/ping").json() == {"status": "ok"} pact.write_file(PACT_DIR, overwrite=True) diff --git a/services/order/tests/test_saga_and_outbox.py b/services/order/tests/test_saga_and_outbox.py index 2a546d7..8e5b740 100644 --- a/services/order/tests/test_saga_and_outbox.py +++ b/services/order/tests/test_saga_and_outbox.py @@ -17,7 +17,7 @@ def calls(monkeypatch): monkeypatch.setattr(clients, "product_prices", lambda: {1: 1299}) monkeypatch.setattr(clients, "reserve_stock", lambda rid, oid, items: log.append(("reserve", rid)) or {}) monkeypatch.setattr(clients, "release_stock", lambda rid: log.append(("release", rid)) or {}) - monkeypatch.setattr(clients, "charge", lambda oid, amount, simulate="approve": log.append(("charge", simulate)) or { + monkeypatch.setattr(clients, "charge", lambda oid, amount, simulate="approve", **key: log.append(("charge", simulate)) or { "id": 9, "status": "DECLINED" if simulate == "decline" else "APPROVED"}) clients.BREAKER.close() return log diff --git a/services/order/tests/test_slow_payment.py b/services/order/tests/test_slow_payment.py new file mode 100644 index 0000000..8caeb99 --- /dev/null +++ b/services/order/tests/test_slow_payment.py @@ -0,0 +1,158 @@ +"""Demo 13: payment is slow in the middle of checkout. The charge call times out, so the saga +cannot know whether the customer was charged. It voids the charge's key before it undoes anything, +and payment answers how the charge now stands: + + APPROVED confirm the order (the customer paid, so they get it) + DECLINED release the stock, 402 like any decline + VOIDED release the stock (payment never took it, and now never will) + PROCESSING / no answer the order waits as pending; reconcile.resolve_pending() settles it later +""" +import pytest +import requests + +from application import reconcile +from application.models import OutboxEvent, SagaStep +from application.order_api.api import clients + +AUTH = {"Authorization": "Bearer test"} + + +@pytest.fixture +def payment(monkeypatch): + """Payment that times out on charge. `status` is what a void answers.""" + state = {"status": "PROCESSING", "keys": [], "voids": [], "released": []} + + def timed_out(order_id, amount, simulate="approve", *, idempotency_key): + state["keys"].append(idempotency_key) + raise clients.PaymentUnavailable("failed") + + def void(key, order_id, amount_cents): + state["voids"].append((key, amount_cents)) + if state["status"] == "UNREACHABLE": + raise requests.ConnectTimeout("payment did not answer") + return {"id": 9, "status": state["status"]} + + monkeypatch.setattr(clients, "current_user_id", lambda header: 1 if header else None) + monkeypatch.setattr(clients, "product_prices", lambda: {1: 1299}) + monkeypatch.setattr(clients, "reserve_stock", lambda rid, oid, items: {}) + monkeypatch.setattr(clients, "release_stock", lambda rid: state["released"].append(rid) or {}) + monkeypatch.setattr(clients, "charge", timed_out) + monkeypatch.setattr(clients, "void_charge", void) + clients.BREAKER.close() + return state + + +def _checkout(client): + client.post("/api/order/add-item", data={"product_id": 1, "qty": 2}, headers=AUTH) + return client.post("/api/order/checkout", json={}, headers=AUTH) + + +def _events(): + return [e.type for e in OutboxEvent.query.order_by(OutboxEvent.created_at)] + + +def _cart_is_open(client): + return client.get("/api/order", headers=AUTH).get_json().get("result", {}).get("is_open") is True + + +def test_the_charge_and_the_void_carry_the_saga_id_as_the_key(client, payment): + saga_id = _checkout(client).get_json()["saga_id"] + assert payment["keys"] == [saga_id] + assert payment["voids"] == [(saga_id, 2 * 1299)] + + +def test_a_timed_out_charge_that_went_through_confirms_the_order(client, payment): + payment["status"] = "APPROVED" + r = _checkout(client) + assert r.status_code == 200 + assert payment["released"] == [] # the customer paid: never give their stock away + assert _events() == ["StockReserved", "PaymentCharged", "OrderConfirmed"] + assert not _cart_is_open(client) + + +@pytest.mark.parametrize("answer, http_status", [("VOIDED", 503), ("DECLINED", 402)]) +def test_a_timed_out_charge_that_did_not_happen_releases_the_stock(client, payment, answer, http_status): + payment["status"] = answer + r = _checkout(client) + assert r.status_code == http_status + assert payment["released"] == [r.get_json()["saga_id"]] + assert _events() == ["StockReserved", "CheckoutFailed"] + assert "nothing was charged" in r.get_json()["message"].lower() + assert _cart_is_open(client) + + +@pytest.mark.parametrize("answer", ["PROCESSING", "UNREACHABLE"]) +def test_an_unknown_charge_leaves_the_order_pending_and_the_stock_held(client, payment, answer): + payment["status"] = answer + r = _checkout(client) + assert r.status_code == 202 + assert r.get_json()["pending"] is True + assert payment["released"] == [] + assert _events() == ["StockReserved"] # no CheckoutFailed: nothing is decided yet + assert SagaStep.query.order_by(SagaStep.id.desc()).first().status == "pending" + + +def test_a_pending_order_cannot_be_checked_out_or_changed(client, payment): + _checkout(client) + second = client.post("/api/order/checkout", json={}, headers=AUTH) + assert second.status_code == 409 + changed = client.post("/api/order/add-item", data={"product_id": 1, "qty": 1}, headers=AUTH) + assert changed.status_code == 409 + assert second.get_json()["message"] == changed.get_json()["message"] + assert "waiting for payment" in changed.get_json()["message"] + assert len(payment["keys"]) == 1 # no second charge attempt + + +def test_reconcile_confirms_a_pending_order_once_payment_approves(client, payment): + _checkout(client) + payment["status"] = "APPROVED" + assert reconcile.resolve_pending() == 1 + assert _events() == ["StockReserved", "PaymentCharged", "OrderConfirmed"] + assert payment["released"] == [] + assert not _cart_is_open(client) + assert reconcile.resolve_pending() == 0 # settled once, never twice + + +def test_reconcile_releases_the_stock_when_payment_voided_the_charge(client, payment): + saga_id = _checkout(client).get_json()["saga_id"] + payment["status"] = "VOIDED" + assert reconcile.resolve_pending() == 1 + assert payment["released"] == [saga_id] + assert _events() == ["StockReserved", "CheckoutFailed"] + assert _cart_is_open(client) + payment["status"] = "APPROVED" # the cart can be checked out again + assert client.post("/api/order/checkout", json={}, headers=AUTH).status_code == 200 + + +def test_reconcile_leaves_an_order_pending_while_payment_still_has_no_answer(client, payment): + _checkout(client) + payment["status"] = "UNREACHABLE" + assert reconcile.resolve_pending() == 0 + assert _events() == ["StockReserved"] + + +def test_the_saga_history_shows_a_pending_checkout(client, payment): + _checkout(client) + assert client.get("/api/order/sagas", headers=AUTH).get_json()["results"][0]["outcome"] == "pending" + + +def test_reconcile_commits_its_claim_before_it_calls_inventory(client, payment, monkeypatch): + """The release is an HTTP call: the other replica must not wait on this one's database lock.""" + from application.models import PendingPayment + + _checkout(client) + payment["status"] = "VOIDED" + seen = [] + monkeypatch.setattr(clients, "release_stock", lambda rid: seen.append(_claim_is_committed()) or {}) + reconcile.resolve_pending() + assert seen == [True] + assert PendingPayment.query.count() == 0 + + +def _claim_is_committed() -> bool: + from sqlalchemy import text + + from application import db + + with db.engine.connect() as other: # a second connection sees only committed rows + return other.execute(text("SELECT COUNT(*) FROM pending_payment")).scalar() == 0 diff --git a/services/payment/application/__init__.py b/services/payment/application/__init__.py index f1c2782..a3de7a2 100644 --- a/services/payment/application/__init__.py +++ b/services/payment/application/__init__.py @@ -30,5 +30,9 @@ def create_app(config_name: str | None = None) -> Flask: app.register_blueprint(payment_api) db.create_all() + # Demo 13 added payment.idempotency_key: a database made before it keeps its rows. + from shop_common.db_setup import add_missing_columns + + add_missing_columns(db) install_observability(app, "payment", db) return app diff --git a/services/payment/application/models.py b/services/payment/application/models.py index 4768d7e..4b5ad10 100644 --- a/services/payment/application/models.py +++ b/services/payment/application/models.py @@ -13,7 +13,10 @@ class Payment(db.Model): id = db.Column(db.Integer, primary_key=True) order_id = db.Column(db.Integer, nullable=False, index=True) # the order service's id; no cross-DB FK amount_cents = db.Column(db.Integer, nullable=False) - status = db.Column(db.String(20), nullable=False) # APPROVED | DECLINED + status = db.Column(db.String(20), nullable=False) # PROCESSING | APPROVED | DECLINED | VOIDED + # Demo 13: the caller's key for this charge. A retry with the same key gets this row back + # instead of a second charge. Unique, so two racing requests cannot both insert it. + idempotency_key = db.Column(db.String(64), nullable=True, unique=True) created_at = db.Column(db.DateTime, default=_utcnow) def to_json(self): @@ -22,5 +25,6 @@ def to_json(self): "order_id": self.order_id, "amount_cents": self.amount_cents, "status": self.status, + "idempotency_key": self.idempotency_key, "created_at": self.created_at.isoformat() if self.created_at else None, } diff --git a/services/payment/application/routes.py b/services/payment/application/routes.py index 8245e57..abfd895 100644 --- a/services/payment/application/routes.py +++ b/services/payment/application/routes.py @@ -1,9 +1,11 @@ import time +from datetime import datetime, timedelta, timezone from typing import Literal from flask import Blueprint, jsonify, make_response, request from pydantic import BaseModel, Field, ValidationError from shop_common.flask_support import chaos_enabled +from sqlalchemy.exc import IntegrityError from . import db from .models import Payment @@ -12,26 +14,37 @@ # Pattern 4 demo switch: "healthy", "failing" (every call returns 500) or "slow" (every call takes # SLOW_SECONDS, longer than the order service waits). Held in memory: it is a lab switch, not data. +# The switch makes charging sick, not settling: void and the list always answer, so the demo 13 +# page can show where the money is while payment is slow. MODES = ("healthy", "failing", "slow") SLOW_SECONDS = 3 _mode = {"value": "healthy"} +_ALWAYS_ANSWERS = {"payment_api.chaos", "payment_api.void", "payment_api.list_payments"} +# Demo 13: a charge still PROCESSING after this long lost its process (a crash or restart), so a +# void may cancel it. Far longer than any charge takes, slow mode included. +PROCESSING_LIMIT_SECONDS = 30 -class ChargeRequest(BaseModel): +class VoidRequest(BaseModel): order_id: int = Field(gt=0) amount_cents: int = Field(gt=0) + + +class ChargeRequest(VoidRequest): # Pattern 8 demo: "decline" acts like a card the bank refuses. A decline is a normal business # answer (200, status DECLINED), not a failure, so it never trips the order service's breaker. simulate: Literal["approve", "decline"] = "approve" + # Demo 13: one key per checkout attempt, sent again on every retry of that attempt. + idempotency_key: str = Field(min_length=1, max_length=64) @payment_api.before_request def _apply_chaos(): - if request.endpoint == "payment_api.chaos": + if request.endpoint in _ALWAYS_ANSWERS: return None if _mode["value"] == "failing": return make_response(jsonify({"message": "Payment is failing (demo switch)"}), 500) - if _mode["value"] == "slow": + if _mode["value"] == "slow" and request.endpoint != "payment_api.charge": # charge() is slow itself time.sleep(SLOW_SECONDS) return None @@ -46,17 +59,64 @@ def ping(): return jsonify({"status": "ok"}) +def _invalid(exc: ValidationError): + return make_response(jsonify({"message": "Invalid request", "errors": exc.errors(include_url=False)}), 400) + + +def _record(key: str, data: VoidRequest, status: str) -> tuple[Payment, bool]: + """The row for this key: the existing one, or a new one with this status. True if new.""" + payment = Payment.query.filter_by(idempotency_key=key).first() + if payment is not None: + return payment, False + db.session.add(Payment(order_id=data.order_id, amount_cents=data.amount_cents, status=status, idempotency_key=key)) + try: + db.session.commit() + except IntegrityError: # another request with this key got there first: use its row + db.session.rollback() + return Payment.query.filter_by(idempotency_key=key).one(), False + return Payment.query.filter_by(idempotency_key=key).one(), True + + +def _finish(payment: Payment, status: str) -> Payment: + """PROCESSING -> status, only if nothing (a void) changed the row meanwhile.""" + Payment.query.filter_by(id=payment.id, status="PROCESSING").update({"status": status}) + db.session.commit() + db.session.refresh(payment) + return payment + + @payment_api.post("/api/payment/charge") def charge(): raw = request.get_json(silent=True) or request.form.to_dict() try: data = ChargeRequest.model_validate(raw) except ValidationError as exc: - return make_response(jsonify({"message": "Invalid request", "errors": exc.errors(include_url=False)}), 400) - status = "DECLINED" if data.simulate == "decline" else "APPROVED" - payment = Payment(order_id=data.order_id, amount_cents=data.amount_cents, status=status) - db.session.add(payment) - db.session.commit() + return _invalid(exc) + # Demo 13: the charge is recorded as PROCESSING before the slow part, so a void sent while it + # runs sees it in flight. A retry with the same key gets this row back, never a new charge. + payment, created = _record(data.idempotency_key, data, "PROCESSING") + if not created: + if (payment.order_id, payment.amount_cents) != (data.order_id, data.amount_cents): + return make_response(jsonify({"message": "This key was already used for a different charge"}), 409) + return jsonify({"result": payment.to_json()}) + if _mode["value"] == "slow": + time.sleep(SLOW_SECONDS) + return jsonify({"result": _finish(payment, "DECLINED" if data.simulate == "decline" else "APPROVED").to_json()}) + + +@payment_api.post("/api/payment/charges//void") +def void(key: str): + """Demo 13: the order service's check before it undoes anything. A charge that never arrived + is recorded as VOIDED, so it can never be charged later; one whose process died is voided. + Answers the charge as it now stands: APPROVED, DECLINED, VOIDED or still PROCESSING.""" + try: + data = VoidRequest.model_validate(request.get_json(silent=True) or {}) + except ValidationError as exc: + return _invalid(exc) + payment, _ = _record(key, data, "VOIDED") + created = payment.created_at.replace(tzinfo=payment.created_at.tzinfo or timezone.utc) + if payment.status == "PROCESSING" and datetime.now(timezone.utc) - created > timedelta(seconds=PROCESSING_LIMIT_SECONDS): + payment = _finish(payment, "VOIDED") return jsonify({"result": payment.to_json()}) diff --git a/services/payment/tests/test_contract_provider.py b/services/payment/tests/test_contract_provider.py index bbf9692..7a95fd4 100644 --- a/services/payment/tests/test_contract_provider.py +++ b/services/payment/tests/test_contract_provider.py @@ -11,9 +11,23 @@ def test_payment_honours_the_order_services_contract(app): - from application import routes + from application import db, routes + from application.models import Payment + + # Pact calls the state handlers on another thread: end this thread's transaction first (SQLite). + db.session.commit() + db.session.remove() def healthy() -> None: routes._mode["value"] = "healthy" - verify_provider(app, provider="payment", consumer="order", states={"payment is healthy": healthy}, pact_dir=PACT_DIR) + def charge_exists() -> None: + healthy() + with app.app_context(): + if Payment.query.filter_by(idempotency_key="saga-42").first() is None: + db.session.add(Payment(order_id=42, amount_cents=2598, status="APPROVED", idempotency_key="saga-42")) + db.session.commit() + db.session.remove() + + verify_provider(app, provider="payment", consumer="order", + states={"payment is healthy": healthy, "a charge exists": charge_exists}, pact_dir=PACT_DIR) diff --git a/services/payment/tests/test_payment.py b/services/payment/tests/test_payment.py index e38febd..9ae2cf7 100644 --- a/services/payment/tests/test_payment.py +++ b/services/payment/tests/test_payment.py @@ -1,5 +1,5 @@ def test_charge_records_an_approved_payment(client): - r = client.post("/api/payment/charge", data={"order_id": 7, "amount_cents": 3798}) + r = client.post("/api/payment/charge", data={"order_id": 7, "amount_cents": 3798, "idempotency_key": "k7"}) assert r.status_code == 200 assert r.get_json()["result"]["status"] == "APPROVED" assert client.get("/api/payments").get_json()["results"][0]["order_id"] == 7 @@ -17,7 +17,7 @@ def test_health_db_reports_only_own_tables(client): def test_charge_accepts_json(client): - r = client.post("/api/payment/charge", json={"order_id": 3, "amount_cents": 500}) + r = client.post("/api/payment/charge", json={"order_id": 3, "amount_cents": 500, "idempotency_key": "k3"}) assert r.get_json()["result"]["amount_cents"] == 500 @@ -35,6 +35,167 @@ def test_chaos_switch_is_off_unless_enabled(client, monkeypatch): def test_a_simulated_decline_is_a_normal_answer(client): - r = client.post("/api/payment/charge", json={"order_id": 4, "amount_cents": 900, "simulate": "decline"}) + r = client.post("/api/payment/charge", json={"order_id": 4, "amount_cents": 900, "simulate": "decline", "idempotency_key": "k4"}) assert r.status_code == 200 assert r.get_json()["result"]["status"] == "DECLINED" + + +# --- Demo 13: a slow payment mid-checkout. Idempotency key and void. ------------------------------ + +def _charge(client, key, **body): + return client.post("/api/payment/charge", json={"order_id": 5, "amount_cents": 700, "idempotency_key": key, **body}) + + +def test_a_retry_with_the_same_key_charges_once(client): + first = _charge(client, "saga-1").get_json()["result"] + again = _charge(client, "saga-1").get_json()["result"] + assert again["id"] == first["id"] + assert len(client.get("/api/payments").get_json()["results"]) == 1 + + +def test_a_new_key_is_a_new_charge(client): + _charge(client, "saga-1") + _charge(client, "saga-2") + assert len(client.get("/api/payments").get_json()["results"]) == 2 + + +def test_a_charge_needs_an_idempotency_key(client): + assert client.post("/api/payment/charge", json={"order_id": 5, "amount_cents": 700}).status_code == 400 + + +def _void(client, key, order_id=5, amount_cents=700): + return client.post(f"/api/payment/charges/{key}/void", json={"order_id": order_id, "amount_cents": amount_cents}) + + +def _slow(client, monkeypatch, on_sleep): + from application import routes + + monkeypatch.setattr(routes.time, "sleep", on_sleep) + monkeypatch.setenv("CHAOS_ENABLED", "1") + client.post("/api/payment/chaos", json={"mode": "slow"}) + + +def test_a_reused_key_with_a_different_charge_is_refused(client): + _charge(client, "saga-1") + r = client.post("/api/payment/charge", json={"order_id": 5, "amount_cents": 999, "idempotency_key": "saga-1"}) + assert r.status_code == 409 + assert len(client.get("/api/payments").get_json()["results"]) == 1 + + +def test_void_reports_a_charge_that_went_through_and_leaves_it(client): + _charge(client, "saga-1") + assert _void(client, "saga-1").get_json()["result"]["status"] == "APPROVED" + + +def test_a_voided_key_can_never_be_charged_later(client): + assert _void(client, "saga-1").get_json()["result"]["status"] == "VOIDED" + assert _charge(client, "saga-1").get_json()["result"]["status"] == "VOIDED" # the late charge + assert [p["status"] for p in client.get("/api/payments").get_json()["results"]] == ["VOIDED"] + + +def test_void_leaves_a_charge_in_flight_alone_until_it_is_too_old(client): + from datetime import timedelta + + from application import db, routes + from application.models import Payment + + db.session.add(Payment(order_id=5, amount_cents=700, status="PROCESSING", idempotency_key="saga-1")) + db.session.commit() + assert _void(client, "saga-1").get_json()["result"]["status"] == "PROCESSING" + row = Payment.query.one() + row.created_at = row.created_at - timedelta(seconds=routes.PROCESSING_LIMIT_SECONDS + 1) + db.session.commit() + assert _void(client, "saga-1").get_json()["result"]["status"] == "VOIDED" # its process died + + +def test_a_charge_voided_while_it_ran_does_not_approve_when_it_finishes(client, monkeypatch): + from application import routes + + _slow(client, monkeypatch, lambda s: _force_void("saga-1")) + try: + assert _charge(client, "saga-1").get_json()["result"]["status"] == "VOIDED" + finally: + routes._mode["value"] = "healthy" + + +def _force_void(key): + from application import db + from application.models import Payment + + Payment.query.filter_by(idempotency_key=key).update({"status": "VOIDED"}) + db.session.commit() + + +def test_a_slow_retry_does_not_wait_again(client, monkeypatch): + from application import routes + + sleeps = [] + _slow(client, monkeypatch, sleeps.append) + try: + _charge(client, "saga-1") + _charge(client, "saga-1") + finally: + routes._mode["value"] = "healthy" + assert len(sleeps) == 1 + + +def test_a_slow_charge_is_recorded_as_processing_before_the_slow_part(client, monkeypatch): + from application import routes + from application.models import Payment + + seen_while_slow = [] + monkeypatch.setattr(routes.time, "sleep", lambda s: seen_while_slow.append(Payment.query.one().status)) + monkeypatch.setenv("CHAOS_ENABLED", "1") + client.post("/api/payment/chaos", json={"mode": "slow"}) + try: + assert _charge(client, "saga-1").get_json()["result"]["status"] == "APPROVED" + finally: + routes._mode["value"] = "healthy" + assert seen_while_slow == ["PROCESSING"] # a void during the slow part sees it in flight + + +def test_void_answers_while_charges_fail(client, monkeypatch): + _charge(client, "saga-1") + monkeypatch.setenv("CHAOS_ENABLED", "1") + client.post("/api/payment/chaos", json={"mode": "failing"}) + try: + assert _charge(client, "saga-2").status_code == 500 + assert _void(client, "saga-1").status_code == 200 + finally: + client.post("/api/payment/chaos", json={"mode": "healthy"}) + + +def test_a_database_from_before_demo_13_gains_the_key_column_at_startup(app): + from sqlalchemy import inspect, text + + from application import create_app, db + + db.drop_all() + db.session.execute(text("CREATE TABLE payment (id INTEGER PRIMARY KEY, order_id INTEGER NOT NULL, " + "amount_cents INTEGER NOT NULL, status VARCHAR(20) NOT NULL, created_at DATETIME)")) + db.session.commit() + create_app("development") + assert "idempotency_key" in {c["name"] for c in inspect(db.engine).get_columns("payment")} + + +def test_two_processes_upgrading_the_same_database_at_once_both_start(app, monkeypatch): + """The other process added the column after this one looked: the upgrade must not crash.""" + import sqlalchemy + + from application import db + from shop_common.db_setup import add_missing_columns + + real = sqlalchemy.inspect + + class Stale: + def __init__(self, engine): + self._real = real(engine) + + def has_table(self, name): + return self._real.has_table(name) + + def get_columns(self, name): + return [c for c in self._real.get_columns(name) if c["name"] != "idempotency_key"] + + monkeypatch.setattr(sqlalchemy, "inspect", Stale) + add_missing_columns(db) # sees the column as missing, but it is already there diff --git a/shared/shop_common/db_setup.py b/shared/shop_common/db_setup.py index 9c8cdcb..296c7b4 100644 --- a/shared/shop_common/db_setup.py +++ b/shared/shop_common/db_setup.py @@ -16,3 +16,40 @@ def create_tables(db) -> None: raise db.session.rollback() db.create_all() + + +def add_missing_columns(db) -> None: + """Adds model columns that an existing table lacks, so a database made by an older version + keeps its rows (there are no Alembic revisions). Only for new nullable columns: a unique one + gets a unique index, which allows many NULLs on SQLite and MySQL. Safe when two processes + start at once: a column or index the other one just added is skipped. + """ + from sqlalchemy import inspect + + inspector = inspect(db.engine) + quote = db.engine.dialect.identifier_preparer.quote + for table in db.metadata.sorted_tables: + if not inspector.has_table(table.name): + continue + present = {c["name"] for c in inspector.get_columns(table.name)} + for column in table.columns: + if column.name in present or not column.nullable: + continue + kind = column.type.compile(dialect=db.engine.dialect) + _run_once(db, f"ALTER TABLE {quote(table.name)} ADD COLUMN {quote(column.name)} {kind}") + if column.unique: + index = quote(f"uq_{table.name}_{column.name}") + _run_once(db, f"CREATE UNIQUE INDEX {index} ON {quote(table.name)} ({quote(column.name)})") + + +def _run_once(db, statement: str) -> None: + """Runs one schema change, skipping it if another process already made it.""" + from sqlalchemy import text + + try: + db.session.execute(text(statement)) + db.session.commit() + except OperationalError as exc: + db.session.rollback() + if "duplicate" not in str(exc).lower() and "already exists" not in str(exc).lower(): + raise diff --git a/tests/smoke/test_post_run.py b/tests/smoke/test_post_run.py index 65800a7..2ea3fb1 100644 --- a/tests/smoke/test_post_run.py +++ b/tests/smoke/test_post_run.py @@ -208,6 +208,52 @@ def test_declined_payment_is_compensated_and_stock_is_unchanged(): assert httpx.get(f"{GATEWAY_URL}/api/shop/order", headers=headers).json()["result"]["is_open"] is True +def test_demo_13_a_slow_payment_ends_as_one_charge_and_one_sale(): + """Payment slows down mid-checkout: the order waits as pending, then settles as exactly 1 charge.""" + _require_stack() + api = f"{GATEWAY_URL}/api/patterns/breaker" + headers = _login_with_cart() + before = _stock(1) + assert httpx.post(f"{api}/payment-mode", json={"mode": "slow"}).status_code == 200 + try: + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15) + finally: + httpx.post(f"{api}/payment-mode", json={"mode": "healthy"}) + assert r.status_code == 202, r.text # the charge timed out and payment still says PROCESSING + saga_id = r.json()["saga_id"] + assert _stock(1)["reserved"] == before["reserved"] + 3 # held, not given away + + def charges() -> list[dict]: + return [p for p in httpx.get(f"{GATEWAY_URL}/api/shop/payments").json()["results"] if p["idempotency_key"] == saga_id] + + saga = lambda: httpx.get(f"{GATEWAY_URL}/api/shop/order/sagas", headers=headers).json()["results"][0] # noqa: E731 + assert _wait_for(lambda: saga()["outcome"] == "completed", seconds=15), saga() + assert [c["status"] for c in charges()] == ["APPROVED"] # the retry did not charge twice + assert _wait_for(lambda: _stock(1)["on_hand"] == before["on_hand"] - 3), _stock(1) + assert _stock(1)["reserved"] == before["reserved"] + + +def test_demo_13_a_charge_payment_never_took_is_voided_and_the_stock_goes_back(): + """Payment fails every charge: the saga voids the key, so a late copy can never charge.""" + _require_stack() + api = f"{GATEWAY_URL}/api/patterns/breaker" + headers = _login_with_cart() + before = _stock(1) + assert httpx.post(f"{api}/payment-mode", json={"mode": "failing"}).status_code == 200 + try: + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15) + finally: + httpx.post(f"{api}/payment-mode", json={"mode": "healthy"}) + assert r.status_code == 503, r.text + saga_id = r.json()["saga_id"] + payments = httpx.get(f"{GATEWAY_URL}/api/shop/payments").json()["results"] + assert [p["status"] for p in payments if p["idempotency_key"] == saga_id] == ["VOIDED"] + assert _stock(1) == before + assert httpx.get(f"{GATEWAY_URL}/api/shop/order", headers=headers).json()["result"]["is_open"] is True + # The failed charges count toward a breaker: one good call per replica resets the count. + assert _wait_for(lambda: {httpx.get(f"{api}/call").json()["outcome"] for _ in range(2)} == {"ok"}, seconds=20) + + def test_events_wait_in_the_outbox_while_the_bus_is_down_then_drain(): _require_stack() api = f"{GATEWAY_URL}/api/patterns/events"