From fdde22eef9a4ed88c02c8f4d20ee30bf391193b6 Mon Sep 17 00:00:00 2001 From: Marcos Oliveira Date: Sun, 15 Nov 2026 16:19:04 -0500 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20M3a=20=E2=80=94=20Saga,=20Event-Dri?= =?UTF-8?q?ven=20Architecture=20(outbox=20+=20Redis),=20hardened=20contain?= =?UTF-8?q?ers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Pattern 8: checkout is an orchestrated saga in the order service: price (catalog), hold stock (inventory), charge (payment), confirm. A decline, an open breaker or a payment error releases the hold; if that call fails, StockReleaseRequested goes through the outbox. Steps in saga_step. - Pattern 7: OrderConfirmed is written to an outbox table in the same transaction as the order; a relay publishes to the Redis Stream shop.events; inventory consumes it in its own group and turns the hold into a sale, deduping on event id. A demo switch disconnects the bus. - Pattern 9: multi-stage Dockerfiles running as uid 10001, .dockerignore everywhere (local venvs were being uploaded), GIT_SHA build arg, CI builds and runs all 7 images for linux/amd64. - Fixes found on the way: two order replicas racing to create tables; Flask's reloader watcher process running a second, unswitchable outbox relay; 18 catalog products with no stock record. - make run starts an in-memory Redis on 6390. Contracts add order -> inventory and a declined charge. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 45 ++++ CLAUDE.md | 2 +- contracts/pacts/order-inventory.json | 199 ++++++++++++++++++ contracts/pacts/order-payment.json | 78 +++++++ docs/PLAN.md | 27 +++ docs/screenshots/p07-event-driven.jpg | Bin 0 -> 65319 bytes docs/screenshots/p08-saga.jpg | Bin 0 -> 47353 bytes docs/screenshots/p09-containerization.jpg | Bin 0 -> 71269 bytes frontend/src/api/gatewayClient.ts | 74 +++++++ frontend/src/pages/Home.tsx | 2 +- frontend/src/pages/PatternPage.tsx | 6 + frontend/src/pages/Patterns.tsx | 2 +- frontend/src/patterns/content.ts | 71 ++++++- .../patterns/demos/ContainerizationDemo.tsx | 112 ++++++++++ .../src/patterns/demos/EventDrivenDemo.tsx | 169 +++++++++++++++ frontend/src/patterns/demos/SagaDemo.tsx | 163 ++++++++++++++ frontend/src/theme/contoso.css | 21 ++ gateway/.dockerignore | 10 + gateway/Dockerfile | 35 +-- gateway/app/observability.py | 7 +- gateway/app/routers/resilience.py | 74 ++++++- gateway/tests/test_api.py | 17 ++ registry/.dockerignore | 10 + registry/Dockerfile | 26 +++ scripts/run_local.py | 37 +++- scripts/service_table.py | 9 +- services/catalog/.dockerignore | 10 + services/catalog/Dockerfile | 39 ++-- services/inventory/.dockerignore | 10 + services/inventory/Dockerfile | 39 ++-- services/inventory/application/__init__.py | 10 + services/inventory/application/consumer.py | 42 ++++ services/inventory/application/models.py | 51 +++++ services/inventory/application/routes.py | 66 +++++- services/inventory/application/seed.py | 14 +- services/inventory/application/stock.py | 64 ++++++ services/inventory/requirements.txt | 1 + .../inventory/tests/test_contract_provider.py | 36 ++++ services/inventory/tests/test_inventory.py | 2 +- .../inventory/tests/test_saga_and_events.py | 74 +++++++ services/order/.dockerignore | 10 + services/order/Dockerfile | 39 ++-- services/order/application/__init__.py | 12 +- services/order/application/models.py | 45 ++++ .../application/order_api/api/clients.py | 31 ++- .../order/application/order_api/routes.py | 61 +++--- services/order/application/outbox.py | 73 +++++++ services/order/application/saga.py | 131 ++++++++++++ services/order/requirements.txt | 1 + .../order/tests/test_checkout_and_breaker.py | 5 +- .../order/tests/test_contracts_consumer.py | 49 +++++ services/order/tests/test_saga_and_outbox.py | 107 ++++++++++ services/order/tests/test_startup.py | 64 ++++++ services/payment/.dockerignore | 10 + services/payment/Dockerfile | 39 ++-- services/payment/application/routes.py | 7 +- services/payment/tests/test_payment.py | 6 + services/user/.dockerignore | 10 + services/user/Dockerfile | 39 ++-- shared/shop_common/db_setup.py | 18 ++ shared/shop_common/events.py | 88 ++++++++ shared/shop_common/flask_support.py | 20 +- shared/shop_common/runtime.py | 21 ++ tests/smoke/test_post_run.py | 77 ++++++- 64 files changed, 2488 insertions(+), 129 deletions(-) create mode 100644 contracts/pacts/order-inventory.json create mode 100644 docs/screenshots/p07-event-driven.jpg create mode 100644 docs/screenshots/p08-saga.jpg create mode 100644 docs/screenshots/p09-containerization.jpg create mode 100644 frontend/src/patterns/demos/ContainerizationDemo.tsx create mode 100644 frontend/src/patterns/demos/EventDrivenDemo.tsx create mode 100644 frontend/src/patterns/demos/SagaDemo.tsx create mode 100644 gateway/.dockerignore create mode 100644 registry/.dockerignore create mode 100644 registry/Dockerfile create mode 100644 services/catalog/.dockerignore create mode 100644 services/inventory/.dockerignore create mode 100644 services/inventory/application/consumer.py create mode 100644 services/inventory/application/stock.py create mode 100644 services/inventory/tests/test_contract_provider.py create mode 100644 services/inventory/tests/test_saga_and_events.py create mode 100644 services/order/.dockerignore create mode 100644 services/order/application/outbox.py create mode 100644 services/order/application/saga.py create mode 100644 services/order/tests/test_saga_and_outbox.py create mode 100644 services/order/tests/test_startup.py create mode 100644 services/payment/.dockerignore create mode 100644 services/user/.dockerignore create mode 100644 shared/shop_common/db_setup.py create mode 100644 shared/shop_common/events.py create mode 100644 shared/shop_common/runtime.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2339c22..99da61e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,6 +51,7 @@ jobs: requirements: services/inventory/requirements.txt tests: services/inventory/tests shared: flask + contracts: true steps: - uses: actions/checkout@v4 @@ -101,6 +102,50 @@ jobs: - name: Type-check and build run: npm run build + containers: + # Pattern 9. Builds every image exactly as Azure will run it (linux/amd64), starts it, and checks + # it answers /health and does not run as root. Nothing is pushed anywhere. + name: Container image (${{ matrix.image }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - { image: user, dir: services/user, port: 5101, shared: true } + - { image: catalog, dir: services/catalog, port: 5102, shared: true } + - { image: order, dir: services/order, port: 5103, shared: true } + - { image: payment, dir: services/payment, port: 5104, shared: true } + - { image: inventory, dir: services/inventory, port: 5105, shared: true } + - { image: gateway, dir: gateway, port: 8100, shared: true } + - { image: registry, dir: registry, port: 8500, shared: false } + steps: + - uses: actions/checkout@v4 + + - name: Stage shared package (shop_common) + if: matrix.shared + run: cp -r shared "${{ matrix.dir }}/_shared" + + - name: Build for linux/amd64 + run: > + docker build --platform linux/amd64 --build-arg GIT_SHA=${{ github.sha }} + -t ms12p-${{ matrix.image }}:${{ github.sha }} ${{ matrix.dir }} + + - name: Run it, check health and that it is not root + run: | + docker run -d --name svc -p ${{ matrix.port }}:${{ matrix.port }} -e RUN_MODE=local \ + ms12p-${{ matrix.image }}:${{ github.sha }} + for i in $(seq 1 30); do curl -sf http://127.0.0.1:${{ matrix.port }}/health && break; sleep 1; done + curl -sf http://127.0.0.1:${{ matrix.port }}/health + uid=$(docker exec svc id -u) + echo "runs as uid $uid" + test "$uid" != "0" + size=$(docker image inspect ms12p-${{ matrix.image }}:${{ github.sha }} --format '{{.Size}}') + echo "| ${{ matrix.image }} | $((size / 1024 / 1024)) MB | uid $uid | linux/amd64 |" >> "$GITHUB_STEP_SUMMARY" + + - name: Container logs (on failure) + if: failure() + run: docker logs svc || true + bicep: name: Bicep (build) runs-on: ubuntu-latest diff --git a/CLAUDE.md b/CLAUDE.md index 1957bc2..5f26c25 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA - **Local + Azure.** `make provision` / `make teardown` / `make verify`, $25/mo budget alert. Nothing is deployed to Azure before milestone M3, and only with the owner's go-ahead. - **Phased delivery**: M0 bootstrap, then M1 (patterns 1, 2, 5, 6), M2 (10, 12, 4, 11), - M3 (7, 8, 9, 3 + Azure). One PR per milestone. + M3a (8, 7, 9, local) and M3b (3 + Azure, owner go-ahead). One PR per milestone. - Screenshots live in `docs/screenshots/` and are referenced by relative path. Never use GitHub `user-attachments` links (they went dead in the parent project). diff --git a/contracts/pacts/order-inventory.json b/contracts/pacts/order-inventory.json new file mode 100644 index 0000000..149f17d --- /dev/null +++ b/contracts/pacts/order-inventory.json @@ -0,0 +1,199 @@ +{ + "consumer": { + "name": "order" + }, + "interactions": [ + { + "description": "a release of a stock hold", + "pending": false, + "providerStates": [ + { + "name": "a stock hold exists", + "params": { + "reservation_id": "3f0c1d2e-0000-4000-8000-000000000001" + } + } + ], + "request": { + "method": "POST", + "path": "/api/inventory/reservations/3f0c1d2e-0000-4000-8000-000000000001/release" + }, + "response": { + "body": { + "content": { + "result": { + "reservation_id": "3f0c1d2e-0000-4000-8000-000000000001", + "status": "RELEASED" + } + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + }, + { + "description": "a stock hold for a checkout", + "pending": false, + "providerStates": [ + { + "name": "product 1 has stock" + } + ], + "request": { + "body": { + "content": { + "items": [ + { + "product_id": 1, + "quantity": 2 + } + ], + "order_id": 42, + "reservation_id": "3f0c1d2e-0000-4000-8000-000000000001" + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "method": "POST", + "path": "/api/inventory/reservations" + }, + "response": { + "body": { + "content": { + "result": { + "reservation_id": "3f0c1d2e-0000-4000-8000-000000000001", + "status": "RESERVED" + } + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.result.reservation_id": { + "combine": "AND", + "matchers": [ + { + "match": "type" + } + ] + } + } + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + }, + { + "description": "a stock hold that is more than inventory has", + "pending": false, + "providerStates": [ + { + "name": "product 1 has stock" + } + ], + "request": { + "body": { + "content": { + "items": [ + { + "product_id": 1, + "quantity": 100000 + } + ], + "order_id": 43, + "reservation_id": "3f0c1d2e-0000-4000-8000-000000000002" + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "method": "POST", + "path": "/api/inventory/reservations" + }, + "response": { + "body": { + "content": { + "short": [ + { + "available": 25, + "product_id": 1 + } + ] + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.short": { + "combine": "AND", + "matchers": [ + { + "match": "type", + "min": 1 + } + ] + }, + "$.short[*].available": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.short[*].product_id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "status": 409 + }, + "type": "Synchronous/HTTP" + } + ], + "metadata": { + "pactRust": { + "ffi": "0.5.12", + "models": "1.3.16" + }, + "pactSpecification": { + "version": "4.0" + } + }, + "provider": { + "name": "inventory" + } +} \ No newline at end of file diff --git a/contracts/pacts/order-payment.json b/contracts/pacts/order-payment.json index 7eb390d..64303f3 100644 --- a/contracts/pacts/order-payment.json +++ b/contracts/pacts/order-payment.json @@ -98,6 +98,84 @@ }, "type": "Synchronous/HTTP" }, + { + "description": "a charge the bank declines", + "pending": false, + "providerStates": [ + { + "name": "payment is healthy" + } + ], + "request": { + "body": { + "content": { + "amount_cents": 899, + "order_id": 43, + "simulate": "decline" + }, + "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/charge" + }, + "response": { + "body": { + "content": { + "result": { + "id": 2, + "status": "DECLINED" + } + }, + "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 health check through the circuit breaker", "pending": false, diff --git a/docs/PLAN.md b/docs/PLAN.md index 1fe585b..e97dc74 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -129,3 +129,30 @@ Each milestone ends with: tests green, a click-through of its 4 pattern pages, s - Manual click-through of all 12 pattern pages in the browser pane, with a trace visible in `otel-desktop-viewer` for one order. - CI: a commit touching only `services/order/` runs only that matrix leg; the documented contract-break branch goes red. - M3 only: `make provision`, repeat the smoke flow against Azure, `make teardown`, `make verify` returns PASS. + +## M3 review (2026-11-15, after M1 and M2 shipped) + +What changed since this plan was written: checkout already prices from catalog and charges payment +behind the circuit breaker (M2), checkout does not reserve stock yet, the registry is local only, +the login signing key has no Azure home yet, and Redis is not installed locally yet. + +Decisions: +1. **Saga style: orchestrated.** The order service calls inventory (reserve), then payment (charge), + then confirms. If payment fails or its breaker is open, it releases the stock and cancels the + order. Each step also publishes an event through the outbox for pattern 7. Chosen over a fully + event-driven saga: checkout answers in about 1 s and reuses the M2 breaker. +2. **Event consumer: inventory finishes the sale.** The saga only reserves stock. Inventory reads + `OrderConfirmed` from Redis and moves the units from reserved to sold (on hand goes down). + "Stop the bus" leaves stock reserved with events waiting in the outbox, then it settles when Redis + is back. Chosen over a new notifications service: no 6th service, and the effect is visible stock. +3. **Pipeline reach: GitHub deploys to Azure.** A manual "Deploy" workflow builds the changed images + and updates the Container Apps, logging in with OIDC (no Azure secret stored in GitHub). One Azure + identity for this repo, with access to `rg-microservices-12-patterns` only; `make provision` + re-grants it after each teardown. One-time setup done together with the owner. + Settled without a decision: Redis in Azure is one more Container App (1 replica while provisioned, + about $0.05 per 8-hour session; Azure Cache for Redis starts near $16/mo). `make provision` creates + the JWT signing key and stores it as a Container Apps secret. +4. **Delivery: M3 splits into 2 PRs.** M3a = patterns 8, 7, 9 (saga, outbox events, inventory + consumer, hardened containers), all local, about 2 days. M3b = pattern 3 (path-filtered CI, OIDC + Deploy workflow, Azure identity setup) plus the one real Azure run, about 1 day, started only on the + owner's go-ahead after M3a merges. diff --git a/docs/screenshots/p07-event-driven.jpg b/docs/screenshots/p07-event-driven.jpg new file mode 100644 index 0000000000000000000000000000000000000000..f077b277cdfa855e40b22404edf6bd9866477924 GIT binary patch literal 65319 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 literal 0 HcmV?d00001 diff --git a/docs/screenshots/p09-containerization.jpg b/docs/screenshots/p09-containerization.jpg new file mode 100644 index 0000000000000000000000000000000000000000..e5c7c17255671d59019e1fdb13110b73e2c0ae39 GIT binary patch literal 71269 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 z zl@A9hTGzdz_J#?u>)zq^^;d<|5Y}uO;h#Qrp}*8MUJ#OozAxG=)9NhFucHoLmEHqM zfADh)(IRxf26u(O*^{IXkkPrh-rd^bW$JVdPMMmK>v~cFv8EK}ch1ZQZd+(EQZD-U z9(&O}LyMC}-WBSxhDGme%04fM^zZ2EH}^KIOW9BK4oPVc*Kzc&aGb&n_~nDfFJ&2* zLHykmI=He=@}?nc_+iTde{;*IyUr~L1W&`&A-%rZQ|J9tgZQo>V*!o12_J`Cvzyvo$19{_VyZj6x`H`y2RAI%9XO)bxOdHQmIJsDqlGgi4^ zXQpl%0v!PE$q6>!G`|(nE>=lnlrPDVJl@4XCC|I~O8wl=ej7~}u*H+mB+y6dK4~cm zWB?ZMLAkxvh-D|;;;1mB8*X0okb*jjG&X={tWA4kB(kq#6j9q`Y77B$;c~AkrhDg3hx)%g7(IO2i7h)4O3$$=;#%^X#W<#E_H*der_ zW9BaN_0(Twb-Mg?5Dvd67GAO^H-_4|X6=FH!z9Oj%JXW}1#I~T*dDc0o+m5?TV+l? z0O4fWqOi554D`!4{T0{`$|rAX3<+t`+|W=GNp2muVL!qwHq9csK||qF_@!2@qqMY6 zgZA+x@^$PT#T(5$scVA|h}4Kp3w-yv%SvAf5=SJhsfq_HT`1^jm0)>mopjbc8BC;4 z1BG(wTEq$)3*?cEWW6CR714#7GNWn3>D5`t&5-kwXK(aJPbFgb0NP(W$&^m;B<;na zglq<)acVL!E3me zC#VIORh@pgNT;@==QEoMYx9kmnyAnQaX)QiXFs|VbK<;sQg?n@F6#IV!gcG5UvzPgo%lwj-VocN)&2 kN`;|+sdW4wR5bj%n5KX0J-?S)215uXmM77eyT8r; + created_at: string | null; + published_at: string | null; + attempts: number; + last_error: string | null; +} + +export interface StockRow { + product_id: number; + on_hand: number; + reserved: number; + available: number; +} + +export interface EventsView { + outbox: { pending: number; results: OutboxRow[]; bus_connected: boolean } | null; + consumed: { event_id: string; type: string; reservation_id: string | null; outcome: string; handled_at: string | null }[] | null; + stock: StockRow[] | null; + reservations: { reservation_id: string; order_id: number; status: string; items: { product_id: number; quantity: number }[] }[] | null; + bus_connected: boolean[] | null; + chaos_enabled: boolean; +} + +export interface RuntimeInfo { + service: string; + instance: string; + uid?: number | null; + root?: boolean; + in_container?: boolean; + os?: string; + arch?: string; + python?: string; + git_sha?: string; + unreachable?: boolean; +} + +export const asyncApi = { + checkout: (token: string, simulateDecline: boolean) => + getAny<{ message?: string; saga_id?: string; failed_step?: string }>("/api/shop/order/checkout", { + method: "POST", + headers: { ...authHeaders(token), "Content-Type": "application/json" }, + body: JSON.stringify({ simulate_decline: simulateDecline }), + }), + sagas: (token: string) => request<{ results: SagaRun[] }>("/api/shop/order/sagas", { headers: authHeaders(token) }), + addToCart: (token: string, productId: number, qty: number) => shopApi.addToCart(token, productId, qty), + events: () => request("/api/patterns/events"), + setBus: (connected: boolean) => + getAny<{ bus_connected?: boolean; message?: string }>("/api/patterns/events/bus", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ connected }), + }), + runtime: () => request<{ processes: RuntimeInfo[] }>("/api/patterns/runtime"), +}; diff --git a/frontend/src/pages/Home.tsx b/frontend/src/pages/Home.tsx index cbed26d..fa8bff0 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. 8 are live now, from Database per Service to Service Discovery; the last 4 arrive in M3.

+

The 12 patterns. 11 are live now; CI-CD arrives in M3b.

diff --git a/frontend/src/pages/PatternPage.tsx b/frontend/src/pages/PatternPage.tsx index 162bdd2..7874e03 100644 --- a/frontend/src/pages/PatternPage.tsx +++ b/frontend/src/pages/PatternPage.tsx @@ -3,9 +3,12 @@ import { Link, useParams } from "react-router-dom"; import ApiGatewayDemo from "../patterns/demos/ApiGatewayDemo"; import BoundedContextDemo from "../patterns/demos/BoundedContextDemo"; import CircuitBreakerDemo from "../patterns/demos/CircuitBreakerDemo"; +import ContainerizationDemo from "../patterns/demos/ContainerizationDemo"; import ContractTestingDemo from "../patterns/demos/ContractTestingDemo"; +import EventDrivenDemo from "../patterns/demos/EventDrivenDemo"; 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 StatelessDemo from "../patterns/demos/StatelessDemo"; import { PATTERNS } from "../patterns/content"; @@ -19,6 +22,9 @@ const DEMOS: Record ReactNode> = { "stateless-services": () => , "contract-testing": () => , "service-discovery": () => , + "event-driven-architecture": () => , + saga: () => , + containerization: () => , }; export default function PatternPage() { diff --git a/frontend/src/pages/Patterns.tsx b/frontend/src/pages/Patterns.tsx index fce17c7..5ca1ef6 100644 --- a/frontend/src/pages/Patterns.tsx +++ b/frontend/src/pages/Patterns.tsx @@ -9,7 +9,7 @@ export default function Patterns() {

The 12 patterns

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; the rest arrive in milestone M3. + services. {liveCount} of 12 are live; the last one, CI-CD, arrives in milestone M3b.

diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts index ee341a3..1e073ab 100644 --- a/frontend/src/patterns/content.ts +++ b/frontend/src/patterns/content.ts @@ -123,9 +123,74 @@ export const PATTERNS: PatternInfo[] = [ ], source: { label: "OpenTelemetry — Python zero-code instrumentation", url: "https://opentelemetry.io/docs/zero-code/python/" }, }, - { n: 7, slug: "event-driven-architecture", name: "Event-Driven Architecture", what: "Services communicate by publishing and consuming events.", milestone: "M3", live: false }, - { n: 8, slug: "saga", name: "Saga Pattern", what: "Coordinates distributed transactions and rolls back failures safely.", milestone: "M3", live: false }, - { n: 9, slug: "containerization", name: "Containerization", what: "Packages each service with all its dependencies.", milestone: "M3", live: false }, + { + n: 7, + slug: "event-driven-architecture", + name: "Event-Driven Architecture", + what: "Services communicate by publishing and consuming events.", + milestone: "M3", + live: true, + problem: + "If the order service had to call inventory, shipping and email directly to finish every sale, it would wait on all of them and fail whenever any one is down. Every new listener means changing the order service.", + inThisProject: [ + "The order service saves OrderConfirmed in an outbox table, in the same database transaction as the order. The event exists if and only if the order does.", + "A relay publishes outbox events to one Redis Stream, shop.events, once a second. If Redis is down, they wait in the table.", + "Inventory reads the stream in its own consumer group and turns the stock hold into a sale. It acknowledges an event only after handling it.", + "Delivery is at least once, so inventory records every event id it handled and skips duplicates.", + ], + whenNotToUse: [ + "When the caller needs the answer now, such as \"is this in stock?\", call the service directly. An event cannot answer a question.", + "Events make the system eventually consistent: for a moment, stock shows as held, not sold. The UI and the business must accept that.", + "Tracing a flow through events is harder than through calls. Carry IDs in every event, as these do.", + ], + source: { label: "microservices.io — Transactional outbox", url: "https://microservices.io/patterns/data/transactional-outbox.html" }, + }, + { + n: 8, + slug: "saga", + name: "Saga Pattern", + what: "Coordinates distributed transactions and rolls back failures safely.", + milestone: "M3", + live: true, + problem: + "Checkout touches 3 databases: stock, payment and orders. No transaction spans them. If the card is declined after stock was held, something must put the stock back, or it is lost for good.", + inThisProject: [ + "The order service orchestrates the saga: price (catalog), hold stock (inventory), charge (payment), confirm.", + "If a step fails, it undoes the earlier ones in reverse order. Only the stock hold changed another service, so the undo is releasing it.", + "If the release call itself fails, a StockReleaseRequested event goes through the outbox, so inventory releases it later.", + "Every step is logged in saga_step. Holds are keyed by the saga id, so a retried request never holds stock twice.", + "A declined card is a normal answer, not a failure, so it does not trip the M2 circuit breaker. The cart is kept for another try.", + ], + whenNotToUse: [ + "If the data can live in one database, use one local transaction. A saga is the price of splitting data, not a goal.", + "Every step needs an undo, and the undo must be safe to run twice. Steps that cannot be undone, such as sending an email, go last.", + "Between steps, other users can see the half-done state (held stock). Design for it.", + ], + source: { label: "microservices.io — Saga", url: "https://microservices.io/patterns/data/saga.html" }, + }, + { + n: 9, + slug: "containerization", + name: "Containerization", + what: "Packages each service with all its dependencies.", + milestone: "M3", + live: true, + problem: + "\"It works on my machine\": each server needs the right Python, libraries and settings. The owner's Mac is arm64 and Azure runs amd64, so even the processor differs.", + inThisProject: [ + "One image per service, plus the gateway and the registry: 7 Dockerfiles.", + "Multi-stage builds: dependencies are installed in a first stage, and only the virtualenv and source are copied into the final image.", + "Every image runs as uid 10001, never root, and carries the git commit it was built from.", + "Images are built only in the cloud (az acr build) or in GitHub Actions, always for linux/amd64. Never on the Mac.", + "CI builds every image on every pull request, starts it, checks /health, and fails if it runs as root.", + ], + whenNotToUse: [ + "A container is not a security boundary on its own. Non-root, small images and patched base images still matter.", + "Do not put secrets in images. Here, keys and passwords come from Container Apps secrets at run time.", + "For a single small app, a managed platform that builds from source can be simpler than owning Dockerfiles.", + ], + source: { label: "Docker docs — Multi-stage builds", url: "https://docs.docker.com/build/building/multi-stage/" }, + }, { n: 10, slug: "stateless-services", diff --git a/frontend/src/patterns/demos/ContainerizationDemo.tsx b/frontend/src/patterns/demos/ContainerizationDemo.tsx new file mode 100644 index 0000000..0aa7276 --- /dev/null +++ b/frontend/src/patterns/demos/ContainerizationDemo.tsx @@ -0,0 +1,112 @@ +import { useEffect, useState } from "react"; +import { RuntimeInfo, asyncApi } from "../../api/gatewayClient"; + +const DOCKERFILE = `FROM python:3.12-slim AS build # stage 1: install dependencies +RUN python -m venv /opt/venv +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" + +FROM python:3.12-slim # stage 2: only what runs +ARG GIT_SHA=unknown +ENV RUN_MODE=azure GIT_SHA=$GIT_SHA ... +RUN useradd --uid 10001 --no-create-home app +COPY --from=build /opt/venv /opt/venv # no pip cache, no build files +COPY --chown=10001:10001 . . +USER 10001 # never root +CMD ["gunicorn", "--workers", "1", "--threads", "4", ...]`; + +export default function ContainerizationDemo() { + const [processes, setProcesses] = useState([]); + const [error, setError] = useState(null); + + useEffect(() => { + asyncApi + .runtime() + .then((r) => setProcesses(r.processes)) + .catch((err) => setError(String(err))); + }, []); + + const anyContainer = processes.some((p) => p.in_container); + + return ( +
+
+

How each process is running right now

+

+ {anyContainer + ? "These processes run in containers built from the Dockerfiles below." + : "Locally, make run starts plain processes, no containers (this project never uses Docker on the Mac). In Azure and in CI the same code runs in the images below, as uid 10001."} +

+ {error &&

{error}

} +
+ + + + + + + + + + + + + {processes.map((p) => ( + + + {p.unreachable ? ( + + ) : ( + <> + + + + + + + )} + + ))} + +
ProcessContainerRuns asPlatformPythonBuild
+ + {p.instance} + + unreachable + {p.in_container ? "yes" : "no"} + {p.root ? "root" : `uid ${p.uid}`} + + {p.os?.toLowerCase()}/{p.arch} + {p.python} + {p.git_sha === "local" ? "local" : p.git_sha?.slice(0, 7)} +
+
+
+ +
+
+

Every service's Dockerfile, in short

+
{DOCKERFILE}
+
+
+

What CI checks on every pull request

+
    +
  1. + Builds all 7 images (5 services, gateway, registry) for linux/amd64, the platform Azure + Container Apps runs. The owner's Mac is arm64, so images are never built on it. +
  2. +
  3. Starts each image and waits for /health to answer.
  4. +
  5. Fails if the process inside runs as root (uid 0).
  6. +
  7. Writes each image's size to the run summary.
  8. +
+

+ A .dockerignore in each service keeps local virtualenvs, databases and keys out of the build. + The image is labelled with the git commit it was built from, shown in the Build column in Azure. +

+
+
+
+ ); +} diff --git a/frontend/src/patterns/demos/EventDrivenDemo.tsx b/frontend/src/patterns/demos/EventDrivenDemo.tsx new file mode 100644 index 0000000..93fdb79 --- /dev/null +++ b/frontend/src/patterns/demos/EventDrivenDemo.tsx @@ -0,0 +1,169 @@ +import { useEffect, useState } from "react"; +import { EventsView, asyncApi, savedToken } from "../../api/gatewayClient"; + +function time(iso: string | null): string { + return iso ? new Date(iso.endsWith("Z") || iso.includes("+") ? iso : `${iso}Z`).toLocaleTimeString() : "–"; +} + +export default function EventDrivenDemo() { + const token = savedToken(); + const [view, setView] = useState(null); + const [error, setError] = useState(null); + const [message, setMessage] = useState(null); + const [busy, setBusy] = useState(false); + + function load() { + asyncApi + .events() + .then((v) => { + setView(v); + setError(null); + }) + .catch((err) => setError(String(err))); + } + + useEffect(() => { + load(); + const timer = setInterval(load, 1500); + return () => clearInterval(timer); + }, []); + + async function setBus(connected: boolean) { + const { status, body } = await asyncApi.setBus(connected); + setMessage(status === 200 ? (connected ? "Bus reconnected. Watch the waiting events go out." : "Bus disconnected. Buy something and watch the event wait.") : body.message ?? `HTTP ${status}`); + load(); + } + + async function buyOne() { + if (!token) return; + setBusy(true); + try { + await asyncApi.addToCart(token, 1, 1); + const { status, body } = await asyncApi.checkout(token, false); + setMessage(status === 200 ? "Bought 1 mug. OrderConfirmed is in the outbox." : body.message ?? `HTTP ${status}`); + } finally { + setBusy(false); + load(); + } + } + + const connected = view?.bus_connected?.every(Boolean) ?? true; + const mug = view?.stock?.find((s) => s.product_id === 1); + + return ( +
+ {error &&

{error}

} +
+
+

The bus

+

+ {connected ? "connected" : "disconnected"}{" "} + + {view?.outbox ? `${view.outbox.pending} event(s) waiting in the outbox` : "order service unreachable"} + +

+
+ + + {token && ( + + )} +
+ {!view?.chaos_enabled &&

Demo switches are off. Run the stack with make run to use them.

} + {message &&

{message}

} +
+
+

Mug stock in inventory

+ {mug && ( + + + + + + + + + + + +
On hand{mug.on_hand}
Held, waiting for OrderConfirmed{mug.reserved}
+ )} +

+ While the bus is down, a sale stays "held". Inventory sells it as soon as the event arrives. +

+
+
+ +
+
+

Order's outbox (publisher)

+

+ Saved in the same database transaction as the order. A relay publishes it to Redis, once a second. +

+
+ + + + + + + + + + + {view?.outbox?.results.slice(0, 8).map((e) => ( + + + + + + + ))} + +
EventSavedStatusTries
+ {e.type} + {time(e.created_at)} + + {e.published_at ? `published ${time(e.published_at)}` : "waiting"} + + {e.attempts}
+
+
+
+

What inventory did (consumer)

+

+ Reads the stream in the "inventory" consumer group. Each event is acted on once, even if delivered twice. +

+
+ + + + + + + + + + {view?.consumed?.slice(0, 8).map((e) => ( + + + + + + ))} + +
EventHandledResult
+ {e.type} + {time(e.handled_at)}{e.outcome}
+
+
+
+
+ ); +} diff --git a/frontend/src/patterns/demos/SagaDemo.tsx b/frontend/src/patterns/demos/SagaDemo.tsx new file mode 100644 index 0000000..f0b8f71 --- /dev/null +++ b/frontend/src/patterns/demos/SagaDemo.tsx @@ -0,0 +1,163 @@ +import { useEffect, useState } from "react"; +import { Link } from "react-router-dom"; +import { SagaRun, StockRow, asyncApi, savedToken } from "../../api/gatewayClient"; + +const STEP_LABEL: Record = { + price: "1. Price the cart (catalog)", + reserve_stock: "2. Hold the stock (inventory)", + charge_payment: "3. Charge the card (payment)", + confirm: "4. Confirm the order", + release_stock: "Undo step 2: release the stock", +}; + +const PILL: Record = { done: "done", failed: "failed", compensated: "running" }; +const DEMO_PRODUCT = 1; + +export default function SagaDemo() { + const token = savedToken(); + const [decline, setDecline] = useState(false); + const [busy, setBusy] = useState(false); + const [result, setResult] = useState<{ ok: boolean; message: string } | null>(null); + const [sagas, setSagas] = useState([]); + const [stock, setStock] = useState(null); + + async function refresh() { + if (!token) return; + const [history, view] = await Promise.all([asyncApi.sagas(token).catch(() => null), asyncApi.events().catch(() => null)]); + if (history) setSagas(history.results); + setStock(view?.stock?.find((s) => s.product_id === DEMO_PRODUCT) ?? null); + } + + useEffect(() => { + refresh(); + // 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 buy() { + if (!token) return; + setBusy(true); + setResult(null); + try { + await asyncApi.addToCart(token, DEMO_PRODUCT, 2); + const { status, body } = await asyncApi.checkout(token, decline); + setResult({ ok: status === 200, message: status === 200 ? "Order placed. Payment approved." : body.message ?? `HTTP ${status}` }); + } catch (err) { + setResult({ ok: false, message: String(err) }); + } finally { + await refresh(); + setTimeout(refresh, 1500); // inventory sells the hold a moment later, when it reads the event + setBusy(false); + } + } + + const latest = sagas[0]; + + return ( +
+
+
+

Step 1. Buy 2 Contoso Mugs

+

Adds 2 mugs to your cart and checks out. The order service runs the saga below.

+ + + {result && ( +

+ {result.ok ? "Completed" : "Rolled back"}{" "} + {result.message} +

+ )} +
+
+

Mug stock in inventory

+ {stock ? ( + + + + + + + + + + + + + + + +
On hand{stock.on_hand}
Held for checkouts in progress{stock.reserved}
Available to sell{stock.available}
+ ) : ( +

Inventory is unreachable.

+ )} +

+ A declined card leaves all 3 numbers as they were. An approved one lowers on hand by 2, once inventory reads + the OrderConfirmed event. +

+
+
+ + {latest && ( +
+

Step 2. What the saga did

+

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

+
    + {latest.steps.map((s, i) => ( +
  1. + {s.status} + {STEP_LABEL[s.step] ?? s.step} + {s.detail && · {s.detail}} +
  2. + ))} +
+
+ )} + + {sagas.length > 1 && ( +
+

Your earlier checkouts

+ + + + + + + + + + + {sagas.slice(1).map((s) => ( + + + + + + + ))} + +
SagaOrderOutcomeStopped at
+ {s.saga_id.slice(0, 8)} + #{s.order_id}{s.outcome}{s.steps.find((x) => x.status === "failed")?.step ?? "–"}
+
+ )} +
+ ); +} diff --git a/frontend/src/theme/contoso.css b/frontend/src/theme/contoso.css index 579ec6f..4fe916d 100644 --- a/frontend/src/theme/contoso.css +++ b/frontend/src/theme/contoso.css @@ -337,3 +337,24 @@ h3 { padding-left: 1.1rem; font-size: 0.85rem; } + +/* Saga timeline (pattern 8) */ +.saga-timeline { + list-style: none; + padding: 0; + margin: 0; + display: grid; + gap: 0.4rem; +} +.saga-step { + display: flex; + flex-wrap: wrap; + gap: 0.5rem; + align-items: baseline; + padding: 0.5rem 0.75rem; + border-left: 3px solid var(--contoso-success); + background: var(--contoso-bg); + border-radius: 4px; +} +.saga-step.failed { border-left-color: var(--contoso-danger); } +.saga-step.compensated { border-left-color: var(--contoso-warning); } diff --git a/gateway/.dockerignore b/gateway/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/gateway/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/gateway/Dockerfile b/gateway/Dockerfile index f949e6b..4ec3257 100644 --- a/gateway/Dockerfile +++ b/gateway/Dockerfile @@ -1,18 +1,29 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: built only in the cloud (az acr build) or in GitHub Actions, for linux/amd64. +# Multi-stage: dependencies in a virtualenv, then a clean image running as an unprivileged user. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[fastapi]" - -ENV RUN_MODE=azure \ - PYTHONUNBUFFERED=1 +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[fastapi]" +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared +USER 10001 EXPOSE 8100 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8100"] diff --git a/gateway/app/observability.py b/gateway/app/observability.py index ab65b4f..042aedc 100644 --- a/gateway/app/observability.py +++ b/gateway/app/observability.py @@ -13,10 +13,11 @@ from opentelemetry import trace from shop_common import metrics +from shop_common.runtime import runtime_info from shop_common.telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing SERVICE_NAME = "gateway" -_QUIET_PATHS = ("/health", "/metrics", "/debug/spans") +_QUIET_PATHS = ("/health", "/metrics", "/debug/spans", "/debug/runtime") def install(app: FastAPI) -> None: @@ -54,6 +55,10 @@ async def prometheus_metrics(): body, content_type = metrics.render() return Response(content=body, media_type=content_type) + @app.get("/debug/runtime", include_in_schema=False) + async def debug_runtime(): + return runtime_info(SERVICE_NAME, SERVICE_NAME) + @app.get("/debug/spans", include_in_schema=False) async def debug_spans(trace_id: str | None = None): spans = SPAN_STORE.by_trace(trace_id) if trace_id else SPAN_STORE.recent() diff --git a/gateway/app/routers/resilience.py b/gateway/app/routers/resilience.py index 488cca0..44940a5 100644 --- a/gateway/app/routers/resilience.py +++ b/gateway/app/routers/resilience.py @@ -1,5 +1,5 @@ -"""Live demo endpoints for the M2 pattern pages: 4 (Circuit Breaker), 10 (Stateless Services) and -12 (Service Discovery). The stop and break switches work only with CHAOS_ENABLED=1 (make run).""" +"""Live demo endpoints for patterns 4 (Circuit Breaker), 7 (Event-Driven), 10 (Stateless Services) +and 12 (Service Discovery). The stop, break and bus switches work only with CHAOS_ENABLED=1 (make run).""" import asyncio import time @@ -120,3 +120,73 @@ async def set_payment_mode(body: PaymentMode): except httpx.HTTPError as exc: return JSONResponse({"message": f"payment unreachable ({exc.__class__.__name__})"}, status_code=503) return JSONResponse(response.json(), status_code=response.status_code) + + +# --- Pattern 7: Event-Driven Architecture ------------------------------------------------------ + +@router.get("/events") +async def events(request: Request): + """Both ends of the bus: order's outbox (published or waiting) and what inventory acted on, + plus current stock, so the page can show a hold turning into a sale.""" + async def get(service: str, path: str, base: str | None = None): + try: + response = await client.get(f"{base or config.url_for(service)}{path}", headers=upstream_headers(request)) + return response.json() if response.status_code == 200 else None + except httpx.HTTPError: + return None + + async with _client() as client: + order_bases = config.urls_for("order") + outbox, consumed, stock, reservations, *buses = await asyncio.gather( + get("order", "/api/order/outbox"), + get("inventory", "/api/inventory/events"), + get("inventory", "/api/inventory"), + get("inventory", "/api/inventory/reservations"), + *(get("order", "/api/order/outbox", base=b) for b in order_bases), + ) + return { + "outbox": outbox, + "consumed": consumed["results"] if consumed else None, + "stock": stock["results"] if stock else None, + "reservations": reservations["results"] if reservations else None, + "bus_connected": [b["bus_connected"] for b in buses if b] or None, + "chaos_enabled": config.CHAOS_ENABLED, + } + + +class BusSwitch(BaseModel): + connected: bool + + +@router.post("/events/bus") +async def set_bus(body: BusSwitch): + """Disconnects (or reconnects) every order replica's outbox relay from the bus.""" + if not config.CHAOS_ENABLED: + return JSONResponse(_CHAOS_OFF, status_code=403) + async with _client() as client: + results = await asyncio.gather( + *(client.post(f"{base}/debug/bus", json={"connected": body.connected}) for base in config.urls_for("order")), + return_exceptions=True, + ) + switched = sum(1 for r in results if isinstance(r, httpx.Response) and r.status_code == 200) + return {"bus_connected": body.connected, "replicas_switched": switched} + + +# --- Pattern 9: Containerization --------------------------------------------------------------- + +@router.get("/runtime") +async def runtime(request: Request): + """How every process runs: as root or not, in a container or not, which build (git SHA).""" + from shop_common.runtime import runtime_info + + async def one(service: str, base: str) -> dict: + try: + response = await client.get(f"{base}/debug/runtime", headers=upstream_headers(request)) + return response.json() + except (httpx.HTTPError, ValueError): + return {"service": service, "instance": base, "unreachable": True} + + async with _client() as client: + targets = [(n, url) for n in config.SERVICE_BASE_URLS for url in config.urls_for(n)] + services = await asyncio.gather(*(one(n, url) for n, url in targets)) + return {"processes": [runtime_info("gateway", "gateway"), *services]} diff --git a/gateway/tests/test_api.py b/gateway/tests/test_api.py index 0ee81b3..e99fd3d 100644 --- a/gateway/tests/test_api.py +++ b/gateway/tests/test_api.py @@ -119,3 +119,20 @@ async def fake_request(self, method, url, **kwargs): assert r.status_code == 200 assert r.headers["X-Instance-Id"] == "catalog-alive" assert "http://dead/api/products" in tried + + +def test_events_view_reports_unreachable_services_as_none(monkeypatch): + from app import config + + for name in config.SERVICE_BASE_URLS: + monkeypatch.setitem(config.SERVICE_BASE_URLS, name, "http://127.0.0.1:9") + body = client.get("/api/patterns/events").json() + assert body["outbox"] is None and body["stock"] is None + assert client.post("/api/patterns/events/bus", json={"connected": False}).status_code == 403 + + +def test_runtime_reports_the_gateway_without_a_user_name(): + gateway = client.get("/api/patterns/runtime").json()["processes"][0] + assert gateway["service"] == "gateway" + assert set(gateway) >= {"uid", "root", "in_container", "arch", "git_sha"} + assert "user" not in gateway diff --git a/registry/.dockerignore b/registry/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/registry/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/registry/Dockerfile b/registry/Dockerfile new file mode 100644 index 0000000..79dcad8 --- /dev/null +++ b/registry/Dockerfile @@ -0,0 +1,26 @@ +# Pattern 9: built only in the cloud (az acr build) or in GitHub Actions, for linux/amd64. +# Multi-stage: dependencies in a virtualenv, then a clean image running as an unprivileged user. + +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared +USER 10001 +EXPOSE 8500 + +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8500"] diff --git a/scripts/run_local.py b/scripts/run_local.py index 5b5c4a8..2bc8cf9 100644 --- a/scripts/run_local.py +++ b/scripts/run_local.py @@ -5,10 +5,12 @@ the gateway, then the frontend, each gated on its /health endpoint. The list comes from scripts/service_table.py. +Redis (the event bus, patterns 7 and 8) starts first, in memory only, if redis-server is installed. A service process that exits (for example one stopped from the Stateless or Service Discovery demo) is restarted after RESTART_DELAY_SECONDS, so the registry shows it leave and come back. """ import os +import shutil import signal import subprocess import sys @@ -20,10 +22,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) from _procutil import ensure_port_free # noqa: E402 from service_table import ( # noqa: E402 - FLASK_SERVICES, FRONTEND_DIR, FRONTEND_PORT, GATEWAY, REGISTRY, REPLICA_PORTS, Service, + FLASK_SERVICES, FRONTEND_DIR, FRONTEND_PORT, GATEWAY, REDIS_PORT, REDIS_URL, REGISTRY, REPLICA_PORTS, + REPO_ROOT, Service, ) RESTART_DELAY_SECONDS = 20 +redis_running = False processes: list[subprocess.Popen] = [] # pid -> how to start that process again (Flask services only) restartable: dict[int, tuple[str, object]] = {} @@ -51,9 +55,38 @@ def _service_url_env() -> dict[str, str]: """Every process gets every service's static URL (the fallback), the registry, and the demo switches.""" env = {f"{s.name.upper()}_SERVICE_BASE_URL": s.local_url for s in FLASK_SERVICES} env.update(REGISTRY_URL=REGISTRY.local_url, CHAOS_ENABLED="1") + if redis_running: + env["REDIS_URL"] = REDIS_URL return env +def start_redis() -> bool: + """Starts a throwaway redis-server: in memory only, no files written, stopped with the stack.""" + global redis_running + if shutil.which("redis-server") is None: + print(" ! redis-server not found (brew install redis). Events will wait in the outbox.") + return False + ensure_port_free(REDIS_PORT, "redis") + proc = subprocess.Popen( + ["redis-server", "--port", str(REDIS_PORT), "--bind", "127.0.0.1", "--save", "", "--appendonly", "no", + "--loglevel", "warning"], + cwd=str(REPO_ROOT), + ) + processes.append(proc) + print(f" redis starting on :{REDIS_PORT} (pid {proc.pid})…") + for _ in range(20): + try: + import socket + + with socket.create_connection(("127.0.0.1", REDIS_PORT), timeout=0.5): + redis_running = True + return True + except OSError: + time.sleep(0.25) + print(" ! redis did not start. Events will wait in the outbox.") + return False + + def start_registry() -> subprocess.Popen: ensure_port_free(REGISTRY.local_port, REGISTRY.name) proc = subprocess.Popen( @@ -125,6 +158,7 @@ def main() -> int: signal.signal(signal.SIGTERM, shutdown) print("=== Starting local stack (no Docker) ===") + start_redis() start_registry() if not _wait_for_health(f"{REGISTRY.local_url}/health"): print("registry failed to become healthy — aborting.") @@ -152,6 +186,7 @@ def main() -> int: Frontend http://127.0.0.1:{FRONTEND_PORT} Gateway {GATEWAY.local_url} Registry {REGISTRY.local_url} + Redis {REDIS_URL if redis_running else "not running (events wait in the outbox)"} {services} Press Ctrl+C to stop everything. diff --git a/scripts/service_table.py b/scripts/service_table.py index 8c33890..229bec7 100644 --- a/scripts/service_table.py +++ b/scripts/service_table.py @@ -40,13 +40,18 @@ def local_url(self) -> str: PYTHON_SERVICES = FLASK_SERVICES + [GATEWAY, REGISTRY] +# The event bus (patterns 7 and 8): a Homebrew redis-server, no Docker. Offset from Redis' default +# 6379 so a Redis the owner already runs is never touched. +REDIS_PORT = int(os.environ.get("REDIS_PORT", 6390)) +REDIS_URL = f"redis://127.0.0.1:{REDIS_PORT}/0" + # Extra local replicas (pattern 10): service name -> extra ports. Each runs as its own process # from the same folder, and registers with the registry under its own instance id. REPLICA_PORTS: dict[str, list[int]] = {"order": [5113]} -# Suites whose tests need pact-python (pattern 11): order is the consumer, payment and catalog +# Suites whose tests need pact-python (pattern 11): order is the consumer; payment, catalog and inventory # verify they still honour its contracts. -CONTRACT_SUITES = {"order", "payment", "catalog"} +CONTRACT_SUITES = {"order", "payment", "catalog", "inventory"} CONTRACTS_DIR = REPO_ROOT / "contracts" # shop_common (shared/), installed into every Python venv by setup.py. diff --git a/services/catalog/.dockerignore b/services/catalog/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/services/catalog/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/services/catalog/Dockerfile b/services/catalog/Dockerfile index beafb77..5c37183 100644 --- a/services/catalog/Dockerfile +++ b/services/catalog/Dockerfile @@ -1,19 +1,34 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: one image per service, built only in the cloud (az acr build) or in GitHub Actions, +# always for linux/amd64 (Azure Container Apps). Never built on the owner's arm64 Mac. +# +# Stage 1 installs dependencies into a virtualenv. Stage 2 copies only that virtualenv and the +# source into a clean image and runs as an unprivileged user, so no compiler cache, pip cache or +# root process ends up in production. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" -ENV RUN_MODE=azure \ +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ FLASK_ENV=production \ - PYTHONUNBUFFERED=1 - + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared && mkdir -p instance && chown 10001:10001 instance +USER 10001 EXPOSE 5102 # One process with threads, so the in-memory span store (pattern 6) sees every request. diff --git a/services/inventory/.dockerignore b/services/inventory/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/services/inventory/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/services/inventory/Dockerfile b/services/inventory/Dockerfile index 0c0ab19..1daa4af 100644 --- a/services/inventory/Dockerfile +++ b/services/inventory/Dockerfile @@ -1,19 +1,34 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: one image per service, built only in the cloud (az acr build) or in GitHub Actions, +# always for linux/amd64 (Azure Container Apps). Never built on the owner's arm64 Mac. +# +# Stage 1 installs dependencies into a virtualenv. Stage 2 copies only that virtualenv and the +# source into a clean image and runs as an unprivileged user, so no compiler cache, pip cache or +# root process ends up in production. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" -ENV RUN_MODE=azure \ +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ FLASK_ENV=production \ - PYTHONUNBUFFERED=1 - + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared && mkdir -p instance && chown 10001:10001 instance +USER 10001 EXPOSE 5105 # One process with threads, so the in-memory span store (pattern 6) sees every request. diff --git a/services/inventory/application/__init__.py b/services/inventory/application/__init__.py index a497636..64c0d80 100644 --- a/services/inventory/application/__init__.py +++ b/services/inventory/application/__init__.py @@ -3,6 +3,9 @@ Bounded context (pattern 2): Inventory does not know a product's name or price. It knows a StockItem keyed by the catalog's product_id, with how many are on hand and how many are reserved. Catalog owns "what we sell"; Inventory owns "how many we have". + +M3: holds stock for the checkout saga (pattern 8) and finishes the sale when an OrderConfirmed +event arrives from the bus (pattern 7). """ import os @@ -35,4 +38,11 @@ def create_app(config_name: str | None = None) -> Flask: seed_stock_if_empty() install_observability(app, "inventory", db) + + # Pattern 7: act on OrderConfirmed events from the bus (no-op without REDIS_URL). + from shop_common.flask_support import instance_id + + from .consumer import start as start_consumer + + start_consumer(app, instance_id("inventory")) return app diff --git a/services/inventory/application/consumer.py b/services/inventory/application/consumer.py new file mode 100644 index 0000000..2d1049b --- /dev/null +++ b/services/inventory/application/consumer.py @@ -0,0 +1,42 @@ +"""Inventory's event handler (pattern 7): finishes a sale when the order service confirms it. + +OrderConfirmed -> commit the reservation (reserved units become sold, on hand goes down) +StockReleaseRequested -> release the reservation (the saga's fallback when its direct call failed) +Anything else is not inventory's business and is acknowledged without action. +""" +from . import db, stock +from .models import ConsumedEvent + +HANDLERS = {"OrderConfirmed": stock.commit, "StockReleaseRequested": stock.release} + + +def handle(event: dict) -> None: + action = HANDLERS.get(event.get("type")) + if action is None: + return + if db.session.get(ConsumedEvent, event["event_id"]) is not None: + return # seen before: at-least-once delivery sent it twice + reservation_id = event["payload"].get("reservation_id") + reservation = action(reservation_id) + outcome = f"reservation {reservation.status}" if reservation else "no such reservation" + db.session.add(ConsumedEvent(event_id=event["event_id"], type=event["type"], + reservation_id=reservation_id, outcome=outcome)) + db.session.commit() + + +def start(app, instance_id: str) -> None: + from shop_common.events import start_consumer + from shop_common.flask_support import is_serving_process + from shop_common.telemetry import get_logger + + if not is_serving_process(app): + return + + def in_app(event: dict) -> None: + with app.app_context(): + try: + handle(event) + finally: + db.session.remove() + + start_consumer("inventory", instance_id, in_app, log=get_logger()) diff --git a/services/inventory/application/models.py b/services/inventory/application/models.py index 4ca5a28..e77bf13 100644 --- a/services/inventory/application/models.py +++ b/services/inventory/application/models.py @@ -21,3 +21,54 @@ def to_json(self): "reserved": self.reserved, "available": self.available, } + + +def _utcnow(): + from datetime import datetime, timezone + + return datetime.now(timezone.utc) + + +class Reservation(db.Model): + """Stock held for one checkout attempt (pattern 8). Keyed by the order service's saga id, so a + retried request or a redelivered event finds the same row instead of holding stock twice.""" + + __tablename__ = "reservation" + + id = db.Column(db.String(36), primary_key=True) # the saga id + order_id = db.Column(db.Integer, nullable=False, index=True) + items = db.Column(db.JSON, nullable=False) # [{"product_id": 1, "quantity": 2}] + status = db.Column(db.String(10), nullable=False) # RESERVED -> SOLD | RELEASED + created_at = db.Column(db.DateTime, default=_utcnow) + updated_at = db.Column(db.DateTime, default=_utcnow, onupdate=_utcnow) + + def to_json(self): + return { + "reservation_id": self.id, + "order_id": self.order_id, + "items": self.items, + "status": self.status, + "updated_at": self.updated_at.isoformat() if self.updated_at else None, + } + + +class ConsumedEvent(db.Model): + """Every event inventory acted on (pattern 7). Also the dedupe record: an event id seen before + is skipped, which makes handling idempotent under at-least-once delivery.""" + + __tablename__ = "consumed_event" + + event_id = db.Column(db.String(36), primary_key=True) + type = db.Column(db.String(40), nullable=False) + reservation_id = db.Column(db.String(36), nullable=True) + outcome = db.Column(db.String(120), nullable=False) + handled_at = db.Column(db.DateTime, default=_utcnow) + + def to_json(self): + return { + "event_id": self.event_id, + "type": self.type, + "reservation_id": self.reservation_id, + "outcome": self.outcome, + "handled_at": self.handled_at.isoformat() if self.handled_at else None, + } diff --git a/services/inventory/application/routes.py b/services/inventory/application/routes.py index e3cb0cc..fdef102 100644 --- a/services/inventory/application/routes.py +++ b/services/inventory/application/routes.py @@ -1,11 +1,24 @@ -from flask import Blueprint, jsonify, make_response +from flask import Blueprint, jsonify, make_response, request +from pydantic import BaseModel, Field, ValidationError +from shop_common.flask_support import chaos_enabled -from . import db -from .models import StockItem +from . import db, stock +from .models import ConsumedEvent, Reservation, StockItem inventory_api = Blueprint("inventory_api", __name__) +class Line(BaseModel): + product_id: int = Field(gt=0) + quantity: int = Field(gt=0) + + +class ReserveRequest(BaseModel): + reservation_id: str = Field(min_length=8, max_length=36) + order_id: int = Field(gt=0) + items: list[Line] = Field(min_length=1) + + @inventory_api.get("/api/inventory") def list_stock(): return jsonify({"results": [s.to_json() for s in StockItem.query.order_by(StockItem.product_id)]}) @@ -17,3 +30,50 @@ def get_stock(product_id: int): if item is None: return make_response(jsonify({"message": f"No stock record for product {product_id}"}), 404) return jsonify({"result": item.to_json()}) + + +@inventory_api.post("/api/inventory/reservations") +def reserve(): + try: + data = ReserveRequest.model_validate(request.get_json(silent=True) or {}) + except ValidationError as exc: + return make_response(jsonify({"message": "Invalid request", "errors": exc.errors(include_url=False)}), 400) + try: + reservation = stock.reserve(data.reservation_id, data.order_id, [line.model_dump() for line in data.items]) + except stock.OutOfStock as exc: + return make_response(jsonify({"message": "Not enough stock", "short": exc.args[0]}), 409) + return jsonify({"result": reservation.to_json()}) + + +@inventory_api.post("/api/inventory/reservations//release") +def release(reservation_id: str): + reservation = stock.release(reservation_id) + if reservation is None: + return make_response(jsonify({"message": "No such reservation"}), 404) + return jsonify({"result": reservation.to_json()}) + + +@inventory_api.get("/api/inventory/reservations") +def list_reservations(): + rows = Reservation.query.order_by(Reservation.updated_at.desc()).limit(20) + return jsonify({"results": [r.to_json() for r in rows]}) + + +@inventory_api.get("/api/inventory/events") +def consumed_events(): + rows = ConsumedEvent.query.order_by(ConsumedEvent.handled_at.desc()).limit(20) + return jsonify({"results": [e.to_json() for e in rows]}) + + +@inventory_api.post("/api/inventory//restock") +def restock(product_id: int): + """Demo and smoke-test helper: adds units on hand. Only with CHAOS_ENABLED=1 (make run).""" + if not chaos_enabled(): + return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) + quantity = int((request.get_json(silent=True) or {}).get("quantity", 0)) + item = db.session.get(StockItem, product_id) + if item is None or not 0 < quantity <= 1000: + return make_response(jsonify({"message": "Unknown product or quantity not in 1-1000"}), 400) + item.on_hand += quantity + db.session.commit() + return jsonify({"result": item.to_json()}) diff --git a/services/inventory/application/seed.py b/services/inventory/application/seed.py index 11cfbb4..0d39c4a 100644 --- a/services/inventory/application/seed.py +++ b/services/inventory/application/seed.py @@ -1,13 +1,17 @@ -"""Seeds stock for the catalog's 6 sample products (ids 1-6) on first local start. Idempotent.""" +"""Seeds stock for the catalog's 24 sample products (ids 1-24) on start. Idempotent: it only adds +rows that are missing, so counts that changed through sales are never reset.""" from . import db from .models import StockItem -SAMPLE_STOCK = {1: 25, 2: 40, 3: 60, 4: 15, 5: 10, 6: 30} +CATALOG_SAMPLE_COUNT = 24 +SAMPLE_STOCK = {1: 25, 2: 40, 3: 60, 4: 15, 5: 10, 6: 30} | { + product_id: 20 for product_id in range(7, CATALOG_SAMPLE_COUNT + 1) +} def seed_stock_if_empty() -> None: - if StockItem.query.first() is not None: - return + existing = {row.product_id for row in db.session.query(StockItem.product_id)} for product_id, on_hand in SAMPLE_STOCK.items(): - db.session.add(StockItem(product_id=product_id, on_hand=on_hand, reserved=0)) + if product_id not in existing: + db.session.add(StockItem(product_id=product_id, on_hand=on_hand, reserved=0)) db.session.commit() diff --git a/services/inventory/application/stock.py b/services/inventory/application/stock.py new file mode 100644 index 0000000..b18f17c --- /dev/null +++ b/services/inventory/application/stock.py @@ -0,0 +1,64 @@ +"""Stock rules for the checkout saga (pattern 8) and the event consumer (pattern 7). + +reserve: available -> reserved (saga step 1; all lines or none) +release: reserved -> available (saga compensation) +commit: reserved -> sold (on OrderConfirmed: on hand goes down) + +Each is idempotent: calling it again for the same reservation changes nothing. +""" +from . import db +from .models import Reservation, StockItem + + +class OutOfStock(Exception): + pass + + +def _lock(product_id: int) -> StockItem | None: + # Row lock on MySQL; SQLite serialises writers anyway. + return db.session.query(StockItem).filter_by(product_id=product_id).with_for_update().one_or_none() + + +def reserve(reservation_id: str, order_id: int, items: list[dict]) -> Reservation: + existing = db.session.get(Reservation, reservation_id) + if existing is not None: + return existing + short = [] + for line in items: + stock = _lock(line["product_id"]) + if stock is None or stock.available < line["quantity"]: + short.append({"product_id": line["product_id"], "wanted": line["quantity"], + "available": stock.available if stock else 0}) + if short: + db.session.rollback() + raise OutOfStock(short) + for line in items: + _lock(line["product_id"]).reserved += line["quantity"] + reservation = Reservation(id=reservation_id, order_id=order_id, items=items, status="RESERVED") + db.session.add(reservation) + db.session.commit() + return reservation + + +def release(reservation_id: str) -> Reservation | None: + reservation = db.session.get(Reservation, reservation_id) + if reservation is None or reservation.status != "RESERVED": + return reservation + for line in reservation.items: + _lock(line["product_id"]).reserved -= line["quantity"] + reservation.status = "RELEASED" + db.session.commit() + return reservation + + +def commit(reservation_id: str) -> Reservation | None: + reservation = db.session.get(Reservation, reservation_id) + if reservation is None or reservation.status != "RESERVED": + return reservation + for line in reservation.items: + stock = _lock(line["product_id"]) + stock.reserved -= line["quantity"] + stock.on_hand -= line["quantity"] + reservation.status = "SOLD" + db.session.commit() + return reservation diff --git a/services/inventory/requirements.txt b/services/inventory/requirements.txt index a12dc90..565f591 100644 --- a/services/inventory/requirements.txt +++ b/services/inventory/requirements.txt @@ -7,3 +7,4 @@ python-dotenv==1.0.1 gunicorn==23.0.0 pydantic==2.10.3 opentelemetry-instrumentation-flask==0.50b0 +redis==8.1.0 diff --git a/services/inventory/tests/test_contract_provider.py b/services/inventory/tests/test_contract_provider.py new file mode 100644 index 0000000..c22a16d --- /dev/null +++ b/services/inventory/tests/test_contract_provider.py @@ -0,0 +1,36 @@ +"""Provider side of pattern 11: inventory replays the order service's contract against itself.""" +from pathlib import Path + +from shop_common.contract_testing import verify_provider + +PACT_DIR = Path(__file__).resolve().parents[3] / "contracts" / "pacts" +HOLD_ID = "3f0c1d2e-0000-4000-8000-000000000001" + + +def test_inventory_honours_the_order_services_contract(app): + from application import db, stock + from application.models import Reservation + from application.seed import seed_stock_if_empty + + seed_stock_if_empty() + # Pact calls the state handlers on another thread. End this thread's transaction first, or + # SQLite's write lock makes the handlers wait forever. + db.session.commit() + db.session.remove() + + def no_hold_yet() -> None: + with app.app_context(): + if db.session.get(Reservation, HOLD_ID) is not None: + stock.release(HOLD_ID) + db.session.delete(db.session.get(Reservation, HOLD_ID)) + db.session.commit() + db.session.remove() + + def hold_exists() -> None: + no_hold_yet() + with app.app_context(): + stock.reserve(HOLD_ID, 42, [{"product_id": 1, "quantity": 2}]) + db.session.remove() + + verify_provider(app, provider="inventory", consumer="order", + states={"product 1 has stock": no_hold_yet, "a stock hold exists": hold_exists}, pact_dir=PACT_DIR) diff --git a/services/inventory/tests/test_inventory.py b/services/inventory/tests/test_inventory.py index d16d86a..33604c2 100644 --- a/services/inventory/tests/test_inventory.py +++ b/services/inventory/tests/test_inventory.py @@ -23,4 +23,4 @@ def test_get_stock_and_404(client): def test_health_db_reports_only_own_tables(client): body = client.get("/health/db").get_json() assert body["service"] == "inventory" - assert body["tables"] == ["stock_item"] + assert body["tables"] == ["consumed_event", "reservation", "stock_item"] diff --git a/services/inventory/tests/test_saga_and_events.py b/services/inventory/tests/test_saga_and_events.py new file mode 100644 index 0000000..ce6bbea --- /dev/null +++ b/services/inventory/tests/test_saga_and_events.py @@ -0,0 +1,74 @@ +"""Stock holds for the checkout saga (pattern 8) and the OrderConfirmed handler (pattern 7).""" +import pytest + +from application import consumer, db, stock +from application.models import StockItem +from application.seed import seed_stock_if_empty + +RID = "saga-0001-aaaa" + + +@pytest.fixture +def seeded(app): + seed_stock_if_empty() + return app + + +def _stock(product_id): + return db.session.get(StockItem, product_id).to_json() + + +def _reserve(client, rid=RID, qty=2): + return client.post("/api/inventory/reservations", + json={"reservation_id": rid, "order_id": 7, "items": [{"product_id": 1, "quantity": qty}]}) + + +def test_reserve_holds_stock_and_is_idempotent(seeded, client): + assert _reserve(client).status_code == 200 + assert _reserve(client).status_code == 200 # a retried request holds nothing extra + assert _stock(1) == {"product_id": 1, "on_hand": 25, "reserved": 2, "available": 23} + + +def test_reserve_is_all_or_nothing(seeded, client): + r = client.post("/api/inventory/reservations", json={"reservation_id": RID, "order_id": 7, "items": [ + {"product_id": 1, "quantity": 1}, {"product_id": 5, "quantity": 99}]}) + assert r.status_code == 409 + assert r.get_json()["short"][0]["product_id"] == 5 + assert _stock(1)["reserved"] == 0 + + +def test_release_returns_the_stock_once(seeded, client): + _reserve(client) + for _ in range(2): + assert client.post(f"/api/inventory/reservations/{RID}/release").get_json()["result"]["status"] == "RELEASED" + assert _stock(1)["reserved"] == 0 + + +def test_order_confirmed_event_finishes_the_sale_once(seeded, client): + _reserve(client, qty=3) + event = {"event_id": "evt-1", "type": "OrderConfirmed", "payload": {"reservation_id": RID, "order_id": 7}} + consumer.handle(event) + consumer.handle(event) # redelivered: must not sell twice + assert _stock(1) == {"product_id": 1, "on_hand": 22, "reserved": 0, "available": 22} + assert client.get("/api/inventory/events").get_json()["results"][0]["outcome"] == "reservation SOLD" + + +def test_released_reservation_cannot_be_sold_later(seeded, client): + _reserve(client) + stock.release(RID) + consumer.handle({"event_id": "evt-2", "type": "OrderConfirmed", "payload": {"reservation_id": RID}}) + assert _stock(1)["on_hand"] == 25 + + +def test_other_events_are_ignored(seeded): + from application.models import ConsumedEvent + + consumer.handle({"event_id": "evt-3", "type": "CheckoutFailed", "payload": {}}) + assert ConsumedEvent.query.count() == 0 + + +def test_restock_is_a_demo_switch(seeded, client, monkeypatch): + monkeypatch.delenv("CHAOS_ENABLED", raising=False) + assert client.post("/api/inventory/1/restock", json={"quantity": 5}).status_code == 403 + monkeypatch.setenv("CHAOS_ENABLED", "1") + assert client.post("/api/inventory/1/restock", json={"quantity": 5}).get_json()["result"]["on_hand"] == 30 diff --git a/services/order/.dockerignore b/services/order/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/services/order/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/services/order/Dockerfile b/services/order/Dockerfile index 906945d..ebb5da6 100644 --- a/services/order/Dockerfile +++ b/services/order/Dockerfile @@ -1,19 +1,34 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: one image per service, built only in the cloud (az acr build) or in GitHub Actions, +# always for linux/amd64 (Azure Container Apps). Never built on the owner's arm64 Mac. +# +# Stage 1 installs dependencies into a virtualenv. Stage 2 copies only that virtualenv and the +# source into a clean image and runs as an unprivileged user, so no compiler cache, pip cache or +# root process ends up in production. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" -ENV RUN_MODE=azure \ +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ FLASK_ENV=production \ - PYTHONUNBUFFERED=1 - + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared && mkdir -p instance && chown 10001:10001 instance +USER 10001 EXPOSE 5103 # One process with threads, so the in-memory span store (pattern 6) sees every request. diff --git a/services/order/application/__init__.py b/services/order/application/__init__.py index e512bdb..047f088 100644 --- a/services/order/application/__init__.py +++ b/services/order/application/__init__.py @@ -3,6 +3,7 @@ This service has no access to the user table at all. It learns who the caller is from the signed login token (pattern 10), prices orders by asking the catalog, and charges through the payment service behind a circuit breaker (pattern 4). See order_api/api/clients.py. +Checkout is a saga (pattern 8, saga.py) whose events leave through an outbox (pattern 7, outbox.py). """ import os @@ -33,9 +34,18 @@ def create_app(config_name: str | None = None) -> Flask: # db.create_all() runs regardless of RUN_MODE (migrations/ has no actual Alembic revisions, so gating # this to local-only left Azure MySQL with no schema at all). - db.create_all() + # Two order replicas share one database and start together (pattern 10). + from shop_common.db_setup import create_tables + + create_tables(db) # /health, /health/db, /debug/spans, /metrics, tracing and JSON logs (patterns 1 and 6). install_observability(app, "order", db) + # Pattern 7: publish outbox events to the bus in the background (no-op without REDIS_URL). + from shop_common.flask_support import instance_id + + from .outbox import start as start_outbox_relay + + start_outbox_relay(app, instance_id("order")) return app diff --git a/services/order/application/models.py b/services/order/application/models.py index 1ec9560..6cf70e4 100644 --- a/services/order/application/models.py +++ b/services/order/application/models.py @@ -37,3 +37,48 @@ def __init__(self, product_id, quantity): def to_json(self): return {"product_id": self.product_id, "quantity": self.quantity} + + +class SagaStep(db.Model): + """One line of a checkout saga's log (pattern 8). A saga is all rows sharing a saga_id.""" + + __tablename__ = "saga_step" + + id = db.Column(db.Integer, primary_key=True) + saga_id = db.Column(db.String(36), nullable=False, index=True) + order_id = db.Column(db.Integer, nullable=False) + user_id = db.Column(db.Integer, nullable=False, index=True) + step = db.Column(db.String(30), nullable=False) # price, reserve_stock, charge_payment, ... + status = db.Column(db.String(12), nullable=False) # done | failed | compensated | skipped + detail = db.Column(db.String(300), nullable=True) + at = db.Column(db.DateTime, default=_utcnow) + + def to_json(self): + return {"step": self.step, "status": self.status, "detail": self.detail, + "at": self.at.isoformat() if self.at else None} + + +class OutboxEvent(db.Model): + """An event waiting to be published (pattern 7). Written in the same transaction as the change + it describes; the relay in outbox.py publishes it to Redis and stamps published_at.""" + + __tablename__ = "outbox_event" + + id = db.Column(db.String(36), primary_key=True) # also the event id consumers dedupe on + type = db.Column(db.String(40), nullable=False) + payload = db.Column(db.JSON, nullable=False) + created_at = db.Column(db.DateTime, default=_utcnow, index=True) + published_at = db.Column(db.DateTime, nullable=True, index=True) + attempts = db.Column(db.Integer, default=0, nullable=False) + last_error = db.Column(db.String(200), nullable=True) + + def to_json(self): + return { + "event_id": self.id, + "type": self.type, + "payload": self.payload, + "created_at": self.created_at.isoformat() if self.created_at else None, + "published_at": self.published_at.isoformat() if self.published_at else None, + "attempts": self.attempts, + "last_error": self.last_error, + } diff --git a/services/order/application/order_api/api/clients.py b/services/order/application/order_api/api/clients.py index 40e48ba..9be3984 100644 --- a/services/order/application/order_api/api/clients.py +++ b/services/order/application/order_api/api/clients.py @@ -21,6 +21,7 @@ "user": os.environ.get("USER_SERVICE_BASE_URL", "http://127.0.0.1:5101"), "catalog": os.environ.get("CATALOG_SERVICE_BASE_URL", "http://127.0.0.1:5102"), "payment": os.environ.get("PAYMENT_SERVICE_BASE_URL", "http://127.0.0.1:5104"), + "inventory": os.environ.get("INVENTORY_SERVICE_BASE_URL", "http://127.0.0.1:5105"), } PAYMENT_TIMEOUT_SECONDS = float(os.environ.get("PAYMENT_TIMEOUT_SECONDS", "1.0")) @@ -49,6 +50,29 @@ def product_prices() -> dict[int, int]: return {p["id"]: p["price"] for p in response.json()["results"]} +# --- Inventory (saga steps, pattern 8) ------------------------------------------------------------ + +class OutOfStock(Exception): + def __init__(self, short: list[dict]): + super().__init__("not enough stock") + self.short = short + + +def reserve_stock(reservation_id: str, order_id: int, items: list[dict]) -> dict: + response = requests.post(f"{base_url('inventory')}/api/inventory/reservations", timeout=3, + json={"reservation_id": reservation_id, "order_id": order_id, "items": items}) + if response.status_code == 409: + raise OutOfStock(response.json().get("short", [])) + response.raise_for_status() + return response.json()["result"] + + +def release_stock(reservation_id: str) -> dict: + response = requests.post(f"{base_url('inventory')}/api/inventory/reservations/{reservation_id}/release", timeout=3) + response.raise_for_status() + return response.json()["result"] + + # --- Payment, behind the circuit breaker ---------------------------------------------------------- BREAKER = pybreaker.CircuitBreaker(fail_max=FAIL_MAX, reset_timeout=RESET_SECONDS, name="payment") @@ -84,8 +108,11 @@ def attempt() -> requests.Response: raise PaymentUnavailable("failed") -def charge(order_id: int, amount_cents: int) -> dict: - response = call_payment("POST", "/api/payment/charge", {"order_id": order_id, "amount_cents": amount_cents}) +def charge(order_id: int, amount_cents: int, simulate: str = "approve") -> dict: + body = {"order_id": order_id, "amount_cents": amount_cents} + if simulate != "approve": + body["simulate"] = simulate + response = call_payment("POST", "/api/payment/charge", body) response.raise_for_status() return response.json()["result"] diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index bd4f33e..ca2194b 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -1,11 +1,12 @@ import time -import requests from flask import jsonify, make_response, request from . import order_api_blueprint -from .. import db -from ..models import Order, OrderItem +from shop_common.flask_support import chaos_enabled + +from .. import db, outbox, saga +from ..models import Order, OrderItem, OutboxEvent from ..schemas import OrderAddItemRequest from ..validation import validate_form from .api import clients @@ -73,30 +74,38 @@ def checkout(): if order_model is None: return make_response(jsonify({"message": "No open order"}), 404) - try: - prices = clients.product_prices() - except requests.RequestException: - return make_response(jsonify({"message": "The catalog is unavailable, so the order cannot be priced. Your cart is kept."}), 503) - missing = [i.product_id for i in order_model.items if i.product_id not in prices] - if missing: - return make_response(jsonify({"message": f"Product(s) {missing} are no longer sold"}), 409) - amount = sum(prices[i.product_id] * i.quantity for i in order_model.items) + # Pattern 8 demo: {"simulate_decline": true} makes payment refuse the charge. + options = request.get_json(silent=True) or request.form + simulate = "decline" if str(options.get("simulate_decline", "")).lower() in ("1", "true", "yes") else "approve" + status, body = saga.run_checkout(order_model, u_id, simulate) + return make_response(jsonify(body), status) - try: - payment = clients.charge(order_model.id, amount) - except clients.PaymentUnavailable as exc: - state = clients.breaker_state() - wait = f" Try again in {state['retry_in_seconds']:.0f} s." if state["retry_in_seconds"] else "" - return make_response(jsonify({ - "message": f"Payment is unavailable right now, so nothing was charged. Your cart is kept.{wait}", - "reason": exc.reason, - "breaker": state, - }), 503) - - order_model.is_open = False - db.session.add(order_model) - db.session.commit() - return jsonify({"result": order_model.to_json(), "payment": payment}) + +@order_api_blueprint.route("/api/order/sagas", methods=["GET"]) +def sagas(): + u_id = _user_id() + if u_id is None: + return _not_logged_in() + return jsonify({"results": saga.recent_sagas(u_id)}) + + +# Pattern 7 demo: what is waiting in the outbox and what has been published. No personal data: +# events carry ids, quantities and amounts only. +@order_api_blueprint.route("/api/order/outbox", methods=["GET"]) +def outbox_events(): + rows = OutboxEvent.query.order_by(OutboxEvent.created_at.desc()).limit(20).all() + pending = OutboxEvent.query.filter(OutboxEvent.published_at.is_(None)).count() + return jsonify({"pending": pending, "results": [r.to_json() for r in rows], + "bus_connected": outbox.is_connected()}) + + +@order_api_blueprint.route("/debug/bus", methods=["POST"]) +def bus_switch(): + if not chaos_enabled(): + return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) + connected = bool((request.get_json(silent=True) or {}).get("connected", True)) + outbox.set_connected(connected) + return jsonify({"bus_connected": connected}) # Pattern 4 demo: one cheap call to payment through the same breaker that protects checkout. diff --git a/services/order/application/outbox.py b/services/order/application/outbox.py new file mode 100644 index 0000000..ab56c46 --- /dev/null +++ b/services/order/application/outbox.py @@ -0,0 +1,73 @@ +"""The outbox relay (pattern 7): publishes saved events to the Redis bus, oldest first. + +Runs on a background thread in every order replica, once a second. Both replicas read the same +outbox table, so an event can occasionally be published twice; consumers dedupe on event_id +(at-least-once delivery). If Redis is down, events stay in the table, unpublished, and go out +once it is back. Nothing is lost and checkout never waits for the bus. + +Demo switch (CHAOS_ENABLED=1 only): disconnect() makes this replica's relay behave as if the bus +were down, so the page can show events piling up and then draining. +""" +import threading +import time +from datetime import datetime, timezone + +from shop_common import events + +from . import db +from .models import OutboxEvent + +BATCH = 50 +_bus = {"connected": True} + + +def set_connected(connected: bool) -> None: + _bus["connected"] = connected + + +def is_connected() -> bool: + return _bus["connected"] + + +def publish_pending(client, source: str) -> int: + """Publishes up to BATCH pending events. Returns how many went out.""" + pending = (OutboxEvent.query.filter(OutboxEvent.published_at.is_(None)) + .order_by(OutboxEvent.created_at).limit(BATCH).all()) + sent = 0 + for event in pending: + try: + if client is None or not _bus["connected"]: + raise ConnectionError("event bus unreachable" if client else "no REDIS_URL configured") + fields = events.to_fields(event.id, event.type, event.payload, source, event.created_at.isoformat()) + client.xadd(events.STREAM, fields, maxlen=10_000, approximate=True) + event.published_at = datetime.now(timezone.utc) + event.last_error = None + sent += 1 + except Exception as exc: # the bus is down: stop this pass, keep the events for later + event.attempts += 1 + event.last_error = str(exc)[:200] + break + db.session.commit() + return sent + + +def start(app, source: str) -> None: + from shop_common.flask_support import is_serving_process + + if not events.redis_url() or not is_serving_process(app): + return # events wait in the table; unit tests, the reloader's watcher and no-Redis land here + + def loop() -> None: + client = None + while True: + time.sleep(1) + with app.app_context(): + try: + client = client or events.connect() + publish_pending(client, source) + except Exception: + client = None + finally: + db.session.remove() + + threading.Thread(target=loop, name="outbox-relay", daemon=True).start() diff --git a/services/order/application/saga.py b/services/order/application/saga.py new file mode 100644 index 0000000..0d62ca1 --- /dev/null +++ b/services/order/application/saga.py @@ -0,0 +1,131 @@ +"""The checkout saga (pattern 8), orchestrated by the order service. + + 1. price ask catalog for current prices + 2. reserve_stock inventory holds the units compensation: release_stock + 3. charge_payment payment charges the card (nothing to undo if it fails) + 4. confirm close the order and, in the SAME transaction, write OrderConfirmed to the + outbox. Inventory turns the hold into a sale when it reads that event (7). + +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. +The cart stays open after a failed saga, so the shopper can try again. + +Every step is written to saga_step, which is what the Saga page draws. +""" +import uuid + +import requests + +from . import db +from .models import Order, OutboxEvent, SagaStep +from .order_api.api import clients + + +class Saga: + def __init__(self, order: Order, user_id: int): + self.id = str(uuid.uuid4()) + self.order = order + self.user_id = user_id + + def log(self, step: str, status: str, detail: str | None = None) -> None: + db.session.add(SagaStep(saga_id=self.id, order_id=self.order.id, user_id=self.user_id, + step=step, status=status, detail=(detail or "")[:300])) + db.session.commit() + + def emit(self, event_type: str, payload: dict) -> None: + """Adds an event to the outbox. Committed by the caller, with the change it describes.""" + db.session.add(OutboxEvent(id=str(uuid.uuid4()), type=event_type, + payload={"saga_id": self.id, "order_id": self.order.id, **payload})) + + def fail(self, step: str, detail: str, http_status: int, message: str, **extra) -> tuple[int, dict]: + self.log(step, "failed", detail) + self.emit("CheckoutFailed", {"failed_step": step, "reason": detail}) + db.session.commit() + return http_status, {"message": message, "saga_id": self.id, "failed_step": step, **extra} + + +def run_checkout(order: Order, user_id: int, simulate: str = "approve") -> tuple[int, dict]: + saga = Saga(order, user_id) + items = [{"product_id": i.product_id, "quantity": i.quantity} for i in order.items] + + # 1. price + try: + prices = clients.product_prices() + except requests.RequestException as exc: + return saga.fail("price", f"catalog unreachable: {exc.__class__.__name__}", 503, + "The catalog is unavailable, so the order cannot be priced. Your cart is kept.") + missing = [i["product_id"] for i in items if i["product_id"] not in prices] + if missing: + return saga.fail("price", f"unknown products {missing}", 409, f"Product(s) {missing} are no longer sold") + amount = sum(prices[i["product_id"]] * i["quantity"] for i in items) + saga.log("price", "done", f"{len(items)} line(s), total {amount} cents") + + # 2. reserve stock + try: + clients.reserve_stock(saga.id, order.id, items) + except clients.OutOfStock as exc: + return saga.fail("reserve_stock", f"short: {exc.short}", 409, + "Not enough stock for your cart. Nothing was charged. Your cart is kept.", short=exc.short) + except requests.RequestException as exc: + return saga.fail("reserve_stock", f"inventory unreachable: {exc.__class__.__name__}", 503, + "Inventory is unavailable. Nothing was charged. Your cart is kept.") + saga.log("reserve_stock", "done", f"held {sum(i['quantity'] for i in items)} unit(s)") + + # 3. charge payment (behind the M2 circuit breaker) + failure = None + try: + payment = clients.charge(order.id, amount, simulate) + if payment["status"] != "APPROVED": + failure = ("declined", 402, "Your payment was declined. Nothing was charged; the stock was released. Your cart is kept.") + except clients.PaymentUnavailable as exc: + state = clients.breaker_state() + wait = f" Try again in {state['retry_in_seconds']:.0f} s." if state["retry_in_seconds"] else "" + failure = (f"payment unavailable ({exc.reason})", 503, + f"Payment is unavailable right now, so nothing was charged; the stock was released. Your cart is kept.{wait}") + except requests.RequestException as exc: + failure = (f"payment error: {exc.__class__.__name__}", 502, "Payment failed. The stock was released. Your cart is kept.") + + if failure: + reason, http_status, message = failure + saga.log("charge_payment", "failed", reason) + _compensate(saga) + saga.emit("CheckoutFailed", {"failed_step": "charge_payment", "reason": reason}) + db.session.commit() + body = {"message": message, "saga_id": saga.id, "failed_step": "charge_payment"} + if http_status == 503: + body["breaker"] = clients.breaker_state() + return http_status, body + saga.log("charge_payment", "done", f"payment {payment['id']} APPROVED, {amount} cents") + + # 4. confirm: the order change and its event commit together, or not at all + order.is_open = False + saga.emit("OrderConfirmed", {"reservation_id": saga.id, "amount_cents": amount, "items": items}) + db.session.add(SagaStep(saga_id=saga.id, order_id=order.id, user_id=user_id, step="confirm", + status="done", detail="order closed; OrderConfirmed in the outbox")) + db.session.commit() + return 200, {"result": order.to_json(), "payment": payment, "saga_id": saga.id} + + +def _compensate(saga: Saga) -> None: + try: + clients.release_stock(saga.id) + saga.log("release_stock", "compensated", "stock returned to inventory") + except requests.RequestException as exc: + # Could not undo directly: ask inventory through the bus. It is idempotent, so a release + # that did go through and this event together are harmless. + saga.emit("StockReleaseRequested", {"reservation_id": saga.id}) + saga.log("release_stock", "compensated", f"inventory unreachable ({exc.__class__.__name__}); release sent as an event") + + +def recent_sagas(user_id: int, limit: int = 5) -> list[dict]: + saga_ids = [row.saga_id for row in db.session.query(SagaStep.saga_id, db.func.max(SagaStep.id).label("last")) + .filter_by(user_id=user_id).group_by(SagaStep.saga_id).order_by(db.desc("last")).limit(limit)] + result = [] + 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" + 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/requirements.txt b/services/order/requirements.txt index 55ce5bc..f3b24dc 100644 --- a/services/order/requirements.txt +++ b/services/order/requirements.txt @@ -10,3 +10,4 @@ pydantic==2.10.3 opentelemetry-instrumentation-flask==0.50b0 pybreaker==1.4.1 tenacity==9.2.1 +redis==8.1.0 diff --git a/services/order/tests/test_checkout_and_breaker.py b/services/order/tests/test_checkout_and_breaker.py index e3ad073..17685ea 100644 --- a/services/order/tests/test_checkout_and_breaker.py +++ b/services/order/tests/test_checkout_and_breaker.py @@ -17,6 +17,9 @@ def _isolate(monkeypatch): monkeypatch.setattr(clients, "current_user_id", lambda header: 1 if header else None) monkeypatch.setitem(clients.STATIC_URLS, "payment", "http://127.0.0.1:9") # nothing listens on :9 monkeypatch.setattr(clients, "product_prices", lambda: {1: 1299, 2: 899}) + # Inventory is not running in unit tests: holds always succeed unless a test says otherwise. + monkeypatch.setattr(clients, "reserve_stock", lambda rid, order_id, items: {"status": "RESERVED"}) + monkeypatch.setattr(clients, "release_stock", lambda rid: {"status": "RELEASED"}) clients.BREAKER.close() yield clients.BREAKER.close() @@ -54,7 +57,7 @@ def test_checkout_keeps_the_cart_when_payment_is_down(client): def test_checkout_charges_the_catalog_price_and_closes_the_order(client, monkeypatch): charged = {} - def fake_charge(order_id, amount_cents): + def fake_charge(order_id, amount_cents, simulate="approve"): charged.update(order_id=order_id, amount_cents=amount_cents) return {"id": 1, "order_id": order_id, "amount_cents": amount_cents, "status": "APPROVED"} diff --git a/services/order/tests/test_contracts_consumer.py b/services/order/tests/test_contracts_consumer.py index e8a9c13..1159a16 100644 --- a/services/order/tests/test_contracts_consumer.py +++ b/services/order/tests/test_contracts_consumer.py @@ -37,6 +37,14 @@ def test_order_to_payment_contract(monkeypatch): "status": "APPROVED", }}, "application/json") ) + ( + 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") + .will_respond_with(200) + .with_body({"result": {"id": match.int(2), "status": "DECLINED"}}, "application/json") + ) ( pact.upon_receiving("a health check through the circuit breaker") .given("payment is healthy") @@ -49,6 +57,7 @@ def test_order_to_payment_contract(monkeypatch): payment = clients.charge(42, 2598) assert payment["status"] == "APPROVED" assert payment["amount_cents"] == 2598 + assert clients.charge(43, 899, "decline")["status"] == "DECLINED" assert clients.call_payment("GET", "/api/payment/ping").json() == {"status": "ok"} pact.write_file(PACT_DIR, overwrite=True) @@ -66,3 +75,43 @@ def test_order_to_catalog_contract(monkeypatch): monkeypatch.setitem(clients.STATIC_URLS, "catalog", str(server.url).rstrip("/")) assert clients.product_prices() == {1: 1299} pact.write_file(PACT_DIR, overwrite=True) + + +def test_order_to_inventory_contract(monkeypatch): + pact = Pact("order", "inventory").with_specification("V4") + rid = "3f0c1d2e-0000-4000-8000-000000000001" + ( + pact.upon_receiving("a stock hold for a checkout") + .given("product 1 has stock") + .with_request("POST", "/api/inventory/reservations") + # Exact request bodies (no matchers): the mock tells this request and the next one apart + # by their bodies, since both are POSTs to the same path. + .with_body({"reservation_id": rid, "order_id": 42, "items": [{"product_id": 1, "quantity": 2}]}, + "application/json") + .will_respond_with(200) + .with_body({"result": {"reservation_id": match.str(rid), "status": "RESERVED"}}, "application/json") + ) + ( + pact.upon_receiving("a stock hold that is more than inventory has") + .given("product 1 has stock") + .with_request("POST", "/api/inventory/reservations") + .with_body({"reservation_id": "3f0c1d2e-0000-4000-8000-000000000002", "order_id": 43, + "items": [{"product_id": 1, "quantity": 100000}]}, "application/json") + .will_respond_with(409) + .with_body({"short": match.each_like({"product_id": match.int(1), "available": match.int(25)}, min=1)}, + "application/json") + ) + ( + pact.upon_receiving("a release of a stock hold") + .given("a stock hold exists", reservation_id=rid) + .with_request("POST", f"/api/inventory/reservations/{rid}/release") + .will_respond_with(200) + .with_body({"result": {"reservation_id": rid, "status": "RELEASED"}}, "application/json") + ) + with pact.serve() as server: + monkeypatch.setitem(clients.STATIC_URLS, "inventory", str(server.url).rstrip("/")) + assert clients.reserve_stock(rid, 42, [{"product_id": 1, "quantity": 2}])["status"] == "RESERVED" + with pytest.raises(clients.OutOfStock): + clients.reserve_stock("3f0c1d2e-0000-4000-8000-000000000002", 43, [{"product_id": 1, "quantity": 100000}]) + assert clients.release_stock(rid)["status"] == "RELEASED" + 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 new file mode 100644 index 0000000..87c8c9c --- /dev/null +++ b/services/order/tests/test_saga_and_outbox.py @@ -0,0 +1,107 @@ +"""The checkout saga (pattern 8) and the outbox relay (pattern 7), with every other service stubbed.""" +import pytest +import requests + +from application import outbox +from application.models import OutboxEvent, SagaStep +from application.order_api.api import clients + +AUTH = {"Authorization": "Bearer test"} + + +@pytest.fixture +def calls(monkeypatch): + log = [] + 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: 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 { + "id": 9, "status": "DECLINED" if simulate == "decline" else "APPROVED"}) + clients.BREAKER.close() + return log + + +def _checkout(client, **body): + client.post("/api/order/add-item", data={"product_id": 1, "qty": 2}, headers=AUTH) + return client.post("/api/order/checkout", json=body, headers=AUTH) + + +def _steps(): + return [(s.step, s.status) for s in SagaStep.query.order_by(SagaStep.id)] + + +def _events(): + return [e.type for e in OutboxEvent.query.order_by(OutboxEvent.created_at)] + + +def test_happy_path_confirms_and_queues_order_confirmed(client, calls): + r = _checkout(client) + assert r.status_code == 200 + assert _steps() == [("price", "done"), ("reserve_stock", "done"), ("charge_payment", "done"), ("confirm", "done")] + assert _events() == ["OrderConfirmed"] + event = OutboxEvent.query.one() + assert event.payload["reservation_id"] == r.get_json()["saga_id"] # inventory sells exactly this hold + assert event.published_at is None # nothing published inside the request + + +def test_declined_payment_releases_the_stock_and_keeps_the_cart(client, calls): + r = _checkout(client, simulate_decline=True) + assert r.status_code == 402 + assert [c[0] for c in calls] == ["reserve", "charge", "release"] + assert _steps()[-2:] == [("charge_payment", "failed"), ("release_stock", "compensated")] + assert _events() == ["CheckoutFailed"] + assert client.get("/api/order", headers=AUTH).get_json()["result"]["is_open"] is True + + +def test_out_of_stock_stops_before_payment(client, calls, monkeypatch): + def short(rid, oid, items): + raise clients.OutOfStock([{"product_id": 1, "wanted": 2, "available": 0}]) + + monkeypatch.setattr(clients, "reserve_stock", short) + r = _checkout(client) + assert r.status_code == 409 + assert not any(c[0] == "charge" for c in calls) + + +def test_release_falls_back_to_an_event_when_inventory_is_down(client, calls, monkeypatch): + def down(rid): + raise requests.ConnectionError("inventory down") + + monkeypatch.setattr(clients, "release_stock", down) + _checkout(client, simulate_decline=True) + assert _events() == ["StockReleaseRequested", "CheckoutFailed"] + + +def test_saga_history_is_per_user(client, calls): + _checkout(client, simulate_decline=True) + sagas = client.get("/api/order/sagas", headers=AUTH).get_json()["results"] + assert sagas[0]["outcome"] == "compensated" + + +class FakeBus: + def __init__(self): + self.sent = [] + + def xadd(self, stream, fields, **kwargs): + self.sent.append(fields["type"]) + + +def test_relay_publishes_pending_events_once(client, calls): + _checkout(client) + bus = FakeBus() + assert outbox.publish_pending(bus, "order-test") == 1 + assert outbox.publish_pending(bus, "order-test") == 0 + assert bus.sent == ["OrderConfirmed"] + + +def test_events_wait_while_the_bus_is_down(client, calls): + _checkout(client) + outbox.set_connected(False) + try: + assert outbox.publish_pending(FakeBus(), "order-test") == 0 + assert client.get("/api/order/outbox").get_json()["pending"] == 1 + assert OutboxEvent.query.one().attempts == 1 + finally: + outbox.set_connected(True) + assert outbox.publish_pending(FakeBus(), "order-test") == 1 diff --git a/services/order/tests/test_startup.py b/services/order/tests/test_startup.py new file mode 100644 index 0000000..71519f8 --- /dev/null +++ b/services/order/tests/test_startup.py @@ -0,0 +1,64 @@ +"""Two order replicas start at the same moment and share one database (pattern 10).""" +import pytest +from sqlalchemy.exc import OperationalError + + +def test_replica_survives_another_replica_creating_the_tables_first(app, monkeypatch): + from application import db + from shop_common.db_setup import create_tables + + real_create_all = db.create_all + calls = [] + + def racing_create_all(): + calls.append(1) + if len(calls) == 1: # the other replica won the race between "check" and "create" + raise OperationalError("CREATE TABLE saga_step", {}, Exception("table saga_step already exists")) + real_create_all() + + monkeypatch.setattr(db, "create_all", racing_create_all) + create_tables(db) + assert len(calls) == 2 + + +def test_other_database_errors_still_stop_startup(app, monkeypatch): + from application import db + from shop_common.db_setup import create_tables + + def broken(): + raise OperationalError("CREATE TABLE x", {}, Exception("disk I/O error")) + + monkeypatch.setattr(db, "create_all", broken) + with pytest.raises(OperationalError): + create_tables(db) + + +def _relay_threads(): + import threading + + return [t for t in threading.enumerate() if t.name == "outbox-relay"] + + +def test_reloader_watcher_process_does_not_publish_events(app, monkeypatch): + """With app.run(debug=True), Flask runs a watcher process plus a worker process, and both build + the app. Only the worker serves requests, so only it may publish, or the bus switch (which + reaches the worker) would not stop publishing.""" + from application import outbox + + monkeypatch.setenv("REDIS_URL", "redis://127.0.0.1:1/0") + monkeypatch.delenv("WERKZEUG_RUN_MAIN", raising=False) + app.debug = True + before = len(_relay_threads()) + outbox.start(app, "order-test") + assert len(_relay_threads()) == before + + +def test_worker_process_publishes_events(app, monkeypatch): + from application import outbox + + monkeypatch.setenv("REDIS_URL", "redis://127.0.0.1:1/0") + monkeypatch.setenv("WERKZEUG_RUN_MAIN", "true") + app.debug = True + before = len(_relay_threads()) + outbox.start(app, "order-test") + assert len(_relay_threads()) == before + 1 diff --git a/services/payment/.dockerignore b/services/payment/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/services/payment/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/services/payment/Dockerfile b/services/payment/Dockerfile index a4aec98..e4fadce 100644 --- a/services/payment/Dockerfile +++ b/services/payment/Dockerfile @@ -1,19 +1,34 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: one image per service, built only in the cloud (az acr build) or in GitHub Actions, +# always for linux/amd64 (Azure Container Apps). Never built on the owner's arm64 Mac. +# +# Stage 1 installs dependencies into a virtualenv. Stage 2 copies only that virtualenv and the +# source into a clean image and runs as an unprivileged user, so no compiler cache, pip cache or +# root process ends up in production. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" -ENV RUN_MODE=azure \ +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ FLASK_ENV=production \ - PYTHONUNBUFFERED=1 - + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared && mkdir -p instance && chown 10001:10001 instance +USER 10001 EXPOSE 5104 # One process with threads, so the in-memory span store (pattern 6) sees every request. diff --git a/services/payment/application/routes.py b/services/payment/application/routes.py index ce6b9b0..8245e57 100644 --- a/services/payment/application/routes.py +++ b/services/payment/application/routes.py @@ -1,4 +1,5 @@ import time +from typing import Literal from flask import Blueprint, jsonify, make_response, request from pydantic import BaseModel, Field, ValidationError @@ -19,6 +20,9 @@ class ChargeRequest(BaseModel): order_id: int = Field(gt=0) amount_cents: int = Field(gt=0) + # 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" @payment_api.before_request @@ -49,7 +53,8 @@ def charge(): data = ChargeRequest.model_validate(raw) except ValidationError as exc: return make_response(jsonify({"message": "Invalid request", "errors": exc.errors(include_url=False)}), 400) - payment = Payment(order_id=data.order_id, amount_cents=data.amount_cents, status="APPROVED") + 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 jsonify({"result": payment.to_json()}) diff --git a/services/payment/tests/test_payment.py b/services/payment/tests/test_payment.py index 225526b..e38febd 100644 --- a/services/payment/tests/test_payment.py +++ b/services/payment/tests/test_payment.py @@ -32,3 +32,9 @@ def test_failing_mode_returns_500_until_healed(client, monkeypatch): def test_chaos_switch_is_off_unless_enabled(client, monkeypatch): monkeypatch.delenv("CHAOS_ENABLED", raising=False) assert client.post("/api/payment/chaos", json={"mode": "failing"}).status_code == 403 + + +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"}) + assert r.status_code == 200 + assert r.get_json()["result"]["status"] == "DECLINED" diff --git a/services/user/.dockerignore b/services/user/.dockerignore new file mode 100644 index 0000000..39daf35 --- /dev/null +++ b/services/user/.dockerignore @@ -0,0 +1,10 @@ +# Keeps the build context (what az acr build uploads) to source only. Pattern 9. +.venv/ +instance/ +tests/ +__pycache__/ +*.pyc +*.sqlite3 +*.pem +.env +.pytest_cache/ diff --git a/services/user/Dockerfile b/services/user/Dockerfile index a5ea4ec..1848427 100644 --- a/services/user/Dockerfile +++ b/services/user/Dockerfile @@ -1,19 +1,34 @@ -# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. -FROM python:3.12-slim - -WORKDIR /app +# Pattern 9: one image per service, built only in the cloud (az acr build) or in GitHub Actions, +# always for linux/amd64 (Azure Container Apps). Never built on the owner's arm64 Mac. +# +# Stage 1 installs dependencies into a virtualenv. Stage 2 copies only that virtualenv and the +# source into a clean image and runs as an unprivileged user, so no compiler cache, pip cache or +# root process ends up in production. +FROM python:3.12-slim AS build +WORKDIR /build +RUN python -m venv /opt/venv +ENV PATH=/opt/venv/bin:$PATH COPY requirements.txt . -RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt - -COPY . . -# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. -RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" +RUN pip install --no-cache-dir -r requirements.txt +# shared/ (shop_common) is staged into ./_shared before the build (infra/provision.py, CI). +COPY _shared ./_shared +RUN pip install --no-cache-dir "./_shared[flask]" -ENV RUN_MODE=azure \ +FROM python:3.12-slim +ARG GIT_SHA=unknown +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + RUN_MODE=azure \ FLASK_ENV=production \ - PYTHONUNBUFFERED=1 - + GIT_SHA=$GIT_SHA +RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app +WORKDIR /app +COPY --from=build /opt/venv /opt/venv +COPY --chown=10001:10001 . . +RUN rm -rf _shared && mkdir -p instance && chown 10001:10001 instance +USER 10001 EXPOSE 5101 # One process with threads, so the in-memory span store (pattern 6) sees every request. diff --git a/shared/shop_common/db_setup.py b/shared/shop_common/db_setup.py new file mode 100644 index 0000000..9c8cdcb --- /dev/null +++ b/shared/shop_common/db_setup.py @@ -0,0 +1,18 @@ +"""Creating a service's tables at startup, safely when several replicas start at once.""" +from sqlalchemy.exc import OperationalError + + +def create_tables(db) -> None: + """db.create_all(), tolerating another replica creating the same table at the same moment. + + create_all() checks which tables exist, then creates the missing ones. Two replicas sharing a + database can both pass the check, and the slower one then fails with "already exists". On that + error only, run it once more: the check now sees the table and skips it. + """ + try: + db.create_all() + except OperationalError as exc: + if "already exists" not in str(exc): + raise + db.session.rollback() + db.create_all() diff --git a/shared/shop_common/events.py b/shared/shop_common/events.py new file mode 100644 index 0000000..5277b90 --- /dev/null +++ b/shared/shop_common/events.py @@ -0,0 +1,88 @@ +"""The event bus (pattern 7): one Redis Stream, `shop.events`, shared by every service. + +- Publishers never write to Redis inside a request. They save the event in their own database's + outbox table in the same transaction as the business change, and a relay publishes it later + (see services/order/application/outbox.py). So an event is never lost and never sent for a change + that was rolled back. +- Consumers read with a consumer group, so each event is handled once per group, and acknowledge + only after handling it. Unacknowledged events are redelivered after a restart. +- Delivery is at least once. Every handler must be idempotent: handling the same event twice must + change nothing the second time. + +Needs the `redis` package (order and inventory list it). Without REDIS_URL nothing is published or +read, and outbox events simply wait. +""" +import json +import os +import threading +import time +from typing import Callable + +STREAM = "shop.events" + + +def redis_url() -> str | None: + return os.environ.get("REDIS_URL") or None + + +def connect(): + """A Redis client with short timeouts, or None when no bus is configured.""" + url = redis_url() + if not url: + return None + import redis + + return redis.Redis.from_url(url, socket_timeout=3, socket_connect_timeout=2, decode_responses=True) + + +def to_fields(event_id: str, event_type: str, payload: dict, source: str, occurred_at: str) -> dict: + return {"event_id": event_id, "type": event_type, "payload": json.dumps(payload), "source": source, + "occurred_at": occurred_at} + + +def from_fields(fields: dict) -> dict: + return {**fields, "payload": json.loads(fields.get("payload") or "{}")} + + +def start_consumer(group: str, consumer: str, handle: Callable[[dict], None], log=None) -> threading.Thread | None: + """Reads the stream as `consumer` in `group` on a background thread and acks each handled event. + + handle() gets the decoded event. If it raises, the event is not acked and is retried on the + next pass. Returns None when no bus is configured. + """ + if not redis_url(): + return None + + def loop() -> None: + import redis + + client, start_id = None, "0" # "0" first: our own unacked events from before a restart + while True: + try: + if client is None: + client = connect() + try: + client.xgroup_create(STREAM, group, id="0", mkstream=True) + except redis.ResponseError as exc: + if "BUSYGROUP" not in str(exc): + raise + batches = client.xreadgroup(group, consumer, {STREAM: start_id}, count=20, block=2000) + messages = batches[0][1] if batches else [] + if start_id == "0" and not messages: + start_id = ">" # backlog done, now only new events + for message_id, fields in messages: + try: + handle(from_fields(fields)) + client.xack(STREAM, group, message_id) + except Exception as exc: # leave it unacked; it is retried from "0" next pass + if log: + log.warning(f"event {message_id} failed: {exc}") + start_id = "0" + time.sleep(1) # do not spin on an event that keeps failing + except (redis.ConnectionError, redis.TimeoutError, OSError): + client = None + time.sleep(2) + + thread = threading.Thread(target=loop, name=f"consumer-{group}", daemon=True) + thread.start() + return thread diff --git a/shared/shop_common/flask_support.py b/shared/shop_common/flask_support.py index 06f07b6..d37c33e 100644 --- a/shared/shop_common/flask_support.py +++ b/shared/shop_common/flask_support.py @@ -5,6 +5,7 @@ GET /health/db which database this service owns (pattern 1); credentials never shown GET /debug/spans this process's recent spans, optionally filtered by ?trace_id= (pattern 6) GET /metrics Prometheus text format (pattern 6) + GET /debug/runtime what this process runs as: uid, container or not, image git SHA (pattern 9) POST /debug/crash stops this process, for the replica and discovery demos (CHAOS_ENABLED=1 only) Every response carries X-Instance-Id, so a demo can show which replica answered (pattern 10). @@ -19,6 +20,7 @@ from . import metrics from .discovery import DISCOVERY +from .runtime import runtime_info from .telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing @@ -30,6 +32,16 @@ def instance_id(service_name: str) -> str: return os.environ.get("INSTANCE_ID") or os.environ.get("CONTAINER_APP_REPLICA_NAME") or f"{service_name}-{os.getpid()}" +def is_serving_process(app: Flask) -> bool: + """False in the file-watcher process of app.run(debug=True). + + The reloader runs a watcher plus a worker (marked WERKZEUG_RUN_MAIN=true), and both build the + app. Only the worker serves requests, so only it may run background threads (registry + heartbeats, outbox relay, event consumer). Under gunicorn there is no reloader. + """ + return not app.debug or os.environ.get("WERKZEUG_RUN_MAIN") == "true" + + def chaos_enabled() -> bool: return os.environ.get("CHAOS_ENABLED") == "1" @@ -55,7 +67,7 @@ def _start_timer(): def _record(response): response.headers[INSTANCE_HEADER] = this_instance route = request.url_rule.rule if request.url_rule else "unmatched" - if route in ("/health", "/debug/spans", "/metrics"): + if route in ("/health", "/debug/spans", "/metrics", "/debug/runtime"): return response elapsed = time.perf_counter() - g.get("request_started", time.perf_counter()) metrics.observe(service_name, request.method, route, response.status_code, elapsed) @@ -97,6 +109,10 @@ def prometheus_metrics(): body, content_type = metrics.render() return Response(body, content_type=content_type) + @app.get("/debug/runtime") + def debug_runtime(): + return jsonify(runtime_info(service_name, this_instance)) + @app.post("/debug/crash") def debug_crash(): if not chaos_enabled(): @@ -107,5 +123,5 @@ def debug_crash(): return jsonify({"stopping": this_instance}) public_url = os.environ.get("SERVICE_PUBLIC_URL") - if public_url: + if public_url and is_serving_process(app): DISCOVERY.register(service_name, this_instance, public_url) diff --git a/shared/shop_common/runtime.py b/shared/shop_common/runtime.py new file mode 100644 index 0000000..b5e5e40 --- /dev/null +++ b/shared/shop_common/runtime.py @@ -0,0 +1,21 @@ +"""Facts about the running process (pattern 9). No Flask or FastAPI import, so both can use it.""" +import os + + +def runtime_info(service_name: str, instance: str) -> dict: + """Facts about the running process, for the Containerization page. Never the user name.""" + import platform + from pathlib import Path + + uid = os.getuid() if hasattr(os, "getuid") else None + return { + "service": service_name, + "instance": instance, + "uid": uid, + "root": uid == 0, + "in_container": Path("/.dockerenv").exists() or bool(os.environ.get("CONTAINER_APP_NAME")), + "os": platform.system(), + "arch": platform.machine(), + "python": platform.python_version(), + "git_sha": os.environ.get("GIT_SHA", "local"), + } diff --git a/tests/smoke/test_post_run.py b/tests/smoke/test_post_run.py index da61a37..65800a7 100644 --- a/tests/smoke/test_post_run.py +++ b/tests/smoke/test_post_run.py @@ -35,13 +35,17 @@ def _checkout_flow(user_url: str, catalog_url: str, order_url: str) -> None: product_id = r.json()["product"]["id"] headers = {"Authorization": f"Bearer {login_token}"} - r = httpx.post(f"{order_url}/order/add-item", data={"product_id": product_id, "qty": 2}, headers=headers) + # Buy a seeded product: a product created a moment ago has no stock record in inventory, so the + # saga's reserve step would (correctly) refuse it. + assert product_id > 0 + httpx.post(f"{order_url}/inventory/1/restock", json={"quantity": 10}) + r = httpx.post(f"{order_url}/order/add-item", data={"product_id": 1, "qty": 2}, headers=headers) assert r.status_code == 200, r.text # order verifies the token itself, no call to user r = httpx.post(f"{order_url}/order/checkout", headers=headers) assert r.status_code == 200, r.text assert r.json()["result"]["is_open"] is False - assert r.json()["payment"]["amount_cents"] == 3000 # priced by catalog, charged by payment + assert r.json()["payment"]["amount_cents"] == 2 * 1299 # priced by catalog, charged by payment def test_services_full_flow_direct(): @@ -73,7 +77,7 @@ def test_each_service_owns_only_its_tables(): services = {s["service"]: s for s in httpx.get(f"{GATEWAY_URL}/api/patterns/databases").json()["services"]} assert set(services) == set(URLS) assert services["catalog"]["tables"] == ["product"] - assert services["inventory"]["tables"] == ["stock_item"] + assert services["inventory"]["tables"] == ["consumed_event", "reservation", "stock_item"] assert "product" not in services["order"]["tables"] @@ -101,6 +105,8 @@ def test_one_request_is_traced_across_services(): # --- M2 pattern demos (patterns 10, 12, 4), through the gateway ---------------------------------- def _login_with_cart() -> dict: + # Top up stock first, so repeated smoke runs never run product 1 out of stock. + httpx.post(f"{GATEWAY_URL}/api/shop/inventory/1/restock", json={"quantity": 10}) tag = uuid.uuid4().hex[:8] shop = f"{GATEWAY_URL}/api/shop" httpx.post(f"{shop}/user/create", data={"username": f"m2{tag}", "email": f"m2{tag}@example.com", "password": "secret123"}) @@ -158,3 +164,68 @@ def test_breaker_opens_when_payment_fails_and_closes_after_it_heals(): outcomes = {httpx.get(f"{api}/call").json()["outcome"] for _ in range(2)} assert outcomes == {"ok"} assert {b["state"] for b in httpx.get(f"{api}/state").json()["breakers"]} == {"closed"} + + +# --- M3a pattern demos (patterns 8, 7, 9), through the gateway ---------------------------------- + +def _stock(product_id: int) -> dict: + return next(s for s in httpx.get(f"{GATEWAY_URL}/api/shop/inventory").json()["results"] if s["product_id"] == product_id) + + +def _wait_for(condition, seconds: float = 8.0) -> bool: + import time + + deadline = time.monotonic() + seconds + while time.monotonic() < deadline: + if condition(): + return True + time.sleep(0.5) + return False + + +def test_saga_sale_holds_then_sells_through_the_event_bus(): + _require_stack() + headers = _login_with_cart() # 3 units of product 1 + before = _stock(1) + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15) + assert r.status_code == 200, r.text + steps = httpx.get(f"{GATEWAY_URL}/api/shop/order/sagas", headers=headers).json()["results"][0]["steps"] + assert [s["step"] for s in steps] == ["price", "reserve_stock", "charge_payment", "confirm"] + # Inventory sells the hold when it reads OrderConfirmed from Redis, a moment later. + assert _wait_for(lambda: _stock(1)["on_hand"] == before["on_hand"] - 3), _stock(1) + assert _stock(1)["reserved"] == before["reserved"] + + +def test_declined_payment_is_compensated_and_stock_is_unchanged(): + _require_stack() + headers = _login_with_cart() + before = _stock(1) + r = httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", json={"simulate_decline": True}, headers=headers, timeout=15) + assert r.status_code == 402, r.text + saga = httpx.get(f"{GATEWAY_URL}/api/shop/order/sagas", headers=headers).json()["results"][0] + assert saga["outcome"] == "compensated" + assert _stock(1) == before + assert httpx.get(f"{GATEWAY_URL}/api/shop/order", headers=headers).json()["result"]["is_open"] is True + + +def test_events_wait_in_the_outbox_while_the_bus_is_down_then_drain(): + _require_stack() + api = f"{GATEWAY_URL}/api/patterns/events" + assert httpx.post(f"{api}/bus", json={"connected": False}).json()["replicas_switched"] == 2 + try: + headers = _login_with_cart() + before = _stock(1) + assert httpx.post(f"{GATEWAY_URL}/api/shop/order/checkout", headers=headers, timeout=15).status_code == 200 + assert _wait_for(lambda: httpx.get(api).json()["outbox"]["pending"] >= 1) + assert _stock(1)["reserved"] == before["reserved"] + 3 # held, not yet sold + finally: + httpx.post(f"{api}/bus", json={"connected": True}) + assert _wait_for(lambda: httpx.get(api).json()["outbox"]["pending"] == 0) + assert _wait_for(lambda: _stock(1)["on_hand"] == before["on_hand"] - 3) + + +def test_every_process_reports_how_it_runs(): + _require_stack() + processes = httpx.get(f"{GATEWAY_URL}/api/patterns/runtime").json()["processes"] + assert len(processes) == 7 # gateway + 5 services, order twice + assert all("uid" in p for p in processes) From 3db1ae3b7a7391316fe7ee7fb156f2cced667f06 Mon Sep 17 00:00:00 2001 From: Marcos Oliveira Date: Sun, 15 Nov 2026 16:27:09 -0500 Subject: [PATCH 2/2] fix: M3a code-review findings, test-first; docs for patterns 7, 8, 9 Two-axis review (Matt Pocock code-review: standards + spec). Each fix below has a failing test first, except the two concurrency fixes (noted). - Event reader: one failing event no longer blocks the ones behind it; it is retried between new reads and moved to shop.events.dead after 5 tries (Reader.read_once, tested with a fake Redis). - Checkout: one saga per order at a time (checkout_lock, expires after 60 s), so a double click cannot hold stock or charge twice. - Every saga step publishes an event: StockReserved, PaymentCharged, OrderConfirmed, CheckoutFailed. - A timed-out stock hold is released through the bus (StockReleaseRequested). - A payment timeout no longer tells the shopper "nothing was charged". - The decline switch needs CHAOS_ENABLED=1; restock input is validated (400, 404). - Concurrency, no unit test (needs 2 real DB sessions): stock rows locked in product id order; a duplicate hold insert returns the existing hold. - Tidy-ups: seed_missing_stock rename, shared failure path in Saga.fail, imports, one fewer call. - README, CLAUDE.md, .env.example and PLAN.md updated; build preference recorded in CLAUDE.md. Co-Authored-By: Claude Opus 5.5 --- .env.example | 6 +- CLAUDE.md | 34 +++-- README.md | 52 +++++-- docs/PLAN.md | 12 ++ docs/screenshots/p07-event-driven.jpg | Bin 65319 -> 64603 bytes gateway/app/routers/resilience.py | 16 ++- registry/Dockerfile | 1 - scripts/run_local.py | 3 +- services/inventory/application/__init__.py | 4 +- services/inventory/application/consumer.py | 2 + services/inventory/application/routes.py | 15 +- services/inventory/application/seed.py | 2 +- services/inventory/application/stock.py | 19 ++- .../inventory/tests/test_contract_provider.py | 4 +- services/inventory/tests/test_event_reader.py | 67 +++++++++ services/inventory/tests/test_inventory.py | 8 +- .../inventory/tests/test_saga_and_events.py | 11 +- services/order/application/models.py | 11 ++ .../order/application/order_api/routes.py | 2 + services/order/application/saga.py | 135 ++++++++++++------ .../order/tests/test_checkout_and_breaker.py | 16 +++ services/order/tests/test_saga_and_outbox.py | 74 ++++++++-- shared/shop_common/events.py | 62 +++++--- 23 files changed, 435 insertions(+), 121 deletions(-) create mode 100644 services/inventory/tests/test_event_reader.py diff --git a/.env.example b/.env.example index 955379a..fe88adc 100644 --- a/.env.example +++ b/.env.example @@ -31,7 +31,11 @@ INVENTORY_SERVICE_BASE_URL=http://127.0.0.1:5105 # make run sets this; with it unset, callers use the fixed URLs above (as in unit tests and Azure). # REGISTRY_URL=http://127.0.0.1:8500 -# --- Demo switches (patterns 4, 10, 12) --- +# --- Event bus (patterns 7 and 8) --- +# make run starts redis-server on 6390 and sets this. Unset: events wait in the order outbox. +# REDIS_URL=redis://127.0.0.1:6390/0 + +# --- Demo switches (patterns 4, 7, 10, 12) --- # make run sets CHAOS_ENABLED=1 so the pages can stop a replica and break payment. Keep it off anywhere public. # CHAOS_ENABLED=1 diff --git a/CLAUDE.md b/CLAUDE.md index 5f26c25..9d7d8f9 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 (M2: patterns 1, 2, 4, 5, 6, 10, 11, 12 live) +## Current state (M3a: every pattern except 3 is live) - Folders: `services/{user,catalog,order,payment,inventory}/` (Flask, one DB each), `gateway/` (FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`, `scripts/`, `tests/`. @@ -35,7 +35,19 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA `REPLICA_PORTS` (order also on 5113) and `CONTRACT_SUITES`. `setup.py`, `run_local.py`, `provision.py` and the smoke tests all read it. Add a service there. - Ports: user 5101, catalog 5102, order 5103 + 5113, payment 5104, inventory 5105, gateway 8100, - registry 8500, frontend 5273. + registry 8500, Redis 6390, frontend 5273. +- Saga (pattern 8): `services/order/application/saga.py`, orchestrated: price, reserve_stock, + 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). +- 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` + (chaos) disconnects a replica's relay. Without `REDIS_URL` events just wait in the outbox. +- Background threads (heartbeat, relay, consumer) start only where `is_serving_process(app)` is true: + Flask's debug reloader runs a watcher plus a worker, and both build the app. +- Containers (pattern 9): multi-stage Dockerfiles, uid 10001, `.dockerignore` per service, `GIT_SHA` + build arg, `/debug/runtime`. CI job "Container image" builds, runs and checks all 7 images. - **`shop_common`** (`shared/`): every service calls `shop_common.flask_support.install(app, name, db)` inside its app context. It adds `/health`, `/health/db`, `/debug/spans`, `/metrics`, `POST /debug/crash` (only with `CHAOS_ENABLED=1`), the `X-Instance-Id` header, tracing, JSON logs, @@ -52,17 +64,23 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA - Circuit breaker (pattern 4): `services/order/application/order_api/api/clients.py`, pybreaker (3 failures, 15 s) + tenacity (1 retry, 1 s timeout), only 5xx/timeouts count. Checkout prices from catalog, charges payment, keeps the cart on 503. Payment has a `healthy|failing|slow` switch. -- Contracts (pattern 11): order's tests write `contracts/pacts/order-{payment,catalog}.json`; payment - and catalog verify them. CI fails if the regenerated files differ. Pact (pact-python 4.2) is +- Contracts (pattern 11): order's tests write `contracts/pacts/order-{payment,catalog,inventory}.json`; + those 3 services verify them. CI fails if the regenerated files differ. Pact (pact-python 4.2) is test-only, installed from `contracts/requirements.txt`, never in images. -- `make run` sets `REGISTRY_URL`, `CHAOS_ENABLED=1`, `INSTANCE_ID`, and restarts a stopped service - after 20 s. Registry TTL 10 s, heartbeat 2 s. Azure uses Container Apps DNS (no registry yet). +- `make run` sets `REGISTRY_URL`, `REDIS_URL`, `CHAOS_ENABLED=1`, `INSTANCE_ID`, and restarts a stopped + service after 20 s. Inventory seeds stock for all 24 catalog products; `POST /api/inventory//restock` + (chaos only) keeps smoke runs from running out. Registry TTL 10 s, heartbeat 2 s. Azure uses Container Apps DNS (no registry yet). - Gotchas solved: FastAPI tracing middleware must be added AFTER the request-ID middleware; Flask- - SQLAlchemy's engine is instrumented per engine; Pact's `Verifier` needs `host="127.0.0.1"`; DB writes - inside a Pact state handler deadlock on SQLite (seed before verifying instead). + SQLAlchemy's engine is instrumented per engine; Pact's `Verifier` needs `host="127.0.0.1"`; Pact state + handlers run on another thread, so end the test's DB transaction first or SQLite deadlocks; two + replicas racing `create_all()` (use `shop_common.db_setup.create_tables`). - Smoke tests create users and products in the local SQLite DBs; delete `services/*/instance/` for a clean catalog (this also deletes the local signing key, which logs everyone out). +## How to build (owner's preference) +Follow the Matt Pocock `implement` skill (read it from the mattpocock-skills plugin folder): TDD at +agreed seams, red test first; then `mattpocock-skills:code-review`; then commit. + ## Stack Python 3.12 (Flask 3.1 services, FastAPI gateway), Node 18+ (React 18, TypeScript 5, Vite 5), SQLite locally, Azure MySQL Flexible Server (one server, one DB per service) in Azure. diff --git a/README.md b/README.md index 62dd4cc..4fce399 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ A small Contoso e-commerce system that shows **12 microservices patterns working Each pattern gets its own page with an explanation, when *not* to use it, and a live demo you can click. -> **Status: M2, resilience and independence.** 8 of 12 patterns are live: M1's Database per -> Service, Bounded Context, API Gateway and Observability, plus M2's Circuit Breaker, Stateless -> Services, Contract Testing and Service Discovery. The foundation is copied from +> **Status: M3a, async and packaging.** 11 of 12 patterns are live. M3a adds the Saga, +> Event-Driven Architecture and Containerization to M1 (patterns 1, 2, 5, 6) and M2 (4, 10, 11, 12). +> The foundation is copied from > [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration). -> The last 4 arrive in milestone M3. See [docs/PLAN.md](docs/PLAN.md). +> CI-CD and the Azure run arrive in M3b. See [docs/PLAN.md](docs/PLAN.md). ## The 12 patterns @@ -16,13 +16,13 @@ can click. |---|---|---|---| | 1 | Database per Service | Gives each service its own database | **Live (M1)** | | 2 | Bounded Context | Splits one large domain into clear business domains | **Live (M1)** | -| 3 | CI-CD Pipeline | Builds, tests and deploys every service automatically | M3 | +| 3 | CI-CD Pipeline | Builds, tests and deploys every service automatically | M3b | | 4 | Circuit Breaker | Stops calls to a failing service to prevent more failures | **Live (M2)** | | 5 | API Gateway | Routes client requests to the right service | **Live (M1)** | | 6 | Observability | Collects logs, metrics and traces from every service | **Live (M1)** | -| 7 | Event-Driven Architecture | Services communicate by publishing and consuming events | M3 | -| 8 | Saga Pattern | Coordinates distributed transactions and rolls back failures safely | M3 | -| 9 | Containerization | Packages each service with all its dependencies | M3 | +| 7 | Event-Driven Architecture | Services communicate by publishing and consuming events | **Live (M3a)** | +| 8 | Saga Pattern | Coordinates distributed transactions and rolls back failures safely | **Live (M3a)** | +| 9 | Containerization | Packages each service with all its dependencies | **Live (M3a)** | | 10 | Stateless Services | Stores session data outside the service | **Live (M2)** | | 11 | Contract Testing | Checks that APIs stay compatible across services | **Live (M2)** | | 12 | Service Discovery | Finds service instances automatically at runtime | **Live (M2)** | @@ -32,11 +32,12 @@ can click. ``` Browser → API gateway ──┬──► user → user_db (signs login tokens) (checks tokens, ├──► catalog → catalog_db - request IDs, ├──► order ×2 → order_db ──► catalog (prices) - tracing, metrics, │ └─► payment, behind a circuit breaker + request IDs, ├──► order ×2 → order_db checkout saga: price → hold stock → + tracing, metrics, │ charge (circuit breaker) → confirm aggregation, ├──► payment → payment_db failover) └──► inventory → inventory_db +order_db outbox ──relay──► Redis Stream "shop.events" ──► inventory (sells the held stock) Every service heartbeats into the registry (:8500); callers look each other up there. ``` @@ -47,11 +48,13 @@ Every service heartbeats into the registry (:8500); callers look each other up t - **`shop_common`** (`shared/`): OpenTelemetry tracing, JSON logs with trace IDs, Prometheus metrics, the `/health/db`, `/debug/spans`, `/metrics` endpoints, token checks and the discovery client. - **Service registry** (`registry/`): about 90 lines of FastAPI. Local only; Azure uses Container Apps DNS. -- **Contracts** (`contracts/pacts/`): the Pact files the order service needs payment and catalog to honour. +- **Contracts** (`contracts/pacts/`): the Pact files the order service needs payment, catalog and inventory to honour. +- **Redis** (Homebrew `redis-server`, in memory, port 6390): the event bus. `make run` starts and stops it. +- **Dockerfiles**: one per service plus gateway and registry, multi-stage, non-root, built only in + the cloud or CI for `linux/amd64`. - **React + TypeScript** frontend (`frontend/`) with a page per pattern. -Still to come (M3): Redis Streams events with an outbox, checkout saga, hardened containers, -deploy pipeline, and a real Azure run. +Still to come (M3b): path-filtered CI with a manual Deploy workflow (OIDC), and a real Azure run. ## The live demos @@ -105,11 +108,30 @@ 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 +### 7. Event-Driven Architecture +Disconnect the bus and buy a mug: OrderConfirmed waits in the order service's outbox, and the mug +stays held in inventory. Reconnect: the event goes out and inventory turns the hold into a sale. + +Event-Driven demo: bus disconnected, one OrderConfirmed waiting in the outbox, one mug held + +### 8. Saga +Buy 2 mugs with "make the bank decline the card" ticked. The saga prices the cart, holds the stock, +the charge fails, and it releases the stock. Stock ends exactly where it started; the cart is kept. + +Saga demo: a declined card, with the stock hold released by the compensation step + +### 9. Containerization +How each process runs (uid, container or not, platform, build). Locally they are plain processes; +CI builds and runs every image for linux/amd64 and fails any that runs as root. + +Containerization demo: every process, its uid and platform, and the Dockerfile shape + ## Run locally (no Docker) ```bash +brew install redis # once: the event bus (patterns 7 and 8) make setup # one venv per service + gateway, shop_common, frontend packages -make run # frontend http://127.0.0.1:5273, gateway http://127.0.0.1:8100, registry :8500 +make run # frontend :5273, gateway :8100, registry :8500, Redis :6390 make test # unit tests, each suite in its own venv make contracts # Pact: order writes its contracts, payment and catalog verify them make smoke # end-to-end checks against the running stack @@ -122,5 +144,5 @@ collector. Without it, traces stay in each process's memory and the Observabilit Azure Container Apps (one app per service plus the gateway, all scale-to-zero) + MySQL Flexible Server, provisioned with `make provision` and removed with `make teardown`. About $0.21 for an -8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1 or M2 has been deployed +8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1, M2 or M3a has been deployed yet. In Azure, discovery uses Container Apps DNS (no registry), and the demo switches stay off. diff --git a/docs/PLAN.md b/docs/PLAN.md index e97dc74..bb6c93a 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -156,3 +156,15 @@ Decisions: consumer, hardened containers), all local, about 2 days. M3b = pattern 3 (path-filtered CI, OIDC Deploy workflow, Azure identity setup) plus the one real Azure run, about 1 day, started only on the owner's go-ahead after M3a merges. + +M3a code review (Matt Pocock code-review skill, 2 axes) — what changed after it: +- Fixed: one failing event no longer blocks the ones behind it (retry, then dead-letter stream after + 5 tries); one checkout per order at a time (`checkout_lock`); stock rows locked in product order; + a duplicate hold insert returns the existing hold; a payment timeout no longer claims "nothing was + charged"; restock input validated; the decline switch needs `CHAOS_ENABLED=1`. +- Spec gaps closed: every saga step publishes an event (StockReserved, PaymentCharged, + OrderConfirmed, CheckoutFailed); a timed-out stock hold is released through the bus. +- Wording: the "stop the bus" demo disconnects the order service's relay from Redis. It does not stop + Redis itself; a real Redis outage behaves the same for the publisher (events wait in the outbox). +- Moved to M3b: SHA image tags and the GIT_SHA build arg on the `az acr build` path (provision), image + size on the Containerization page (it is in the CI run summary today). diff --git a/docs/screenshots/p07-event-driven.jpg b/docs/screenshots/p07-event-driven.jpg index f077b277cdfa855e40b22404edf6bd9866477924..e42e8675ea3f79dd37a4c6efc04bcd4d46db3990 100644 GIT binary patch literal 64603 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 dict: try: response = await client.get(f"{base}/debug/runtime", headers=upstream_headers(request)) diff --git a/registry/Dockerfile b/registry/Dockerfile index 79dcad8..6b25c45 100644 --- a/registry/Dockerfile +++ b/registry/Dockerfile @@ -19,7 +19,6 @@ RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin app WORKDIR /app COPY --from=build /opt/venv /opt/venv COPY --chown=10001:10001 . . -RUN rm -rf _shared USER 10001 EXPOSE 8500 diff --git a/scripts/run_local.py b/scripts/run_local.py index 2bc8cf9..51d8e10 100644 --- a/scripts/run_local.py +++ b/scripts/run_local.py @@ -12,6 +12,7 @@ import os import shutil import signal +import socket import subprocess import sys import time @@ -76,8 +77,6 @@ def start_redis() -> bool: print(f" redis starting on :{REDIS_PORT} (pid {proc.pid})…") for _ in range(20): try: - import socket - with socket.create_connection(("127.0.0.1", REDIS_PORT), timeout=0.5): redis_running = True return True diff --git a/services/inventory/application/__init__.py b/services/inventory/application/__init__.py index 64c0d80..c200054 100644 --- a/services/inventory/application/__init__.py +++ b/services/inventory/application/__init__.py @@ -34,9 +34,9 @@ def create_app(config_name: str | None = None) -> Flask: app.register_blueprint(inventory_api) db.create_all() - from .seed import seed_stock_if_empty + from .seed import seed_missing_stock - seed_stock_if_empty() + seed_missing_stock() install_observability(app, "inventory", db) # Pattern 7: act on OrderConfirmed events from the bus (no-op without REDIS_URL). diff --git a/services/inventory/application/consumer.py b/services/inventory/application/consumer.py index 2d1049b..9102b84 100644 --- a/services/inventory/application/consumer.py +++ b/services/inventory/application/consumer.py @@ -17,6 +17,8 @@ def handle(event: dict) -> None: if db.session.get(ConsumedEvent, event["event_id"]) is not None: return # seen before: at-least-once delivery sent it twice reservation_id = event["payload"].get("reservation_id") + # action() commits on its own. If we crash before the ConsumedEvent row below, the event is + # redelivered and action() is a no-op the second time (it checks the reservation's status). reservation = action(reservation_id) outcome = f"reservation {reservation.status}" if reservation else "no such reservation" db.session.add(ConsumedEvent(event_id=event["event_id"], type=event["type"], diff --git a/services/inventory/application/routes.py b/services/inventory/application/routes.py index fdef102..6587d5b 100644 --- a/services/inventory/application/routes.py +++ b/services/inventory/application/routes.py @@ -65,15 +65,22 @@ def consumed_events(): return jsonify({"results": [e.to_json() for e in rows]}) +class RestockRequest(BaseModel): + quantity: int = Field(gt=0, le=1000) + + @inventory_api.post("/api/inventory//restock") def restock(product_id: int): """Demo and smoke-test helper: adds units on hand. Only with CHAOS_ENABLED=1 (make run).""" if not chaos_enabled(): return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) - quantity = int((request.get_json(silent=True) or {}).get("quantity", 0)) + try: + data = RestockRequest.model_validate(request.get_json(silent=True) or {}) + except ValidationError as exc: + return make_response(jsonify({"message": "Invalid request", "errors": exc.errors(include_url=False)}), 400) item = db.session.get(StockItem, product_id) - if item is None or not 0 < quantity <= 1000: - return make_response(jsonify({"message": "Unknown product or quantity not in 1-1000"}), 400) - item.on_hand += quantity + if item is None: + return make_response(jsonify({"message": f"No stock record for product {product_id}"}), 404) + item.on_hand += data.quantity db.session.commit() return jsonify({"result": item.to_json()}) diff --git a/services/inventory/application/seed.py b/services/inventory/application/seed.py index 0d39c4a..ee92b0f 100644 --- a/services/inventory/application/seed.py +++ b/services/inventory/application/seed.py @@ -9,7 +9,7 @@ } -def seed_stock_if_empty() -> None: +def seed_missing_stock() -> None: existing = {row.product_id for row in db.session.query(StockItem.product_id)} for product_id, on_hand in SAMPLE_STOCK.items(): if product_id not in existing: diff --git a/services/inventory/application/stock.py b/services/inventory/application/stock.py index b18f17c..7bc538a 100644 --- a/services/inventory/application/stock.py +++ b/services/inventory/application/stock.py @@ -6,6 +6,8 @@ Each is idempotent: calling it again for the same reservation changes nothing. """ +from sqlalchemy.exc import IntegrityError + from . import db from .models import Reservation, StockItem @@ -19,10 +21,17 @@ def _lock(product_id: int) -> StockItem | None: return db.session.query(StockItem).filter_by(product_id=product_id).with_for_update().one_or_none() +def _in_lock_order(items: list[dict]) -> list[dict]: + """Always lock stock rows in product id order, so two checkouts for the same products cannot + each hold one row and wait for the other's (a deadlock on MySQL).""" + return sorted(items, key=lambda line: line["product_id"]) + + def reserve(reservation_id: str, order_id: int, items: list[dict]) -> Reservation: existing = db.session.get(Reservation, reservation_id) if existing is not None: return existing + items = _in_lock_order(items) short = [] for line in items: stock = _lock(line["product_id"]) @@ -36,7 +45,11 @@ def reserve(reservation_id: str, order_id: int, items: list[dict]) -> Reservatio _lock(line["product_id"]).reserved += line["quantity"] reservation = Reservation(id=reservation_id, order_id=order_id, items=items, status="RESERVED") db.session.add(reservation) - db.session.commit() + try: + db.session.commit() + except IntegrityError: # the same hold, sent twice at once, landed first: keep that one + db.session.rollback() + return db.session.get(Reservation, reservation_id) return reservation @@ -44,7 +57,7 @@ def release(reservation_id: str) -> Reservation | None: reservation = db.session.get(Reservation, reservation_id) if reservation is None or reservation.status != "RESERVED": return reservation - for line in reservation.items: + for line in _in_lock_order(reservation.items): _lock(line["product_id"]).reserved -= line["quantity"] reservation.status = "RELEASED" db.session.commit() @@ -55,7 +68,7 @@ def commit(reservation_id: str) -> Reservation | None: reservation = db.session.get(Reservation, reservation_id) if reservation is None or reservation.status != "RESERVED": return reservation - for line in reservation.items: + for line in _in_lock_order(reservation.items): stock = _lock(line["product_id"]) stock.reserved -= line["quantity"] stock.on_hand -= line["quantity"] diff --git a/services/inventory/tests/test_contract_provider.py b/services/inventory/tests/test_contract_provider.py index c22a16d..cdc1b8c 100644 --- a/services/inventory/tests/test_contract_provider.py +++ b/services/inventory/tests/test_contract_provider.py @@ -10,9 +10,9 @@ def test_inventory_honours_the_order_services_contract(app): from application import db, stock from application.models import Reservation - from application.seed import seed_stock_if_empty + from application.seed import seed_missing_stock - seed_stock_if_empty() + seed_missing_stock() # Pact calls the state handlers on another thread. End this thread's transaction first, or # SQLite's write lock makes the handlers wait forever. db.session.commit() diff --git a/services/inventory/tests/test_event_reader.py b/services/inventory/tests/test_event_reader.py new file mode 100644 index 0000000..af66343 --- /dev/null +++ b/services/inventory/tests/test_event_reader.py @@ -0,0 +1,67 @@ +"""The bus reader in shop_common.events, driven with a fake Redis (pattern 7). + +One event that keeps failing must not stop the events behind it, and must not be retried forever. +""" +from shop_common import events + + +class FakeRedis: + """Just enough of a consumer group: new messages, a pending list, acks, a dead-letter stream.""" + + def __init__(self, messages): + self.new = list(messages) + self.pending = {} + self.acked = [] + self.dead = [] + + def xreadgroup(self, group, consumer, streams, count, block): + start = streams[events.STREAM] + if start == "0": + batch = list(self.pending.items()) + else: + batch, self.new = self.new[:count], self.new[count:] + self.pending.update(batch) + return [(events.STREAM, batch)] if batch else [] + + def xack(self, stream, group, message_id): + self.acked.append(message_id) + self.pending.pop(message_id, None) + + def xadd(self, stream, fields, **kwargs): + assert stream == events.DEAD_LETTER_STREAM + self.dead.append(fields["event_id"]) + + +def _event(n, event_type="OrderConfirmed"): + return f"{n}-0", events.to_fields(f"evt-{n}", event_type, {}, "test", "now") + + +def test_a_failing_event_does_not_block_the_events_behind_it(): + redis = FakeRedis([_event(1, "Poison")]) + handled = [] + + def handle(event): + if event["type"] == "Poison": + raise ValueError("cannot handle") + handled.append(event["event_id"]) + + reader = events.Reader("inventory", "inventory-1", handle) + reader.read_once(redis) # the poison event fails + redis.new.append(_event(2)) # a good event arrives after it + for _ in range(4): + reader.read_once(redis) + assert handled == ["evt-2"] + + +def test_an_event_that_keeps_failing_goes_to_the_dead_letter_stream(): + redis = FakeRedis([_event(1, "Poison")]) + + def handle(event): + raise ValueError("cannot handle") + + reader = events.Reader("inventory", "inventory-1", handle) + for _ in range(2 * events.MAX_ATTEMPTS): + reader.read_once(redis) + assert redis.dead == ["evt-1"] + assert redis.acked == ["1-0"] + assert redis.pending == {} diff --git a/services/inventory/tests/test_inventory.py b/services/inventory/tests/test_inventory.py index 33604c2..d7cbc10 100644 --- a/services/inventory/tests/test_inventory.py +++ b/services/inventory/tests/test_inventory.py @@ -1,5 +1,5 @@ from application.models import StockItem -from application.seed import SAMPLE_STOCK, seed_stock_if_empty +from application.seed import SAMPLE_STOCK, seed_missing_stock def test_available_is_on_hand_minus_reserved(): @@ -7,13 +7,13 @@ def test_available_is_on_hand_minus_reserved(): def test_seed_is_idempotent(app): - seed_stock_if_empty() - seed_stock_if_empty() + seed_missing_stock() + seed_missing_stock() assert StockItem.query.count() == len(SAMPLE_STOCK) def test_get_stock_and_404(client): - seed_stock_if_empty() + seed_missing_stock() r = client.get("/api/inventory/1") assert r.status_code == 200 assert r.get_json()["result"]["on_hand"] == SAMPLE_STOCK[1] diff --git a/services/inventory/tests/test_saga_and_events.py b/services/inventory/tests/test_saga_and_events.py index ce6bbea..9a844d8 100644 --- a/services/inventory/tests/test_saga_and_events.py +++ b/services/inventory/tests/test_saga_and_events.py @@ -3,14 +3,14 @@ from application import consumer, db, stock from application.models import StockItem -from application.seed import seed_stock_if_empty +from application.seed import seed_missing_stock RID = "saga-0001-aaaa" @pytest.fixture def seeded(app): - seed_stock_if_empty() + seed_missing_stock() return app @@ -72,3 +72,10 @@ def test_restock_is_a_demo_switch(seeded, client, monkeypatch): assert client.post("/api/inventory/1/restock", json={"quantity": 5}).status_code == 403 monkeypatch.setenv("CHAOS_ENABLED", "1") assert client.post("/api/inventory/1/restock", json={"quantity": 5}).get_json()["result"]["on_hand"] == 30 + + +def test_restock_rejects_bad_input_with_400(seeded, client, monkeypatch): + monkeypatch.setenv("CHAOS_ENABLED", "1") + assert client.post("/api/inventory/1/restock", json={"quantity": "lots"}).status_code == 400 + assert client.post("/api/inventory/1/restock", json={"quantity": 0}).status_code == 400 + assert client.post("/api/inventory/999/restock", json={"quantity": 5}).status_code == 404 diff --git a/services/order/application/models.py b/services/order/application/models.py index 6cf70e4..7eafd49 100644 --- a/services/order/application/models.py +++ b/services/order/application/models.py @@ -82,3 +82,14 @@ def to_json(self): "attempts": self.attempts, "last_error": self.last_error, } + + +class CheckoutLock(db.Model): + """At most one checkout saga per order at a time. The primary key makes a second insert fail, + even from the other replica, so a double click cannot hold stock or charge twice.""" + + __tablename__ = "checkout_lock" + + 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) diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index ca2194b..f4e0002 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -77,6 +77,8 @@ def checkout(): # Pattern 8 demo: {"simulate_decline": true} makes payment refuse the charge. options = request.get_json(silent=True) or request.form simulate = "decline" if str(options.get("simulate_decline", "")).lower() in ("1", "true", "yes") else "approve" + if simulate == "decline" and not chaos_enabled(): + return make_response(jsonify({"message": "Demo switches are off (CHAOS_ENABLED is not 1)"}), 403) status, body = saga.run_checkout(order_model, u_id, simulate) return make_response(jsonify(body), status) diff --git a/services/order/application/saga.py b/services/order/application/saga.py index 0d62ca1..f098815 100644 --- a/services/order/application/saga.py +++ b/services/order/application/saga.py @@ -1,10 +1,11 @@ """The checkout saga (pattern 8), orchestrated by the order service. 1. price ask catalog for current prices - 2. reserve_stock inventory holds the units compensation: release_stock - 3. charge_payment payment charges the card (nothing to undo if it fails) + 2. reserve_stock inventory holds the units event StockReserved; undo: release_stock + 3. charge_payment payment charges the card event PaymentCharged 4. confirm close the order and, in the SAME transaction, write OrderConfirmed to the 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). 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, @@ -14,11 +15,13 @@ Every step is written to saga_step, which is what the Saga page draws. """ import uuid +from datetime import datetime, timedelta, timezone import requests +from sqlalchemy.exc import IntegrityError from . import db -from .models import Order, OutboxEvent, SagaStep +from .models import CheckoutLock, Order, OutboxEvent, SagaStep from .order_api.api import clients @@ -28,33 +31,81 @@ def __init__(self, order: Order, user_id: int): self.order = order self.user_id = user_id - def log(self, step: str, status: str, detail: str | None = None) -> None: + def emit(self, event_type: str, payload: dict | None = None) -> None: + """Adds an event to the outbox. It is committed together with the next log() line.""" + db.session.add(OutboxEvent(id=str(uuid.uuid4()), type=event_type, + payload={"saga_id": self.id, "order_id": self.order.id, **(payload or {})})) + + def log(self, step: str, status: str, detail: str | None = None, event: str | None = None, + payload: dict | None = None) -> None: + """Records a step and, in the same transaction, its event and any pending order change.""" db.session.add(SagaStep(saga_id=self.id, order_id=self.order.id, user_id=self.user_id, step=step, status=status, detail=(detail or "")[:300])) + if event: + self.emit(event, payload) db.session.commit() - def emit(self, event_type: str, payload: dict) -> None: - """Adds an event to the outbox. Committed by the caller, with the change it describes.""" - db.session.add(OutboxEvent(id=str(uuid.uuid4()), type=event_type, - payload={"saga_id": self.id, "order_id": self.order.id, **payload})) - - def fail(self, step: str, detail: str, http_status: int, message: str, **extra) -> tuple[int, dict]: + def fail(self, step: str, detail: str, http_status: int, message: str, compensate: bool = False, + **extra) -> tuple[int, dict]: + """Logs the failed step, undoes the stock hold if asked, and reports CheckoutFailed.""" self.log(step, "failed", detail) + if compensate: + _compensate(self) self.emit("CheckoutFailed", {"failed_step": step, "reason": detail}) db.session.commit() return http_status, {"message": message, "saga_id": self.id, "failed_step": step, **extra} +# A lock older than this was left by a replica that crashed mid-saga; the next checkout may take it. +LOCK_TIMEOUT = timedelta(seconds=60) + + +def _acquire_lock(order: Order, saga_id: str) -> bool: + now = datetime.now(timezone.utc) + existing = db.session.get(CheckoutLock, order.id) + if existing is not None: + started = existing.started_at.replace(tzinfo=existing.started_at.tzinfo or timezone.utc) + if now - started < LOCK_TIMEOUT: + return False + db.session.delete(existing) + db.session.flush() + db.session.add(CheckoutLock(order_id=order.id, saga_id=saga_id, started_at=now)) + try: + db.session.commit() + return True + except IntegrityError: # the other click (or replica) got there first + db.session.rollback() + return False + + +def _release_lock(order_id: int) -> None: + lock = db.session.get(CheckoutLock, order_id) + if lock is not None: + db.session.delete(lock) + db.session.commit() + + 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: + return _run_steps(saga, simulate) + finally: + _release_lock(order.id) + + +def _run_steps(saga: Saga, simulate: str) -> tuple[int, dict]: + order = saga.order items = [{"product_id": i.product_id, "quantity": i.quantity} for i in order.items] + kept = "Your cart is kept." # 1. price try: prices = clients.product_prices() except requests.RequestException as exc: return saga.fail("price", f"catalog unreachable: {exc.__class__.__name__}", 503, - "The catalog is unavailable, so the order cannot be priced. Your cart is kept.") + f"The catalog is unavailable, so the order cannot be priced. {kept}") missing = [i["product_id"] for i in items if i["product_id"] not in prices] if missing: return saga.fail("price", f"unknown products {missing}", 409, f"Product(s) {missing} are no longer sold") @@ -66,44 +117,44 @@ def run_checkout(order: Order, user_id: int, simulate: str = "approve") -> tuple clients.reserve_stock(saga.id, order.id, items) except clients.OutOfStock as exc: return saga.fail("reserve_stock", f"short: {exc.short}", 409, - "Not enough stock for your cart. Nothing was charged. Your cart is kept.", short=exc.short) + f"Not enough stock for your cart. Nothing was charged. {kept}", short=exc.short) except requests.RequestException as exc: + # No answer does not mean no hold: inventory may have held the stock before the reply was + # lost. Ask it to release through the bus; releasing an unknown hold is a no-op. + saga.emit("StockReleaseRequested", {"reservation_id": saga.id}) return saga.fail("reserve_stock", f"inventory unreachable: {exc.__class__.__name__}", 503, - "Inventory is unavailable. Nothing was charged. Your cart is kept.") - saga.log("reserve_stock", "done", f"held {sum(i['quantity'] for i in items)} unit(s)") + f"Inventory is unavailable. Nothing was charged. {kept}") + units = sum(i["quantity"] for i in items) + 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) - failure = None try: payment = clients.charge(order.id, amount, simulate) - if payment["status"] != "APPROVED": - failure = ("declined", 402, "Your payment was declined. Nothing was charged; the stock was released. Your cart is kept.") except clients.PaymentUnavailable as exc: - state = clients.breaker_state() - wait = f" Try again in {state['retry_in_seconds']:.0f} s." if state["retry_in_seconds"] else "" - failure = (f"payment unavailable ({exc.reason})", 503, - f"Payment is unavailable right now, so nothing was charged; the stock was released. Your cart is kept.{wait}") + breaker = clients.breaker_state() + if exc.reason == "open": # the breaker refused the call: payment was never contacted + 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) except requests.RequestException as exc: - failure = (f"payment error: {exc.__class__.__name__}", 502, "Payment failed. The stock was released. Your cart is kept.") - - if failure: - reason, http_status, message = failure - saga.log("charge_payment", "failed", reason) - _compensate(saga) - saga.emit("CheckoutFailed", {"failed_step": "charge_payment", "reason": reason}) - db.session.commit() - body = {"message": message, "saga_id": saga.id, "failed_step": "charge_payment"} - if http_status == 503: - body["breaker"] = clients.breaker_state() - return http_status, body - saga.log("charge_payment", "done", f"payment {payment['id']} APPROVED, {amount} cents") - - # 4. confirm: the order change and its event commit together, or not at all + 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) + 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}) + + # 4. confirm: the order change, its log line and its event commit together, or not at all order.is_open = False - saga.emit("OrderConfirmed", {"reservation_id": saga.id, "amount_cents": amount, "items": items}) - db.session.add(SagaStep(saga_id=saga.id, order_id=order.id, user_id=user_id, step="confirm", - status="done", detail="order closed; OrderConfirmed in the outbox")) - db.session.commit() + 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} @@ -114,8 +165,8 @@ def _compensate(saga: Saga) -> None: except requests.RequestException as exc: # Could not undo directly: ask inventory through the bus. It is idempotent, so a release # that did go through and this event together are harmless. - saga.emit("StockReleaseRequested", {"reservation_id": saga.id}) - saga.log("release_stock", "compensated", f"inventory unreachable ({exc.__class__.__name__}); release sent as an event") + saga.log("release_stock", "compensated", f"inventory unreachable ({exc.__class__.__name__}); release sent as an event", + event="StockReleaseRequested", payload={"reservation_id": saga.id}) def recent_sagas(user_id: int, limit: int = 5) -> list[dict]: diff --git a/services/order/tests/test_checkout_and_breaker.py b/services/order/tests/test_checkout_and_breaker.py index 17685ea..fd485ae 100644 --- a/services/order/tests/test_checkout_and_breaker.py +++ b/services/order/tests/test_checkout_and_breaker.py @@ -86,3 +86,19 @@ def down(): monkeypatch.setattr(clients, "product_prices", down) _cart(client) assert client.post("/api/order/checkout", headers=AUTH).status_code == 503 + + +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 + + +def test_an_open_breaker_does_say_nothing_was_charged(client): + _cart(client) + for _ in range(clients.FAIL_MAX): + client.get("/api/order/payment-check") + message = client.post("/api/order/checkout", headers=AUTH).get_json()["message"] + assert "nothing was charged" in message diff --git a/services/order/tests/test_saga_and_outbox.py b/services/order/tests/test_saga_and_outbox.py index 87c8c9c..2a546d7 100644 --- a/services/order/tests/test_saga_and_outbox.py +++ b/services/order/tests/test_saga_and_outbox.py @@ -12,6 +12,7 @@ @pytest.fixture def calls(monkeypatch): log = [] + monkeypatch.setenv("CHAOS_ENABLED", "1") # the decline demo switch, as under make run 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: log.append(("reserve", rid)) or {}) @@ -39,8 +40,8 @@ def test_happy_path_confirms_and_queues_order_confirmed(client, calls): r = _checkout(client) assert r.status_code == 200 assert _steps() == [("price", "done"), ("reserve_stock", "done"), ("charge_payment", "done"), ("confirm", "done")] - assert _events() == ["OrderConfirmed"] - event = OutboxEvent.query.one() + assert _events() == ["StockReserved", "PaymentCharged", "OrderConfirmed"] # one event per step + event = OutboxEvent.query.filter_by(type="OrderConfirmed").one() assert event.payload["reservation_id"] == r.get_json()["saga_id"] # inventory sells exactly this hold assert event.published_at is None # nothing published inside the request @@ -50,7 +51,7 @@ def test_declined_payment_releases_the_stock_and_keeps_the_cart(client, calls): assert r.status_code == 402 assert [c[0] for c in calls] == ["reserve", "charge", "release"] assert _steps()[-2:] == [("charge_payment", "failed"), ("release_stock", "compensated")] - assert _events() == ["CheckoutFailed"] + assert _events() == ["StockReserved", "CheckoutFailed"] assert client.get("/api/order", headers=AUTH).get_json()["result"]["is_open"] is True @@ -70,7 +71,7 @@ def down(rid): monkeypatch.setattr(clients, "release_stock", down) _checkout(client, simulate_decline=True) - assert _events() == ["StockReleaseRequested", "CheckoutFailed"] + assert _events() == ["StockReserved", "StockReleaseRequested", "CheckoutFailed"] def test_saga_history_is_per_user(client, calls): @@ -90,9 +91,9 @@ def xadd(self, stream, fields, **kwargs): def test_relay_publishes_pending_events_once(client, calls): _checkout(client) bus = FakeBus() - assert outbox.publish_pending(bus, "order-test") == 1 + assert outbox.publish_pending(bus, "order-test") == 3 assert outbox.publish_pending(bus, "order-test") == 0 - assert bus.sent == ["OrderConfirmed"] + assert bus.sent == ["StockReserved", "PaymentCharged", "OrderConfirmed"] def test_events_wait_while_the_bus_is_down(client, calls): @@ -100,8 +101,63 @@ def test_events_wait_while_the_bus_is_down(client, calls): outbox.set_connected(False) try: assert outbox.publish_pending(FakeBus(), "order-test") == 0 - assert client.get("/api/order/outbox").get_json()["pending"] == 1 - assert OutboxEvent.query.one().attempts == 1 + assert client.get("/api/order/outbox").get_json()["pending"] == 3 finally: outbox.set_connected(True) - assert outbox.publish_pending(FakeBus(), "order-test") == 1 + assert outbox.publish_pending(FakeBus(), "order-test") == 3 + + +def test_a_second_checkout_while_one_is_running_is_refused(client, calls): + from datetime import datetime, timezone + + from application import db + from application.models import CheckoutLock, Order + + client.post("/api/order/add-item", data={"product_id": 1, "qty": 2}, headers=AUTH) + order = Order.query.one() + # The first click's saga is still running: it holds the order's checkout lock. + db.session.add(CheckoutLock(order_id=order.id, saga_id="first-click", started_at=datetime.now(timezone.utc))) + db.session.commit() + r = client.post("/api/order/checkout", json={}, headers=AUTH) + assert r.status_code == 409 + assert "already in progress" in r.get_json()["message"] + assert calls == [] # no hold, no charge + + +def test_the_lock_is_released_when_a_saga_ends(client, calls, monkeypatch): + monkeypatch.setenv("CHAOS_ENABLED", "1") + assert _checkout(client, simulate_decline=True).status_code == 402 + assert client.post("/api/order/checkout", json={}, headers=AUTH).status_code == 200 + + +def test_a_lock_left_by_a_crashed_replica_expires(client, calls): + from datetime import datetime, timedelta, timezone + + from application import db + from application.models import CheckoutLock, Order + + client.post("/api/order/add-item", data={"product_id": 1, "qty": 2}, headers=AUTH) + order = Order.query.one() + stale = datetime.now(timezone.utc) - timedelta(minutes=5) + db.session.add(CheckoutLock(order_id=order.id, saga_id="crashed", started_at=stale)) + db.session.commit() + assert client.post("/api/order/checkout", json={}, headers=AUTH).status_code == 200 + + +def test_the_decline_switch_is_off_unless_demo_switches_are_on(client, calls, monkeypatch): + monkeypatch.delenv("CHAOS_ENABLED") + r = _checkout(client, simulate_decline=True) + assert r.status_code == 403 + assert calls == [] + + +def test_a_timed_out_hold_is_released_through_the_bus(client, calls, monkeypatch): + """Inventory may have held the stock before the answer was lost: ask it to release, idempotently.""" + def timeout(rid, oid, items): + raise requests.Timeout("inventory slow") + + monkeypatch.setattr(clients, "reserve_stock", timeout) + r = _checkout(client) + assert r.status_code == 503 + assert _events() == ["StockReleaseRequested", "CheckoutFailed"] + assert OutboxEvent.query.filter_by(type="StockReleaseRequested").one().payload["reservation_id"] == r.get_json()["saga_id"] diff --git a/shared/shop_common/events.py b/shared/shop_common/events.py index 5277b90..4b82e03 100644 --- a/shared/shop_common/events.py +++ b/shared/shop_common/events.py @@ -44,19 +44,55 @@ def from_fields(fields: dict) -> dict: return {**fields, "payload": json.loads(fields.get("payload") or "{}")} -def start_consumer(group: str, consumer: str, handle: Callable[[dict], None], log=None) -> threading.Thread | None: - """Reads the stream as `consumer` in `group` on a background thread and acks each handled event. +MAX_ATTEMPTS = 5 +DEAD_LETTER_STREAM = "shop.events.dead" + + +class Reader: + """One consumer in a consumer group. read_once() is one pass; start_consumer() loops it. - handle() gets the decoded event. If it raises, the event is not acked and is retried on the - next pass. Returns None when no bus is configured. + Alternates between new events (">") and this consumer's own unacknowledged ones ("0"), so a + failing event is retried without holding back the events behind it. After MAX_ATTEMPTS it is + copied to the dead-letter stream and acknowledged, for a person to look at. """ + + def __init__(self, group: str, consumer: str, handle: Callable[[dict], None], log=None): + self.group, self.consumer, self.handle, self.log = group, consumer, handle, log + self.start_id = "0" # first pass: our own unacked events from before a restart + self.failures: dict[str, int] = {} + + def read_once(self, client) -> None: + start_id = self.start_id + batches = client.xreadgroup(self.group, self.consumer, {STREAM: start_id}, count=20, block=2000) + messages = batches[0][1] if batches else [] + for message_id, fields in messages: + try: + self.handle(from_fields(fields)) + client.xack(STREAM, self.group, message_id) + self.failures.pop(message_id, None) + except Exception as exc: + attempts = self.failures.get(message_id, 0) + 1 + self.failures[message_id] = attempts + if self.log: + self.log.warning(f"event {message_id} failed (attempt {attempts}): {exc}") + if attempts >= MAX_ATTEMPTS: + client.xadd(DEAD_LETTER_STREAM, {**fields, "group": self.group, "error": str(exc)[:200]}) + client.xack(STREAM, self.group, message_id) + self.failures.pop(message_id, None) + # Retry failures on the next pass, new events on the one after: neither starves the other. + self.start_id = "0" if start_id == ">" and self.failures else ">" + + +def start_consumer(group: str, consumer: str, handle: Callable[[dict], None], log=None) -> threading.Thread | None: + """Runs a Reader on a background thread. Returns None when no bus is configured.""" if not redis_url(): return None + reader = Reader(group, consumer, handle, log) def loop() -> None: import redis - client, start_id = None, "0" # "0" first: our own unacked events from before a restart + client = None while True: try: if client is None: @@ -66,19 +102,9 @@ def loop() -> None: except redis.ResponseError as exc: if "BUSYGROUP" not in str(exc): raise - batches = client.xreadgroup(group, consumer, {STREAM: start_id}, count=20, block=2000) - messages = batches[0][1] if batches else [] - if start_id == "0" and not messages: - start_id = ">" # backlog done, now only new events - for message_id, fields in messages: - try: - handle(from_fields(fields)) - client.xack(STREAM, group, message_id) - except Exception as exc: # leave it unacked; it is retried from "0" next pass - if log: - log.warning(f"event {message_id} failed: {exc}") - start_id = "0" - time.sleep(1) # do not spin on an event that keeps failing + reader.read_once(client) + if reader.failures: + time.sleep(1) # do not spin on an event that keeps failing except (redis.ConnectionError, redis.TimeoutError, OSError): client = None time.sleep(2)