diff --git a/.env.example b/.env.example index 028d174..955379a 100644 --- a/.env.example +++ b/.env.example @@ -17,6 +17,7 @@ ORDER_SERVICE_PORT=5103 PAYMENT_SERVICE_PORT=5104 INVENTORY_SERVICE_PORT=5105 GATEWAY_PORT=8100 +REGISTRY_PORT=8500 FRONTEND_PORT=5273 # --- Service base URLs (used by the gateway and by services calling each other) --- @@ -26,6 +27,19 @@ ORDER_SERVICE_BASE_URL=http://127.0.0.1:5103 PAYMENT_SERVICE_BASE_URL=http://127.0.0.1:5104 INVENTORY_SERVICE_BASE_URL=http://127.0.0.1:5105 +# --- Service discovery (pattern 12) --- +# 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) --- +# make run sets CHAOS_ENABLED=1 so the pages can stop a replica and break payment. Keep it off anywhere public. +# CHAOS_ENABLED=1 + +# --- Login tokens (pattern 10) --- +# The user service signs tokens with this RSA private key. Unset locally: it creates +# services/user/instance/jwt_private.pem on first start (git-ignored). Never commit a real key. +# JWT_PRIVATE_KEY_PEM= + # --- SQLite (local mode, default) --- # Optional overrides — each path is relative to that service's own directory. # Leave unset to use instance/.sqlite3 inside each service folder. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 17f0caf..2339c22 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,9 @@ jobs: requirements: gateway/requirements.txt tests: gateway/tests shared: fastapi + - suite: registry + requirements: registry/requirements.txt + tests: registry/tests - suite: user requirements: services/user/requirements.txt tests: services/user/tests @@ -33,14 +36,17 @@ jobs: requirements: services/catalog/requirements.txt tests: services/catalog/tests shared: flask + contracts: true - suite: order requirements: services/order/requirements.txt tests: services/order/tests shared: flask + contracts: true - suite: payment requirements: services/payment/requirements.txt tests: services/payment/tests shared: flask + contracts: true - suite: inventory requirements: services/inventory/requirements.txt tests: services/inventory/tests @@ -61,9 +67,19 @@ jobs: if: matrix.shared run: pip install "./shared[${{ matrix.shared }}]" + - name: Install Pact (contract tests) + if: matrix.contracts + run: pip install -r contracts/requirements.txt + - name: Run tests run: python -m pytest ${{ matrix.tests }} -v + # The order suite regenerates the contracts it consumes. If they differ from the committed + # files, the consumer changed what it needs without committing the new contract. + - name: Contracts are up to date + if: matrix.suite == 'order' + run: git diff --exit-code contracts/pacts + frontend: name: Frontend (build) runs-on: ubuntu-latest diff --git a/CLAUDE.md b/CLAUDE.md index f6241a8..1957bc2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,34 +27,41 @@ 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 (M1, foundation: patterns 1, 2, 5, 6 live) +## Current state (M2: patterns 1, 2, 4, 5, 6, 10, 11, 12 live) - Folders: `services/{user,catalog,order,payment,inventory}/` (Flask, one DB each), `gateway/` - (FastAPI), `shared/` (`shop_common`), `frontend/`, `infra/`, `scripts/`, `tests/`. -- **One service table**: `scripts/service_table.py` lists every local process, folder and port. - `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, payment 5104, inventory 5105, gateway 8100, - frontend 5273 (registry 8500 arrives in M2). + (FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`, + `scripts/`, `tests/`. +- **One service table**: `scripts/service_table.py` lists every local process, folder and port, plus + `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. - **`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`, OpenTelemetry - tracing (Flask, requests, SQLAlchemy per engine), JSON logs with trace/request IDs, and metrics. - The gateway uses `gateway/app/observability.py` (FastAPI + httpx). `setup.py` installs `shared/` - editable into every venv; `provision.py` stages it as `/_shared` for `az acr build`. -- Traces: each process keeps its last 2,000 spans in memory (`SPAN_STORE`); the gateway stitches a - trace from every service's `/debug/spans`. Database span names are trimmed to the file name so - no local path leaks. Containers run gunicorn with 1 worker + 4 threads so one process holds all - spans. `OTEL_EXPORTER_OTLP_ENDPOINT` optionally exports too. -- Gotchas solved: FastAPI tracing middleware must be added AFTER the request-ID middleware (the - last-added Starlette middleware runs outermost); Flask-SQLAlchemy's engine is missed by the - global SQLAlchemy hook, so it is instrumented per engine; the httpx hook only loads where httpx - is installed. -- Gateway: `/api/shop/` (GET/POST only) routed by `ROUTE_OWNERS`; `/api/order-summary` - aggregation; demo endpoints in `gateway/app/routers/patterns.py`. No auth check yet (JWT is M2). -- The catalog service keeps the `product` resource name in its API (`/api/product(s)`). The - unauthenticated `DELETE /api/product/` was removed. -- Frontend: `/patterns` grid, `/patterns/:slug` page from `frontend/src/patterns/content.ts`, demos - in `frontend/src/patterns/demos/`. Signed-in user is read from localStorage `shop_auth`. + 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, + metrics, and registry heartbeats when `SERVICE_PUBLIC_URL` and `REGISTRY_URL` are set. + `auth.py` verifies RS256 tokens; `discovery.py` heartbeats and round-robins (urllib, so no spans); + `contract_testing.py` runs Pact provider verification. `setup.py` installs `shared/` editable; + `provision.py` stages it as `/_shared` for `az acr build`. +- Tokens (pattern 10): the user service signs (key from `JWT_PRIVATE_KEY_PEM`, else + `services/user/instance/jwt_private.pem`, git-ignored). Gateway and order verify with + `/api/user/public-key`. Flask-Login and the `api_key` column are gone. Frontend sends `Bearer`. +- Gateway: rejects `order` paths with a bad token at the edge; `config.url_for()` round-robins via + the registry, falls back to `SERVICE_BASE_URLS`; the shop proxy fails over to the next replica on a + refused connection. Trace stitching and metrics read every replica (`config.urls_for()`). +- 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 + 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). +- 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). - Smoke tests create users and products in the local SQLite DBs; delete `services/*/instance/` - for a clean catalog. + for a clean catalog (this also deletes the local signing key, which logs everyone out). ## Stack Python 3.12 (Flask 3.1 services, FastAPI gateway), Node 18+ (React 18, TypeScript 5, Vite 5), diff --git a/Makefile b/Makefile index 4912200..d2fad5a 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: setup run provision pause resume teardown verify test smoke clean +.PHONY: setup run provision pause resume teardown verify test contracts smoke clean setup: python3.12 scripts/setup.py @@ -29,6 +29,13 @@ test: services/payment/.venv/bin/python -m pytest services/payment/tests -v services/inventory/.venv/bin/python -m pytest services/inventory/tests -v gateway/.venv/bin/python -m pytest gateway/tests -v + registry/.venv/bin/python -m pytest registry/tests -v + +# Pattern 11 only: the order service writes its contracts, then payment and catalog verify them. +contracts: + services/order/.venv/bin/python -m pytest services/order/tests/test_contracts_consumer.py -v + services/payment/.venv/bin/python -m pytest services/payment/tests/test_contract_provider.py -v + services/catalog/.venv/bin/python -m pytest services/catalog/tests/test_contract_provider.py -v smoke: .venv/bin/python -m pytest tests/smoke -v diff --git a/README.md b/README.md index e8a4514..62dd4cc 100644 --- a/README.md +++ b/README.md @@ -4,10 +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: M1, foundation.** 4 of 12 patterns are live: Database per Service, Bounded Context, -> API Gateway and Observability. The foundation is copied from +> **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 > [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration). -> The rest arrive in milestones M2 and M3. See [docs/PLAN.md](docs/PLAN.md). +> The last 4 arrive in milestone M3. See [docs/PLAN.md](docs/PLAN.md). ## The 12 patterns @@ -16,36 +17,41 @@ 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 | -| 4 | Circuit Breaker | Stops calls to a failing service to prevent more failures | M2 | +| 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 | -| 10 | Stateless Services | Stores session data outside the service | M2 | -| 11 | Contract Testing | Checks that APIs stay compatible across services | M2 | -| 12 | Service Discovery | Finds service instances automatically at runtime | M2 | +| 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)** | ## Architecture today ``` -Browser → API gateway ──┬──► user → user_db - (request IDs, ├──► catalog → catalog_db - tracing, metrics, ├──► order → order_db ──HTTP──► user (validates the caller) - aggregation) ├──► payment → payment_db - └──► inventory → inventory_db +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 + aggregation, ├──► payment → payment_db + failover) └──► inventory → inventory_db + +Every service heartbeats into the registry (:8500); callers look each other up there. ``` - **5 Flask services** (`services/`), each with its own database: SQLite locally, one logical - MySQL database each in Azure. + MySQL database each in Azure. Locally the order service runs as 2 replicas. - **FastAPI gateway** (`gateway/`): the only thing the browser talks to. Routes `/api/shop/*` to the owning service, adds request IDs, aggregates `/api/order-summary`, serves the demo endpoints. - **`shop_common`** (`shared/`): OpenTelemetry tracing, JSON logs with trace IDs, Prometheus - metrics, and the `/health/db`, `/debug/spans`, `/metrics` endpoints every service exposes. + 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. - **React + TypeScript** frontend (`frontend/`) with a page per pattern. -Still to come: service registry, JWT and replicas, circuit breaker, Pact contract tests (M2); -Redis Streams events with an outbox, checkout saga, hardened containers, deploy pipeline (M3). +Still to come (M3): Redis Streams events with an outbox, checkout saga, hardened containers, +deploy pipeline, and a real Azure run. ## The live demos @@ -73,12 +79,39 @@ database queries, drawn as a waterfall. Metrics per service come from each `/met Observability demo: a trace waterfall across gateway, user, order, catalog and inventory +### 4. Circuit Breaker +Switch payment to slow and send 10 calls. Each order replica's breaker opens after 3 failures. +A real failure took 2,215 ms; a call the open breaker stopped took 0 ms. After 15 s with payment +healthy again, both breakers close. + +Circuit Breaker demo: both order replicas' breakers open; failed calls take 2.2 s, short-circuited calls 0 ms + +### 10. Stateless Services +Your login is a signed token, readable by anyone, signed only by the user service. Ask for your +cart 6 times: both order replicas answer. Stop one: all 6 calls still succeed, same cart, still +logged in. + +Stateless Services demo: one order replica stopped, all 6 cart requests still succeed on the other + +### 11. Contract Testing +The order service's contracts with payment and catalog, read from the committed Pact files, and +the real CI output when payment renames one field the order service relies on. + +Contract Testing demo: the contract break output and how CI runs consumer and provider checks + +### 12. Service Discovery +The live registry. Stop an instance: its heartbeat stops, the registry expires it after 10 s, and +`make run` restarts it 20 s later, when it registers again. + +Service Discovery demo: registry table and an expired then re-registered order replica + ## Run locally (no Docker) ```bash 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 +make run # frontend http://127.0.0.1:5273, gateway http://127.0.0.1:8100, registry :8500 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 ``` @@ -89,4 +122,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 has been deployed yet. +8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1 or M2 has been deployed +yet. In Azure, discovery uses Container Apps DNS (no registry), and the demo switches stay off. diff --git a/contracts/pacts/order-catalog.json b/contracts/pacts/order-catalog.json new file mode 100644 index 0000000..77bee7d --- /dev/null +++ b/contracts/pacts/order-catalog.json @@ -0,0 +1,82 @@ +{ + "consumer": { + "name": "order" + }, + "interactions": [ + { + "description": "a request for every product and its price", + "pending": false, + "providerStates": [ + { + "name": "products exist" + } + ], + "request": { + "method": "GET", + "path": "/api/products" + }, + "response": { + "body": { + "content": { + "results": [ + { + "id": 1, + "price": 1299 + } + ] + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.results": { + "combine": "AND", + "matchers": [ + { + "match": "type", + "min": 1 + } + ] + }, + "$.results[*].id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.results[*].price": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + } + ], + "metadata": { + "pactRust": { + "ffi": "0.5.12", + "models": "1.3.16" + }, + "pactSpecification": { + "version": "4.0" + } + }, + "provider": { + "name": "catalog" + } +} \ No newline at end of file diff --git a/contracts/pacts/order-payment.json b/contracts/pacts/order-payment.json new file mode 100644 index 0000000..7eb390d --- /dev/null +++ b/contracts/pacts/order-payment.json @@ -0,0 +1,143 @@ +{ + "consumer": { + "name": "order" + }, + "interactions": [ + { + "description": "a charge for an order", + "pending": false, + "providerStates": [ + { + "name": "payment is healthy" + } + ], + "request": { + "body": { + "content": { + "amount_cents": 2598, + "order_id": 42 + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.amount_cents": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.order_id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "method": "POST", + "path": "/api/payment/charge" + }, + "response": { + "body": { + "content": { + "result": { + "amount_cents": 2598, + "id": 1, + "order_id": 42, + "status": "APPROVED" + } + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "matchingRules": { + "body": { + "$.result.amount_cents": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.result.id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + }, + "$.result.order_id": { + "combine": "AND", + "matchers": [ + { + "match": "integer" + } + ] + } + } + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + }, + { + "description": "a health check through the circuit breaker", + "pending": false, + "providerStates": [ + { + "name": "payment is healthy" + } + ], + "request": { + "method": "GET", + "path": "/api/payment/ping" + }, + "response": { + "body": { + "content": { + "status": "ok" + }, + "contentType": "application/json", + "encoded": false + }, + "headers": { + "Content-Type": [ + "application/json" + ] + }, + "status": 200 + }, + "type": "Synchronous/HTTP" + } + ], + "metadata": { + "pactRust": { + "ffi": "0.5.12", + "models": "1.3.16" + }, + "pactSpecification": { + "version": "4.0" + } + }, + "provider": { + "name": "payment" + } +} \ No newline at end of file diff --git a/contracts/requirements.txt b/contracts/requirements.txt new file mode 100644 index 0000000..b149b40 --- /dev/null +++ b/contracts/requirements.txt @@ -0,0 +1 @@ +pact-python==4.2.0 diff --git a/docs/screenshots/p04-circuit-breaker.jpg b/docs/screenshots/p04-circuit-breaker.jpg new file mode 100644 index 0000000..6eb615a Binary files /dev/null and b/docs/screenshots/p04-circuit-breaker.jpg differ diff --git a/docs/screenshots/p10-stateless-services.jpg b/docs/screenshots/p10-stateless-services.jpg new file mode 100644 index 0000000..dfa94a3 Binary files /dev/null and b/docs/screenshots/p10-stateless-services.jpg differ diff --git a/docs/screenshots/p11-contract-testing.jpg b/docs/screenshots/p11-contract-testing.jpg new file mode 100644 index 0000000..d64b47a Binary files /dev/null and b/docs/screenshots/p11-contract-testing.jpg differ diff --git a/docs/screenshots/p12-service-discovery.jpg b/docs/screenshots/p12-service-discovery.jpg new file mode 100644 index 0000000..2dbc050 Binary files /dev/null and b/docs/screenshots/p12-service-discovery.jpg differ diff --git a/frontend/src/api/gatewayClient.ts b/frontend/src/api/gatewayClient.ts index fe93d79..af4175c 100644 --- a/frontend/src/api/gatewayClient.ts +++ b/frontend/src/api/gatewayClient.ts @@ -5,7 +5,13 @@ async function request(path: string, options: RequestInit = {}): Promise { const response = await fetch(`${GATEWAY_BASE_URL}${path}`, options); if (!response.ok) { const body = await response.text(); - throw new Error(`${response.status} ${response.statusText}: ${body}`); + let message = body; + try { + message = (JSON.parse(body) as { message?: string }).message ?? body; + } catch { + // not JSON: keep the raw text + } + throw new Error(`${response.status}: ${message}`); } return response.json() as Promise; } @@ -26,8 +32,9 @@ function toForm(fields: Record): URLSearchParams { return form; } -function authHeaders(apiKey: string): HeadersInit { - return { Authorization: `Basic ${apiKey}` }; +// Pattern 10: the signed login token travels with every request; no server keeps a session. +function authHeaders(token: string): HeadersInit { + return { Authorization: `Bearer ${token}` }; } export interface Product { @@ -66,27 +73,27 @@ export const shopApi = { }), login: (username: string, password: string) => - request<{ api_key: string }>(`/api/shop/user/login`, { + request<{ token: string; expires_in: number }>(`/api/shop/user/login`, { method: "POST", body: toForm({ username, password }), }), - addToCart: (apiKey: string, productId: number, qty: number) => + addToCart: (token: string, productId: number, qty: number) => request<{ result: Order }>(`/api/shop/order/add-item`, { method: "POST", - headers: authHeaders(apiKey), + headers: authHeaders(token), body: toForm({ product_id: productId, qty }), }), - getCart: (apiKey: string) => + getCart: (token: string) => request<{ result?: Order; message?: string }>(`/api/shop/order`, { - headers: authHeaders(apiKey), + headers: authHeaders(token), }), - checkout: (apiKey: string) => + checkout: (token: string) => request<{ result: Order }>(`/api/shop/order/checkout`, { method: "POST", - headers: authHeaders(apiKey), + headers: authHeaders(token), }), }; @@ -155,17 +162,77 @@ export const patternsApi = { databases: () => request<{ services: ServiceDatabase[] }>("/api/patterns/databases"), isolationTest: (table: string) => request(`/api/patterns/isolation-test?table=${encodeURIComponent(table)}`), boundedContext: (productId: number) => requestWithIds(`/api/patterns/bounded-context/${productId}`), - orderSummary: (apiKey: string) => requestWithIds("/api/order-summary", { headers: authHeaders(apiKey) }), + orderSummary: (token: string) => requestWithIds("/api/order-summary", { headers: authHeaders(token) }), trace: (traceId: string) => request<{ trace_id: string; spans: Span[] }>(`/api/observability/trace/${traceId}`), metrics: () => request<{ services: ServiceMetrics[] }>("/api/observability/metrics"), }; /** The Shop page stores the signed-in user here; demos that need a login reuse it. */ -export function savedApiKey(): string | null { +export function savedToken(): string | null { try { const raw = localStorage.getItem("shop_auth"); - return raw ? (JSON.parse(raw) as { apiKey: string }).apiKey : null; + return raw ? ((JSON.parse(raw) as { token?: string }).token ?? null) : null; } catch { return null; } } + +// --- M2 demo endpoints (patterns 4, 10, 12) ------------------------------------------------------ + +export interface RegistryInstance { + instance_id: string; + url: string; + last_heartbeat_s: number | null; + up_for_s: number | null; +} + +export interface RegistryView { + mode: "registry" | "static" | "registry-unreachable"; + ttl_seconds: number | null; + services: Record; + events: { at: number; event: string; service: string; instance_id: string }[]; +} + +export interface BreakerState { + instance: string | null; + state: "closed" | "open" | "half-open" | "unreachable"; + failures_in_a_row?: number; + fail_max?: number; + reset_seconds?: number; + retry_in_seconds?: number | null; +} + +export interface BreakerCall { + outcome: "ok" | "failed" | "short-circuited" | string; + ms?: number; + total_ms?: number; + instance: string | null; + breaker?: BreakerState; +} + +/** GET with the token, returning the status and which replica answered (X-Instance-Id). */ +async function getWithInstance(path: string, token: string): Promise<{ status: number; instance: string | null; body: T }> { + const response = await fetch(`${GATEWAY_BASE_URL}${path}`, { headers: authHeaders(token) }); + return { status: response.status, instance: response.headers.get("X-Instance-Id"), body: (await response.json()) as T }; +} + +async function getAny(path: string, options: RequestInit = {}): Promise<{ status: number; body: T }> { + const response = await fetch(`${GATEWAY_BASE_URL}${path}`, options); + return { status: response.status, body: (await response.json()) as T }; +} + +export const resilienceApi = { + registry: () => request("/api/patterns/registry"), + stopReplica: (instanceId: string) => + getAny<{ stopping?: string; message?: string }>(`/api/patterns/replicas/${encodeURIComponent(instanceId)}/stop`, { method: "POST" }), + cartFromAnyReplica: (token: string) => getWithInstance<{ result?: Order; message?: string }>("/api/shop/order", token), + breakerCall: () => getAny("/api/patterns/breaker/call"), + breakerState: () => + request<{ breakers: BreakerState[]; payment: { mode: string; enabled?: boolean }; chaos_enabled: boolean }>("/api/patterns/breaker/state"), + setPaymentMode: (mode: string) => + getAny<{ mode?: string; message?: string }>("/api/patterns/breaker/payment-mode", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ mode }), + }), +}; diff --git a/frontend/src/pages/Home.tsx b/frontend/src/pages/Home.tsx index cc297ae..cbed26d 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. Database per Service, Bounded Context, API Gateway and Observability are live now.

