Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/`.
Expand All @@ -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/<key>/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`
Expand Down
28 changes: 25 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -191,6 +194,25 @@ The live registry. Stop an instance: its heartbeat stops, the registry expires i

<img width="100%" alt="Service Discovery demo: registry table and an expired then re-registered order replica" src="docs/screenshots/p12-service-discovery.jpg" />

### 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.

<img width="100%" alt="Demo 13: payment slowed mid-checkout; the order waits as pending, then settles as 1 charge, 1 order, 2 mugs sold" src="docs/screenshots/p13-slow-payment.jpg" />

## Run locally (no Docker)

```bash
Expand Down
183 changes: 183 additions & 0 deletions contracts/pacts/order-payment.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
"body": {
"content": {
"amount_cents": 2598,
"idempotency_key": "saga-42",
"order_id": 42
},
"contentType": "application/json",
Expand All @@ -35,6 +36,14 @@
}
]
},
"$.idempotency_key": {
"combine": "AND",
"matchers": [
{
"match": "type"
}
]
},
"$.order_id": {
"combine": "AND",
"matchers": [
Expand Down Expand Up @@ -110,6 +119,7 @@
"body": {
"content": {
"amount_cents": 899,
"idempotency_key": "saga-43",
"order_id": 43,
"simulate": "decline"
},
Expand All @@ -131,6 +141,14 @@
}
]
},
"$.idempotency_key": {
"combine": "AND",
"matchers": [
{
"match": "type"
}
]
},
"$.order_id": {
"combine": "AND",
"matchers": [
Expand Down Expand Up @@ -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": {
Expand Down
Binary file added docs/screenshots/p13-slow-payment.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 16 additions & 3 deletions frontend/src/api/gatewayClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,9 @@ export const shopApi = {
headers: authHeaders(token),
}),

// 200 has the closed order. 202 means payment was too slow to tell (demo 13): the order waits as pending.
checkout: (token: string) =>
request<{ result: Order }>(`/api/shop/order/checkout`, {
request<{ result?: Order; pending?: boolean; message?: string }>(`/api/shop/order/checkout`, {
method: "POST",
headers: authHeaders(token),
}),
Expand Down Expand Up @@ -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[];
}

Expand Down Expand Up @@ -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 }),
Expand All @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/pages/Home.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ export default function Home() {
</Link>
<Link to="/patterns" className="card" style={{ textDecoration: "none", color: "inherit" }}>
<h3>Patterns</h3>
<p className="muted">The 12 patterns. All 12 are live, each with a working demo.</p>
<p className="muted">The 12 patterns. All 12 are live, each with a working demo, plus demo 13: a slow payment in the middle of checkout.</p>
</Link>
</div>

Expand Down
2 changes: 2 additions & 0 deletions frontend/src/pages/PatternPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -27,6 +28,7 @@ const DEMOS: Record<string, () => ReactNode> = {
saga: () => <SagaDemo />,
containerization: () => <ContainerizationDemo />,
"ci-cd-pipeline": () => <CiCdDemo />,
"slow-payment": () => <SlowPaymentDemo />,
};

export default function PatternPage() {
Expand Down
7 changes: 4 additions & 3 deletions frontend/src/pages/Patterns.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
<div className="grid" style={{ gap: "1.5rem" }}>
<section className="card">
<h1>The 12 patterns</h1>
<h1>The 12 patterns, plus demo 13</h1>
<p className="muted">
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.
</p>
</section>
<div className="grid cols-3">
Expand Down
Loading
Loading