+

The 12 patterns. 8 are live now, from Database per Service to Service Discovery; the last 4 arrive in M3.

diff --git a/frontend/src/pages/PatternPage.tsx b/frontend/src/pages/PatternPage.tsx index e5418c6..162bdd2 100644 --- a/frontend/src/pages/PatternPage.tsx +++ b/frontend/src/pages/PatternPage.tsx @@ -2,8 +2,12 @@ import { ReactNode } from "react"; 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 ContractTestingDemo from "../patterns/demos/ContractTestingDemo"; import DatabasePerServiceDemo from "../patterns/demos/DatabasePerServiceDemo"; import ObservabilityDemo from "../patterns/demos/ObservabilityDemo"; +import ServiceDiscoveryDemo from "../patterns/demos/ServiceDiscoveryDemo"; +import StatelessDemo from "../patterns/demos/StatelessDemo"; import { PATTERNS } from "../patterns/content"; const DEMOS: Record ReactNode> = { @@ -11,6 +15,10 @@ const DEMOS: Record ReactNode> = { "bounded-context": () => , "api-gateway": () => , observability: () => , + "circuit-breaker": () => , + "stateless-services": () => , + "contract-testing": () => , + "service-discovery": () => , }; export default function PatternPage() { diff --git a/frontend/src/pages/Patterns.tsx b/frontend/src/pages/Patterns.tsx index 3aa0ee3..fce17c7 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 milestones M2 and M3. + services. {liveCount} of 12 are live; the rest arrive in milestone M3.

diff --git a/frontend/src/pages/Shop.tsx b/frontend/src/pages/Shop.tsx index ef61ca9..1936082 100644 --- a/frontend/src/pages/Shop.tsx +++ b/frontend/src/pages/Shop.tsx @@ -3,14 +3,16 @@ import { Order, Product, shopApi } from "../api/gatewayClient"; interface Auth { username: string; - apiKey: string; + token: string; } const AUTH_KEY = "shop_auth"; function loadAuth(): Auth | null { const raw = localStorage.getItem(AUTH_KEY); - return raw ? (JSON.parse(raw) as Auth) : null; + const auth = raw ? (JSON.parse(raw) as Partial) : null; + // Sign-ins saved before M2 hold an old API key, not a token: treat them as signed out. + return auth?.token && auth.username ? (auth as Auth) : null; } function saveAuth(auth: Auth | null) { @@ -61,7 +63,7 @@ export default function Shop() { return; } shopApi - .getCart(currentAuth.apiKey) + .getCart(currentAuth.token) .then((data) => setCart(data.result ?? null)) .catch(() => setCart(null)); } @@ -85,8 +87,8 @@ export default function Shop() { if (authMode === "register") { await shopApi.register(username, email, password); } - const { api_key } = await shopApi.login(username, password); - const newAuth = { username, apiKey: api_key }; + const { token } = await shopApi.login(username, password); + const newAuth = { username, token }; setAuth(newAuth); saveAuth(newAuth); refreshCart(newAuth); @@ -107,7 +109,7 @@ export default function Shop() { if (!auth) return; setCartError(null); try { - const { result } = await shopApi.addToCart(auth.apiKey, productId, 1); + const { result } = await shopApi.addToCart(auth.token, productId, 1); setCart(result); } catch (err) { setCartError(String(err)); @@ -119,7 +121,7 @@ export default function Shop() { setCartError(null); setCheckoutMessage(null); try { - const { result } = await shopApi.checkout(auth.apiKey); + const { result } = await shopApi.checkout(auth.token); setCart(result); setCheckoutMessage("Order placed! Thank you."); } catch (err) { diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts index 85ccbc1..ee341a3 100644 --- a/frontend/src/patterns/content.ts +++ b/frontend/src/patterns/content.ts @@ -26,7 +26,7 @@ export const PATTERNS: PatternInfo[] = [ inThisProject: [ "Each of the 5 services has its own database: a SQLite file locally, a separate logical database on one MySQL server in Azure.", "A service reaches another service's data only through that service's API, never through SQL.", - "The order service validates users by calling the user service over HTTP, not by joining the user table.", + "The order service learns who you are from your signed token and prices orders by asking the catalog over HTTP, never by joining their tables.", ], whenNotToUse: [ "Small teams with one deployable: the cost of no joins and no cross-service transactions outweighs the benefit.", @@ -57,7 +57,29 @@ export const PATTERNS: PatternInfo[] = [ source: { label: "Martin Fowler — BoundedContext", url: "https://martinfowler.com/bliki/BoundedContext.html" }, }, { n: 3, slug: "ci-cd-pipeline", name: "CI-CD Pipeline", what: "Builds, tests and deploys every service automatically.", milestone: "M3", live: false }, - { n: 4, slug: "circuit-breaker", name: "Circuit Breaker", what: "Stops calls to a failing service to prevent more failures.", milestone: "M2", live: false }, + { + n: 4, + slug: "circuit-breaker", + name: "Circuit Breaker", + what: "Stops calls to a failing service to prevent more failures.", + milestone: "M2", + live: true, + problem: + "When payment hangs, every checkout waits for it. Threads pile up in the order service until it stops answering too, and one sick service takes down the ones that call it.", + inThisProject: [ + "Every order-to-payment call goes through one breaker (pybreaker). It opens after 3 failed calls in a row, fails calls at once for 15 s, then lets one trial call through.", + "Each call waits at most 1 s and is retried once after 0.2 s (tenacity), so a single blip does not count as a failure.", + "Only 5xx errors and timeouts count. A 400 is the caller's mistake, not a sick service.", + "Checkout while the breaker is open returns a clear 503: nothing was charged, the cart is kept, try again in N seconds.", + "Each order replica has its own breaker. They do not share state, which this page shows.", + ], + whenNotToUse: [ + "Not for calls that must not be skipped, such as writing an audit record. Queue those instead (event-driven, M3).", + "Retries without a breaker multiply load on a struggling service. Always cap retries and pair them with a breaker.", + "Per-replica breakers open at different times. For many replicas, a shared state store or a service mesh does this better.", + ], + source: { label: "Martin Fowler — CircuitBreaker", url: "https://martinfowler.com/bliki/CircuitBreaker.html" }, + }, { n: 5, slug: "api-gateway", @@ -104,9 +126,72 @@ export const PATTERNS: PatternInfo[] = [ { 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: 10, slug: "stateless-services", name: "Stateless Services", what: "Stores session data outside the service.", milestone: "M2", live: false }, - { n: 11, slug: "contract-testing", name: "Contract Testing", what: "Checks that APIs stay compatible across services.", milestone: "M2", live: false }, - { n: 12, slug: "service-discovery", name: "Service Discovery", what: "Finds service instances automatically at runtime.", milestone: "M2", live: false }, + { + n: 10, + slug: "stateless-services", + name: "Stateless Services", + what: "Stores session data outside the service.", + milestone: "M2", + live: true, + problem: + "If a service keeps your login or cart in its own memory, every request must go back to that one process. Restarting or adding a copy logs people out and empties carts.", + inThisProject: [ + "Login returns a token signed by the user service (RS256 JWT, 1 hour). Nothing is written to a database or a session.", + "The gateway and the order service check the signature with the user service's public key, fetched once. No call to the user service per request.", + "The cart lives in the order database, not in the order process.", + "make run starts 2 order replicas. Every response says which one answered (X-Instance-Id), and either can serve you.", + ], + whenNotToUse: [ + "A JWT cannot be cancelled before it expires. Keep lifetimes short, or keep a deny-list if you need instant logout.", + "Never put secrets or personal data in the token: anyone holding it can read the claims. Only the signature is protected.", + "Stateless does not mean no state. The state moved to a database, which now has to scale and stay available.", + ], + source: { label: "The Twelve-Factor App — VI. Processes", url: "https://12factor.net/processes" }, + }, + { + n: 11, + slug: "contract-testing", + name: "Contract Testing", + what: "Checks that APIs stay compatible across services.", + milestone: "M2", + live: true, + problem: + "Each service's own tests pass, yet a renamed field in payment breaks checkout in production. End-to-end tests would catch it, but they are slow and need every service running.", + inThisProject: [ + "The order service is the consumer. Its tests record what it sends to payment and catalog and which fields it reads back, as Pact contracts in contracts/pacts/.", + "Payment and catalog are the providers. Their test suites start the real service and replay every request in the contract.", + "Renaming amount_cents in payment fails the payment suite, so CI is red on that pull request.", + "No Pact broker: the contracts are committed next to the code. pact-python 4.2.", + ], + whenNotToUse: [ + "Not a replacement for testing business logic. A contract checks the shape of messages, not that prices are right.", + "Without a broker, consumer and provider must live in one repo. Across repos and teams, use a Pact broker and can-i-deploy.", + "For a public API with unknown consumers, use a versioned schema (OpenAPI) and compatibility checks instead.", + ], + source: { label: "Pact documentation — How Pact works", url: "https://docs.pact.io/getting_started/how_pact_works" }, + }, + { + n: 12, + slug: "service-discovery", + name: "Service Discovery", + what: "Finds service instances automatically at runtime.", + milestone: "M2", + live: true, + problem: + "With fixed addresses in config, adding a replica means editing every caller, and callers keep sending traffic to an instance that has crashed.", + inThisProject: [ + "A small registry (port 8500) holds every live instance. Each service re-registers every 2 s, a heartbeat.", + "An instance silent for more than 10 s is dropped, so a crashed replica disappears without anyone telling the registry.", + "The gateway and the order service keep a copy of the registry, refreshed every 2 s, and spread calls across the live instances.", + "If the registry is not running, callers fall back to fixed URLs. In Azure, Container Apps' built-in DNS and load balancing do this job instead.", + ], + whenNotToUse: [ + "On Kubernetes or Container Apps, use the platform's DNS-based discovery. Running your own registry duplicates it.", + "A registry is now a critical dependency. Callers must cache its answers and keep working when it is down, as these do.", + "Heartbeat timing is a trade-off: a short TTL drops crashed instances fast but may drop slow ones by mistake.", + ], + source: { label: "microservices.io — Client-side service discovery", url: "https://microservices.io/patterns/client-side-discovery.html" }, + }, ]; export const SERVICE_NAMES = ["gateway", "user", "catalog", "order", "payment", "inventory"] as const; diff --git a/frontend/src/patterns/demos/ApiGatewayDemo.tsx b/frontend/src/patterns/demos/ApiGatewayDemo.tsx index a203db2..3767e02 100644 --- a/frontend/src/patterns/demos/ApiGatewayDemo.tsx +++ b/frontend/src/patterns/demos/ApiGatewayDemo.tsx @@ -1,20 +1,20 @@ import { useState } from "react"; import { Link } from "react-router-dom"; -import { OrderSummary, ServiceCall, patternsApi, savedApiKey } from "../../api/gatewayClient"; +import { OrderSummary, ServiceCall, patternsApi, savedToken } from "../../api/gatewayClient"; export default function ApiGatewayDemo() { const [summary, setSummary] = useState(null); const [calls, setCalls] = useState([]); const [error, setError] = useState(null); const [busy, setBusy] = useState(false); - const apiKey = savedApiKey(); + const token = savedToken(); async function run() { - if (!apiKey) return; + if (!token) return; setBusy(true); setError(null); try { - const { body } = await patternsApi.orderSummary(apiKey); + const { body } = await patternsApi.orderSummary(token); setSummary(body); setCalls(body.calls); } catch (err) { @@ -27,7 +27,7 @@ export default function ApiGatewayDemo() { } } - if (!apiKey) { + if (!token) { return (

This demo builds your order summary, so it needs a signed-in user. Register or log in on the diff --git a/frontend/src/patterns/demos/CircuitBreakerDemo.tsx b/frontend/src/patterns/demos/CircuitBreakerDemo.tsx new file mode 100644 index 0000000..efcf1ef --- /dev/null +++ b/frontend/src/patterns/demos/CircuitBreakerDemo.tsx @@ -0,0 +1,170 @@ +import { useEffect, useState } from "react"; +import { BreakerCall, BreakerState, resilienceApi } from "../../api/gatewayClient"; + +const MODES: { mode: string; label: string; help: string }[] = [ + { mode: "healthy", label: "Healthy", help: "answers at once" }, + { mode: "failing", label: "Failing", help: "every call returns 500" }, + { mode: "slow", label: "Slow", help: "every call takes 3 s; order gives up after 1 s" }, +]; + +const PILL: Record = { closed: "done", open: "failed", "half-open": "running", unreachable: "pending" }; + +interface LogRow extends BreakerCall { + n: number; +} + +export default function CircuitBreakerDemo() { + const [breakers, setBreakers] = useState([]); + const [paymentMode, setPaymentMode] = useState(""); + const [chaos, setChaos] = useState(true); + const [log, setLog] = useState([]); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(null); + + function loadState() { + resilienceApi + .breakerState() + .then((s) => { + setBreakers(s.breakers); + setPaymentMode(s.payment.mode); + setChaos(s.chaos_enabled); + }) + .catch((err) => setError(String(err))); + } + + useEffect(() => { + loadState(); + const timer = setInterval(loadState, 1000); + return () => clearInterval(timer); + }, []); + + async function setMode(mode: string) { + const { status, body } = await resilienceApi.setPaymentMode(mode); + setError(status === 200 ? null : body.message ?? `HTTP ${status}`); + loadState(); + } + + async function send(count: number) { + setBusy(true); + let n = log.length ? log[0].n : 0; + for (let i = 0; i < count; i++) { + const { body } = await resilienceApi.breakerCall(); + n += 1; + const row = { ...body, n }; + setLog((prev) => [row, ...prev].slice(0, 30)); + } + setBusy(false); + loadState(); + } + + return ( +

+
+
+

Step 1. Choose how the payment service behaves

+ {!chaos &&

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

} +
+ {MODES.map((m) => ( + + ))} +
+

+ Payment is now {paymentMode || "unknown"}: {MODES.find((m) => m.mode === paymentMode)?.help ?? "–"}. +

+ {error &&

{error}

} +
+
+

Each order replica's breaker

+

+ Opens after 3 failed calls in a row. While open, calls fail at once without reaching payment. After 15 s, + one trial call decides whether it closes again. +

+ + + + + + + + + + + {breakers.map((b) => ( + + + + + + + ))} + +
ReplicaStateFailuresRetry in
+ + {b.instance} + + {b.state.toUpperCase()} + + {b.failures_in_a_row ?? "–"} / {b.fail_max ?? "–"} + {b.retry_in_seconds ? `${Math.ceil(b.retry_in_seconds)} s` : "–"}
+
+
+ +
+

Step 2. Send calls from order to payment

+

+ The gateway sends each call to the next order replica, which calls payment through its breaker. Compare the + time of a real failure with a call the open breaker stopped. +

+
+ + + +
+ {log.length > 0 && ( + + + + + + + + + + + + {log.map((r) => ( + + + + + + + + ))} + +
CallReplicaOutcomeTime in orderBreaker after
{r.n} + {r.instance ?? "–"} + + + {r.outcome} + + {r.ms !== undefined ? `${r.ms} ms` : "–"}{r.breaker?.state ?? "–"}
+ )} +
+
+ ); +} diff --git a/frontend/src/patterns/demos/ContractTestingDemo.tsx b/frontend/src/patterns/demos/ContractTestingDemo.tsx new file mode 100644 index 0000000..a0d256c --- /dev/null +++ b/frontend/src/patterns/demos/ContractTestingDemo.tsx @@ -0,0 +1,133 @@ +// The real contract files, written by the order service's tests and committed in contracts/pacts/. +import orderCatalog from "../../../../contracts/pacts/order-catalog.json"; +import orderPayment from "../../../../contracts/pacts/order-payment.json"; + +interface Body { + content?: unknown; +} + +interface Interaction { + description: string; + providerStates?: { name: string }[]; + request: { method: string; path: string; body?: Body }; + response: { status: number; body?: Body }; +} + +interface PactFile { + consumer: { name: string }; + provider: { name: string }; + interactions: Interaction[]; +} + +const CONTRACTS = [orderPayment, orderCatalog] as unknown as PactFile[]; + +const BREAK_OUTPUT = `$ make contracts (payment renamed "amount_cents" to "amount") + +Verifying a pact between order and payment + a charge for an order + returns a response which + has status code 200 (OK) + has a matching body (FAILED) + +Failures: + $.result -> Actual map is missing the following keys: amount_cents + +There were 1 pact failures +FAILED services/payment/tests/test_contract_provider.py`; + +export default function ContractTestingDemo() { + return ( +
+
+

The contracts in this repo

+

+ The order service's tests record exactly what it sends and what it reads back. Payment and catalog then + replay those requests against themselves in CI. These tables are read from the committed contract files. +

+ {CONTRACTS.map((c) => ( +
+

+ + {c.consumer.name} needs from + {c.provider.name} +

+
+ + + + + + + + + + {c.interactions.map((i) => ( + + + + + + ))} + +
InteractionRequestResponse the consumer relies on
+ {i.description} + {i.providerStates?.length ? ( +
+ given: {i.providerStates.map((s) => s.name).join(", ")} +
+ ) : null} +
+ + {i.request.method} {i.request.path} + + {i.request.body?.content !== undefined && ( +
+                            {JSON.stringify(i.request.body.content, null, 2)}
+                          
+ )} +
+ {i.response.status} +
+                          {JSON.stringify(i.response.body?.content, null, 2)}
+                        
+
+
+
+ ))} +

+ Values are examples. The contract checks types (any integer id, any integer price) and exact values only + where they matter, such as "status": "APPROVED". Fields the consumer does not read, like{" "} + created_at, are left out on purpose, so the provider can change them freely. +

+
+ +
+
+

When a provider breaks the contract

+

+ Real output from renaming one field in the payment service. The payment suite fails, so CI turns red on + that pull request, before checkout ever breaks. +

+
{BREAK_OUTPUT}
+
+
+

How CI runs it

+
    +
  1. + The order suite runs its client code against a Pact mock and rewrites the contract + files. CI fails if they differ from the committed ones. +
  2. +
  3. + The payment and catalog suites start the real service and replay + every interaction in its contract. +
  4. +
  5. No broker: the contracts live in the repo, next to the code, and change in the same pull request.
  6. +
+

+ Run it yourself: make contracts +

+
+
+
+ ); +} diff --git a/frontend/src/patterns/demos/ObservabilityDemo.tsx b/frontend/src/patterns/demos/ObservabilityDemo.tsx index cb7bb6a..a5f778d 100644 --- a/frontend/src/patterns/demos/ObservabilityDemo.tsx +++ b/frontend/src/patterns/demos/ObservabilityDemo.tsx @@ -1,5 +1,5 @@ import { useEffect, useState } from "react"; -import { ServiceMetrics, Span, patternsApi, savedApiKey } from "../../api/gatewayClient"; +import { ServiceMetrics, Span, patternsApi, savedToken } from "../../api/gatewayClient"; function Waterfall({ spans }: { spans: Span[] }) { if (spans.length === 0) return

No spans found for this trace yet.

; @@ -39,7 +39,7 @@ export default function ObservabilityDemo() { const [metrics, setMetrics] = useState([]); const [error, setError] = useState(null); const [busy, setBusy] = useState(false); - const apiKey = savedApiKey(); + const token = savedToken(); function loadMetrics() { patternsApi @@ -55,7 +55,7 @@ export default function ObservabilityDemo() { setError(null); try { // Signed in: the 4-service order summary. Otherwise: the 2-service bounded-context view. - const result = apiKey ? await patternsApi.orderSummary(apiKey) : await patternsApi.boundedContext(1); + const result = token ? await patternsApi.orderSummary(token) : await patternsApi.boundedContext(1); setTraceId(result.traceId); setRequestId(result.requestId); if (result.traceId) { @@ -75,7 +75,7 @@ export default function ObservabilityDemo() {

Traces: follow one click through every service

- {apiKey + {token ? "Sends GET /api/order-summary (gateway, user, order, catalog, inventory), then collects that trace's spans from every process." : "Sends GET /api/patterns/bounded-context/1 (gateway, catalog, inventory). Log in on the Shop page to trace the bigger 4-service order summary."}

diff --git a/frontend/src/patterns/demos/ServiceDiscoveryDemo.tsx b/frontend/src/patterns/demos/ServiceDiscoveryDemo.tsx new file mode 100644 index 0000000..ff349d5 --- /dev/null +++ b/frontend/src/patterns/demos/ServiceDiscoveryDemo.tsx @@ -0,0 +1,131 @@ +import { useEffect, useState } from "react"; +import { RegistryView, resilienceApi } from "../../api/gatewayClient"; + +export default function ServiceDiscoveryDemo() { + const [view, setView] = useState(null); + const [error, setError] = useState(null); + const [message, setMessage] = useState(null); + + function load() { + resilienceApi + .registry() + .then((v) => { + setView(v); + setError(null); + }) + .catch((err) => setError(String(err))); + } + + useEffect(() => { + load(); + const timer = setInterval(load, 2000); + return () => clearInterval(timer); + }, []); + + async function stop(instanceId: string) { + const { body } = await resilienceApi.stopReplica(instanceId); + setMessage( + body.stopping + ? `${body.stopping} stopped without telling the registry. Watch its heartbeat age climb until it expires.` + : body.message ?? null, + ); + } + + const live = view?.mode === "registry"; + + return ( +
+
+

The registry, refreshed every 2 seconds

+ {error &&

{error}

} + {view && !live && ( +

+ Mode: {view.mode}. The gateway is using its fixed URL list. Run the stack with make run to + start the registry. +

+ )} + {live && ( +

+ Each instance re-registers every 2 s. One that is silent for more than {view?.ttl_seconds} s is dropped, + and callers stop sending it traffic. +

+ )} +
+ + + + + + + + + + + {view && + Object.entries(view.services).flatMap(([service, instances]) => + instances.map((i) => { + const stale = i.last_heartbeat_s !== null && i.last_heartbeat_s > 3; + return ( + + + + + + + + ); + }), + )} + +
ServiceInstanceAddressLast heartbeat +
+ + {service} + + {i.instance_id} + + {i.url} + + {i.last_heartbeat_s === null ? "–" : `${i.last_heartbeat_s.toFixed(1)} s ago`} + + {live && ( + + )} +
+
+ {message &&

{message}

} +
+ + {live && ( +
+

What the registry saw

+

A stopped instance is marked expired by the registry itself. make run restarts it after 20 s, and it registers again.

+ + + + + + + + + + {view?.events.slice(0, 10).map((e, idx) => ( + + + + + + ))} + +
TimeEventInstance
{new Date(e.at * 1000).toLocaleTimeString()} + {e.event} + + {e.instance_id} +
+
+ )} +
+ ); +} diff --git a/frontend/src/patterns/demos/StatelessDemo.tsx b/frontend/src/patterns/demos/StatelessDemo.tsx new file mode 100644 index 0000000..7b59b67 --- /dev/null +++ b/frontend/src/patterns/demos/StatelessDemo.tsx @@ -0,0 +1,176 @@ +import { useEffect, useState } from "react"; +import { Link } from "react-router-dom"; +import { RegistryInstance, resilienceApi, savedToken } from "../../api/gatewayClient"; + +interface Row { + n: number; + instance: string | null; + status: number; + items: number | null; +} + +/** The middle part of a JWT is plain base64url JSON: anyone can read it, only the user service can sign it. */ +function readClaims(token: string): Record | null { + try { + const part = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"); + return JSON.parse(atob(part)) as Record; + } catch { + return null; + } +} + +export default function StatelessDemo() { + const token = savedToken(); + const [rows, setRows] = useState([]); + const [replicas, setReplicas] = useState([]); + const [mode, setMode] = useState(""); + const [message, setMessage] = useState(null); + const [busy, setBusy] = useState(false); + + function loadReplicas() { + resilienceApi + .registry() + .then((view) => { + setMode(view.mode); + setReplicas(view.services.order ?? []); + }) + .catch(() => setReplicas([])); + } + + useEffect(() => { + loadReplicas(); + const timer = setInterval(loadReplicas, 2000); + return () => clearInterval(timer); + }, []); + + if (!token) { + return ( +

+ This demo reads your cart, so it needs a signed-in user. Register or log in on the Shop + page, add something to your cart, then come back. +

+ ); + } + + async function askSixTimes() { + if (!token) return; + setBusy(true); + const next: Row[] = []; + for (let n = 1; n <= 6; n++) { + try { + const { status, instance, body } = await resilienceApi.cartFromAnyReplica(token); + next.push({ n, instance, status, items: status === 200 ? (body.result?.items.reduce((sum, i) => sum + i.quantity, 0) ?? 0) : null }); + } catch { + next.push({ n, instance: null, status: 0, items: null }); + } + setRows([...next]); + } + setBusy(false); + } + + async function stop(instanceId: string) { + const { body } = await resilienceApi.stopReplica(instanceId); + setMessage(body.stopping ? `${body.stopping} stopped. make run restarts it in about 20 seconds.` : body.message ?? null); + setTimeout(loadReplicas, 500); + } + + const claims = readClaims(token); + const served = new Set(rows.filter((r) => r.instance).map((r) => r.instance)); + const sameCart = rows.length > 0 && new Set(rows.map((r) => r.items)).size === 1 && rows.every((r) => r.status === 200); + + return ( +
+
+
+

Step 1. Your login is a signed token, not a server session

+

+ Your browser holds this. Every service can check the signature with the user service's public key, so no + server has to remember you. +

+
{JSON.stringify(claims, null, 2)}
+
+
+

Order replicas running now

+ {mode !== "registry" && ( +

No registry ({mode}): only one order replica is in use. Run the stack with make run.

+ )} + + + + + + + + + {replicas.map((r) => ( + + + + + + ))} + +
ReplicaUp for +
+ + {r.instance_id} + {r.up_for_s === null ? "–" : `${Math.round(r.up_for_s)} s`} + {mode === "registry" && ( + + )} +
+ {message &&

{message}

} +
+
+ +
+

Step 2. Ask for your cart 6 times

+

+ The gateway spreads the calls across the order replicas. Stop one replica above, then ask again: you stay + logged in and your cart is unchanged, because neither lived in the replica. +

+ + {rows.length > 0 && ( + <> + + + + + + + + + + + {rows.map((r) => ( + + + + + + + ))} + +
CallAnswered byStatusItems in cart
{r.n} + {r.instance ?? "no answer"} + {r.status || "failed"}{r.items ?? "–"}
+ {!busy && ( +

+ + {sameCart ? "Same cart every time" : "Not every call succeeded"} + {" "} + + {served.size} replica{served.size === 1 ? "" : "s"} answered. + +

+ )} + + )} +
+
+ ); +} diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index afa0e83..8244046 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -7,5 +7,7 @@ export default defineConfig({ server: { port: Number(process.env.FRONTEND_PORT) || 5273, host: true, + // The Contract Testing page imports the committed contracts from ../contracts/pacts. + fs: { allow: [".."] }, }, }); diff --git a/gateway/app/auth.py b/gateway/app/auth.py new file mode 100644 index 0000000..691b309 --- /dev/null +++ b/gateway/app/auth.py @@ -0,0 +1,6 @@ +"""The gateway's token check (pattern 10): verify once at the edge with the user service's public key.""" +from shop_common.auth import TokenVerifier + +from . import config + +TOKENS = TokenVerifier(lambda: config.url_for("user")) diff --git a/gateway/app/config.py b/gateway/app/config.py index cd7cdde..0f0516c 100644 --- a/gateway/app/config.py +++ b/gateway/app/config.py @@ -1,11 +1,12 @@ """Environment-driven settings for the API gateway. No secrets required.""" import os +from shop_common.discovery import DISCOVERY + RUN_MODE = os.environ.get("RUN_MODE", "local") -# Where each service lives. Locally these are fixed ports (scripts/service_table.py passes them -# in); in Azure, provision sets them to the Container Apps URLs. Pattern 12 (Service Discovery, -# milestone M2) replaces this static map with registry lookups. +# Where each service lives when there is no registry: fixed local ports, or the Container Apps URLs +# in Azure. With REGISTRY_URL set (make run), url_for() asks the registry instead (pattern 12). SERVICE_BASE_URLS: dict[str, str] = { "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"), @@ -14,6 +15,34 @@ "inventory": os.environ.get("INVENTORY_SERVICE_BASE_URL", "http://127.0.0.1:5105"), } + + +def url_for(service: str) -> str: + """A live instance of the service (round-robin across replicas), or its static URL.""" + return DISCOVERY.url_for(service, SERVICE_BASE_URLS[service]) + + +def candidates(service: str) -> list[str]: + """The round-robin pick first, then every other live instance, for failover.""" + first = url_for(service) + return [first] + [u for u in urls_for(service) if u != first] + + +def urls_for(service: str) -> list[str]: + """Every live instance of the service, e.g. both order replicas, for fan-out reads.""" + return [i["url"] for i in DISCOVERY.instances(service)] or [SERVICE_BASE_URLS[service]] + + +# Services whose every route needs a signed-in user. The gateway checks the token once, at the +# edge, before any call is made (pattern 10). The service still verifies it too. +LOGIN_REQUIRED_OWNERS = {"order"} + +# The demo pages can stop a replica (patterns 10, 12) and break payment (pattern 4) only when on. +CHAOS_ENABLED = os.environ.get("CHAOS_ENABLED") == "1" + +# The service registry (pattern 12). Unset in unit tests and in Azure (Container Apps DNS). +REGISTRY_URL = os.environ.get("REGISTRY_URL") or None + # First path segment of /api/shop/ -> owning service (its bounded context). ROUTE_OWNERS: dict[str, str] = { "user": "user", diff --git a/gateway/app/main.py b/gateway/app/main.py index d513364..e1ed06d 100644 --- a/gateway/app/main.py +++ b/gateway/app/main.py @@ -1,15 +1,17 @@ from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware +from shop_common.discovery import DISCOVERY + from . import config, observability -from .routers import patterns, services, shop +from .routers import patterns, resilience, services, shop app = FastAPI( title="Microservices 12 Patterns — API Gateway", description="Single entry point for the frontend (pattern 5). Routes /api/shop/* to the " "service that owns each path, aggregates /api/order-summary, and serves the " "live demo endpoints for the pattern pages.", - version="0.3.0", + version="0.4.0", ) observability.install(app) @@ -21,11 +23,15 @@ allow_methods=["*"], allow_headers=["*"], # Lets the frontend read these on cross-origin responses, to link a click to its trace. - expose_headers=["X-Request-Id", "X-Trace-Id"], + expose_headers=["X-Request-Id", "X-Trace-Id", "X-Instance-Id"], ) +# Keep a fresh copy of the registry (every 2 s) when REGISTRY_URL is set; a no-op otherwise. +DISCOVERY.start() + app.include_router(shop.router) app.include_router(patterns.router) +app.include_router(resilience.router) app.include_router(services.router) diff --git a/gateway/app/routers/patterns.py b/gateway/app/routers/patterns.py index a0a48f4..54ce0c4 100644 --- a/gateway/app/routers/patterns.py +++ b/gateway/app/routers/patterns.py @@ -18,11 +18,12 @@ router = APIRouter(tags=["patterns"]) -async def _call(client: httpx.AsyncClient, service: str, path: str, request: Request, calls: list[dict]) -> httpx.Response | None: +async def _call(client: httpx.AsyncClient, service: str, path: str, request: Request, calls: list[dict], + base: str | None = None) -> httpx.Response | None: """GET one service, recording service, path, status and duration for the demo panel.""" started = time.perf_counter() try: - response = await client.get(f"{config.SERVICE_BASE_URLS[service]}{path}", headers=upstream_headers(request)) + response = await client.get(f"{base or config.url_for(service)}{path}", headers=upstream_headers(request)) status = response.status_code except httpx.HTTPError as exc: response, status = None, f"unreachable ({exc.__class__.__name__})" @@ -132,9 +133,10 @@ async def trace_waterfall(trace_id: str, request: Request): """Stitches one trace's spans from the gateway and every service into a single list.""" calls: list[dict] = [] async with _client() as client: - names = list(config.SERVICE_BASE_URLS) + # Every instance, not just one: the trace may have passed through either order replica. + targets = [(n, url) for n in config.SERVICE_BASE_URLS for url in config.urls_for(n)] responses = await asyncio.gather( - *(_call(client, n, f"/debug/spans?trace_id={trace_id}", request, calls) for n in names) + *(_call(client, n, f"/debug/spans?trace_id={trace_id}", request, calls, base=url) for n, url in targets) ) spans = list(SPAN_STORE.by_trace(trace_id)) for response in responses: @@ -149,15 +151,19 @@ async def metrics_summary(request: Request): """Total requests and average latency per service, read from each service's /metrics.""" calls: list[dict] = [] async with _client() as client: - names = list(config.SERVICE_BASE_URLS) - responses = await asyncio.gather(*(_call(client, n, "/metrics", request, calls) for n in names)) + targets = [(n, url) for n in config.SERVICE_BASE_URLS for url in config.urls_for(n)] + responses = await asyncio.gather(*(_call(client, n, "/metrics", request, calls, base=url) for n, url in targets)) + by_service: dict[str, list[httpx.Response]] = {n: [] for n in config.SERVICE_BASE_URLS} + for (name, _url), response in zip(targets, responses): + if response is not None and response.status_code == 200: + by_service[name].append(response) summary = [] - for name, response in zip(names, responses): - if response is None or response.status_code != 200: + for name, ok_responses in by_service.items(): # replicas are summed into one row per service + if not ok_responses: summary.append({"service": name, "reachable": False}) continue requests_total, latency_sum, latency_count, errors = 0.0, 0.0, 0.0, 0.0 - for family in text_string_to_metric_families(response.text): + for family in (f for r in ok_responses for f in text_string_to_metric_families(r.text)): for sample in family.samples: if sample.name == "shop_http_requests_total": requests_total += sample.value @@ -170,6 +176,7 @@ async def metrics_summary(request: Request): summary.append({ "service": name, "reachable": True, + "instances": len(ok_responses), "requests": int(requests_total), "errors_5xx": int(errors), "avg_ms": round(latency_sum / latency_count * 1000, 1) if latency_count else None, diff --git a/gateway/app/routers/resilience.py b/gateway/app/routers/resilience.py new file mode 100644 index 0000000..488cca0 --- /dev/null +++ b/gateway/app/routers/resilience.py @@ -0,0 +1,122 @@ +"""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).""" +import asyncio +import time + +import httpx +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse +from pydantic import BaseModel + +from .. import config +from ..observability import upstream_headers + +router = APIRouter(prefix="/api/patterns", tags=["patterns"]) + +_CHAOS_OFF = {"message": "Demo switches are off. Set CHAOS_ENABLED=1 (make run does this)."} + + +def _client() -> httpx.AsyncClient: + return httpx.AsyncClient(timeout=config.UPSTREAM_TIMEOUT_SECONDS) + + +# --- Pattern 12: Service Discovery ------------------------------------------------------------- + +async def _registry_snapshot() -> dict | None: + base = config.REGISTRY_URL + if not base: + return None + try: + async with _client() as client: + response = await client.get(f"{base}/services") + return response.json() + except httpx.HTTPError: + return None + + +@router.get("/registry") +async def registry(): + """What the registry knows right now. Without a registry, the gateway's static URL map.""" + snapshot = await _registry_snapshot() + if snapshot is not None: + return {"mode": "registry", **snapshot} + services = {name: [{"instance_id": "static", "url": url, "last_heartbeat_s": None, "up_for_s": None}] + for name, url in config.SERVICE_BASE_URLS.items()} + return {"mode": "static" if not config.REGISTRY_URL else "registry-unreachable", + "ttl_seconds": None, "services": services, "events": []} + + +@router.post("/replicas/{instance_id}/stop") +async def stop_replica(instance_id: str): + """Stops one service process, as if it crashed. It does not say goodbye to the registry.""" + if not config.CHAOS_ENABLED: + return JSONResponse(_CHAOS_OFF, status_code=403) + snapshot = await _registry_snapshot() + instances = [i for group in (snapshot or {}).get("services", {}).values() for i in group] + target = next((i for i in instances if i["instance_id"] == instance_id), None) + if target is None: + return JSONResponse({"message": f"No live instance '{instance_id}' in the registry"}, status_code=404) + try: + async with _client() as client: + response = await client.post(f"{target['url']}/debug/crash") + except httpx.HTTPError as exc: + return JSONResponse({"message": f"Could not reach {instance_id}: {exc.__class__.__name__}"}, status_code=502) + return JSONResponse(response.json(), status_code=response.status_code) + + +# --- Pattern 4: Circuit Breaker ---------------------------------------------------------------- + +@router.get("/breaker/call") +async def breaker_call(request: Request): + """One call from an order replica to payment, through that replica's breaker.""" + started = time.perf_counter() + response = None + async with _client() as client: + for base in config.candidates("order"): # skip a stopped replica, as the shop proxy does + try: + response = await client.get(f"{base}/api/order/payment-check", headers=upstream_headers(request)) + break + except httpx.HTTPError: + continue + if response is None: + return JSONResponse({"outcome": "order unreachable", "instance": None}, status_code=503) + body = response.json() + body.update(instance=response.headers.get("x-instance-id"), + total_ms=round((time.perf_counter() - started) * 1000, 1)) + return JSONResponse(body, status_code=response.status_code) + + +@router.get("/breaker/state") +async def breaker_state(request: Request): + """Each order replica's breaker (they do not share state), plus payment's demo switch.""" + async def one(url: str) -> dict: + try: + response = await client.get(f"{url}/api/order/breaker", headers=upstream_headers(request)) + return {"instance": response.headers.get("x-instance-id"), **response.json()} + except httpx.HTTPError: + return {"instance": url, "state": "unreachable"} + + async with _client() as client: + breakers = await asyncio.gather(*(one(url) for url in config.urls_for("order"))) + try: + mode = (await client.get(f"{config.url_for('payment')}/api/payment/chaos")).json() + except httpx.HTTPError: + mode = {"mode": "unreachable"} + return {"breakers": sorted(breakers, key=lambda b: b["instance"] or ""), "payment": mode, + "chaos_enabled": config.CHAOS_ENABLED} + + +class PaymentMode(BaseModel): + mode: str + + +@router.post("/breaker/payment-mode") +async def set_payment_mode(body: PaymentMode): + if not config.CHAOS_ENABLED: + return JSONResponse(_CHAOS_OFF, status_code=403) + try: + async with _client() as client: + response = await client.post(f"{config.url_for('payment')}/api/payment/chaos", json={"mode": body.mode}) + 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) diff --git a/gateway/app/routers/shop.py b/gateway/app/routers/shop.py index 345bfcc..c7bdbda 100644 --- a/gateway/app/routers/shop.py +++ b/gateway/app/routers/shop.py @@ -3,6 +3,9 @@ The owner is picked from the first path segment (config.ROUTE_OWNERS), e.g. /api/shop/products -> catalog, /api/shop/order/checkout -> order. Only GET and POST are exposed; nothing in the shop needs PUT or DELETE from the browser. + +Paths owned by a login-required service are rejected with 401 here, at the edge, when the token is +missing or invalid, so the service is never called (pattern 10). """ import json @@ -10,6 +13,7 @@ from fastapi import APIRouter, Request, Response from .. import config +from ..auth import TOKENS from ..observability import upstream_headers router = APIRouter(prefix="/api/shop", tags=["shop"]) @@ -29,14 +33,29 @@ async def proxy(path: str, request: Request) -> Response: if owner is None: return _error(404, f"No service owns path '{path}'") - url = f"{config.SERVICE_BASE_URLS[owner]}/api/{path}" - try: - async with httpx.AsyncClient(timeout=config.UPSTREAM_TIMEOUT_SECONDS) as client: - upstream = await client.request( - request.method, url, headers=upstream_headers(request), - params=request.query_params, content=await request.body(), - ) - except httpx.HTTPError as exc: - return _error(503, f"'{owner}' service is unreachable: {exc.__class__.__name__}") + if owner in config.LOGIN_REQUIRED_OWNERS and TOKENS.verify(request.headers.get("authorization")) is None: + return _error(401, "Not logged in (checked at the gateway)") + + body = await request.body() + upstream = None + async with httpx.AsyncClient(timeout=config.UPSTREAM_TIMEOUT_SECONDS) as client: + # A replica that crashed stays in the registry until its heartbeat expires (about 10 s). + # A refused connection means the request never arrived, so the next replica can safely + # take it, even a POST (patterns 10 and 12). + for base in config.candidates(owner): + try: + upstream = await client.request( + request.method, f"{base}/api/{path}", headers=upstream_headers(request), + params=request.query_params, content=body, + ) + break + except httpx.ConnectError as exc: + error = exc + except httpx.HTTPError as exc: + error = exc + break + if upstream is None: + return _error(503, f"'{owner}' service is unreachable: {error.__class__.__name__}") + passthrough = {k: v for k, v in upstream.headers.items() if k.lower() == "x-instance-id"} return Response(content=upstream.content, status_code=upstream.status_code, - media_type=upstream.headers.get("content-type")) + media_type=upstream.headers.get("content-type"), headers=passthrough) diff --git a/gateway/tests/test_api.py b/gateway/tests/test_api.py index b0f9746..0ee81b3 100644 --- a/gateway/tests/test_api.py +++ b/gateway/tests/test_api.py @@ -63,3 +63,59 @@ def test_order_summary_requires_login(monkeypatch): r = client.get("/api/order-summary") assert r.status_code == 401 assert {c["service"] for c in r.json()["calls"]} == {"user", "order"} + + +def test_order_paths_need_a_valid_token_at_the_edge(monkeypatch): + from app import config + + called = [] + monkeypatch.setitem(config.SERVICE_BASE_URLS, "order", "http://127.0.0.1:9") + monkeypatch.setattr("app.routers.shop.httpx.AsyncClient.request", lambda *a, **k: called.append(1)) + r = client.get("/api/shop/order", headers={"Authorization": "Bearer not-a-real-token"}) + assert r.status_code == 401 + assert "gateway" in r.json()["message"] + assert called == [] # the order service was never called + + +def test_registry_view_falls_back_to_the_static_map(): + body = client.get("/api/patterns/registry").json() + assert body["mode"] == "static" + assert set(body["services"]) == {"user", "catalog", "order", "payment", "inventory"} + + +def test_chaos_switches_are_off_by_default(): + assert client.post("/api/patterns/replicas/order-5103/stop").status_code == 403 + assert client.post("/api/patterns/breaker/payment-mode", json={"mode": "failing"}).status_code == 403 + + +def test_url_for_round_robins_across_registered_replicas(monkeypatch): + from app import config + from shop_common.discovery import DISCOVERY + + monkeypatch.setattr(DISCOVERY, "_snapshot", {"order": [{"url": "http://a"}, {"url": "http://b"}]}) + assert {config.url_for("order") for _ in range(4)} == {"http://a", "http://b"} + assert config.urls_for("order") == ["http://a", "http://b"] + assert config.url_for("user") == config.SERVICE_BASE_URLS["user"] + + +def test_proxy_fails_over_when_a_replica_refuses_the_connection(monkeypatch): + import httpx + + from app import config + from shop_common.discovery import DISCOVERY + + monkeypatch.setattr(DISCOVERY, "_snapshot", {"catalog": [{"url": "http://dead"}, {"url": "http://alive"}]}) + tried = [] + + async def fake_request(self, method, url, **kwargs): + tried.append(url) + if url.startswith("http://dead"): + raise httpx.ConnectError("refused") + return httpx.Response(200, json={"results": []}, headers={"X-Instance-Id": "catalog-alive"}) + + monkeypatch.setattr(httpx.AsyncClient, "request", fake_request) + for _ in range(2): # whichever replica round-robin picks first, the call succeeds + r = client.get("/api/shop/products") + assert r.status_code == 200 + assert r.headers["X-Instance-Id"] == "catalog-alive" + assert "http://dead/api/products" in tried diff --git a/infra/bicep/main.bicep b/infra/bicep/main.bicep index 64737da..f5502be 100644 --- a/infra/bicep/main.bicep +++ b/infra/bicep/main.bicep @@ -133,8 +133,11 @@ module order 'modules/container-app.bicep' = { imageTag: imageTag targetPort: 5103 minReplicas: minReplicas + // In Azure, Container Apps DNS does service discovery (pattern 12): no REGISTRY_URL here. envVars: concat(commonEnv, [ { name: 'USER_SERVICE_BASE_URL', value: 'https://${user.outputs.fqdn}' } + { name: 'CATALOG_SERVICE_BASE_URL', value: 'https://${catalog.outputs.fqdn}' } + { name: 'PAYMENT_SERVICE_BASE_URL', value: 'https://${payment.outputs.fqdn}' } ]) } } diff --git a/registry/app/__init__.py b/registry/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/registry/app/main.py b/registry/app/main.py new file mode 100644 index 0000000..7ccfcd3 --- /dev/null +++ b/registry/app/main.py @@ -0,0 +1,83 @@ +"""Service registry (pattern 12): who is running, and where. + +Instances POST /register every couple of seconds (a heartbeat). An instance that misses +heartbeats for longer than TTL_SECONDS is dropped, so a crashed replica disappears by itself. +State is in memory on purpose: after a registry restart, every live instance re-registers +within one heartbeat. + +Locally only. In Azure, Container Apps' built-in DNS does this job (DISCOVERY=dns, see docs). +""" +import os +import threading +import time +from collections import deque + +from fastapi import FastAPI +from pydantic import BaseModel, Field + +TTL_SECONDS = float(os.environ.get("REGISTRY_TTL_SECONDS", "10")) + +app = FastAPI(title="Microservices 12 Patterns — Service Registry", version="0.1.0") + +_lock = threading.Lock() +_instances: dict[tuple[str, str], dict] = {} +_events: deque = deque(maxlen=50) + + +class Registration(BaseModel): + name: str = Field(min_length=1, max_length=40) + instance_id: str = Field(min_length=1, max_length=80) + url: str = Field(min_length=1, max_length=200) + + +def _event(kind: str, name: str, instance_id: str) -> None: + _events.appendleft({"at": time.time(), "event": kind, "service": name, "instance_id": instance_id}) + + +def _expire(now: float) -> None: + for key, inst in list(_instances.items()): + if now - inst["last_seen"] > TTL_SECONDS: + del _instances[key] + _event("expired", *key) + + +@app.get("/health") +def health(): + return {"status": "ok", "service": "registry"} + + +@app.post("/register") +def register(reg: Registration): + now = time.monotonic() + with _lock: + key = (reg.name, reg.instance_id) + if key not in _instances: + _instances[key] = {"registered_at": now} + _event("registered", *key) + _instances[key].update(url=reg.url, last_seen=now) + return {"registered": reg.instance_id, "ttl_seconds": TTL_SECONDS} + + +@app.delete("/register/{name}/{instance_id}") +def deregister(name: str, instance_id: str): + with _lock: + if _instances.pop((name, instance_id), None) is not None: + _event("deregistered", name, instance_id) + return {"deregistered": instance_id} + return {"deregistered": None} + + +@app.get("/services") +def services(): + now = time.monotonic() + with _lock: + _expire(now) + result: dict[str, list[dict]] = {} + for (name, instance_id), inst in sorted(_instances.items()): + result.setdefault(name, []).append({ + "instance_id": instance_id, + "url": inst["url"], + "last_heartbeat_s": round(now - inst["last_seen"], 1), + "up_for_s": round(now - inst["registered_at"], 1), + }) + return {"ttl_seconds": TTL_SECONDS, "services": result, "events": list(_events)} diff --git a/registry/requirements.txt b/registry/requirements.txt new file mode 100644 index 0000000..4f4d9eb --- /dev/null +++ b/registry/requirements.txt @@ -0,0 +1,3 @@ +fastapi==0.115.6 +uvicorn[standard]==0.32.1 +httpx==0.28.1 diff --git a/registry/tests/conftest.py b/registry/tests/conftest.py new file mode 100644 index 0000000..5801bea --- /dev/null +++ b/registry/tests/conftest.py @@ -0,0 +1,4 @@ +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) diff --git a/registry/tests/test_registry.py b/registry/tests/test_registry.py new file mode 100644 index 0000000..f69d597 --- /dev/null +++ b/registry/tests/test_registry.py @@ -0,0 +1,49 @@ +import time + +from fastapi.testclient import TestClient + +from app import main + +client = TestClient(main.app) + + +def _register(name="order", instance_id="order-5103", url="http://127.0.0.1:5103"): + return client.post("/register", json={"name": name, "instance_id": instance_id, "url": url}) + + +def setup_function(): + main._instances.clear() + main._events.clear() + + +def test_registered_instances_are_listed_by_service(): + _register() + _register(instance_id="order-5113", url="http://127.0.0.1:5113") + body = client.get("/services").json() + assert [i["instance_id"] for i in body["services"]["order"]] == ["order-5103", "order-5113"] + assert [e["event"] for e in body["events"]] == ["registered", "registered"] + + +def test_heartbeat_keeps_one_entry_per_instance(): + _register() + _register() + assert len(client.get("/services").json()["services"]["order"]) == 1 + + +def test_silent_instances_expire_after_the_ttl(monkeypatch): + _register() + later = time.monotonic() + main.TTL_SECONDS + 1 + monkeypatch.setattr(main.time, "monotonic", lambda: later) + body = client.get("/services").json() + assert body["services"] == {} + assert body["events"][0]["event"] == "expired" + + +def test_deregister_removes_the_instance(): + _register() + assert client.delete("/register/order/order-5103").json() == {"deregistered": "order-5103"} + assert client.get("/services").json()["services"] == {} + + +def test_bad_registration_is_rejected(): + assert client.post("/register", json={"name": "", "instance_id": "x", "url": "u"}).status_code == 422 diff --git a/scripts/run_local.py b/scripts/run_local.py index 2cada64..5b5c4a8 100644 --- a/scripts/run_local.py +++ b/scripts/run_local.py @@ -1,8 +1,12 @@ #!/usr/bin/env python3 """make run — launches the full local stack as plain Python/Node processes. -No Docker Desktop, no containers. Starts every Flask service, then the gateway, then the -frontend, each gated on its /health endpoint. The list comes from scripts/service_table.py. +No Docker Desktop, no containers. Starts the registry, every Flask service (order twice), then +the gateway, then the frontend, each gated on its /health endpoint. The list comes from +scripts/service_table.py. + +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 signal @@ -15,9 +19,14 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) from _procutil import ensure_port_free # noqa: E402 -from service_table import FLASK_SERVICES, FRONTEND_DIR, FRONTEND_PORT, GATEWAY, Service # noqa: E402 +from service_table import ( # noqa: E402 + FLASK_SERVICES, FRONTEND_DIR, FRONTEND_PORT, GATEWAY, REGISTRY, REPLICA_PORTS, Service, +) +RESTART_DELAY_SECONDS = 20 processes: list[subprocess.Popen] = [] +# pid -> how to start that process again (Flask services only) +restartable: dict[int, tuple[str, object]] = {} def _venv_python(service_dir: Path) -> str: @@ -39,20 +48,41 @@ def _wait_for_health(url: str, timeout: float = 20.0) -> bool: def _service_url_env() -> dict[str, str]: - """Every process gets every service's local URL (e.g. USER_SERVICE_BASE_URL).""" - return {f"{s.name.upper()}_SERVICE_BASE_URL": s.local_url for s in FLASK_SERVICES} + """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") + return env + +def start_registry() -> subprocess.Popen: + ensure_port_free(REGISTRY.local_port, REGISTRY.name) + proc = subprocess.Popen( + [_venv_python(REGISTRY.path), "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", + "--port", str(REGISTRY.local_port), "--log-level", "warning"], + cwd=str(REGISTRY.path), env={**os.environ}, + ) + processes.append(proc) + print(f" registry starting on :{REGISTRY.local_port} (pid {proc.pid})…") + return proc -def start_flask_service(svc: Service) -> subprocess.Popen: - ensure_port_free(svc.local_port, svc.name) + +def start_flask_service(svc: Service, port: int | None = None) -> subprocess.Popen: + port = port or svc.local_port + ensure_port_free(port, svc.name) + url = f"http://127.0.0.1:{port}" env = {**os.environ, **_service_url_env(), "RUN_MODE": "local", "FLASK_ENV": "development", - svc.port_env: str(svc.local_port)} + svc.port_env: str(port), "INSTANCE_ID": f"{svc.name}-{port}", "SERVICE_PUBLIC_URL": url} proc = subprocess.Popen([_venv_python(svc.path), "run.py"], cwd=str(svc.path), env=env) processes.append(proc) - print(f" {svc.name} starting on :{svc.local_port} (pid {proc.pid})…") + restartable[proc.pid] = (svc, port) + print(f" {svc.name}-{port} starting on :{port} (pid {proc.pid})…") return proc +def _flask_instances() -> list[tuple[Service, int]]: + return [(svc, port) for svc in FLASK_SERVICES for port in [svc.local_port, *REPLICA_PORTS.get(svc.name, [])]] + + def start_gateway() -> subprocess.Popen: ensure_port_free(GATEWAY.local_port, GATEWAY.name) env = {**os.environ, **_service_url_env(), "RUN_MODE": "local", @@ -95,11 +125,16 @@ def main() -> int: signal.signal(signal.SIGTERM, shutdown) print("=== Starting local stack (no Docker) ===") - for svc in FLASK_SERVICES: - start_flask_service(svc) - for svc in FLASK_SERVICES: - if not _wait_for_health(f"{svc.local_url}/health"): - print(f"{svc.name} failed to become healthy — aborting.") + start_registry() + if not _wait_for_health(f"{REGISTRY.local_url}/health"): + print("registry failed to become healthy — aborting.") + shutdown() + return 1 + for svc, port in _flask_instances(): + start_flask_service(svc, port) + for svc, port in _flask_instances(): + if not _wait_for_health(f"http://127.0.0.1:{port}/health"): + print(f"{svc.name}-{port} failed to become healthy — aborting.") shutdown() return 1 @@ -111,22 +146,37 @@ def main() -> int: start_frontend() - services = "\n".join(f" {s.name:<9} {s.local_url}" for s in FLASK_SERVICES) + services = "\n".join(f" {svc.name:<9} http://127.0.0.1:{port}" for svc, port in _flask_instances()) print(f""" Local stack is up: Frontend http://127.0.0.1:{FRONTEND_PORT} Gateway {GATEWAY.local_url} + Registry {REGISTRY.local_url} {services} Press Ctrl+C to stop everything. """) + pending: dict[int, float] = {} # pid of an exited service -> when to restart it try: while True: time.sleep(1) - for proc in processes: - if proc.poll() is not None: + for proc in list(processes): + if proc.poll() is None or proc.pid in pending: + continue + if proc.pid in restartable: + svc, port = restartable[proc.pid] + print(f"{svc.name}-{port} exited (code {proc.returncode}); restarting in {RESTART_DELAY_SECONDS} s.") + pending[proc.pid] = time.monotonic() + RESTART_DELAY_SECONDS + else: print(f"Process {proc.pid} exited unexpectedly (code {proc.returncode}).") + pending[proc.pid] = float("inf") + for pid, when in list(pending.items()): + if time.monotonic() >= when: + del pending[pid] + svc, port = restartable.pop(pid) + processes[:] = [p for p in processes if p.pid != pid] + start_flask_service(svc, port) except KeyboardInterrupt: shutdown() return 0 diff --git a/scripts/service_table.py b/scripts/service_table.py index 04fd11a..8c33890 100644 --- a/scripts/service_table.py +++ b/scripts/service_table.py @@ -36,8 +36,18 @@ def local_url(self) -> str: Service("inventory", REPO_ROOT / "services" / "inventory", 5105, "INVENTORY_SERVICE_PORT", "flask"), ] GATEWAY = Service("gateway", REPO_ROOT / "gateway", 8100, "GATEWAY_PORT", "fastapi") +REGISTRY = Service("registry", REPO_ROOT / "registry", 8500, "REGISTRY_PORT", "fastapi") -PYTHON_SERVICES = FLASK_SERVICES + [GATEWAY] +PYTHON_SERVICES = FLASK_SERVICES + [GATEWAY, REGISTRY] + +# 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 +# verify they still honour its contracts. +CONTRACT_SUITES = {"order", "payment", "catalog"} +CONTRACTS_DIR = REPO_ROOT / "contracts" # shop_common (shared/), installed into every Python venv by setup.py. SHARED_DIR = REPO_ROOT / "shared" diff --git a/scripts/setup.py b/scripts/setup.py index a65ff74..3283c1a 100644 --- a/scripts/setup.py +++ b/scripts/setup.py @@ -14,7 +14,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) from _procutil import ensure_port_free # noqa: E402 -from service_table import FRONTEND_DIR, FRONTEND_PORT, PYTHON_SERVICES, SHARED_DIR # noqa: E402 +from service_table import ( # noqa: E402 + CONTRACT_SUITES, CONTRACTS_DIR, FRONTEND_DIR, FRONTEND_PORT, PYTHON_SERVICES, REPLICA_PORTS, SHARED_DIR, +) MIN_PYTHON = (3, 12) @@ -55,7 +57,8 @@ def check_python_version(python_bin: str | None) -> bool: def check_ports_free() -> bool: all_ok = True - for name, port in [(s.name, s.local_port) for s in PYTHON_SERVICES] + [("frontend", FRONTEND_PORT)]: + replicas = [(f"{name}-{port}", port) for name, ports in REPLICA_PORTS.items() for port in ports] + for name, port in [(s.name, s.local_port) for s in PYTHON_SERVICES] + replicas + [("frontend", FRONTEND_PORT)]: try: ensure_port_free(port, name) print(f"[pre-smoke] Port {port} ({name}) ... OK") @@ -118,6 +121,8 @@ def main() -> int: # Shared observability helpers, editable so changes in shared/ apply without reinstalling. extra = "fastapi" if svc.kind == "fastapi" else "flask" subprocess.run([str(venv_python), "-m", "pip", "install", "-q", "-e", f"{SHARED_DIR}[{extra}]"], check=True) + if name in CONTRACT_SUITES: # Pact, for the contract tests (pattern 11). Test-only, not in images. + subprocess.run([str(venv_python), "-m", "pip", "install", "-q", "-r", str(CONTRACTS_DIR / "requirements.txt")], check=True) install_frontend() print("\nSetup complete. Run `make run` (or `python scripts/run_local.py`) next.") diff --git a/services/catalog/tests/test_contract_provider.py b/services/catalog/tests/test_contract_provider.py new file mode 100644 index 0000000..607ee94 --- /dev/null +++ b/services/catalog/tests/test_contract_provider.py @@ -0,0 +1,15 @@ +"""Provider side of pattern 11: catalog 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" + + +def test_catalog_honours_the_order_services_contract(app): + from application.seed import seed_products_if_empty + + # Seed here, on the test's own thread and database session. The state handler then has nothing + # left to do (doing database writes from Pact's callback thread deadlocks on SQLite). + seed_products_if_empty() + verify_provider(app, provider="catalog", consumer="order", states={"products exist": lambda: None}, pact_dir=PACT_DIR) diff --git a/services/order/application/__init__.py b/services/order/application/__init__.py index 7ec3ce2..e512bdb 100644 --- a/services/order/application/__init__.py +++ b/services/order/application/__init__.py @@ -1,9 +1,8 @@ """order-service — owns orders/order items and its own database. -This service has no access to the user table at all. -To validate a caller's identity it makes a real HTTP call to user-service -(see order_api/api/UserClient.py) — this is the Anti-Corruption-Layer-style -boundary between the Order and User bounded contexts (pattern 2). +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. """ import os diff --git a/services/order/application/order_api/api/UserClient.py b/services/order/application/order_api/api/UserClient.py deleted file mode 100644 index ac0757f..0000000 --- a/services/order/application/order_api/api/UserClient.py +++ /dev/null @@ -1,23 +0,0 @@ -"""Anti-Corruption-Layer-style client: order-service never touches the user -database directly — it always asks user-service over HTTP, exactly like a -production microservices boundary would.""" -import os - -import requests - -USER_SERVICE_BASE_URL = os.environ.get("USER_SERVICE_BASE_URL", "http://127.0.0.1:5101") - - -class UserClient: - @staticmethod - def get_user(api_key: str | None): - if not api_key: - return None - headers = {"Authorization": api_key} - try: - response = requests.get(f"{USER_SERVICE_BASE_URL}/api/user", headers=headers, timeout=5) - except requests.RequestException: - return None - if response.status_code != 200: - return None - return response.json() diff --git a/services/order/application/order_api/api/clients.py b/services/order/application/order_api/api/clients.py new file mode 100644 index 0000000..40e48ba --- /dev/null +++ b/services/order/application/order_api/api/clients.py @@ -0,0 +1,105 @@ +"""How the order service reaches other services. + +- Who is calling: verified locally from the signed token (pattern 10). No call to the user service + per request, only one call to fetch its public key. +- Where a service lives: asked from the registry (pattern 12), static URL as the fallback. +- Payment: every call goes through one circuit breaker (pattern 4). After FAIL_MAX failed calls in + a row it opens and calls fail instantly for RESET_SECONDS, then one trial call decides whether + it closes again. Each failed call is first retried once (tenacity), so a single blip does not + count as a failure. +""" +import os +from datetime import datetime, timezone + +import pybreaker +import requests +from shop_common.auth import TokenVerifier +from shop_common.discovery import DISCOVERY +from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed + +STATIC_URLS = { + "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"), +} + +PAYMENT_TIMEOUT_SECONDS = float(os.environ.get("PAYMENT_TIMEOUT_SECONDS", "1.0")) +FAIL_MAX = 3 +RESET_SECONDS = 15 + + +def base_url(service: str) -> str: + return DISCOVERY.url_for(service, STATIC_URLS[service]) + + +TOKENS = TokenVerifier(lambda: base_url("user")) + + +def current_user_id(authorization_header: str | None) -> int | None: + claims = TOKENS.verify(authorization_header) + return int(claims["sub"]) if claims else None + + +# --- Catalog ----------------------------------------------------------------------------------- + +def product_prices() -> dict[int, int]: + """product id -> price in cents, from the catalog (the context that owns prices).""" + response = requests.get(f"{base_url('catalog')}/api/products", timeout=3) + response.raise_for_status() + return {p["id"]: p["price"] for p in response.json()["results"]} + + +# --- Payment, behind the circuit breaker ---------------------------------------------------------- + +BREAKER = pybreaker.CircuitBreaker(fail_max=FAIL_MAX, reset_timeout=RESET_SECONDS, name="payment") + + +class PaymentUnavailable(Exception): + def __init__(self, reason: str): + super().__init__(reason) + self.reason = reason # "open" (failed fast, no call made) or "failed" (call made, it failed) + + +@retry(stop=stop_after_attempt(2), wait=wait_fixed(0.2), retry=retry_if_exception_type(requests.RequestException), reraise=True) +def _send(method: str, path: str, json: dict | None) -> requests.Response: + response = requests.request(method, f"{base_url('payment')}{path}", json=json, timeout=PAYMENT_TIMEOUT_SECONDS) + if response.status_code >= 500: # 4xx is the caller's mistake, not a sick service + raise requests.HTTPError(f"payment returned {response.status_code}", response=response) + return response + + +def call_payment(method: str, path: str, json: dict | None = None) -> requests.Response: + attempted = [] + + def attempt() -> requests.Response: + attempted.append(True) + return _send(method, path, json) + + try: + return BREAKER.call(attempt) + except pybreaker.CircuitBreakerError: + # pybreaker raises this when already open (no call made) and on the failure that trips it. + raise PaymentUnavailable("failed" if attempted else "open") + except requests.RequestException: + 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}) + response.raise_for_status() + return response.json()["result"] + + +def breaker_state() -> dict: + retry_in = None + opened_at = BREAKER._state_storage.opened_at # pybreaker keeps no public accessor for this + if BREAKER.current_state == "open" and opened_at: + elapsed = (datetime.now(timezone.utc) - opened_at).total_seconds() + retry_in = max(0, round(RESET_SECONDS - elapsed, 1)) + return { + "state": BREAKER.current_state, + "failures_in_a_row": BREAKER.fail_counter, + "fail_max": FAIL_MAX, + "reset_seconds": RESET_SECONDS, + "retry_in_seconds": retry_in, + } diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index 93129e3..bd4f33e 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -1,3 +1,6 @@ +import time + +import requests from flask import jsonify, make_response, request from . import order_api_blueprint @@ -5,7 +8,15 @@ from ..models import Order, OrderItem from ..schemas import OrderAddItemRequest from ..validation import validate_form -from .api.UserClient import UserClient +from .api import clients + + +def _not_logged_in(): + return make_response(jsonify({"message": "Not logged in"}), 401) + + +def _user_id() -> int | None: + return clients.current_user_id(request.headers.get("Authorization")) @order_api_blueprint.route("/api/orders", methods=["GET"]) @@ -15,18 +26,15 @@ def orders(): @order_api_blueprint.route("/api/order/add-item", methods=["POST"]) def order_add_item(): - api_key = request.headers.get("Authorization") - response = UserClient.get_user(api_key) - if not response: - return make_response(jsonify({"message": "Not logged in"}), 401) + u_id = _user_id() + if u_id is None: + return _not_logged_in() data, error = validate_form(OrderAddItemRequest, request.form) if error: return error - user = response["result"] - u_id = int(user["id"]) - + # The cart lives in the order database, not in this process (pattern 10): any replica sees it. known_order = Order.query.filter_by(user_id=u_id, is_open=True).first() if known_order is None: known_order = Order(user_id=u_id, is_open=True) @@ -45,13 +53,11 @@ def order_add_item(): @order_api_blueprint.route("/api/order", methods=["GET"]) def order(): - api_key = request.headers.get("Authorization") - response = UserClient.get_user(api_key) - if not response: - return make_response(jsonify({"message": "Not logged in"}), 401) + u_id = _user_id() + if u_id is None: + return _not_logged_in() - user = response["result"] - open_order = Order.query.filter_by(user_id=user["id"], is_open=True).first() + open_order = Order.query.filter_by(user_id=u_id, is_open=True).first() if open_order is None: return jsonify({"message": "No order found"}) return jsonify({"result": open_order.to_json()}) @@ -59,20 +65,56 @@ def order(): @order_api_blueprint.route("/api/order/checkout", methods=["POST"]) def checkout(): - api_key = request.headers.get("Authorization") - response = UserClient.get_user(api_key) - if not response: - return make_response(jsonify({"message": "Not logged in"}), 401) + u_id = _user_id() + if u_id is None: + return _not_logged_in() - user = response["result"] - order_model = Order.query.filter_by(user_id=user["id"], is_open=True).first() + order_model = Order.query.filter_by(user_id=u_id, is_open=True).first() 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) + + 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()}) + return jsonify({"result": order_model.to_json(), "payment": payment}) + + +# Pattern 4 demo: one cheap call to payment through the same breaker that protects checkout. +@order_api_blueprint.route("/api/order/payment-check", methods=["GET"]) +def payment_check(): + started = time.perf_counter() + try: + clients.call_payment("GET", "/api/payment/ping") + outcome, status = "ok", 200 + except clients.PaymentUnavailable as exc: + outcome, status = ("short-circuited" if exc.reason == "open" else "failed"), 503 + body = {"outcome": outcome, "ms": round((time.perf_counter() - started) * 1000, 1), "breaker": clients.breaker_state()} + return make_response(jsonify(body), status) + + +@order_api_blueprint.route("/api/order/breaker", methods=["GET"]) +def breaker(): + return jsonify(clients.breaker_state()) # Pattern 1 demo: each service only has its own tables. This tries to read another service's diff --git a/services/order/requirements.txt b/services/order/requirements.txt index d539586..55ce5bc 100644 --- a/services/order/requirements.txt +++ b/services/order/requirements.txt @@ -8,3 +8,5 @@ python-dotenv==1.0.1 gunicorn==23.0.0 pydantic==2.10.3 opentelemetry-instrumentation-flask==0.50b0 +pybreaker==1.4.1 +tenacity==9.2.1 diff --git a/services/order/tests/test_checkout_and_breaker.py b/services/order/tests/test_checkout_and_breaker.py new file mode 100644 index 0000000..e3ad073 --- /dev/null +++ b/services/order/tests/test_checkout_and_breaker.py @@ -0,0 +1,85 @@ +"""Checkout and the payment circuit breaker (pattern 4), with no other service running. + +The token check is replaced by a stub so these tests focus on the order service's own behaviour. +""" +import time + +import pytest +import requests + +from application.order_api.api import clients + +AUTH = {"Authorization": "Bearer test"} + + +@pytest.fixture(autouse=True) +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}) + clients.BREAKER.close() + yield + clients.BREAKER.close() + + +def _cart(client): + client.post("/api/order/add-item", data={"product_id": 1, "qty": 2}, headers=AUTH) + + +def test_requests_without_a_token_are_rejected(client): + assert client.get("/api/order").status_code == 401 + assert client.post("/api/order/checkout").status_code == 401 + + +def test_breaker_opens_after_three_failures_then_fails_fast(client): + outcomes = [client.get("/api/order/payment-check").get_json()["outcome"] for _ in range(3)] + assert outcomes == ["failed", "failed", "failed"] + assert clients.breaker_state()["state"] == "open" + + started = time.perf_counter() + body = client.get("/api/order/payment-check").get_json() + assert body["outcome"] == "short-circuited" + assert time.perf_counter() - started < 0.05 # no network call was made + assert 0 < body["breaker"]["retry_in_seconds"] <= clients.RESET_SECONDS + + +def test_checkout_keeps_the_cart_when_payment_is_down(client): + _cart(client) + r = client.post("/api/order/checkout", headers=AUTH) + assert r.status_code == 503 + assert "Your cart is kept" in r.get_json()["message"] + assert client.get("/api/order", headers=AUTH).get_json()["result"]["is_open"] is True + + +def test_checkout_charges_the_catalog_price_and_closes_the_order(client, monkeypatch): + charged = {} + + def fake_charge(order_id, amount_cents): + charged.update(order_id=order_id, amount_cents=amount_cents) + return {"id": 1, "order_id": order_id, "amount_cents": amount_cents, "status": "APPROVED"} + + monkeypatch.setattr(clients, "charge", fake_charge) + _cart(client) + r = client.post("/api/order/checkout", headers=AUTH) + assert r.status_code == 200 + assert charged["amount_cents"] == 2 * 1299 + assert r.get_json()["result"]["is_open"] is False + + +def test_client_errors_do_not_trip_the_breaker(monkeypatch): + class Resp: + status_code = 400 + + monkeypatch.setattr(clients.requests, "request", lambda *a, **k: Resp()) + for _ in range(5): + clients.call_payment("POST", "/api/payment/charge", {}) + assert clients.breaker_state()["state"] == "closed" + + +def test_catalog_down_means_no_charge(client, monkeypatch): + def down(): + raise requests.ConnectionError("catalog down") + + monkeypatch.setattr(clients, "product_prices", down) + _cart(client) + assert client.post("/api/order/checkout", headers=AUTH).status_code == 503 diff --git a/services/order/tests/test_contracts_consumer.py b/services/order/tests/test_contracts_consumer.py new file mode 100644 index 0000000..e8a9c13 --- /dev/null +++ b/services/order/tests/test_contracts_consumer.py @@ -0,0 +1,68 @@ +"""Consumer side of contract testing (pattern 11): what the order service needs from payment and +catalog, written down as Pact contracts in contracts/pacts/. + +Each test runs the order service's real client code against a Pact mock server. The mock only +answers requests that match the contract, and the test fails if the client sends anything else. +The payment and catalog suites then replay these contracts against the real services. +""" +from pathlib import Path + +import pytest +from pact import Pact, match + +from application.order_api.api import clients + +PACT_DIR = Path(__file__).resolve().parents[3] / "contracts" / "pacts" + + +@pytest.fixture(autouse=True) +def _closed_breaker(): + clients.BREAKER.close() + yield + clients.BREAKER.close() + + +def test_order_to_payment_contract(monkeypatch): + pact = Pact("order", "payment").with_specification("V4") + ( + pact.upon_receiving("a charge for an order") + .given("payment is healthy") + .with_request("POST", "/api/payment/charge") + .with_body({"order_id": match.int(42), "amount_cents": match.int(2598)}, "application/json") + .will_respond_with(200) + .with_body({"result": { + "id": match.int(1), + "order_id": match.int(42), + "amount_cents": match.int(2598), + "status": "APPROVED", + }}, "application/json") + ) + ( + pact.upon_receiving("a health check through the circuit breaker") + .given("payment is healthy") + .with_request("GET", "/api/payment/ping") + .will_respond_with(200) + .with_body({"status": "ok"}, "application/json") + ) + with pact.serve() as server: + monkeypatch.setitem(clients.STATIC_URLS, "payment", str(server.url).rstrip("/")) + payment = clients.charge(42, 2598) + assert payment["status"] == "APPROVED" + assert payment["amount_cents"] == 2598 + assert clients.call_payment("GET", "/api/payment/ping").json() == {"status": "ok"} + pact.write_file(PACT_DIR, overwrite=True) + + +def test_order_to_catalog_contract(monkeypatch): + pact = Pact("order", "catalog").with_specification("V4") + ( + pact.upon_receiving("a request for every product and its price") + .given("products exist") + .with_request("GET", "/api/products") + .will_respond_with(200) + .with_body({"results": match.each_like({"id": match.int(1), "price": match.int(1299)}, min=1)}, "application/json") + ) + with pact.serve() as server: + monkeypatch.setitem(clients.STATIC_URLS, "catalog", str(server.url).rstrip("/")) + assert clients.product_prices() == {1: 1299} + pact.write_file(PACT_DIR, overwrite=True) diff --git a/services/payment/application/routes.py b/services/payment/application/routes.py index 30b7b15..ce6b9b0 100644 --- a/services/payment/application/routes.py +++ b/services/payment/application/routes.py @@ -1,29 +1,67 @@ +import time + 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 Payment payment_api = Blueprint("payment_api", __name__) +# Pattern 4 demo switch: "healthy", "failing" (every call returns 500) or "slow" (every call takes +# SLOW_SECONDS, longer than the order service waits). Held in memory: it is a lab switch, not data. +MODES = ("healthy", "failing", "slow") +SLOW_SECONDS = 3 +_mode = {"value": "healthy"} + class ChargeRequest(BaseModel): order_id: int = Field(gt=0) amount_cents: int = Field(gt=0) +@payment_api.before_request +def _apply_chaos(): + if request.endpoint == "payment_api.chaos": + return None + if _mode["value"] == "failing": + return make_response(jsonify({"message": "Payment is failing (demo switch)"}), 500) + if _mode["value"] == "slow": + time.sleep(SLOW_SECONDS) + return None + + @payment_api.get("/api/payments") def list_payments(): return jsonify({"results": [p.to_json() for p in Payment.query.order_by(Payment.id.desc()).limit(50)]}) +@payment_api.get("/api/payment/ping") +def ping(): + return jsonify({"status": "ok"}) + + @payment_api.post("/api/payment/charge") def charge(): + raw = request.get_json(silent=True) or request.form.to_dict() try: - data = ChargeRequest.model_validate(request.form.to_dict()) + 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") db.session.add(payment) db.session.commit() return jsonify({"result": payment.to_json()}) + + +@payment_api.route("/api/payment/chaos", methods=["GET", "POST"]) +def chaos(): + if request.method == "POST": + if not chaos_enabled(): + return make_response(jsonify({"message": "Chaos switches are off (CHAOS_ENABLED is not 1)"}), 403) + mode = (request.get_json(silent=True) or request.form.to_dict()).get("mode") + if mode not in MODES: + return make_response(jsonify({"message": f"mode must be one of {list(MODES)}"}), 400) + _mode["value"] = mode + return jsonify({"mode": _mode["value"], "modes": list(MODES), "enabled": chaos_enabled()}) diff --git a/services/payment/tests/test_contract_provider.py b/services/payment/tests/test_contract_provider.py new file mode 100644 index 0000000..bbf9692 --- /dev/null +++ b/services/payment/tests/test_contract_provider.py @@ -0,0 +1,19 @@ +"""Provider side of pattern 11: payment replays the order service's contract against itself. + +If payment renames or drops a field the order service relies on (for example amount_cents), +this test fails, so CI turns red before the change can break checkout. +""" +from pathlib import Path + +from shop_common.contract_testing import verify_provider + +PACT_DIR = Path(__file__).resolve().parents[3] / "contracts" / "pacts" + + +def test_payment_honours_the_order_services_contract(app): + from application import routes + + def healthy() -> None: + routes._mode["value"] = "healthy" + + verify_provider(app, provider="payment", consumer="order", states={"payment is healthy": healthy}, pact_dir=PACT_DIR) diff --git a/services/payment/tests/test_payment.py b/services/payment/tests/test_payment.py index 479def0..225526b 100644 --- a/services/payment/tests/test_payment.py +++ b/services/payment/tests/test_payment.py @@ -14,3 +14,21 @@ def test_health_db_reports_only_own_tables(client): body = client.get("/health/db").get_json() assert body["service"] == "payment" assert body["tables"] == ["payment"] + + +def test_charge_accepts_json(client): + r = client.post("/api/payment/charge", json={"order_id": 3, "amount_cents": 500}) + assert r.get_json()["result"]["amount_cents"] == 500 + + +def test_failing_mode_returns_500_until_healed(client, monkeypatch): + monkeypatch.setenv("CHAOS_ENABLED", "1") + assert client.post("/api/payment/chaos", json={"mode": "failing"}).get_json()["mode"] == "failing" + assert client.get("/api/payment/ping").status_code == 500 + client.post("/api/payment/chaos", json={"mode": "healthy"}) + assert client.get("/api/payment/ping").status_code == 200 + + +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 diff --git a/services/user/application/__init__.py b/services/user/application/__init__.py index 6dd3490..fbce2b5 100644 --- a/services/user/application/__init__.py +++ b/services/user/application/__init__.py @@ -6,13 +6,11 @@ from flask import Flask from shop_common.flask_support import install as install_observability -from flask_login import LoginManager from flask_sqlalchemy import SQLAlchemy from flask_migrate import Migrate db = SQLAlchemy() migrate = Migrate() -login_manager = LoginManager() def create_app(config_name: str | None = None) -> Flask: @@ -24,7 +22,6 @@ def create_app(config_name: str | None = None) -> Flask: db.init_app(app) migrate.init_app(app, db) - login_manager.init_app(app) with app.app_context(): from . import models # noqa: F401 diff --git a/services/user/application/models.py b/services/user/application/models.py index 41d926a..20634b9 100644 --- a/services/user/application/models.py +++ b/services/user/application/models.py @@ -1,6 +1,5 @@ from datetime import datetime, timezone -from flask_login import UserMixin from passlib.hash import sha256_crypt from . import db @@ -10,7 +9,7 @@ def _utcnow(): return datetime.now(timezone.utc) -class User(UserMixin, db.Model): +class User(db.Model): id = db.Column(db.Integer, primary_key=True) username = db.Column(db.String(255), unique=True, nullable=False) email = db.Column(db.String(255), unique=True, nullable=False) @@ -18,13 +17,9 @@ class User(UserMixin, db.Model): last_name = db.Column(db.String(255), nullable=True) password = db.Column(db.String(255), nullable=False) is_admin = db.Column(db.Boolean, default=False) - api_key = db.Column(db.String(255), unique=True, nullable=True) date_added = db.Column(db.DateTime, default=_utcnow) date_updated = db.Column(db.DateTime, onupdate=_utcnow) - def encode_api_key(self): - self.api_key = sha256_crypt.hash(self.username + str(_utcnow())) - def encode_password(self): self.password = sha256_crypt.hash(self.password) diff --git a/services/user/application/tokens.py b/services/user/application/tokens.py new file mode 100644 index 0000000..8cadb96 --- /dev/null +++ b/services/user/application/tokens.py @@ -0,0 +1,56 @@ +"""Signs login tokens (pattern 10). Only the user service holds the private key. + +Key source, in order: JWT_PRIVATE_KEY_PEM (Azure secret), else instance/jwt_private.pem, created +on first start. Keeping the key in a file means restarting the service does not log anyone out. +""" +import os +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import jwt +from cryptography.hazmat.primitives import serialization +from cryptography.hazmat.primitives.asymmetric import rsa +from shop_common.auth import ALGORITHM, ISSUER + +TOKEN_LIFETIME = timedelta(hours=1) +KEY_FILE = Path(__file__).resolve().parents[1] / os.environ.get("JWT_KEY_FILE", "instance/jwt_private.pem") + +_private_pem: bytes | None = None + + +def _private_key_pem() -> bytes: + global _private_pem + if _private_pem is None: + if os.environ.get("JWT_PRIVATE_KEY_PEM"): + _private_pem = os.environ["JWT_PRIVATE_KEY_PEM"].encode() + elif KEY_FILE.exists(): + _private_pem = KEY_FILE.read_bytes() + else: + key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + _private_pem = key.private_bytes( + serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption() + ) + KEY_FILE.parent.mkdir(parents=True, exist_ok=True) + KEY_FILE.write_bytes(_private_pem) + KEY_FILE.chmod(0o600) + return _private_pem + + +def public_key_pem() -> str: + key = serialization.load_pem_private_key(_private_key_pem(), password=None) + return key.public_key().public_bytes( + serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo + ).decode() + + +def issue(user) -> str: + now = datetime.now(timezone.utc) + claims = {"sub": str(user.id), "username": user.username, "iss": ISSUER, "iat": now, "exp": now + TOKEN_LIFETIME} + return jwt.encode(claims, _private_key_pem(), algorithm=ALGORITHM) + + +def decode(token: str) -> dict | None: + try: + return jwt.decode(token, public_key_pem(), algorithms=[ALGORITHM], issuer=ISSUER) + except jwt.InvalidTokenError: + return None diff --git a/services/user/application/user_api/routes.py b/services/user/application/user_api/routes.py index 378247c..5ff9c07 100644 --- a/services/user/application/user_api/routes.py +++ b/services/user/application/user_api/routes.py @@ -1,25 +1,19 @@ from flask import jsonify, make_response, request -from flask_login import current_user, login_required, login_user, logout_user +from shop_common.auth import bearer_token from sqlalchemy.exc import IntegrityError from . import user_api_blueprint -from .. import db, login_manager +from .. import db, tokens from ..models import User from ..schemas import RegisterRequest, LoginRequest from ..validation import validate_form -@login_manager.user_loader -def load_user(user_id): - return User.query.get(int(user_id)) - - -@login_manager.request_loader -def load_user_from_request(req): - api_key = req.headers.get("Authorization", "").replace("Basic ", "", 1) - if api_key: - return User.query.filter_by(api_key=api_key).first() - return None +def _user_from_token() -> User | None: + """Stateless (pattern 10): who you are comes from the signed token, not a server session.""" + token = bearer_token(request.headers.get("Authorization")) + claims = tokens.decode(token) if token else None + return db.session.get(User, int(claims["sub"])) if claims else None @user_api_blueprint.route("/api/users", methods=["GET"]) @@ -60,19 +54,21 @@ def post_login(): user = User.query.filter_by(username=data.username).first() if user and user.verify_password(data.password): - user.encode_api_key() - db.session.commit() - login_user(user) - return make_response(jsonify({"message": "Logged in", "api_key": user.api_key})) + # Nothing is written to the database or a session: the token itself is the proof. + return jsonify({"message": "Logged in", "token": tokens.issue(user), "expires_in": int(tokens.TOKEN_LIFETIME.total_seconds())}) return make_response(jsonify({"message": "Not logged in"}), 401) @user_api_blueprint.route("/api/user/logout", methods=["POST"]) def post_logout(): - if current_user.is_authenticated: - logout_user() - return make_response(jsonify({"message": "You are logged out"})) - return make_response(jsonify({"message": "You are not logged in"})) + # No server-side session to end. The browser deletes its token; it also expires within an hour. + return jsonify({"message": "Logged out. Tokens are not stored on the server, so the browser just forgets it."}) + + +@user_api_blueprint.route("/api/user/public-key", methods=["GET"]) +def get_public_key(): + """Other services verify tokens with this key. It is public: it can check, not sign.""" + return jsonify({"algorithm": "RS256", "public_key_pem": tokens.public_key_pem()}) @user_api_blueprint.route("/api/user//exists", methods=["GET"]) @@ -83,6 +79,8 @@ def get_username(username): @user_api_blueprint.route("/api/user", methods=["GET"]) -@login_required def get_user(): - return make_response(jsonify({"result": current_user.to_json()})) + user = _user_from_token() + if user is None: + return make_response(jsonify({"message": "Not logged in"}), 401) + return jsonify({"result": user.to_json()}) diff --git a/services/user/requirements.txt b/services/user/requirements.txt index f5acaa3..13fefb9 100644 --- a/services/user/requirements.txt +++ b/services/user/requirements.txt @@ -1,7 +1,6 @@ Flask==3.1.0 Flask-SQLAlchemy==3.1.1 Flask-Migrate==4.0.7 -Flask-Login==0.6.3 SQLAlchemy==2.0.36 PyMySQL==1.1.1 passlib==1.7.4 diff --git a/services/user/tests/test_tokens.py b/services/user/tests/test_tokens.py new file mode 100644 index 0000000..a458b21 --- /dev/null +++ b/services/user/tests/test_tokens.py @@ -0,0 +1,36 @@ +"""Pattern 10: login returns a signed token, and the token alone says who is calling.""" + + +def _register_and_login(client, username="bob"): + client.post("/api/user/create", data={"username": username, "email": f"{username}@example.com", "password": "secret123"}) + return client.post("/api/user/login", data={"username": username, "password": "secret123"}).get_json() + + +def test_login_returns_a_signed_token_and_stores_nothing(client): + body = _register_and_login(client) + assert body["token"].count(".") == 2 # header.claims.signature + assert body["expires_in"] == 3600 + + +def test_token_identifies_the_user_without_a_session(client): + token = _register_and_login(client)["token"] + # A fresh client has no cookies: only the token says who this is. + fresh = client.application.test_client() + r = fresh.get("/api/user", headers={"Authorization": f"Bearer {token}"}) + assert r.status_code == 200 + assert r.get_json()["result"]["username"] == "bob" + assert "Set-Cookie" not in r.headers + + +def test_tampered_or_missing_token_is_rejected(client): + token = _register_and_login(client)["token"] + assert client.get("/api/user").status_code == 401 + assert client.get("/api/user", headers={"Authorization": f"Bearer {token[:-4]}AAAA"}).status_code == 401 + + +def test_public_key_verifies_the_token(client): + import jwt + + token = _register_and_login(client)["token"] + key = client.get("/api/user/public-key").get_json()["public_key_pem"] + assert jwt.decode(token, key, algorithms=["RS256"], issuer="ms12p-user")["username"] == "bob" diff --git a/shared/pyproject.toml b/shared/pyproject.toml index 7e13185..4a14287 100644 --- a/shared/pyproject.toml +++ b/shared/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "shop-common" version = "0.1.0" -description = "Shared observability helpers for every service and the gateway (pattern 6)." +description = "Shared plumbing for every service and the gateway: observability (6), tokens (10), discovery (12)." requires-python = ">=3.12" dependencies = [ "opentelemetry-sdk==1.29.0", @@ -14,6 +14,7 @@ dependencies = [ "opentelemetry-instrumentation-httpx==0.50b0", "opentelemetry-instrumentation-sqlalchemy==0.50b0", "prometheus-client==0.21.1", + "PyJWT[crypto]==2.15.1", ] [project.optional-dependencies] diff --git a/shared/shop_common/auth.py b/shared/shop_common/auth.py new file mode 100644 index 0000000..b007ddb --- /dev/null +++ b/shared/shop_common/auth.py @@ -0,0 +1,66 @@ +"""Stateless login tokens (pattern 10). + +The user service signs a short-lived JWT with its private key (RS256). Every other process +verifies it with the public key, which it fetches once from the user service. No process keeps a +session, so any replica can serve any request and a restart logs nobody out. +""" +import json +import threading +import urllib.request +from typing import Callable + +import jwt + +ALGORITHM = "RS256" +ISSUER = "ms12p-user" +PUBLIC_KEY_PATH = "/api/user/public-key" + + +def bearer_token(header: str | None) -> str | None: + """Accepts 'Bearer ' (or a bare token) from an Authorization header.""" + if not header: + return None + token = header.split(" ", 1)[1] if " " in header else header + return token.strip() or None + + +class TokenVerifier: + """Verifies tokens against the user service's public key, fetched lazily and cached. + + user_base_url is a callable so the key is fetched from wherever discovery says the user + service lives right now. + """ + + def __init__(self, user_base_url: Callable[[], str], timeout: float = 3.0): + self._user_base_url = user_base_url + self._timeout = timeout + self._key: str | None = None + self._lock = threading.Lock() + + def _public_key(self, refresh: bool = False) -> str | None: + with self._lock: + if self._key is None or refresh: + try: + url = f"{self._user_base_url()}{PUBLIC_KEY_PATH}" + with urllib.request.urlopen(url, timeout=self._timeout) as resp: + self._key = json.load(resp)["public_key_pem"] + except (OSError, ValueError, KeyError): + return self._key # keep a previously fetched key if the user service is down + return self._key + + def verify(self, authorization_header: str | None) -> dict | None: + """Returns the token's claims, or None if it is missing, expired or not signed by us.""" + token = bearer_token(authorization_header) + if not token: + return None + for refresh in (False, True): # retry once with a fresh key, in case the user service rotated it + key = self._public_key(refresh=refresh) + if key is None: + return None + try: + return jwt.decode(token, key, algorithms=[ALGORITHM], issuer=ISSUER) + except jwt.InvalidSignatureError: + continue + except jwt.InvalidTokenError: + return None + return None diff --git a/shared/shop_common/contract_testing.py b/shared/shop_common/contract_testing.py new file mode 100644 index 0000000..38dabf2 --- /dev/null +++ b/shared/shop_common/contract_testing.py @@ -0,0 +1,33 @@ +"""Provider side of contract testing (pattern 11): replays a consumer's Pact contract against a +real, running copy of this service. Used by the payment and catalog test suites.""" +import threading +from pathlib import Path +from typing import Callable + + +def verify_provider(app, provider: str, consumer: str, states: dict[str, Callable[[], None]], pact_dir: Path) -> None: + """Starts the Flask app on a free port and verifies every interaction in -.json. + + Raises if any interaction fails. states maps each provider state named in the contract to a + function that puts the service into that state. + """ + from pact import Verifier + from werkzeug.serving import make_server + + def handler(state: str, action: str = "setup", parameters: dict | None = None) -> None: + if action == "setup" and state in states: + states[state]() + + server = make_server("127.0.0.1", 0, app, threaded=True) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + ( + Verifier(provider, host="127.0.0.1") + .add_transport(url=f"http://127.0.0.1:{server.server_port}") + .add_source(pact_dir / f"{consumer}-{provider}.json") + .state_handler(handler, teardown=False) + .verify() + ) + finally: + server.shutdown() diff --git a/shared/shop_common/discovery.py b/shared/shop_common/discovery.py new file mode 100644 index 0000000..80a5962 --- /dev/null +++ b/shared/shop_common/discovery.py @@ -0,0 +1,91 @@ +"""Service discovery client (pattern 12). + +With REGISTRY_URL set, a process can: + - register itself: it re-announces its name, instance id and URL every HEARTBEAT_SECONDS, and + the registry forgets it once heartbeats stop for longer than the registry's TTL; + - look others up: it keeps a snapshot of the registry, refreshed every HEARTBEAT_SECONDS, and + url_for() round-robins across the live instances of a service. + +Without REGISTRY_URL (unit tests, Azure where Container Apps DNS does the job), url_for() returns +the static fallback URL, so callers need no special case. + +Uses urllib on purpose: these background calls are not instrumented, so they do not flood the +trace store with a span every 2 seconds. +""" +import itertools +import json +import os +import threading +import time +import urllib.request + +HEARTBEAT_SECONDS = 2.0 + + +def _registry_url() -> str | None: + return os.environ.get("REGISTRY_URL") or None + + +class Discovery: + def __init__(self) -> None: + self._snapshot: dict[str, list[dict]] = {} + self._registration: dict | None = None + self._counters: dict[str, itertools.count] = {} + self._lock = threading.Lock() + self._thread: threading.Thread | None = None + + @property + def enabled(self) -> bool: + return _registry_url() is not None + + def register(self, name: str, instance_id: str, url: str) -> None: + self._registration = {"name": name, "instance_id": instance_id, "url": url} + self.start() + + def start(self) -> None: + if not self.enabled or self._thread is not None: + return + self._thread = threading.Thread(target=self._loop, name="discovery", daemon=True) + self._thread.start() + + def _loop(self) -> None: + while True: + self.tick() + time.sleep(HEARTBEAT_SECONDS) + + def tick(self) -> None: + """One heartbeat plus one snapshot refresh. Failures are ignored; the next tick retries.""" + base = _registry_url() + if base is None: + return + if self._registration: + try: + req = urllib.request.Request( + f"{base}/register", data=json.dumps(self._registration).encode(), + headers={"Content-Type": "application/json"}, method="POST", + ) + urllib.request.urlopen(req, timeout=2).close() + except OSError: + pass + try: + with urllib.request.urlopen(f"{base}/services", timeout=2) as resp: + services = json.load(resp)["services"] + with self._lock: + self._snapshot = services + except (OSError, ValueError, KeyError): + pass + + def instances(self, name: str) -> list[dict]: + with self._lock: + return list(self._snapshot.get(name, [])) + + def url_for(self, name: str, fallback: str) -> str: + """A live instance's URL (round-robin), or the static fallback if none is known.""" + live = self.instances(name) + if not live: + return fallback + counter = self._counters.setdefault(name, itertools.count()) + return live[next(counter) % len(live)]["url"] + + +DISCOVERY = Discovery() diff --git a/shared/shop_common/flask_support.py b/shared/shop_common/flask_support.py index 2cb431b..06f07b6 100644 --- a/shared/shop_common/flask_support.py +++ b/shared/shop_common/flask_support.py @@ -5,18 +5,38 @@ 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) + 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). +With REGISTRY_URL and SERVICE_PUBLIC_URL set, the service registers itself (pattern 12). """ +import os +import threading import time from flask import Flask, Response, g, jsonify, request from sqlalchemy import inspect from . import metrics +from .discovery import DISCOVERY from .telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing +INSTANCE_HEADER = "X-Instance-Id" + + +def instance_id(service_name: str) -> str: + """Set by run_local.py (e.g. order-5113); Container Apps sets the replica name.""" + return os.environ.get("INSTANCE_ID") or os.environ.get("CONTAINER_APP_REPLICA_NAME") or f"{service_name}-{os.getpid()}" + + +def chaos_enabled() -> bool: + return os.environ.get("CHAOS_ENABLED") == "1" + + def install(app: Flask, service_name: str, db) -> None: init_tracing(service_name) + this_instance = instance_id(service_name) from opentelemetry.instrumentation.flask import FlaskInstrumentor FlaskInstrumentor().instrument_app(app, excluded_urls="health,debug/spans,metrics") @@ -33,6 +53,7 @@ def _start_timer(): @app.after_request 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"): return response @@ -51,7 +72,7 @@ def _record(response): @app.get("/health") def health(): - return {"status": "ok", "service": service_name} + return {"status": "ok", "service": service_name, "instance": this_instance} @app.get("/health/db") def health_db(): @@ -75,3 +96,16 @@ def debug_spans(): def prometheus_metrics(): body, content_type = metrics.render() return Response(body, content_type=content_type) + + @app.post("/debug/crash") + def debug_crash(): + if not chaos_enabled(): + return jsonify({"message": "Chaos endpoints are off (CHAOS_ENABLED is not 1)"}), 403 + # Exit just after the response is sent, like a crashed replica. No deregistration on + # purpose: the registry has to notice the missing heartbeats by itself. + threading.Timer(0.3, os._exit, [1]).start() + return jsonify({"stopping": this_instance}) + + public_url = os.environ.get("SERVICE_PUBLIC_URL") + if public_url: + DISCOVERY.register(service_name, this_instance, public_url) diff --git a/tests/smoke/test_post_run.py b/tests/smoke/test_post_run.py index a4b39b6..da61a37 100644 --- a/tests/smoke/test_post_run.py +++ b/tests/smoke/test_post_run.py @@ -28,19 +28,20 @@ def _checkout_flow(user_url: str, catalog_url: str, order_url: str) -> None: r = httpx.post(f"{user_url}/user/login", data={"username": username, "password": password}) assert r.status_code == 200, r.text - api_key = r.json()["api_key"] + login_token = r.json()["token"] # pattern 10: a signed token, no server session r = httpx.post(f"{catalog_url}/product/create", data={"name": f"P{token}", "slug": f"p{token}", "price": "1500"}) assert r.status_code == 200, r.text product_id = r.json()["product"]["id"] - headers = {"Authorization": f"Basic {api_key}"} + headers = {"Authorization": f"Bearer {login_token}"} r = httpx.post(f"{order_url}/order/add-item", data={"product_id": product_id, "qty": 2}, headers=headers) - assert r.status_code == 200, r.text # order calls user internally to validate the api_key + 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 def test_services_full_flow_direct(): @@ -95,3 +96,65 @@ def test_one_request_is_traced_across_services(): trace_id = r.headers["X-Trace-Id"] spans = httpx.get(f"{GATEWAY_URL}/api/observability/trace/{trace_id}").json()["spans"] assert {"gateway", "catalog", "inventory"} <= {s["service"] for s in spans} + + +# --- M2 pattern demos (patterns 10, 12, 4), through the gateway ---------------------------------- + +def _login_with_cart() -> dict: + 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"}) + login_token = httpx.post(f"{shop}/user/login", data={"username": f"m2{tag}", "password": "secret123"}).json()["token"] + headers = {"Authorization": f"Bearer {login_token}"} + httpx.post(f"{shop}/order/add-item", data={"product_id": 1, "qty": 3}, headers=headers) + return headers + + +def test_registry_lists_both_order_replicas(): + _require_stack() + view = httpx.get(f"{GATEWAY_URL}/api/patterns/registry").json() + assert view["mode"] == "registry" + assert {i["instance_id"] for i in view["services"]["order"]} == {"order-5103", "order-5113"} + assert set(view["services"]) >= set(URLS) + + +def test_any_replica_serves_the_same_cart(): + _require_stack() + headers = _login_with_cart() + seen, carts = set(), set() + for _ in range(6): + r = httpx.get(f"{GATEWAY_URL}/api/shop/order", headers=headers) + assert r.status_code == 200, r.text + seen.add(r.headers["X-Instance-Id"]) + carts.add(r.json()["result"]["items"][0]["quantity"]) + assert seen == {"order-5103", "order-5113"} + assert carts == {3} + + +def test_gateway_rejects_a_bad_token_at_the_edge(): + _require_stack() + r = httpx.get(f"{GATEWAY_URL}/api/shop/order", headers={"Authorization": "Bearer nope"}) + assert r.status_code == 401 + assert "gateway" in r.json()["message"] + + +def test_breaker_opens_when_payment_fails_and_closes_after_it_heals(): + _require_stack() + import time + + api = f"{GATEWAY_URL}/api/patterns/breaker" + assert httpx.post(f"{api}/payment-mode", json={"mode": "failing"}).status_code == 200 + try: + for _ in range(6): # 3 failures on each of the 2 order replicas + httpx.get(f"{api}/call", timeout=10) + states = {b["instance"]: b["state"] for b in httpx.get(f"{api}/state").json()["breakers"]} + assert set(states.values()) == {"open"}, states + r = httpx.get(f"{api}/call").json() + assert r["outcome"] == "short-circuited" + assert r["ms"] < 50 + finally: + httpx.post(f"{api}/payment-mode", json={"mode": "healthy"}) + time.sleep(16) # past the 15 s reset window + 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"}