From 8d7b6f314ae82cd5fd621764ea7f6b5d1ba1a7ce Mon Sep 17 00:00:00 2001 From: Marcos Oliveira Date: Sun, 15 Nov 2026 12:11:38 -0500 Subject: [PATCH] =?UTF-8?q?feat:=20M1=20foundation=20=E2=80=94=20patterns?= =?UTF-8?q?=201,=202,=205,=206=20live?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pattern 1, Database per Service: add payment and inventory services, each with its own database; /health/db on every service; order-service isolation probe shows a real 'no such table' when it tries another service's table. Pattern 2, Bounded Context: inventory owns StockItem keyed by the catalog's product id; gateway endpoint returns one product as Catalog and Inventory each see it; context map page. Pattern 5, API Gateway: request IDs forwarded to every service and echoed back; /api/order-summary aggregates user, order, catalog and inventory; only GET/POST proxied. Pattern 6, Observability: shared shop_common package with OpenTelemetry tracing (Flask, FastAPI, requests, httpx, SQLAlchemy), JSON logs carrying trace and request IDs, Prometheus metrics, and an in-memory span store the gateway stitches into a trace waterfall. Optional OTLP export. Also: remove the unauthenticated DELETE /api/product/; Bicep and provision deploy payment and inventory; CI installs shop_common per suite; pattern pages with live demos and screenshots in the README. Co-Authored-By: Claude Opus 5.5 --- .env.example | 11 ++ .github/workflows/ci.yml | 16 ++ .gitignore | 7 + CLAUDE.md | 38 ++-- Makefile | 2 + README.md | 80 ++++++-- docs/screenshots/p01-database-per-service.jpg | Bin 0 -> 52345 bytes docs/screenshots/p02-bounded-context.jpg | Bin 0 -> 46606 bytes docs/screenshots/p05-api-gateway.jpg | Bin 0 -> 50696 bytes docs/screenshots/p06-observability.jpg | Bin 0 -> 54933 bytes frontend/src/App.tsx | 2 + frontend/src/api/gatewayClient.ts | 90 +++++++++ frontend/src/pages/Home.tsx | 12 +- frontend/src/pages/PatternPage.tsx | 71 +++++++ frontend/src/pages/Patterns.tsx | 49 +++-- frontend/src/patterns/content.ts | 112 +++++++++++ .../src/patterns/demos/ApiGatewayDemo.tsx | 126 +++++++++++++ .../src/patterns/demos/BoundedContextDemo.tsx | 102 ++++++++++ .../patterns/demos/DatabasePerServiceDemo.tsx | 123 ++++++++++++ .../src/patterns/demos/ObservabilityDemo.tsx | 135 +++++++++++++ frontend/src/theme/contoso.css | 96 ++++++++++ frontend/tsconfig.tsbuildinfo | 1 - gateway/Dockerfile | 2 + gateway/app/config.py | 11 +- gateway/app/main.py | 14 +- gateway/app/observability.py | 67 +++++++ gateway/app/routers/patterns.py | 177 ++++++++++++++++++ gateway/app/routers/shop.py | 12 +- gateway/requirements.txt | 1 + gateway/tests/test_api.py | 31 ++- infra/bicep/main.bicep | 41 +++- infra/bicep/modules/container-app.bicep | 2 +- infra/bicep/modules/mysql.bicep | 2 +- infra/provision.py | 31 ++- infra/verify_teardown.py | 2 +- scripts/service_table.py | 4 + scripts/setup.py | 5 +- services/catalog/Dockerfile | 5 +- services/catalog/application/__init__.py | 6 +- .../catalog/application/product_api/routes.py | 12 -- services/catalog/requirements.txt | 1 + services/inventory/Dockerfile | 20 ++ services/inventory/application/__init__.py | 38 ++++ services/inventory/application/models.py | 23 +++ services/inventory/application/routes.py | 19 ++ services/inventory/application/seed.py | 13 ++ services/inventory/config.py | 48 +++++ services/inventory/requirements.txt | 9 + services/inventory/run.py | 14 ++ services/inventory/tests/conftest.py | 47 +++++ services/inventory/tests/test_inventory.py | 26 +++ services/order/Dockerfile | 5 +- services/order/application/__init__.py | 6 +- .../order/application/order_api/routes.py | 29 +++ services/order/requirements.txt | 1 + .../order/tests/test_models_and_schemas.py | 11 ++ services/payment/Dockerfile | 20 ++ services/payment/application/__init__.py | 34 ++++ services/payment/application/models.py | 26 +++ services/payment/application/routes.py | 29 +++ services/payment/config.py | 48 +++++ services/payment/requirements.txt | 9 + services/payment/run.py | 14 ++ services/payment/tests/conftest.py | 47 +++++ services/payment/tests/test_payment.py | 16 ++ services/user/Dockerfile | 5 +- services/user/application/__init__.py | 6 +- services/user/requirements.txt | 1 + shared/build/lib/shop_common/__init__.py | 5 + shared/build/lib/shop_common/flask_support.py | 77 ++++++++ shared/build/lib/shop_common/metrics.py | 23 +++ shared/build/lib/shop_common/telemetry.py | 157 ++++++++++++++++ shared/pyproject.toml | 24 +++ shared/shop_common/__init__.py | 5 + shared/shop_common/flask_support.py | 77 ++++++++ shared/shop_common/metrics.py | 23 +++ shared/shop_common/telemetry.py | 157 ++++++++++++++++ tests/smoke/test_post_run.py | 37 ++++ 78 files changed, 2534 insertions(+), 114 deletions(-) create mode 100644 docs/screenshots/p01-database-per-service.jpg create mode 100644 docs/screenshots/p02-bounded-context.jpg create mode 100644 docs/screenshots/p05-api-gateway.jpg create mode 100644 docs/screenshots/p06-observability.jpg create mode 100644 frontend/src/pages/PatternPage.tsx create mode 100644 frontend/src/patterns/content.ts create mode 100644 frontend/src/patterns/demos/ApiGatewayDemo.tsx create mode 100644 frontend/src/patterns/demos/BoundedContextDemo.tsx create mode 100644 frontend/src/patterns/demos/DatabasePerServiceDemo.tsx create mode 100644 frontend/src/patterns/demos/ObservabilityDemo.tsx delete mode 100644 frontend/tsconfig.tsbuildinfo create mode 100644 gateway/app/observability.py create mode 100644 gateway/app/routers/patterns.py create mode 100644 services/inventory/Dockerfile create mode 100644 services/inventory/application/__init__.py create mode 100644 services/inventory/application/models.py create mode 100644 services/inventory/application/routes.py create mode 100644 services/inventory/application/seed.py create mode 100644 services/inventory/config.py create mode 100644 services/inventory/requirements.txt create mode 100644 services/inventory/run.py create mode 100644 services/inventory/tests/conftest.py create mode 100644 services/inventory/tests/test_inventory.py create mode 100644 services/payment/Dockerfile create mode 100644 services/payment/application/__init__.py create mode 100644 services/payment/application/models.py create mode 100644 services/payment/application/routes.py create mode 100644 services/payment/config.py create mode 100644 services/payment/requirements.txt create mode 100644 services/payment/run.py create mode 100644 services/payment/tests/conftest.py create mode 100644 services/payment/tests/test_payment.py create mode 100644 shared/build/lib/shop_common/__init__.py create mode 100644 shared/build/lib/shop_common/flask_support.py create mode 100644 shared/build/lib/shop_common/metrics.py create mode 100644 shared/build/lib/shop_common/telemetry.py create mode 100644 shared/pyproject.toml create mode 100644 shared/shop_common/__init__.py create mode 100644 shared/shop_common/flask_support.py create mode 100644 shared/shop_common/metrics.py create mode 100644 shared/shop_common/telemetry.py diff --git a/.env.example b/.env.example index eb24893..028d174 100644 --- a/.env.example +++ b/.env.example @@ -14,6 +14,8 @@ SECRET_KEY=change-me-to-a-random-string USER_SERVICE_PORT=5101 CATALOG_SERVICE_PORT=5102 ORDER_SERVICE_PORT=5103 +PAYMENT_SERVICE_PORT=5104 +INVENTORY_SERVICE_PORT=5105 GATEWAY_PORT=8100 FRONTEND_PORT=5273 @@ -21,6 +23,8 @@ FRONTEND_PORT=5273 USER_SERVICE_BASE_URL=http://127.0.0.1:5101 CATALOG_SERVICE_BASE_URL=http://127.0.0.1:5102 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 # --- SQLite (local mode, default) --- # Optional overrides — each path is relative to that service's own directory. @@ -28,6 +32,13 @@ ORDER_SERVICE_BASE_URL=http://127.0.0.1:5103 # USER_DB_PATH=instance/user.sqlite3 # CATALOG_DB_PATH=instance/catalog.sqlite3 # ORDER_DB_PATH=instance/order.sqlite3 +# PAYMENT_DB_PATH=instance/payment.sqlite3 +# INVENTORY_DB_PATH=instance/inventory.sqlite3 + +# --- Observability (pattern 6) --- +# Optional: also export spans over OTLP/HTTP, e.g. to otel-desktop-viewer (http://localhost:4318) +# or an OpenTelemetry collector. Unset = spans stay in each process's in-memory store only. +# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # --- Azure Database for MySQL Flexible Server (azure mode only) --- # Populated automatically into .env by infra/provision.py after provisioning. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 48e41ba..17f0caf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,15 +24,27 @@ jobs: - suite: gateway requirements: gateway/requirements.txt tests: gateway/tests + shared: fastapi - suite: user requirements: services/user/requirements.txt tests: services/user/tests + shared: flask - suite: catalog requirements: services/catalog/requirements.txt tests: services/catalog/tests + shared: flask - suite: order requirements: services/order/requirements.txt tests: services/order/tests + shared: flask + - suite: payment + requirements: services/payment/requirements.txt + tests: services/payment/tests + shared: flask + - suite: inventory + requirements: services/inventory/requirements.txt + tests: services/inventory/tests + shared: flask steps: - uses: actions/checkout@v4 @@ -45,6 +57,10 @@ jobs: - name: Install dependencies run: pip install -r ${{ matrix.requirements }} pytest==8.3.4 pytest-asyncio==0.25.0 + - name: Install shared observability package (shop_common) + if: matrix.shared + run: pip install "./shared[${{ matrix.shared }}]" + - name: Run tests run: python -m pytest ${{ matrix.tests }} -v diff --git a/.gitignore b/.gitignore index b0c2266..8bb4770 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,10 @@ migrations/versions/__pycache__/ # --- Staged for az acr build, cleaned up after (see infra/provision.py build_images) --- bff/scripts/ + +# --- Staged by infra/provision.py for az acr build --- +_shared/ +shared/*.egg-info/ + +# --- TypeScript build cache --- +*.tsbuildinfo diff --git a/CLAUDE.md b/CLAUDE.md index faef0a6..f6241a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,20 +27,34 @@ 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 (M1a, layout) -- Folders: `services/{user,catalog,order}/` (Flask, one DB each), `gateway/` (FastAPI), - `frontend/`, `infra/`, `scripts/`, `tests/`. The monolith and the old migration engine are gone. +## Current state (M1, foundation: patterns 1, 2, 5, 6 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, gateway 8100, frontend 5273 (registry 8500 and - payment/inventory 5104-5105 arrive in later milestones). -- Gateway routes `/api/shop/` to `/api/` on the owning service by first path segment - (`gateway/app/config.py` `ROUTE_OWNERS`). No auth or aggregation yet (M1). -- The catalog service keeps the `product` resource name in its API (`/api/product(s)`) and its - `product_api` package. Only the service, its env vars (`CATALOG_*`) and its DB (`catalog_db`) are - named catalog. -- Azure: one Container App per service plus the gateway, all external ingress, images built with - `az acr build --platform linux/amd64`. +- Ports: user 5101, catalog 5102, order 5103, payment 5104, inventory 5105, gateway 8100, + frontend 5273 (registry 8500 arrives in M2). +- **`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`. +- Smoke tests create users and products in the local SQLite DBs; delete `services/*/instance/` + for a clean catalog. ## 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 ad5d368..4912200 100644 --- a/Makefile +++ b/Makefile @@ -26,6 +26,8 @@ test: services/user/.venv/bin/python -m pytest services/user/tests -v services/catalog/.venv/bin/python -m pytest services/catalog/tests -v services/order/.venv/bin/python -m pytest services/order/tests -v + 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 smoke: diff --git a/README.md b/README.md index 48d3865..e8a4514 100644 --- a/README.md +++ b/README.md @@ -4,20 +4,21 @@ 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: M1a, layout.** Three services, a gateway and the frontend run end to end. The foundation is copied from +> **Status: M1, foundation.** 4 of 12 patterns are live: Database per Service, Bounded Context, +> API Gateway and Observability. The foundation is copied from > [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration). -> The patterns arrive in 3 milestones. See [docs/PLAN.md](docs/PLAN.md). +> The rest arrive in milestones M2 and M3. See [docs/PLAN.md](docs/PLAN.md). ## The 12 patterns -| # | Pattern | What it does | Milestone | +| # | Pattern | What it does | Status | |---|---|---|---| -| 1 | Database per Service | Gives each service its own database | M1 | -| 2 | Bounded Context | Splits one large domain into clear business domains | M1 | +| 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 | -| 5 | API Gateway | Routes client requests to the right service | M1 | -| 6 | Observability | Collects logs, metrics and traces from every service | M1 | +| 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 | @@ -25,24 +26,67 @@ can click. | 11 | Contract Testing | Checks that APIs stay compatible across services | M2 | | 12 | Service Discovery | Finds service instances automatically at runtime | M2 | -## Planned architecture +## Architecture today -- **5 Flask services**, each with its own database: `user`, `catalog`, `order`, `payment`, `inventory`. -- **FastAPI gateway**: single entry point, JWT check, aggregation, live demo feeds. -- **Service registry**: register, heartbeat, lookup (local); Azure Container Apps DNS in the cloud. -- **Redis Streams** event bus with a transactional outbox; a saga orchestrator for checkout. -- **OpenTelemetry** traces, JSON logs and metrics. -- **React + TypeScript** frontend with a page per pattern. +``` +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 +``` + +- **5 Flask services** (`services/`), each with its own database: SQLite locally, one logical + MySQL database each in Azure. +- **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. +- **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). + +## The live demos + +### 1. Database per Service +Each service reports the database it owns. Then the order service tries to read the catalog's +`product` table through its own connection, and the database refuses: `no such table: product`. + +Database per Service demo: 5 services each own their tables; the order service is blocked from reading the catalog's product table + +### 2. Bounded Context +A context map of the 5 business contexts, and one product as two contexts see it: Catalog knows +its name and price, Inventory knows how many are on hand. + +Bounded Context demo: context map and one product seen by Catalog and by Inventory + +### 5. API Gateway +One browser call to `/api/order-summary` becomes 4 service calls. The page shows each call, its +status and timing, and the one request ID forwarded to all of them. + +API Gateway demo: one browser call fans out to user, order, catalog and inventory + +### 6. Observability +One click, traced through every process: 25 spans across 5 processes, including each service's +database queries, drawn as a waterfall. Metrics per service come from each `/metrics` endpoint. + +Observability demo: a trace waterfall across gateway, user, order, catalog and inventory ## Run locally (no Docker) ```bash -make setup +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 test +make test # unit tests, each suite in its own venv +make smoke # end-to-end checks against the running stack ``` +Optional: set `OTEL_EXPORTER_OTLP_ENDPOINT` to also send spans to an OpenTelemetry viewer or +collector. Without it, traces stay in each process's memory and the Observability page draws them. + ## Cloud -Azure Container Apps + 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). +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. diff --git a/docs/screenshots/p01-database-per-service.jpg b/docs/screenshots/p01-database-per-service.jpg new file mode 100644 index 0000000000000000000000000000000000000000..2612b21ac1f6c7ab27ff8decf6b0561ea343b60c GIT binary patch literal 52345 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

9sVA4U6SWh$$%spy-}KpN!Z;4Ia|*G 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

P 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 /> } /> } /> + } /> diff --git a/frontend/src/api/gatewayClient.ts b/frontend/src/api/gatewayClient.ts index 8c63e34..fe93d79 100644 --- a/frontend/src/api/gatewayClient.ts +++ b/frontend/src/api/gatewayClient.ts @@ -10,6 +10,16 @@ async function request(path: string, options: RequestInit = {}): Promise { return response.json() as Promise; } +/** Same as request(), but also returns the gateway's request and trace IDs for this call. */ +async function requestWithIds(path: string, options: RequestInit = {}): Promise<{ body: T; requestId: string | null; traceId: string | null }> { + const response = await fetch(`${GATEWAY_BASE_URL}${path}`, options); + const body = (await response.json()) as T; + if (!response.ok) { + throw Object.assign(new Error(`${response.status} ${response.statusText}`), { body }); + } + return { body, requestId: response.headers.get("X-Request-Id"), traceId: response.headers.get("X-Trace-Id") }; +} + function toForm(fields: Record): URLSearchParams { const form = new URLSearchParams(); for (const [key, value] of Object.entries(fields)) form.append(key, String(value)); @@ -79,3 +89,83 @@ export const shopApi = { headers: authHeaders(apiKey), }), }; + +// --- Pattern demo endpoints -------------------------------------------------------------------- + +export interface ServiceCall { + service: string; + path: string; + status: number | string; + ms: number; +} + +export interface ServiceDatabase { + service: string; + reachable: boolean; + engine?: string; + database?: string; + tables?: string[]; +} + +export interface IsolationResult { + attempted: string; + owner: string; + order_tables: string[]; + blocked: boolean; + error: string | null; +} + +export interface BoundedContextView { + product_id: number; + catalog: Product | null; + inventory: { product_id: number; on_hand: number; reserved: number; available: number } | null; + calls: ServiceCall[]; +} + +export interface OrderSummary { + user: { username: string }; + lines: { product_id: number; name: string | null; unit_price_cents: number | null; quantity: number; available: number | null }[]; + total_cents: number; + calls: ServiceCall[]; + request_id: string; + trace_id: string | null; +} + +export interface Span { + trace_id: string; + span_id: string; + parent_id: string | null; + name: string; + service: string; + kind: string; + start_ns: number; + end_ns: number; + status: string; +} + +export interface ServiceMetrics { + service: string; + reachable: boolean; + requests?: number; + errors_5xx?: number; + avg_ms?: number | null; +} + +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) }), + 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 { + try { + const raw = localStorage.getItem("shop_auth"); + return raw ? (JSON.parse(raw) as { apiKey: string }).apiKey : null; + } catch { + return null; + } +} diff --git a/frontend/src/pages/Home.tsx b/frontend/src/pages/Home.tsx index 85d2942..cc297ae 100644 --- a/frontend/src/pages/Home.tsx +++ b/frontend/src/pages/Home.tsx @@ -18,18 +18,18 @@ export default function Home() {

Patterns

-

The 12 patterns, each with a live demo as its milestone lands.

+

The 12 patterns. Database per Service, Bounded Context, API Gateway and Observability are live now.

Architecture today

{`
-Browser → API gateway ──┬──► user     → user_db
-                        ├──► catalog  → catalog_db
-                        └──► order    → order_db
-                               │
-                               └──HTTP──► user (validates the caller)
+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
 `}
diff --git a/frontend/src/pages/PatternPage.tsx b/frontend/src/pages/PatternPage.tsx new file mode 100644 index 0000000..e5418c6 --- /dev/null +++ b/frontend/src/pages/PatternPage.tsx @@ -0,0 +1,71 @@ +import { ReactNode } from "react"; +import { Link, useParams } from "react-router-dom"; +import ApiGatewayDemo from "../patterns/demos/ApiGatewayDemo"; +import BoundedContextDemo from "../patterns/demos/BoundedContextDemo"; +import DatabasePerServiceDemo from "../patterns/demos/DatabasePerServiceDemo"; +import ObservabilityDemo from "../patterns/demos/ObservabilityDemo"; +import { PATTERNS } from "../patterns/content"; + +const DEMOS: Record ReactNode> = { + "database-per-service": () => , + "bounded-context": () => , + "api-gateway": () => , + observability: () => , +}; + +export default function PatternPage() { + const { slug } = useParams(); + const pattern = PATTERNS.find((p) => p.slug === slug); + + if (!pattern || !pattern.live) { + return ( +
+

{pattern ? pattern.name : "Unknown pattern"}

+

{pattern ? `This demo arrives in ${pattern.milestone}.` : "No pattern with that name."}

+ Back to all patterns +
+ ); + } + + return ( +
+ ); +} diff --git a/frontend/src/pages/Patterns.tsx b/frontend/src/pages/Patterns.tsx index 0d4f713..3aa0ee3 100644 --- a/frontend/src/pages/Patterns.tsx +++ b/frontend/src/pages/Patterns.tsx @@ -1,38 +1,37 @@ -const PATTERNS: { n: number; name: string; what: string; milestone: "M1" | "M2" | "M3" }[] = [ - { n: 1, name: "Database per Service", what: "Gives each service its own database.", milestone: "M1" }, - { n: 2, name: "Bounded Context", what: "Splits one large domain into clear business domains.", milestone: "M1" }, - { n: 3, name: "CI-CD Pipeline", what: "Builds, tests and deploys every service automatically.", milestone: "M3" }, - { n: 4, name: "Circuit Breaker", what: "Stops calls to a failing service to prevent more failures.", milestone: "M2" }, - { n: 5, name: "API Gateway", what: "Routes client requests to the right service.", milestone: "M1" }, - { n: 6, name: "Observability", what: "Collects logs, metrics and traces from every service.", milestone: "M1" }, - { n: 7, name: "Event-Driven Architecture", what: "Services communicate by publishing and consuming events.", milestone: "M3" }, - { n: 8, name: "Saga Pattern", what: "Coordinates distributed transactions and rolls back failures safely.", milestone: "M3" }, - { n: 9, name: "Containerization", what: "Packages each service with all its dependencies.", milestone: "M3" }, - { n: 10, name: "Stateless Services", what: "Stores session data outside the service.", milestone: "M2" }, - { n: 11, name: "Contract Testing", what: "Checks that APIs stay compatible across services.", milestone: "M2" }, - { n: 12, name: "Service Discovery", what: "Finds service instances automatically at runtime.", milestone: "M2" }, -]; +import { Link } from "react-router-dom"; +import { PATTERNS } from "../patterns/content"; export default function Patterns() { + const liveCount = PATTERNS.filter((p) => p.live).length; return (

The 12 patterns

- Each pattern gets its own page with an explanation, when not to use it, and a live demo. - They arrive in three milestones. + 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.

- {PATTERNS.map((p) => ( -
-

- {p.n}. {p.name} -

-

{p.what}

- Coming in {p.milestone} -
- ))} + {PATTERNS.map((p) => + p.live ? ( + +

+ {p.n}. {p.name} +

+

{p.what}

+ Live demo + + ) : ( +
+

+ {p.n}. {p.name} +

+

{p.what}

+ Coming in {p.milestone} +
+ ), + )}
); diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts new file mode 100644 index 0000000..85ccbc1 --- /dev/null +++ b/frontend/src/patterns/content.ts @@ -0,0 +1,112 @@ +export type Milestone = "M1" | "M2" | "M3"; + +export interface PatternInfo { + n: number; + slug: string; + name: string; + what: string; + milestone: Milestone; + live: boolean; + problem?: string; + inThisProject?: string[]; + whenNotToUse?: string[]; + source?: { label: string; url: string }; +} + +export const PATTERNS: PatternInfo[] = [ + { + n: 1, + slug: "database-per-service", + name: "Database per Service", + what: "Gives each service its own database.", + milestone: "M1", + live: true, + problem: + "When services share one database, any schema change can break a service you did not touch, and no service can be deployed or scaled on its own. The database becomes the real monolith.", + 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.", + ], + whenNotToUse: [ + "Small teams with one deployable: the cost of no joins and no cross-service transactions outweighs the benefit.", + "Reporting that needs joins across domains: feed a separate read model or warehouse instead of querying service databases.", + "One MySQL server with one database per service is a cost compromise. It isolates schemas, not load.", + ], + source: { label: "microservices.io — Database per service", url: "https://microservices.io/patterns/data/database-per-service.html" }, + }, + { + n: 2, + slug: "bounded-context", + name: "Bounded Context", + what: "Splits one large domain into clear business domains.", + milestone: "M1", + live: true, + problem: + "One shared model of \"Product\" ends up holding price, stock, images and warehouse data for every team. Every change needs every team's agreement, so nobody can change it.", + inThisProject: [ + "Catalog owns what we sell: name, slug, price.", + "Inventory owns how many we have: on hand, reserved, available. It knows a product only by its id.", + "Order owns carts and orders. Payment owns charges and knows an order only by id and amount.", + "The gateway translates between contexts when it builds a combined view.", + ], + whenNotToUse: [ + "Do not split one context per database table. That gives many tiny CRUD services that must all change together.", + "Boundaries follow business capabilities and team ownership, not technical layers.", + ], + 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: 5, + slug: "api-gateway", + name: "API Gateway", + what: "Routes client requests to the right service.", + milestone: "M1", + live: true, + problem: + "Without a gateway the browser must know every service's address, call several of them for one screen, and every service must handle CORS and request tracking on its own.", + inThisProject: [ + "The browser talks only to the gateway. /api/shop/ is routed to the service that owns .", + "Every request gets an X-Request-Id, forwarded to every service and echoed back, so all logs for one click share one ID.", + "/api/order-summary turns one browser call into 4 service calls (user, order, catalog, inventory) and returns one combined answer.", + "Unknown paths return 404 and an unreachable service returns a clear 503, never a hung request. Only GET and POST are exposed.", + ], + whenNotToUse: [ + "Do not put business rules in the gateway. It routes, aggregates and handles cross-cutting concerns; it does not decide prices or stock.", + "One shared gateway for many very different clients becomes a bottleneck team. Consider one backend-for-frontend per client type.", + ], + source: { label: "microservices.io — API gateway", url: "https://microservices.io/patterns/apigateway.html" }, + }, + { + n: 6, + slug: "observability", + name: "Observability", + what: "Collects logs, metrics and traces from every service.", + milestone: "M1", + live: true, + problem: + "A single click crosses several processes. When it is slow or fails, per-service logs alone cannot tell you which hop caused it.", + inThisProject: [ + "Traces: OpenTelemetry in every service. The W3C traceparent header carries one trace across the gateway and every service, including database queries.", + "Logs: one JSON line per request, carrying trace_id, span_id and request_id.", + "Metrics: request count and latency per route at /metrics in Prometheus format.", + "Each process keeps its last 2,000 spans in memory, so this page can draw a trace with no extra tool. Set OTEL_EXPORTER_OTLP_ENDPOINT to also send spans to a viewer or collector.", + ], + whenNotToUse: [ + "Never label metrics with raw URLs or user IDs: every distinct value becomes a new series. Use route templates.", + "In production, sample traces. Keeping every span is fine for a demo, expensive at scale.", + "The in-memory span store is a teaching aid, not a tracing backend: it forgets on restart and only holds recent spans.", + ], + source: { label: "OpenTelemetry — Python zero-code instrumentation", url: "https://opentelemetry.io/docs/zero-code/python/" }, + }, + { n: 7, slug: "event-driven-architecture", name: "Event-Driven Architecture", what: "Services communicate by publishing and consuming events.", milestone: "M3", live: false }, + { n: 8, slug: "saga", name: "Saga Pattern", what: "Coordinates distributed transactions and rolls back failures safely.", milestone: "M3", live: false }, + { n: 9, slug: "containerization", name: "Containerization", what: "Packages each service with all its dependencies.", milestone: "M3", live: false }, + { n: 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 }, +]; + +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 new file mode 100644 index 0000000..a203db2 --- /dev/null +++ b/frontend/src/patterns/demos/ApiGatewayDemo.tsx @@ -0,0 +1,126 @@ +import { useState } from "react"; +import { Link } from "react-router-dom"; +import { OrderSummary, ServiceCall, patternsApi, savedApiKey } 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(); + + async function run() { + if (!apiKey) return; + setBusy(true); + setError(null); + try { + const { body } = await patternsApi.orderSummary(apiKey); + setSummary(body); + setCalls(body.calls); + } catch (err) { + const body = (err as { body?: { message?: string; calls?: ServiceCall[] } }).body; + setError(body?.message ?? String(err)); + setCalls(body?.calls ?? []); + setSummary(null); + } finally { + setBusy(false); + } + } + + if (!apiKey) { + return ( +

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

+ ); + } + + return ( +
+

+ The browser makes one call: GET /api/order-summary. The gateway fans it out to + the services that own each piece, then returns one combined answer. +

+
+ +
+ {error &&

{error}

} + + {calls.length > 0 && ( +
+
+

What the gateway called

+ + + + + + + + + + + {calls.map((c, i) => ( + + + + + + + ))} + +
ServicePathStatusTime
+ + {c.service} + + {c.path} + {c.status}{c.ms} ms
+ {summary && ( +

+ Request ID {summary.request_id} was forwarded to every call above, so their logs share it. +

+ )} +
+ {summary && ( +
+

What the browser got back

+

+ Signed in as {summary.user.username} +

+ {summary.lines.length === 0 ? ( +

Your cart is empty. Add something on the Shop page and run this again.

+ ) : ( + + + + + + + + + + {summary.lines.map((l) => ( + + + + + + ))} + +
Product (catalog)Qty (order)In stock (inventory)
+ {l.name ?? `#${l.product_id}`} · ${((l.unit_price_cents ?? 0) / 100).toFixed(2)} + {l.quantity}{l.available ?? "unknown"}
+ )} +

+ Total ${(summary.total_cents / 100).toFixed(2)} +

+
+ )} +
+ )} +
+ ); +} diff --git a/frontend/src/patterns/demos/BoundedContextDemo.tsx b/frontend/src/patterns/demos/BoundedContextDemo.tsx new file mode 100644 index 0000000..c5b684f --- /dev/null +++ b/frontend/src/patterns/demos/BoundedContextDemo.tsx @@ -0,0 +1,102 @@ +import { useEffect, useState } from "react"; +import { BoundedContextView, Product, patternsApi, shopApi } from "../../api/gatewayClient"; + +const CONTEXTS = [ + { name: "Identity", service: "user", owns: ["User", "credentials", "API key"] }, + { name: "Catalog", service: "catalog", owns: ["Product: name, slug, price"] }, + { name: "Inventory", service: "inventory", owns: ["StockItem: on hand, reserved"] }, + { name: "Ordering", service: "order", owns: ["Order, OrderItem (product id + qty)"] }, + { name: "Payments", service: "payment", owns: ["Payment: order id, amount, status"] }, +]; + +export default function BoundedContextDemo() { + const [products, setProducts] = useState([]); + const [selected, setSelected] = useState(null); + const [view, setView] = useState(null); + const [error, setError] = useState(null); + + useEffect(() => { + shopApi + .listProducts() + .then((data) => { + setProducts(data.results); + if (data.results.length) setSelected(data.results[0].id); + }) + .catch((err) => setError(String(err))); + }, []); + + useEffect(() => { + if (selected === null) return; + patternsApi + .boundedContext(selected) + .then(({ body }) => setView(body)) + .catch((err) => setError(String(err))); + }, [selected]); + + return ( +
+
+

Context map

+

Five business contexts, one service each. They share ids, never models.

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

+ + {c.name} +

+

+ service: {c.service} +

+
    + {c.owns.map((o) => ( +
  • {o}
  • + ))} +
+
+ ))} +
+
+ +
+

One product, two contexts

+

+ Pick a product. The gateway asks Catalog and Inventory about the same product id. Each answers in its own + words. +

+ {error &&

{error}

} + + {view && ( +
+
+

+ + As Catalog sees it +

+
{JSON.stringify(view.catalog, null, 2)}
+

Knows the name and price. Has no idea how many exist.

+
+
+

+ + As Inventory sees it +

+
{view.inventory ? JSON.stringify(view.inventory, null, 2) : "No stock record for this product id."}
+

Knows the counts. Has no idea what the product is called.

+
+
+ )} +
+
+ ); +} diff --git a/frontend/src/patterns/demos/DatabasePerServiceDemo.tsx b/frontend/src/patterns/demos/DatabasePerServiceDemo.tsx new file mode 100644 index 0000000..f81459d --- /dev/null +++ b/frontend/src/patterns/demos/DatabasePerServiceDemo.tsx @@ -0,0 +1,123 @@ +import { useEffect, useState } from "react"; +import { IsolationResult, ServiceDatabase, patternsApi } from "../../api/gatewayClient"; + +const FOREIGN_TABLES: { table: string; owner: string }[] = [ + { table: "product", owner: "catalog" }, + { table: "stock_item", owner: "inventory" }, + { table: "payment", owner: "payment" }, + { table: "user", owner: "user" }, +]; + +export default function DatabasePerServiceDemo() { + const [services, setServices] = useState(null); + const [error, setError] = useState(null); + const [isolation, setIsolation] = useState(null); + const [busyTable, setBusyTable] = useState(null); + + function load() { + setError(null); + patternsApi + .databases() + .then((data) => setServices(data.services)) + .catch((err) => setError(String(err))); + } + + useEffect(load, []); + + async function tryRead(table: string) { + setBusyTable(table); + try { + setIsolation(await patternsApi.isolationTest(table)); + } catch (err) { + setError(String(err)); + } finally { + setBusyTable(null); + } + } + + return ( +
+
+

Step 1. Each service reports the database it owns

+

+ The gateway asks every service for /health/db. Each answer lists only that service's own tables. +

+ {error &&

{error}

} +
+ + + + + + + + + + + {services?.map((s) => ( + + + {s.reachable ? ( + <> + + + + + ) : ( + + )} + + ))} + +
ServiceEngineDatabaseTables it owns
+ + {s.service} + {s.engine} + {s.database} + {s.tables?.join(", ")} + unreachable +
+
+ +
+ +
+

Step 2. Make the order service read another service's table

+

+ This runs real SQL through the order service's own connection. It fails because that table lives in another + database. +

+
+ {FOREIGN_TABLES.map(({ table, owner }) => ( + + ))} +
+ {isolation && ( +
+

+ + {isolation.blocked ? "Blocked, as designed" : "Not blocked"} + +

+

+ Ran {isolation.attempted} in the order database. +

+ {isolation.error && ( +

+ Database said: {isolation.error} +

+ )} +

+ The order database only has: {isolation.order_tables.join(", ")}. To get {isolation.owner} data, the order + service must call the {isolation.owner} service's API. +

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

No spans found for this trace yet.

; + const start = Math.min(...spans.map((s) => s.start_ns)); + const end = Math.max(...spans.map((s) => s.end_ns)); + const total = Math.max(end - start, 1); + return ( +
+ {spans.map((s) => { + const left = ((s.start_ns - start) / total) * 100; + const width = ((s.end_ns - s.start_ns) / total) * 100; + const ms = ((s.end_ns - s.start_ns) / 1e6).toFixed(1); + return ( +
+ + + {s.service} · {s.name} + + + + +
+ ); + })} +

+ {spans.length} spans across {new Set(spans.map((s) => s.service)).size} processes, {(total / 1e6).toFixed(1)} ms + end to end. +

+
+ ); +} + +export default function ObservabilityDemo() { + const [traceId, setTraceId] = useState(null); + const [requestId, setRequestId] = useState(null); + const [spans, setSpans] = useState([]); + const [metrics, setMetrics] = useState([]); + const [error, setError] = useState(null); + const [busy, setBusy] = useState(false); + const apiKey = savedApiKey(); + + function loadMetrics() { + patternsApi + .metrics() + .then((data) => setMetrics(data.services)) + .catch((err) => setError(String(err))); + } + + useEffect(loadMetrics, []); + + async function sendTracedRequest() { + setBusy(true); + 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); + setTraceId(result.traceId); + setRequestId(result.requestId); + if (result.traceId) { + const data = await patternsApi.trace(result.traceId); + setSpans(data.spans); + } + loadMetrics(); + } catch (err) { + setError(String(err)); + } finally { + setBusy(false); + } + } + + return ( +
+
+

Traces: follow one click through every service

+

+ {apiKey + ? "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."} +

+ + {error &&

{error}

} + {traceId && ( +

+ trace_id {traceId} · request_id {requestId}. Every service's JSON log line for this + click carries both. +

+ )} + {traceId && } +
+ +
+

Metrics: requests and latency per service

+

Read live from each service's Prometheus /metrics endpoint.

+ + + + + + + + + + + {metrics.map((m) => ( + + + {m.reachable ? ( + <> + + + + + ) : ( + + )} + + ))} + +
ServiceRequests5xx errorsAvg latency
+ + {m.service} + {m.requests}{m.errors_5xx}{m.avg_ms === null || m.avg_ms === undefined ? "–" : `${m.avg_ms} ms`} + unreachable +
+ +
+
+ ); +} diff --git a/frontend/src/theme/contoso.css b/frontend/src/theme/contoso.css index 10ac7d8..579ec6f 100644 --- a/frontend/src/theme/contoso.css +++ b/frontend/src/theme/contoso.css @@ -241,3 +241,99 @@ h3 { overflow-y: auto; white-space: pre-wrap; } + +/* --- Pattern pages --- */ +.data-table { + width: 100%; + border-collapse: collapse; + font-size: 0.9rem; +} + +.data-table th, +.data-table td { + text-align: left; + padding: 0.5rem 0.6rem; + border-bottom: 1px solid var(--contoso-border); + vertical-align: top; +} + +.data-table th { + color: var(--contoso-muted); + font-weight: 600; +} + +.table-scroll { + overflow-x: auto; +} + +.waterfall { + display: flex; + flex-direction: column; + gap: 4px; + font-size: 0.8rem; +} + +.waterfall-row { + display: grid; + grid-template-columns: minmax(120px, 34%) 1fr; + gap: 0.5rem; + align-items: center; +} + +.waterfall-label { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.waterfall-track { + position: relative; + height: 14px; + background: var(--contoso-bg); + border-radius: 3px; +} + +.waterfall-bar { + position: absolute; + top: 0; + height: 100%; + min-width: 2px; + border-radius: 3px; +} + +.svc-gateway { background: #0078d4; } +.svc-user { background: #8764b8; } +.svc-catalog { background: #107c10; } +.svc-order { background: #d0742a; } +.svc-payment { background: #c4314b; } +.svc-inventory { background: #038387; } + +.svc-dot { + display: inline-block; + width: 10px; + height: 10px; + border-radius: 50%; + margin-right: 0.4rem; +} + +.context-map { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); + gap: 0.75rem; +} + +.context-box { + border: 2px solid var(--contoso-border); + border-radius: var(--radius); + padding: 0.75rem; +} + +.context-box h4 { + margin: 0 0 0.35rem; +} + +.context-box ul { + margin: 0; + padding-left: 1.1rem; + font-size: 0.85rem; +} diff --git a/frontend/tsconfig.tsbuildinfo b/frontend/tsconfig.tsbuildinfo deleted file mode 100644 index 387b59d..0000000 --- a/frontend/tsconfig.tsbuildinfo +++ /dev/null @@ -1 +0,0 @@ -{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/gatewayclient.ts","./src/components/navbar.tsx","./src/pages/home.tsx","./src/pages/patterns.tsx","./src/pages/shop.tsx"],"version":"5.9.3"} \ No newline at end of file diff --git a/gateway/Dockerfile b/gateway/Dockerfile index e4afd1c..f949e6b 100644 --- a/gateway/Dockerfile +++ b/gateway/Dockerfile @@ -7,6 +7,8 @@ COPY requirements.txt . RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[fastapi]" ENV RUN_MODE=azure \ PYTHONUNBUFFERED=1 diff --git a/gateway/app/config.py b/gateway/app/config.py index 5a5dbe2..cd7cdde 100644 --- a/gateway/app/config.py +++ b/gateway/app/config.py @@ -4,12 +4,14 @@ 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 internal URLs. Pattern 12 (Service -# Discovery, milestone M2) replaces this static map with registry lookups. +# in); in Azure, provision sets them to the Container Apps URLs. Pattern 12 (Service Discovery, +# milestone M2) replaces this static map with registry lookups. 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"), "order": os.environ.get("ORDER_SERVICE_BASE_URL", "http://127.0.0.1:5103"), + "payment": os.environ.get("PAYMENT_SERVICE_BASE_URL", "http://127.0.0.1:5104"), + "inventory": os.environ.get("INVENTORY_SERVICE_BASE_URL", "http://127.0.0.1:5105"), } # First path segment of /api/shop/ -> owning service (its bounded context). @@ -18,8 +20,13 @@ "product": "catalog", "products": "catalog", "order": "order", + "payment": "payment", + "payments": "payment", + "inventory": "inventory", } +UPSTREAM_TIMEOUT_SECONDS = float(os.environ.get("UPSTREAM_TIMEOUT_SECONDS", "10")) + # Browsers treat 'localhost' and '127.0.0.1' as different CORS origins, and Vite binds to both, # so allow both locally. If FRONTEND_ORIGIN is set (e.g. the Static Web App hostname in Azure), # only that exact origin is allowed. diff --git a/gateway/app/main.py b/gateway/app/main.py index 98da903..d513364 100644 --- a/gateway/app/main.py +++ b/gateway/app/main.py @@ -1,25 +1,31 @@ from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware -from . import config -from .routers import services, shop +from . import config, observability +from .routers import patterns, 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.", - version="0.2.0", + "service that owns each path, aggregates /api/order-summary, and serves the " + "live demo endpoints for the pattern pages.", + version="0.3.0", ) +observability.install(app) + app.add_middleware( CORSMiddleware, allow_origins=config.FRONTEND_ORIGINS, allow_credentials=True, 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"], ) app.include_router(shop.router) +app.include_router(patterns.router) app.include_router(services.router) diff --git a/gateway/app/observability.py b/gateway/app/observability.py new file mode 100644 index 0000000..ab65b4f --- /dev/null +++ b/gateway/app/observability.py @@ -0,0 +1,67 @@ +"""Gateway side of patterns 5 and 6. + +- Request IDs: every request gets an X-Request-Id (kept if the client sent one), which is + forwarded to every service call and echoed back, so one ID ties together all the logs. +- Tracing: FastAPI and httpx are instrumented, so each browser request becomes one trace that + continues through every service the gateway calls. +- Metrics: request count and latency per route, at /metrics. +""" +import time +import uuid + +from fastapi import FastAPI, Request, Response +from opentelemetry import trace + +from shop_common import metrics +from shop_common.telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing + +SERVICE_NAME = "gateway" +_QUIET_PATHS = ("/health", "/metrics", "/debug/spans") + + +def install(app: FastAPI) -> None: + init_tracing(SERVICE_NAME) + log = get_logger() + + @app.middleware("http") + async def request_id_and_metrics(request: Request, call_next): + request_id = request.headers.get(REQUEST_ID_HEADER) or uuid.uuid4().hex[:16] + request.state.request_id = request_id + trace.get_current_span().set_attribute("request.id", request_id) + started = time.perf_counter() + response = await call_next(request) + if request.url.path in _QUIET_PATHS: + return response + route = getattr(request.scope.get("route"), "path", request.url.path) + elapsed = time.perf_counter() - started + metrics.observe(SERVICE_NAME, request.method, route, response.status_code, elapsed) + log.info(f"{request.method} {route} -> {response.status_code} in {elapsed * 1000:.1f} ms", + extra={"request_id": request_id}) + response.headers[REQUEST_ID_HEADER] = request_id + trace_id = current_trace_id() + if trace_id: + response.headers["X-Trace-Id"] = trace_id + return response + + # Instrument AFTER adding the middleware above: Starlette runs the last-added middleware + # outermost, so the tracing middleware wraps ours and the span is active inside it. + from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor + + FastAPIInstrumentor.instrument_app(app, excluded_urls="health,metrics,debug/spans") + + @app.get("/metrics", include_in_schema=False) + async def prometheus_metrics(): + body, content_type = metrics.render() + return Response(content=body, media_type=content_type) + + @app.get("/debug/spans", include_in_schema=False) + async def debug_spans(trace_id: str | None = None): + spans = SPAN_STORE.by_trace(trace_id) if trace_id else SPAN_STORE.recent() + return {"service": SERVICE_NAME, "spans": spans} + + +def upstream_headers(request: Request) -> dict[str, str]: + """Headers to forward to a service: the client's, minus hop-specific ones, plus the request ID.""" + headers = {k: v for k, v in request.headers.items() if k.lower() not in ("host", "content-length")} + headers[REQUEST_ID_HEADER] = request.state.request_id + return headers diff --git a/gateway/app/routers/patterns.py b/gateway/app/routers/patterns.py new file mode 100644 index 0000000..a0a48f4 --- /dev/null +++ b/gateway/app/routers/patterns.py @@ -0,0 +1,177 @@ +"""Live demo endpoints for the pattern pages (patterns 1, 2, 5 and 6). + +Each one calls real services and reports exactly what came back, including failures. +""" +import asyncio +import time + +import httpx +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse +from prometheus_client.parser import text_string_to_metric_families + +from shop_common.telemetry import SPAN_STORE, current_trace_id + +from .. import config +from ..observability import upstream_headers + +router = APIRouter(tags=["patterns"]) + + +async def _call(client: httpx.AsyncClient, service: str, path: str, request: Request, calls: list[dict]) -> 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)) + status = response.status_code + except httpx.HTTPError as exc: + response, status = None, f"unreachable ({exc.__class__.__name__})" + calls.append({"service": service, "path": path, "status": status, + "ms": round((time.perf_counter() - started) * 1000, 1)}) + return response + + +def _client() -> httpx.AsyncClient: + return httpx.AsyncClient(timeout=config.UPSTREAM_TIMEOUT_SECONDS) + + +# --- Pattern 1: Database per Service --------------------------------------------------------- + +@router.get("/api/patterns/databases") +async def databases(request: Request): + calls: list[dict] = [] + async with _client() as client: + names = list(config.SERVICE_BASE_URLS) + responses = await asyncio.gather(*(_call(client, n, "/health/db", request, calls) for n in names)) + results = [] + for name, response in zip(names, responses): + if response is not None and response.status_code == 200: + results.append({**response.json(), "reachable": True}) + else: + results.append({"service": name, "reachable": False}) + return {"services": results} + + +@router.get("/api/patterns/isolation-test") +async def isolation_test(request: Request, table: str = "product"): + calls: list[dict] = [] + async with _client() as client: + response = await _call(client, "order", f"/api/order/isolation-test?table={table}", request, calls) + if response is None: + return JSONResponse({"message": "order service is unreachable"}, status_code=503) + return JSONResponse(response.json(), status_code=response.status_code) + + +# --- Pattern 2: Bounded Context ----------------------------------------------------------------- + +@router.get("/api/patterns/bounded-context/{product_id}") +async def bounded_context(product_id: int, request: Request): + """The same product as two contexts see it: Catalog (what we sell) and Inventory (how many).""" + calls: list[dict] = [] + async with _client() as client: + catalog_resp, inventory_resp = await asyncio.gather( + _call(client, "catalog", "/api/products", request, calls), + _call(client, "inventory", f"/api/inventory/{product_id}", request, calls), + ) + catalog_view = None + if catalog_resp is not None and catalog_resp.status_code == 200: + catalog_view = next((p for p in catalog_resp.json()["results"] if p["id"] == product_id), None) + inventory_view = inventory_resp.json().get("result") if inventory_resp is not None and inventory_resp.status_code == 200 else None + return {"product_id": product_id, "catalog": catalog_view, "inventory": inventory_view, "calls": calls} + + +# --- Pattern 5: API Gateway aggregation ---------------------------------------------------------- + +@router.get("/api/order-summary") +async def order_summary(request: Request): + """One browser call, four service calls: who you are, your cart, product details, stock. + + The user and cart calls run first (the cart says which products matter), then catalog and + inventory run in parallel. + """ + calls: list[dict] = [] + async with _client() as client: + user_resp, cart_resp = await asyncio.gather( + _call(client, "user", "/api/user", request, calls), + _call(client, "order", "/api/order", request, calls), + ) + if user_resp is None or user_resp.status_code != 200: + return JSONResponse({"message": "Not logged in", "calls": calls}, status_code=401) + cart = (cart_resp.json().get("result") if cart_resp is not None and cart_resp.status_code == 200 else None) or {"items": []} + catalog_resp, stock_resp = await asyncio.gather( + _call(client, "catalog", "/api/products", request, calls), + _call(client, "inventory", "/api/inventory", request, calls), + ) + + products = {p["id"]: p for p in (catalog_resp.json()["results"] if catalog_resp is not None and catalog_resp.status_code == 200 else [])} + stock = {s["product_id"]: s for s in (stock_resp.json()["results"] if stock_resp is not None and stock_resp.status_code == 200 else [])} + lines = [] + for item in cart["items"]: + product = products.get(item["product_id"], {}) + lines.append({ + "product_id": item["product_id"], + "name": product.get("name"), + "unit_price_cents": product.get("price"), + "quantity": item["quantity"], + "available": stock.get(item["product_id"], {}).get("available"), + }) + return { + "user": {"username": user_resp.json()["result"]["username"]}, + "lines": lines, + "total_cents": sum((line["unit_price_cents"] or 0) * line["quantity"] for line in lines), + "calls": calls, + "request_id": request.state.request_id, + "trace_id": current_trace_id(), + } + + +# --- Pattern 6: Observability ------------------------------------------------------------------- + +@router.get("/api/observability/trace/{trace_id}") +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) + responses = await asyncio.gather( + *(_call(client, n, f"/debug/spans?trace_id={trace_id}", request, calls) for n in names) + ) + spans = list(SPAN_STORE.by_trace(trace_id)) + for response in responses: + if response is not None and response.status_code == 200: + spans.extend(response.json()["spans"]) + spans.sort(key=lambda s: s["start_ns"]) + return {"trace_id": trace_id, "spans": spans} + + +@router.get("/api/observability/metrics") +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)) + summary = [] + for name, response in zip(names, responses): + if response is None or response.status_code != 200: + 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 sample in family.samples: + if sample.name == "shop_http_requests_total": + requests_total += sample.value + if sample.labels.get("status", "").startswith("5"): + errors += sample.value + elif sample.name == "shop_http_request_duration_seconds_sum": + latency_sum += sample.value + elif sample.name == "shop_http_request_duration_seconds_count": + latency_count += sample.value + summary.append({ + "service": name, + "reachable": True, + "requests": int(requests_total), + "errors_5xx": int(errors), + "avg_ms": round(latency_sum / latency_count * 1000, 1) if latency_count else None, + }) + return {"services": summary} diff --git a/gateway/app/routers/shop.py b/gateway/app/routers/shop.py index b1f1d16..345bfcc 100644 --- a/gateway/app/routers/shop.py +++ b/gateway/app/routers/shop.py @@ -1,7 +1,8 @@ """Reverse proxy: /api/shop/ -> /api/ on the service that owns . The owner is picked from the first path segment (config.ROUTE_OWNERS), e.g. -/api/shop/products -> catalog, /api/shop/order/checkout -> order. +/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. """ import json @@ -9,6 +10,7 @@ from fastapi import APIRouter, Request, Response from .. import config +from ..observability import upstream_headers router = APIRouter(prefix="/api/shop", tags=["shop"]) @@ -21,18 +23,18 @@ def _error(status: int, message: str) -> Response: return Response(content=json.dumps({"message": message}), status_code=status, media_type="application/json") -@router.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"]) +@router.api_route("/{path:path}", methods=["GET", "POST"]) async def proxy(path: str, request: Request) -> Response: owner = owner_of(path) if owner is None: return _error(404, f"No service owns path '{path}'") url = f"{config.SERVICE_BASE_URLS[owner]}/api/{path}" - headers = {k: v for k, v in request.headers.items() if k.lower() not in ("host", "content-length")} try: - async with httpx.AsyncClient(timeout=10) as client: + async with httpx.AsyncClient(timeout=config.UPSTREAM_TIMEOUT_SECONDS) as client: upstream = await client.request( - request.method, url, headers=headers, params=request.query_params, content=await request.body() + 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__}") diff --git a/gateway/requirements.txt b/gateway/requirements.txt index bc8cb0f..e210bd8 100644 --- a/gateway/requirements.txt +++ b/gateway/requirements.txt @@ -2,3 +2,4 @@ fastapi==0.115.6 uvicorn[standard]==0.32.1 httpx==0.28.1 python-dotenv==1.0.1 +opentelemetry-instrumentation-fastapi==0.50b0 diff --git a/gateway/tests/test_api.py b/gateway/tests/test_api.py index 869ab00..b0f9746 100644 --- a/gateway/tests/test_api.py +++ b/gateway/tests/test_api.py @@ -17,7 +17,9 @@ def test_routes_each_path_to_its_owning_service(): assert owner_of("product/create") == "catalog" assert owner_of("user/login") == "user" assert owner_of("order/checkout") == "order" - assert owner_of("payments/charge") is None + assert owner_of("payment/charge") == "payment" + assert owner_of("inventory/3") == "inventory" + assert owner_of("admin/secrets") is None def test_unknown_path_returns_404(): @@ -34,7 +36,30 @@ def test_unreachable_service_returns_503(monkeypatch): assert "catalog" in r.json()["message"] -def test_services_lists_all_three(): +def test_services_lists_all_five(): r = client.get("/api/services") assert r.status_code == 200 - assert set(r.json()) == {"user", "catalog", "order"} + assert set(r.json()) == {"user", "catalog", "order", "payment", "inventory"} + + +def test_every_response_carries_a_request_id_and_echoes_the_clients(): + assert len(client.get("/api/services").headers["X-Request-Id"]) == 16 + assert client.get("/api/services", headers={"X-Request-Id": "abc123"}).headers["X-Request-Id"] == "abc123" + + +def test_traced_responses_carry_a_trace_id(): + assert len(client.get("/api/services").headers["X-Trace-Id"]) == 32 + + +def test_delete_is_not_proxied(): + assert client.delete("/api/shop/product/contoso-mug").status_code == 405 + + +def test_order_summary_requires_login(monkeypatch): + from app import config + + for name in config.SERVICE_BASE_URLS: + monkeypatch.setitem(config.SERVICE_BASE_URLS, name, "http://127.0.0.1:9") + r = client.get("/api/order-summary") + assert r.status_code == 401 + assert {c["service"] for c in r.json()["calls"]} == {"user", "order"} diff --git a/infra/bicep/main.bicep b/infra/bicep/main.bicep index 4978d5e..64737da 100644 --- a/infra/bicep/main.bicep +++ b/infra/bicep/main.bicep @@ -1,7 +1,8 @@ @description(''' Deploys the whole stack: ACR (Basic), Container Apps Environment (Consumption), MySQL Flexible Server (Burstable B1ms, one logical DB per service), a Static Web App (Free) for the React -frontend, and one Container App per service (user, catalog, order) plus the API gateway. +frontend, and one Container App per service (user, catalog, order, payment, inventory) plus +the API gateway. Every SKU is the cheapest tier that meets the need. Names are resolved by infra/provision.py BEFORE this deployment runs, after checking for collisions. ''') @@ -138,6 +139,42 @@ module order 'modules/container-app.bicep' = { } } +module payment 'modules/container-app.bicep' = { + name: 'payment' + params: { + location: location + name: 'payment' + environmentId: containerAppsEnv.outputs.environmentId + acrLoginServer: acr.outputs.loginServer + acrUsername: acr.outputs.registryName + acrPassword: acrPassword + mysqlAdminPassword: mysqlAdminPassword + imageName: 'payment' + imageTag: imageTag + targetPort: 5104 + minReplicas: minReplicas + envVars: commonEnv + } +} + +module inventory 'modules/container-app.bicep' = { + name: 'inventory' + params: { + location: location + name: 'inventory' + environmentId: containerAppsEnv.outputs.environmentId + acrLoginServer: acr.outputs.loginServer + acrUsername: acr.outputs.registryName + acrPassword: acrPassword + mysqlAdminPassword: mysqlAdminPassword + imageName: 'inventory' + imageTag: imageTag + targetPort: 5105 + minReplicas: minReplicas + envVars: commonEnv + } +} + module gateway 'modules/container-app.bicep' = { name: 'gateway' params: { @@ -157,6 +194,8 @@ module gateway 'modules/container-app.bicep' = { { name: 'USER_SERVICE_BASE_URL', value: 'https://${user.outputs.fqdn}' } { name: 'CATALOG_SERVICE_BASE_URL', value: 'https://${catalog.outputs.fqdn}' } { name: 'ORDER_SERVICE_BASE_URL', value: 'https://${order.outputs.fqdn}' } + { name: 'PAYMENT_SERVICE_BASE_URL', value: 'https://${payment.outputs.fqdn}' } + { name: 'INVENTORY_SERVICE_BASE_URL', value: 'https://${inventory.outputs.fqdn}' } { name: 'FRONTEND_ORIGIN', value: 'https://${staticWebApp.outputs.defaultHostname}' } ] } diff --git a/infra/bicep/modules/container-app.bicep b/infra/bicep/modules/container-app.bicep index 7bf0705..5fc55f7 100644 --- a/infra/bicep/modules/container-app.bicep +++ b/infra/bicep/modules/container-app.bicep @@ -1,4 +1,4 @@ -@description('One reusable Container App module — instantiated once per service from main.bicep (user, catalog, order, gateway). Explicit cheap defaults: Consumption plan, minReplicas 0 (scale-to-zero), 0.25 vCPU / 0.5Gi.') +@description('One reusable Container App module — instantiated once per service from main.bicep (user, catalog, order, payment, inventory, gateway). Explicit cheap defaults: Consumption plan, minReplicas 0 (scale-to-zero), 0.25 vCPU / 0.5Gi.') param location string param name string param environmentId string diff --git a/infra/bicep/modules/mysql.bicep b/infra/bicep/modules/mysql.bicep index 8c14db4..900043c 100644 --- a/infra/bicep/modules/mysql.bicep +++ b/infra/bicep/modules/mysql.bicep @@ -4,7 +4,7 @@ param name string param adminUsername string @secure() param adminPassword string -param databaseNames array = ['user_db', 'catalog_db', 'order_db'] +param databaseNames array = ['user_db', 'catalog_db', 'order_db', 'payment_db', 'inventory_db'] resource server 'Microsoft.DBforMySQL/flexibleServers@2023-12-30' = { name: name diff --git a/infra/provision.py b/infra/provision.py index f5c811d..b8690c4 100644 --- a/infra/provision.py +++ b/infra/provision.py @@ -20,6 +20,7 @@ import os import secrets import string +import shutil import subprocess import sys import time @@ -192,15 +193,27 @@ def wait_for_acr_ready(resource_group: str, acr_name: str, timeout: float = 60.0 def build_images(resource_group: str, acr_name: str) -> None: for service_name, service_dir in SERVICES.items(): print(f"\n=== az acr build: {service_name} (cloud-side, no local Docker) ===") - run_az([ - "acr", "build", - "--registry", acr_name, - "--resource-group", resource_group, - "--image", f"{service_name}:latest", - # Explicit: Container Apps runs amd64, and the owner's Mac is arm64. - "--platform", "linux/amd64", - str(service_dir), - ], capture=False) + # `az acr build` only uploads the service's own folder, so stage a copy of shared/ + # (shop_common) inside it as _shared/. Each Dockerfile installs ./_shared. Gitignored. + staged = service_dir / "_shared" + shutil.rmtree(staged, ignore_errors=True) + shutil.copytree(REPO_ROOT / "shared", staged, ignore=shutil.ignore_patterns("*.egg-info", "__pycache__")) + try: + _acr_build(resource_group, acr_name, service_name, service_dir) + finally: + shutil.rmtree(staged, ignore_errors=True) + + +def _acr_build(resource_group: str, acr_name: str, service_name: str, service_dir: Path) -> None: + run_az([ + "acr", "build", + "--registry", acr_name, + "--resource-group", resource_group, + "--image", f"{service_name}:latest", + # Explicit: Container Apps runs amd64, and the owner's Mac is arm64. + "--platform", "linux/amd64", + str(service_dir), + ], capture=False) def deploy_bicep(resource_group: str, location: str, names: dict, mysql_password: str, keep_warm: bool) -> dict: diff --git a/infra/verify_teardown.py b/infra/verify_teardown.py index 555c194..397ddf3 100644 --- a/infra/verify_teardown.py +++ b/infra/verify_teardown.py @@ -36,7 +36,7 @@ def main() -> int: if not resource_group_exists(resource_group): print(f"PASS: resource group '{resource_group}' no longer exists.") print("This confirms ACR, Container Apps Environment + every Container App (user, catalog, " - "order, gateway), MySQL " + "order, payment, inventory, gateway), MySQL " "Flexible Server, and the Static Web App were all deleted with it.") STATE_FILE.unlink() print(f"Removed {STATE_FILE}.") diff --git a/scripts/service_table.py b/scripts/service_table.py index 11a11c8..04fd11a 100644 --- a/scripts/service_table.py +++ b/scripts/service_table.py @@ -32,10 +32,14 @@ def local_url(self) -> str: Service("user", REPO_ROOT / "services" / "user", 5101, "USER_SERVICE_PORT", "flask"), Service("catalog", REPO_ROOT / "services" / "catalog", 5102, "CATALOG_SERVICE_PORT", "flask"), Service("order", REPO_ROOT / "services" / "order", 5103, "ORDER_SERVICE_PORT", "flask"), + Service("payment", REPO_ROOT / "services" / "payment", 5104, "PAYMENT_SERVICE_PORT", "flask"), + Service("inventory", REPO_ROOT / "services" / "inventory", 5105, "INVENTORY_SERVICE_PORT", "flask"), ] GATEWAY = Service("gateway", REPO_ROOT / "gateway", 8100, "GATEWAY_PORT", "fastapi") PYTHON_SERVICES = FLASK_SERVICES + [GATEWAY] +# shop_common (shared/), installed into every Python venv by setup.py. +SHARED_DIR = REPO_ROOT / "shared" FRONTEND_DIR = REPO_ROOT / "frontend" FRONTEND_PORT = int(os.environ.get("FRONTEND_PORT", 5273)) diff --git a/scripts/setup.py b/scripts/setup.py index 1edb4ab..a65ff74 100644 --- a/scripts/setup.py +++ b/scripts/setup.py @@ -14,7 +14,7 @@ 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 # noqa: E402 +from service_table import FRONTEND_DIR, FRONTEND_PORT, PYTHON_SERVICES, SHARED_DIR # noqa: E402 MIN_PYTHON = (3, 12) @@ -115,6 +115,9 @@ def main() -> int: # can transiently fail with FileNotFoundError before the new script is fully in place. venv_python = service_dir / ".venv" / "bin" / "python" subprocess.run([str(venv_python), "-m", "pip", "install", "pytest==8.3.4", "-q"], check=True) + # 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) install_frontend() print("\nSetup complete. Run `make run` (or `python scripts/run_local.py`) next.") diff --git a/services/catalog/Dockerfile b/services/catalog/Dockerfile index 5a9fed6..beafb77 100644 --- a/services/catalog/Dockerfile +++ b/services/catalog/Dockerfile @@ -7,6 +7,8 @@ COPY requirements.txt . RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" ENV RUN_MODE=azure \ FLASK_ENV=production \ @@ -14,4 +16,5 @@ ENV RUN_MODE=azure \ EXPOSE 5102 -CMD ["gunicorn", "--bind", "0.0.0.0:5102", "--workers", "2", "run:app"] +# One process with threads, so the in-memory span store (pattern 6) sees every request. +CMD ["gunicorn", "--bind", "0.0.0.0:5102", "--workers", "1", "--threads", "4", "run:app"] diff --git a/services/catalog/application/__init__.py b/services/catalog/application/__init__.py index b78852f..ba12c1b 100644 --- a/services/catalog/application/__init__.py +++ b/services/catalog/application/__init__.py @@ -2,6 +2,7 @@ import os from flask import Flask +from shop_common.flask_support import install as install_observability from flask_sqlalchemy import SQLAlchemy from flask_migrate import Migrate @@ -32,8 +33,7 @@ def create_app(config_name: str | None = None) -> Flask: seed_products_if_empty() - @app.get("/health") - def health(): - return {"status": "ok", "service": "catalog-service"} + # /health, /health/db, /debug/spans, /metrics, tracing and JSON logs (patterns 1 and 6). + install_observability(app, "catalog", db) return app diff --git a/services/catalog/application/product_api/routes.py b/services/catalog/application/product_api/routes.py index 41e0212..7ec9826 100644 --- a/services/catalog/application/product_api/routes.py +++ b/services/catalog/application/product_api/routes.py @@ -31,15 +31,3 @@ def product(slug): return make_response(jsonify({"message": "Cannot find product"}), 404) return jsonify({"result": item.to_json()}) - -@product_api_blueprint.route("/api/product/", methods=["DELETE"]) -def delete_product(slug): - """Lets scripts/benchmark.py clean up the throwaway products it creates - to measure create_product latency, instead of leaving hundreds of - 'bench-*' rows permanently cluttering the Shop catalog.""" - item = Product.query.filter_by(slug=slug).first() - if item is None: - return make_response(jsonify({"message": "Cannot find product"}), 404) - db.session.delete(item) - db.session.commit() - return jsonify({"message": "Product deleted"}) diff --git a/services/catalog/requirements.txt b/services/catalog/requirements.txt index eca3898..a12dc90 100644 --- a/services/catalog/requirements.txt +++ b/services/catalog/requirements.txt @@ -6,3 +6,4 @@ PyMySQL==1.1.1 python-dotenv==1.0.1 gunicorn==23.0.0 pydantic==2.10.3 +opentelemetry-instrumentation-flask==0.50b0 diff --git a/services/inventory/Dockerfile b/services/inventory/Dockerfile new file mode 100644 index 0000000..0c0ab19 --- /dev/null +++ b/services/inventory/Dockerfile @@ -0,0 +1,20 @@ +# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. +FROM python:3.12-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt + +COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" + +ENV RUN_MODE=azure \ + FLASK_ENV=production \ + PYTHONUNBUFFERED=1 + +EXPOSE 5105 + +# One process with threads, so the in-memory span store (pattern 6) sees every request. +CMD ["gunicorn", "--bind", "0.0.0.0:5105", "--workers", "1", "--threads", "4", "run:app"] diff --git a/services/inventory/application/__init__.py b/services/inventory/application/__init__.py new file mode 100644 index 0000000..a497636 --- /dev/null +++ b/services/inventory/application/__init__.py @@ -0,0 +1,38 @@ +"""inventory service — owns stock levels and its own database. + +Bounded context (pattern 2): Inventory does not know a product's name or price. It knows a +StockItem keyed by the catalog's product_id, with how many are on hand and how many are reserved. +Catalog owns "what we sell"; Inventory owns "how many we have". +""" +import os + +from flask import Flask +from flask_migrate import Migrate +from flask_sqlalchemy import SQLAlchemy +from shop_common.flask_support import install as install_observability + +db = SQLAlchemy() +migrate = Migrate() + + +def create_app(config_name: str | None = None) -> Flask: + from config import CONFIG_BY_NAME + + config_name = config_name or os.environ.get("FLASK_ENV", "development") + app = Flask(__name__) + app.config.from_object(CONFIG_BY_NAME[config_name]) + + db.init_app(app) + migrate.init_app(app, db) + + with app.app_context(): + from . import models # noqa: F401 + from .routes import inventory_api + + app.register_blueprint(inventory_api) + db.create_all() + from .seed import seed_stock_if_empty + + seed_stock_if_empty() + install_observability(app, "inventory", db) + return app diff --git a/services/inventory/application/models.py b/services/inventory/application/models.py new file mode 100644 index 0000000..4ca5a28 --- /dev/null +++ b/services/inventory/application/models.py @@ -0,0 +1,23 @@ +from . import db + + +class StockItem(db.Model): + __tablename__ = "stock_item" + + # The catalog's product id. Not a foreign key: the product table lives in another service's + # database, so referential integrity across services is a business rule, not a DB constraint. + product_id = db.Column(db.Integer, primary_key=True, autoincrement=False) + on_hand = db.Column(db.Integer, nullable=False, default=0) + reserved = db.Column(db.Integer, nullable=False, default=0) + + @property + def available(self) -> int: + return self.on_hand - self.reserved + + def to_json(self): + return { + "product_id": self.product_id, + "on_hand": self.on_hand, + "reserved": self.reserved, + "available": self.available, + } diff --git a/services/inventory/application/routes.py b/services/inventory/application/routes.py new file mode 100644 index 0000000..e3cb0cc --- /dev/null +++ b/services/inventory/application/routes.py @@ -0,0 +1,19 @@ +from flask import Blueprint, jsonify, make_response + +from . import db +from .models import StockItem + +inventory_api = Blueprint("inventory_api", __name__) + + +@inventory_api.get("/api/inventory") +def list_stock(): + return jsonify({"results": [s.to_json() for s in StockItem.query.order_by(StockItem.product_id)]}) + + +@inventory_api.get("/api/inventory/") +def get_stock(product_id: int): + item = db.session.get(StockItem, product_id) + if item is None: + return make_response(jsonify({"message": f"No stock record for product {product_id}"}), 404) + return jsonify({"result": item.to_json()}) diff --git a/services/inventory/application/seed.py b/services/inventory/application/seed.py new file mode 100644 index 0000000..11cfbb4 --- /dev/null +++ b/services/inventory/application/seed.py @@ -0,0 +1,13 @@ +"""Seeds stock for the catalog's 6 sample products (ids 1-6) on first local start. Idempotent.""" +from . import db +from .models import StockItem + +SAMPLE_STOCK = {1: 25, 2: 40, 3: 60, 4: 15, 5: 10, 6: 30} + + +def seed_stock_if_empty() -> None: + if StockItem.query.first() is not None: + return + for product_id, on_hand in SAMPLE_STOCK.items(): + db.session.add(StockItem(product_id=product_id, on_hand=on_hand, reserved=0)) + db.session.commit() diff --git a/services/inventory/config.py b/services/inventory/config.py new file mode 100644 index 0000000..0827781 --- /dev/null +++ b/services/inventory/config.py @@ -0,0 +1,48 @@ +"""RUN_MODE=local -> SQLite file. RUN_MODE=azure -> Azure Database for MySQL (own logical DB).""" +import os +from pathlib import Path +import ssl +from urllib.parse import quote_plus + +BASE_DIR = Path(__file__).resolve().parent +RUN_MODE = os.environ.get("RUN_MODE", "local") + + +def _sqlite_uri() -> str: + db_path = os.environ.get("INVENTORY_DB_PATH", "instance/inventory.sqlite3") + abs_path = BASE_DIR / db_path if not Path(db_path).is_absolute() else Path(db_path) + abs_path.parent.mkdir(parents=True, exist_ok=True) + return f"sqlite:///{abs_path}" + + +def _mysql_uri() -> str: + host = os.environ["AZURE_MYSQL_HOST"] + port = os.environ.get("AZURE_MYSQL_PORT", "3306") + user = quote_plus(os.environ["AZURE_MYSQL_ADMIN_USER"]) + # generate_mysql_password() in infra/provision.py includes URI-reserved + # characters (@ $ % ^ etc.) — quote_plus is required or the URL parser + # misreads part of the password as the host. + password = quote_plus(os.environ["AZURE_MYSQL_ADMIN_PASSWORD"]) + # No ?ssl_mode=REQUIRED — that's a mysql-connector-python/mysqlclient + # param name, not PyMySQL's; SQLAlchemy passes URI query params straight + # through as DBAPI connect() kwargs, which raised a real TypeError. + return f"mysql+pymysql://{user}:{password}@{host}:{port}/inventory_db" + + +class Config: + SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-key-change-me") + SQLALCHEMY_TRACK_MODIFICATIONS = False + SQLALCHEMY_DATABASE_URI = _mysql_uri() if RUN_MODE == "azure" else _sqlite_uri() + if RUN_MODE == "azure": + SQLALCHEMY_ENGINE_OPTIONS = {"connect_args": {"ssl": ssl.create_default_context()}} + + +class DevelopmentConfig(Config): + DEBUG = True + + +class ProductionConfig(Config): + DEBUG = False + + +CONFIG_BY_NAME = {"development": DevelopmentConfig, "production": ProductionConfig} diff --git a/services/inventory/requirements.txt b/services/inventory/requirements.txt new file mode 100644 index 0000000..a12dc90 --- /dev/null +++ b/services/inventory/requirements.txt @@ -0,0 +1,9 @@ +Flask==3.1.0 +Flask-SQLAlchemy==3.1.1 +Flask-Migrate==4.0.7 +SQLAlchemy==2.0.36 +PyMySQL==1.1.1 +python-dotenv==1.0.1 +gunicorn==23.0.0 +pydantic==2.10.3 +opentelemetry-instrumentation-flask==0.50b0 diff --git a/services/inventory/run.py b/services/inventory/run.py new file mode 100644 index 0000000..64c6e1a --- /dev/null +++ b/services/inventory/run.py @@ -0,0 +1,14 @@ +"""Entry point for the inventory service. Run with: python run.py""" +import os +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from application import create_app # noqa: E402 + +app = create_app() + +if __name__ == "__main__": + port = int(os.environ.get("INVENTORY_SERVICE_PORT", 5105)) + app.run(host="0.0.0.0", port=port, debug=app.config.get("DEBUG", False)) diff --git a/services/inventory/tests/conftest.py b/services/inventory/tests/conftest.py new file mode 100644 index 0000000..94cf1de --- /dev/null +++ b/services/inventory/tests/conftest.py @@ -0,0 +1,47 @@ +import os +import sys +from pathlib import Path + +import pytest + +SERVICE_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(SERVICE_ROOT)) + +os.environ.setdefault("RUN_MODE", "local") +os.environ.setdefault("FLASK_ENV", "development") +os.environ.setdefault("SECRET_KEY", "test-secret") +TEST_DB_PATH = "instance/test_inventory.sqlite3" +os.environ["INVENTORY_DB_PATH"] = TEST_DB_PATH + + +@pytest.fixture +def app(): + from application import create_app, db + + flask_app = create_app("development") + with flask_app.app_context(): + db.drop_all() + db.create_all() + yield flask_app + db.session.remove() + db.drop_all() + + +@pytest.fixture +def client(app): + return app.test_client() + + +@pytest.fixture(scope="session", autouse=True) +def _cleanup_test_db(): + """Removes only this test suite's own db file (and its SQLite sidecar + files), never the whole instance/ directory — that directory can also + hold the real app's live database if `make run` is active alongside + `make test`, and rmtree-ing it out from under a running process breaks + it (SQLite can no longer create journal/WAL files once the directory is + gone, surfacing as a confusing 'attempt to write a readonly database'). + This was a real bug, found by deleting a live dev database this way.""" + yield + base = SERVICE_ROOT / TEST_DB_PATH + for suffix in ("", "-journal", "-wal", "-shm"): + Path(f"{base}{suffix}").unlink(missing_ok=True) diff --git a/services/inventory/tests/test_inventory.py b/services/inventory/tests/test_inventory.py new file mode 100644 index 0000000..d16d86a --- /dev/null +++ b/services/inventory/tests/test_inventory.py @@ -0,0 +1,26 @@ +from application.models import StockItem +from application.seed import SAMPLE_STOCK, seed_stock_if_empty + + +def test_available_is_on_hand_minus_reserved(): + assert StockItem(product_id=1, on_hand=10, reserved=3).available == 7 + + +def test_seed_is_idempotent(app): + seed_stock_if_empty() + seed_stock_if_empty() + assert StockItem.query.count() == len(SAMPLE_STOCK) + + +def test_get_stock_and_404(client): + seed_stock_if_empty() + r = client.get("/api/inventory/1") + assert r.status_code == 200 + assert r.get_json()["result"]["on_hand"] == SAMPLE_STOCK[1] + assert client.get("/api/inventory/999").status_code == 404 + + +def test_health_db_reports_only_own_tables(client): + body = client.get("/health/db").get_json() + assert body["service"] == "inventory" + assert body["tables"] == ["stock_item"] diff --git a/services/order/Dockerfile b/services/order/Dockerfile index 3a36fa1..906945d 100644 --- a/services/order/Dockerfile +++ b/services/order/Dockerfile @@ -7,6 +7,8 @@ COPY requirements.txt . RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" ENV RUN_MODE=azure \ FLASK_ENV=production \ @@ -14,4 +16,5 @@ ENV RUN_MODE=azure \ EXPOSE 5103 -CMD ["gunicorn", "--bind", "0.0.0.0:5103", "--workers", "2", "run:app"] +# One process with threads, so the in-memory span store (pattern 6) sees every request. +CMD ["gunicorn", "--bind", "0.0.0.0:5103", "--workers", "1", "--threads", "4", "run:app"] diff --git a/services/order/application/__init__.py b/services/order/application/__init__.py index dcb4dbf..7ec3ce2 100644 --- a/services/order/application/__init__.py +++ b/services/order/application/__init__.py @@ -8,6 +8,7 @@ import os from flask import Flask +from shop_common.flask_support import install as install_observability from flask_sqlalchemy import SQLAlchemy from flask_migrate import Migrate @@ -35,8 +36,7 @@ def create_app(config_name: str | None = None) -> Flask: # this to local-only left Azure MySQL with no schema at all). db.create_all() - @app.get("/health") - def health(): - return {"status": "ok", "service": "order-service"} + # /health, /health/db, /debug/spans, /metrics, tracing and JSON logs (patterns 1 and 6). + install_observability(app, "order", db) return app diff --git a/services/order/application/order_api/routes.py b/services/order/application/order_api/routes.py index 268d9e2..93129e3 100644 --- a/services/order/application/order_api/routes.py +++ b/services/order/application/order_api/routes.py @@ -73,3 +73,32 @@ def checkout(): db.session.add(order_model) db.session.commit() return jsonify({"result": order_model.to_json()}) + + +# Pattern 1 demo: each service only has its own tables. This tries to read another service's +# table through the order service's own database connection, and reports what really happens. +# Table names come from a fixed allow-list, never from raw user input, so no SQL injection. +FOREIGN_TABLES = {"product": "catalog", "stock_item": "inventory", "payment": "payment", "user": "user"} + + +@order_api_blueprint.route("/api/order/isolation-test", methods=["GET"]) +def isolation_test(): + from sqlalchemy import inspect, text + + table = request.args.get("table", "product") + if table not in FOREIGN_TABLES: + return make_response(jsonify({"message": f"table must be one of {sorted(FOREIGN_TABLES)}"}), 400) + # Quote for the real dialect: double quotes on SQLite, backticks on MySQL. + sql = f"SELECT COUNT(*) FROM {db.engine.dialect.identifier_preparer.quote(table)}" + result = { + "attempted": sql, + "owner": FOREIGN_TABLES[table], + "order_tables": sorted(inspect(db.engine).get_table_names()), + } + try: + db.session.execute(text(sql)) + result.update(blocked=False, error=None) + except Exception as exc: # the expected outcome: the table does not exist in order_db + db.session.rollback() + result.update(blocked=True, error=str(getattr(exc, "orig", exc))) + return jsonify(result) diff --git a/services/order/requirements.txt b/services/order/requirements.txt index cad9201..d539586 100644 --- a/services/order/requirements.txt +++ b/services/order/requirements.txt @@ -7,3 +7,4 @@ requests==2.32.3 python-dotenv==1.0.1 gunicorn==23.0.0 pydantic==2.10.3 +opentelemetry-instrumentation-flask==0.50b0 diff --git a/services/order/tests/test_models_and_schemas.py b/services/order/tests/test_models_and_schemas.py index ffce603..ebafaad 100644 --- a/services/order/tests/test_models_and_schemas.py +++ b/services/order/tests/test_models_and_schemas.py @@ -28,3 +28,14 @@ def test_order_add_item_rejects_non_positive_qty(): def test_order_add_item_accepts_valid_payload(): req = OrderAddItemRequest(product_id=1, qty=3) assert req.qty == 3 + + +def test_order_cannot_read_another_services_table(client): + body = client.get("/api/order/isolation-test?table=product").get_json() + assert body["blocked"] is True + assert body["owner"] == "catalog" + assert "product" not in body["order_tables"] + + +def test_isolation_test_rejects_unknown_tables(client): + assert client.get("/api/order/isolation-test?table=sqlite_master").status_code == 400 diff --git a/services/payment/Dockerfile b/services/payment/Dockerfile new file mode 100644 index 0000000..a4aec98 --- /dev/null +++ b/services/payment/Dockerfile @@ -0,0 +1,20 @@ +# Built exclusively via `az acr build` (cloud-side) — no local Docker daemon required. +FROM python:3.12-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt + +COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" + +ENV RUN_MODE=azure \ + FLASK_ENV=production \ + PYTHONUNBUFFERED=1 + +EXPOSE 5104 + +# One process with threads, so the in-memory span store (pattern 6) sees every request. +CMD ["gunicorn", "--bind", "0.0.0.0:5104", "--workers", "1", "--threads", "4", "run:app"] diff --git a/services/payment/application/__init__.py b/services/payment/application/__init__.py new file mode 100644 index 0000000..f1c2782 --- /dev/null +++ b/services/payment/application/__init__.py @@ -0,0 +1,34 @@ +"""payment service — owns payment records and its own database. + +Bounded context (pattern 2): Payment knows an order only by its id and an amount in cents. It +never sees products, carts or users. M3 makes it the step of the checkout saga that can fail. +""" +import os + +from flask import Flask +from flask_migrate import Migrate +from flask_sqlalchemy import SQLAlchemy +from shop_common.flask_support import install as install_observability + +db = SQLAlchemy() +migrate = Migrate() + + +def create_app(config_name: str | None = None) -> Flask: + from config import CONFIG_BY_NAME + + config_name = config_name or os.environ.get("FLASK_ENV", "development") + app = Flask(__name__) + app.config.from_object(CONFIG_BY_NAME[config_name]) + + db.init_app(app) + migrate.init_app(app, db) + + with app.app_context(): + from . import models # noqa: F401 + from .routes import payment_api + + app.register_blueprint(payment_api) + db.create_all() + install_observability(app, "payment", db) + return app diff --git a/services/payment/application/models.py b/services/payment/application/models.py new file mode 100644 index 0000000..4768d7e --- /dev/null +++ b/services/payment/application/models.py @@ -0,0 +1,26 @@ +from datetime import datetime, timezone + +from . import db + + +def _utcnow(): + return datetime.now(timezone.utc) + + +class Payment(db.Model): + __tablename__ = "payment" + + id = db.Column(db.Integer, primary_key=True) + order_id = db.Column(db.Integer, nullable=False, index=True) # the order service's id; no cross-DB FK + amount_cents = db.Column(db.Integer, nullable=False) + status = db.Column(db.String(20), nullable=False) # APPROVED | DECLINED + created_at = db.Column(db.DateTime, default=_utcnow) + + def to_json(self): + return { + "id": self.id, + "order_id": self.order_id, + "amount_cents": self.amount_cents, + "status": self.status, + "created_at": self.created_at.isoformat() if self.created_at else None, + } diff --git a/services/payment/application/routes.py b/services/payment/application/routes.py new file mode 100644 index 0000000..30b7b15 --- /dev/null +++ b/services/payment/application/routes.py @@ -0,0 +1,29 @@ +from flask import Blueprint, jsonify, make_response, request +from pydantic import BaseModel, Field, ValidationError + +from . import db +from .models import Payment + +payment_api = Blueprint("payment_api", __name__) + + +class ChargeRequest(BaseModel): + order_id: int = Field(gt=0) + amount_cents: int = Field(gt=0) + + +@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.post("/api/payment/charge") +def charge(): + try: + data = ChargeRequest.model_validate(request.form.to_dict()) + 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()}) diff --git a/services/payment/config.py b/services/payment/config.py new file mode 100644 index 0000000..ca6df36 --- /dev/null +++ b/services/payment/config.py @@ -0,0 +1,48 @@ +"""RUN_MODE=local -> SQLite file. RUN_MODE=azure -> Azure Database for MySQL (own logical DB).""" +import os +from pathlib import Path +import ssl +from urllib.parse import quote_plus + +BASE_DIR = Path(__file__).resolve().parent +RUN_MODE = os.environ.get("RUN_MODE", "local") + + +def _sqlite_uri() -> str: + db_path = os.environ.get("PAYMENT_DB_PATH", "instance/payment.sqlite3") + abs_path = BASE_DIR / db_path if not Path(db_path).is_absolute() else Path(db_path) + abs_path.parent.mkdir(parents=True, exist_ok=True) + return f"sqlite:///{abs_path}" + + +def _mysql_uri() -> str: + host = os.environ["AZURE_MYSQL_HOST"] + port = os.environ.get("AZURE_MYSQL_PORT", "3306") + user = quote_plus(os.environ["AZURE_MYSQL_ADMIN_USER"]) + # generate_mysql_password() in infra/provision.py includes URI-reserved + # characters (@ $ % ^ etc.) — quote_plus is required or the URL parser + # misreads part of the password as the host. + password = quote_plus(os.environ["AZURE_MYSQL_ADMIN_PASSWORD"]) + # No ?ssl_mode=REQUIRED — that's a mysql-connector-python/mysqlclient + # param name, not PyMySQL's; SQLAlchemy passes URI query params straight + # through as DBAPI connect() kwargs, which raised a real TypeError. + return f"mysql+pymysql://{user}:{password}@{host}:{port}/payment_db" + + +class Config: + SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-key-change-me") + SQLALCHEMY_TRACK_MODIFICATIONS = False + SQLALCHEMY_DATABASE_URI = _mysql_uri() if RUN_MODE == "azure" else _sqlite_uri() + if RUN_MODE == "azure": + SQLALCHEMY_ENGINE_OPTIONS = {"connect_args": {"ssl": ssl.create_default_context()}} + + +class DevelopmentConfig(Config): + DEBUG = True + + +class ProductionConfig(Config): + DEBUG = False + + +CONFIG_BY_NAME = {"development": DevelopmentConfig, "production": ProductionConfig} diff --git a/services/payment/requirements.txt b/services/payment/requirements.txt new file mode 100644 index 0000000..a12dc90 --- /dev/null +++ b/services/payment/requirements.txt @@ -0,0 +1,9 @@ +Flask==3.1.0 +Flask-SQLAlchemy==3.1.1 +Flask-Migrate==4.0.7 +SQLAlchemy==2.0.36 +PyMySQL==1.1.1 +python-dotenv==1.0.1 +gunicorn==23.0.0 +pydantic==2.10.3 +opentelemetry-instrumentation-flask==0.50b0 diff --git a/services/payment/run.py b/services/payment/run.py new file mode 100644 index 0000000..81a9267 --- /dev/null +++ b/services/payment/run.py @@ -0,0 +1,14 @@ +"""Entry point for the payment service. Run with: python run.py""" +import os +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +from application import create_app # noqa: E402 + +app = create_app() + +if __name__ == "__main__": + port = int(os.environ.get("PAYMENT_SERVICE_PORT", 5104)) + app.run(host="0.0.0.0", port=port, debug=app.config.get("DEBUG", False)) diff --git a/services/payment/tests/conftest.py b/services/payment/tests/conftest.py new file mode 100644 index 0000000..0d56fcc --- /dev/null +++ b/services/payment/tests/conftest.py @@ -0,0 +1,47 @@ +import os +import sys +from pathlib import Path + +import pytest + +SERVICE_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(SERVICE_ROOT)) + +os.environ.setdefault("RUN_MODE", "local") +os.environ.setdefault("FLASK_ENV", "development") +os.environ.setdefault("SECRET_KEY", "test-secret") +TEST_DB_PATH = "instance/test_payment.sqlite3" +os.environ["PAYMENT_DB_PATH"] = TEST_DB_PATH + + +@pytest.fixture +def app(): + from application import create_app, db + + flask_app = create_app("development") + with flask_app.app_context(): + db.drop_all() + db.create_all() + yield flask_app + db.session.remove() + db.drop_all() + + +@pytest.fixture +def client(app): + return app.test_client() + + +@pytest.fixture(scope="session", autouse=True) +def _cleanup_test_db(): + """Removes only this test suite's own db file (and its SQLite sidecar + files), never the whole instance/ directory — that directory can also + hold the real app's live database if `make run` is active alongside + `make test`, and rmtree-ing it out from under a running process breaks + it (SQLite can no longer create journal/WAL files once the directory is + gone, surfacing as a confusing 'attempt to write a readonly database'). + This was a real bug, found by deleting a live dev database this way.""" + yield + base = SERVICE_ROOT / TEST_DB_PATH + for suffix in ("", "-journal", "-wal", "-shm"): + Path(f"{base}{suffix}").unlink(missing_ok=True) diff --git a/services/payment/tests/test_payment.py b/services/payment/tests/test_payment.py new file mode 100644 index 0000000..479def0 --- /dev/null +++ b/services/payment/tests/test_payment.py @@ -0,0 +1,16 @@ +def test_charge_records_an_approved_payment(client): + r = client.post("/api/payment/charge", data={"order_id": 7, "amount_cents": 3798}) + assert r.status_code == 200 + assert r.get_json()["result"]["status"] == "APPROVED" + assert client.get("/api/payments").get_json()["results"][0]["order_id"] == 7 + + +def test_charge_rejects_bad_input(client): + assert client.post("/api/payment/charge", data={"order_id": 0, "amount_cents": 10}).status_code == 400 + assert client.post("/api/payment/charge", data={"order_id": 1}).status_code == 400 + + +def test_health_db_reports_only_own_tables(client): + body = client.get("/health/db").get_json() + assert body["service"] == "payment" + assert body["tables"] == ["payment"] diff --git a/services/user/Dockerfile b/services/user/Dockerfile index 3a9b558..a5ea4ec 100644 --- a/services/user/Dockerfile +++ b/services/user/Dockerfile @@ -7,6 +7,8 @@ COPY requirements.txt . RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt COPY . . +# shared/ (shop_common) is staged into ./_shared by infra/provision.py before `az acr build`. +RUN pip install --no-cache-dir --root-user-action=ignore "./_shared[flask]" ENV RUN_MODE=azure \ FLASK_ENV=production \ @@ -14,4 +16,5 @@ ENV RUN_MODE=azure \ EXPOSE 5101 -CMD ["gunicorn", "--bind", "0.0.0.0:5101", "--workers", "2", "run:app"] +# One process with threads, so the in-memory span store (pattern 6) sees every request. +CMD ["gunicorn", "--bind", "0.0.0.0:5101", "--workers", "1", "--threads", "4", "run:app"] diff --git a/services/user/application/__init__.py b/services/user/application/__init__.py index b6f9dda..6dd3490 100644 --- a/services/user/application/__init__.py +++ b/services/user/application/__init__.py @@ -5,6 +5,7 @@ import os 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 @@ -35,8 +36,7 @@ def create_app(config_name: str | None = None) -> Flask: # this to local-only left Azure MySQL with no schema at all). db.create_all() - @app.get("/health") - def health(): - return {"status": "ok", "service": "user-service"} + # /health, /health/db, /debug/spans, /metrics, tracing and JSON logs (patterns 1 and 6). + install_observability(app, "user", db) return app diff --git a/services/user/requirements.txt b/services/user/requirements.txt index def309f..f5acaa3 100644 --- a/services/user/requirements.txt +++ b/services/user/requirements.txt @@ -8,3 +8,4 @@ passlib==1.7.4 python-dotenv==1.0.1 gunicorn==23.0.0 pydantic[email]==2.10.3 +opentelemetry-instrumentation-flask==0.50b0 diff --git a/shared/build/lib/shop_common/__init__.py b/shared/build/lib/shop_common/__init__.py new file mode 100644 index 0000000..1de03f4 --- /dev/null +++ b/shared/build/lib/shop_common/__init__.py @@ -0,0 +1,5 @@ +"""Shared helpers used by every service and the gateway. + +Only cross-cutting plumbing lives here (telemetry, logging, metrics). Business logic never does: +each bounded context keeps its own models and rules inside its own service. +""" diff --git a/shared/build/lib/shop_common/flask_support.py b/shared/build/lib/shop_common/flask_support.py new file mode 100644 index 0000000..2cb431b --- /dev/null +++ b/shared/build/lib/shop_common/flask_support.py @@ -0,0 +1,77 @@ +"""Wires a Flask service into the shared observability plumbing and adds standard endpoints. + +Endpoints added to every service: + GET /health liveness + 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) +""" +import time + +from flask import Flask, Response, g, jsonify, request +from sqlalchemy import inspect + +from . import metrics +from .telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing + + +def install(app: Flask, service_name: str, db) -> None: + init_tracing(service_name) + from opentelemetry.instrumentation.flask import FlaskInstrumentor + + FlaskInstrumentor().instrument_app(app, excluded_urls="health,debug/spans,metrics") + from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor + + # Needs an app context (every service calls install() inside one). Once per process. + SQLAlchemyInstrumentor().instrument(engine=db.engine) + log = get_logger() + + @app.before_request + def _start_timer(): + g.request_started = time.perf_counter() + g.request_id = request.headers.get(REQUEST_ID_HEADER) + + @app.after_request + def _record(response): + route = request.url_rule.rule if request.url_rule else "unmatched" + if route in ("/health", "/debug/spans", "/metrics"): + return response + elapsed = time.perf_counter() - g.get("request_started", time.perf_counter()) + metrics.observe(service_name, request.method, route, response.status_code, elapsed) + log.info( + f"{request.method} {route} -> {response.status_code} in {elapsed * 1000:.1f} ms", + extra={"request_id": g.get("request_id")}, + ) + if g.get("request_id"): + response.headers[REQUEST_ID_HEADER] = g.request_id + trace_id = current_trace_id() + if trace_id: + response.headers["X-Trace-Id"] = trace_id + return response + + @app.get("/health") + def health(): + return {"status": "ok", "service": service_name} + + @app.get("/health/db") + def health_db(): + engine = db.engine + url = engine.url + return jsonify({ + "service": service_name, + "engine": url.get_backend_name(), + # SQLite: the file name only. MySQL: the logical database name only. + "database": (url.database or "").rsplit("/", 1)[-1], + "tables": sorted(inspect(engine).get_table_names()), + }) + + @app.get("/debug/spans") + def debug_spans(): + trace_id = request.args.get("trace_id") + spans = SPAN_STORE.by_trace(trace_id) if trace_id else SPAN_STORE.recent() + return jsonify({"service": service_name, "spans": spans}) + + @app.get("/metrics") + def prometheus_metrics(): + body, content_type = metrics.render() + return Response(body, content_type=content_type) diff --git a/shared/build/lib/shop_common/metrics.py b/shared/build/lib/shop_common/metrics.py new file mode 100644 index 0000000..8958c00 --- /dev/null +++ b/shared/build/lib/shop_common/metrics.py @@ -0,0 +1,23 @@ +"""Prometheus metrics shared by every process: request count and latency per route. + +Labels are kept low-cardinality on purpose: the route template (e.g. /api/product/), never +the raw URL, so one metric series does not appear per product slug. +""" +from prometheus_client import CONTENT_TYPE_LATEST, Counter, Histogram, generate_latest + +REQUESTS = Counter( + "shop_http_requests_total", "HTTP requests handled", ["service", "method", "route", "status"] +) +LATENCY = Histogram( + "shop_http_request_duration_seconds", "HTTP request latency", ["service", "method", "route"], + buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5), +) + + +def observe(service: str, method: str, route: str, status: int, seconds: float) -> None: + REQUESTS.labels(service, method, route, str(status)).inc() + LATENCY.labels(service, method, route).observe(seconds) + + +def render() -> tuple[bytes, str]: + return generate_latest(), CONTENT_TYPE_LATEST diff --git a/shared/build/lib/shop_common/telemetry.py b/shared/build/lib/shop_common/telemetry.py new file mode 100644 index 0000000..9b9d2ef --- /dev/null +++ b/shared/build/lib/shop_common/telemetry.py @@ -0,0 +1,157 @@ +"""Pattern 6, Observability: traces, JSON logs with trace IDs, and metrics. + +Traces: OpenTelemetry. Every service keeps its most recent spans in memory (SPAN_STORE) and +serves them at /debug/spans, so the gateway can stitch one request's spans from every service +into a waterfall without any external tool. If OTEL_EXPORTER_OTLP_ENDPOINT is set, spans are +also exported over OTLP/HTTP (e.g. to otel-desktop-viewer locally or a collector in Azure). + +Trace context crosses service boundaries in the W3C `traceparent` header, which the requests +and httpx instrumentations inject and the Flask/FastAPI instrumentations extract. +""" +import json +import logging +import os +import sys +import threading +from collections import deque + +from opentelemetry import trace +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor + +REQUEST_ID_HEADER = "X-Request-Id" + + +class SpanStore(SpanProcessor): + """Ring buffer of finished spans. Thread-safe; oldest spans fall off first.""" + + def __init__(self, maxlen: int = 2000): + self._spans: deque[dict] = deque(maxlen=maxlen) + self._lock = threading.Lock() + + def on_end(self, span: ReadableSpan) -> None: + ctx = span.get_span_context() + attrs = dict(span.attributes or {}) + record = { + "trace_id": format(ctx.trace_id, "032x"), + "span_id": format(ctx.span_id, "016x"), + "parent_id": format(span.parent.span_id, "016x") if span.parent else None, + # Only database spans carry file paths (SQLite); HTTP span names keep their URL paths. + "name": _strip_paths(span.name) if "db.system" in attrs else span.name, + "service": span.resource.attributes.get("service.name", "unknown"), + "kind": span.kind.name, + "start_ns": span.start_time, + "end_ns": span.end_time, + "status": span.status.status_code.name, + # Keep a few readable attributes only; never request bodies or headers. + "attributes": {k: _strip_paths(str(v)) if k == "db.name" else v + for k, v in attrs.items() if k in _KEPT_ATTRIBUTES}, + } + with self._lock: + self._spans.append(record) + + def by_trace(self, trace_id: str) -> list[dict]: + with self._lock: + return [s for s in self._spans if s["trace_id"] == trace_id] + + def recent(self, limit: int = 50) -> list[dict]: + with self._lock: + return list(self._spans)[-limit:] + + def shutdown(self) -> None: # SpanProcessor interface + pass + + def force_flush(self, timeout_millis: int = 30000) -> bool: # SpanProcessor interface + return True + + +def _strip_paths(text: str) -> str: + """SQLite database names are absolute file paths; keep only the file name so a span never + reveals the host's directory layout (e.g. 'SELECT /home/x/catalog.sqlite3' -> 'SELECT catalog.sqlite3').""" + return " ".join(part.rsplit("/", 1)[-1] if part.startswith("/") else part for part in text.split(" ")) + + +_KEPT_ATTRIBUTES = { + "http.method", "http.request.method", "http.route", "http.target", "url.path", + "http.status_code", "http.response.status_code", "http.url", "url.full", + "db.system", "db.name", "db.statement", "request.id", +} + +SPAN_STORE = SpanStore() +_initialised = False + + +def init_tracing(service_name: str) -> trace.Tracer: + """Sets the global tracer provider once per process and instruments outgoing calls.""" + global _initialised + if not _initialised: + provider = TracerProvider(resource=Resource.create({"service.name": service_name})) + provider.add_span_processor(SPAN_STORE) + if os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"): + from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter + + provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) + trace.set_tracer_provider(provider) + + _instrument_if_installed() + _configure_json_logging(service_name) + _initialised = True + return trace.get_tracer(service_name) + + +def _instrument_if_installed() -> None: + """Instruments each HTTP client library only if this process has it: Flask services use + requests, the gateway uses httpx. Database engines are instrumented one by one, see + flask_support.install (Flask-SQLAlchemy creates its engine in a way the global hook misses).""" + import importlib.util + + if importlib.util.find_spec("requests"): + from opentelemetry.instrumentation.requests import RequestsInstrumentor + + RequestsInstrumentor().instrument() + if importlib.util.find_spec("httpx"): + from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor + + HTTPXClientInstrumentor().instrument() + + +def current_trace_id() -> str | None: + ctx = trace.get_current_span().get_span_context() + return format(ctx.trace_id, "032x") if ctx.is_valid else None + + +class JsonLogFormatter(logging.Formatter): + """One JSON object per line, carrying the active trace and span IDs.""" + + def __init__(self, service_name: str): + super().__init__() + self.service_name = service_name + + def format(self, record: logging.LogRecord) -> str: + ctx = trace.get_current_span().get_span_context() + payload = { + "level": record.levelname, + "service": self.service_name, + "logger": record.name, + "message": record.getMessage(), + "trace_id": format(ctx.trace_id, "032x") if ctx.is_valid else None, + "span_id": format(ctx.span_id, "016x") if ctx.is_valid else None, + "request_id": getattr(record, "request_id", None), + } + if record.exc_info: + payload["exception"] = self.formatException(record.exc_info) + return json.dumps(payload) + + +def _configure_json_logging(service_name: str) -> None: + handler = logging.StreamHandler(sys.stdout) + handler.setFormatter(JsonLogFormatter(service_name)) + logger = logging.getLogger("shop") + logger.handlers = [handler] + logger.setLevel(logging.INFO) + logger.propagate = False + + +def get_logger() -> logging.Logger: + return logging.getLogger("shop") diff --git a/shared/pyproject.toml b/shared/pyproject.toml new file mode 100644 index 0000000..7e13185 --- /dev/null +++ b/shared/pyproject.toml @@ -0,0 +1,24 @@ +[build-system] +requires = ["setuptools>=68"] +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)." +requires-python = ">=3.12" +dependencies = [ + "opentelemetry-sdk==1.29.0", + "opentelemetry-exporter-otlp-proto-http==1.29.0", + "opentelemetry-instrumentation-requests==0.50b0", + "opentelemetry-instrumentation-httpx==0.50b0", + "opentelemetry-instrumentation-sqlalchemy==0.50b0", + "prometheus-client==0.21.1", +] + +[project.optional-dependencies] +flask = ["opentelemetry-instrumentation-flask==0.50b0"] +fastapi = ["opentelemetry-instrumentation-fastapi==0.50b0"] + +[tool.setuptools.packages.find] +include = ["shop_common*"] diff --git a/shared/shop_common/__init__.py b/shared/shop_common/__init__.py new file mode 100644 index 0000000..1de03f4 --- /dev/null +++ b/shared/shop_common/__init__.py @@ -0,0 +1,5 @@ +"""Shared helpers used by every service and the gateway. + +Only cross-cutting plumbing lives here (telemetry, logging, metrics). Business logic never does: +each bounded context keeps its own models and rules inside its own service. +""" diff --git a/shared/shop_common/flask_support.py b/shared/shop_common/flask_support.py new file mode 100644 index 0000000..2cb431b --- /dev/null +++ b/shared/shop_common/flask_support.py @@ -0,0 +1,77 @@ +"""Wires a Flask service into the shared observability plumbing and adds standard endpoints. + +Endpoints added to every service: + GET /health liveness + 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) +""" +import time + +from flask import Flask, Response, g, jsonify, request +from sqlalchemy import inspect + +from . import metrics +from .telemetry import REQUEST_ID_HEADER, SPAN_STORE, current_trace_id, get_logger, init_tracing + + +def install(app: Flask, service_name: str, db) -> None: + init_tracing(service_name) + from opentelemetry.instrumentation.flask import FlaskInstrumentor + + FlaskInstrumentor().instrument_app(app, excluded_urls="health,debug/spans,metrics") + from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor + + # Needs an app context (every service calls install() inside one). Once per process. + SQLAlchemyInstrumentor().instrument(engine=db.engine) + log = get_logger() + + @app.before_request + def _start_timer(): + g.request_started = time.perf_counter() + g.request_id = request.headers.get(REQUEST_ID_HEADER) + + @app.after_request + def _record(response): + route = request.url_rule.rule if request.url_rule else "unmatched" + if route in ("/health", "/debug/spans", "/metrics"): + return response + elapsed = time.perf_counter() - g.get("request_started", time.perf_counter()) + metrics.observe(service_name, request.method, route, response.status_code, elapsed) + log.info( + f"{request.method} {route} -> {response.status_code} in {elapsed * 1000:.1f} ms", + extra={"request_id": g.get("request_id")}, + ) + if g.get("request_id"): + response.headers[REQUEST_ID_HEADER] = g.request_id + trace_id = current_trace_id() + if trace_id: + response.headers["X-Trace-Id"] = trace_id + return response + + @app.get("/health") + def health(): + return {"status": "ok", "service": service_name} + + @app.get("/health/db") + def health_db(): + engine = db.engine + url = engine.url + return jsonify({ + "service": service_name, + "engine": url.get_backend_name(), + # SQLite: the file name only. MySQL: the logical database name only. + "database": (url.database or "").rsplit("/", 1)[-1], + "tables": sorted(inspect(engine).get_table_names()), + }) + + @app.get("/debug/spans") + def debug_spans(): + trace_id = request.args.get("trace_id") + spans = SPAN_STORE.by_trace(trace_id) if trace_id else SPAN_STORE.recent() + return jsonify({"service": service_name, "spans": spans}) + + @app.get("/metrics") + def prometheus_metrics(): + body, content_type = metrics.render() + return Response(body, content_type=content_type) diff --git a/shared/shop_common/metrics.py b/shared/shop_common/metrics.py new file mode 100644 index 0000000..8958c00 --- /dev/null +++ b/shared/shop_common/metrics.py @@ -0,0 +1,23 @@ +"""Prometheus metrics shared by every process: request count and latency per route. + +Labels are kept low-cardinality on purpose: the route template (e.g. /api/product/), never +the raw URL, so one metric series does not appear per product slug. +""" +from prometheus_client import CONTENT_TYPE_LATEST, Counter, Histogram, generate_latest + +REQUESTS = Counter( + "shop_http_requests_total", "HTTP requests handled", ["service", "method", "route", "status"] +) +LATENCY = Histogram( + "shop_http_request_duration_seconds", "HTTP request latency", ["service", "method", "route"], + buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5), +) + + +def observe(service: str, method: str, route: str, status: int, seconds: float) -> None: + REQUESTS.labels(service, method, route, str(status)).inc() + LATENCY.labels(service, method, route).observe(seconds) + + +def render() -> tuple[bytes, str]: + return generate_latest(), CONTENT_TYPE_LATEST diff --git a/shared/shop_common/telemetry.py b/shared/shop_common/telemetry.py new file mode 100644 index 0000000..9b9d2ef --- /dev/null +++ b/shared/shop_common/telemetry.py @@ -0,0 +1,157 @@ +"""Pattern 6, Observability: traces, JSON logs with trace IDs, and metrics. + +Traces: OpenTelemetry. Every service keeps its most recent spans in memory (SPAN_STORE) and +serves them at /debug/spans, so the gateway can stitch one request's spans from every service +into a waterfall without any external tool. If OTEL_EXPORTER_OTLP_ENDPOINT is set, spans are +also exported over OTLP/HTTP (e.g. to otel-desktop-viewer locally or a collector in Azure). + +Trace context crosses service boundaries in the W3C `traceparent` header, which the requests +and httpx instrumentations inject and the Flask/FastAPI instrumentations extract. +""" +import json +import logging +import os +import sys +import threading +from collections import deque + +from opentelemetry import trace +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor + +REQUEST_ID_HEADER = "X-Request-Id" + + +class SpanStore(SpanProcessor): + """Ring buffer of finished spans. Thread-safe; oldest spans fall off first.""" + + def __init__(self, maxlen: int = 2000): + self._spans: deque[dict] = deque(maxlen=maxlen) + self._lock = threading.Lock() + + def on_end(self, span: ReadableSpan) -> None: + ctx = span.get_span_context() + attrs = dict(span.attributes or {}) + record = { + "trace_id": format(ctx.trace_id, "032x"), + "span_id": format(ctx.span_id, "016x"), + "parent_id": format(span.parent.span_id, "016x") if span.parent else None, + # Only database spans carry file paths (SQLite); HTTP span names keep their URL paths. + "name": _strip_paths(span.name) if "db.system" in attrs else span.name, + "service": span.resource.attributes.get("service.name", "unknown"), + "kind": span.kind.name, + "start_ns": span.start_time, + "end_ns": span.end_time, + "status": span.status.status_code.name, + # Keep a few readable attributes only; never request bodies or headers. + "attributes": {k: _strip_paths(str(v)) if k == "db.name" else v + for k, v in attrs.items() if k in _KEPT_ATTRIBUTES}, + } + with self._lock: + self._spans.append(record) + + def by_trace(self, trace_id: str) -> list[dict]: + with self._lock: + return [s for s in self._spans if s["trace_id"] == trace_id] + + def recent(self, limit: int = 50) -> list[dict]: + with self._lock: + return list(self._spans)[-limit:] + + def shutdown(self) -> None: # SpanProcessor interface + pass + + def force_flush(self, timeout_millis: int = 30000) -> bool: # SpanProcessor interface + return True + + +def _strip_paths(text: str) -> str: + """SQLite database names are absolute file paths; keep only the file name so a span never + reveals the host's directory layout (e.g. 'SELECT /home/x/catalog.sqlite3' -> 'SELECT catalog.sqlite3').""" + return " ".join(part.rsplit("/", 1)[-1] if part.startswith("/") else part for part in text.split(" ")) + + +_KEPT_ATTRIBUTES = { + "http.method", "http.request.method", "http.route", "http.target", "url.path", + "http.status_code", "http.response.status_code", "http.url", "url.full", + "db.system", "db.name", "db.statement", "request.id", +} + +SPAN_STORE = SpanStore() +_initialised = False + + +def init_tracing(service_name: str) -> trace.Tracer: + """Sets the global tracer provider once per process and instruments outgoing calls.""" + global _initialised + if not _initialised: + provider = TracerProvider(resource=Resource.create({"service.name": service_name})) + provider.add_span_processor(SPAN_STORE) + if os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"): + from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter + + provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) + trace.set_tracer_provider(provider) + + _instrument_if_installed() + _configure_json_logging(service_name) + _initialised = True + return trace.get_tracer(service_name) + + +def _instrument_if_installed() -> None: + """Instruments each HTTP client library only if this process has it: Flask services use + requests, the gateway uses httpx. Database engines are instrumented one by one, see + flask_support.install (Flask-SQLAlchemy creates its engine in a way the global hook misses).""" + import importlib.util + + if importlib.util.find_spec("requests"): + from opentelemetry.instrumentation.requests import RequestsInstrumentor + + RequestsInstrumentor().instrument() + if importlib.util.find_spec("httpx"): + from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor + + HTTPXClientInstrumentor().instrument() + + +def current_trace_id() -> str | None: + ctx = trace.get_current_span().get_span_context() + return format(ctx.trace_id, "032x") if ctx.is_valid else None + + +class JsonLogFormatter(logging.Formatter): + """One JSON object per line, carrying the active trace and span IDs.""" + + def __init__(self, service_name: str): + super().__init__() + self.service_name = service_name + + def format(self, record: logging.LogRecord) -> str: + ctx = trace.get_current_span().get_span_context() + payload = { + "level": record.levelname, + "service": self.service_name, + "logger": record.name, + "message": record.getMessage(), + "trace_id": format(ctx.trace_id, "032x") if ctx.is_valid else None, + "span_id": format(ctx.span_id, "016x") if ctx.is_valid else None, + "request_id": getattr(record, "request_id", None), + } + if record.exc_info: + payload["exception"] = self.formatException(record.exc_info) + return json.dumps(payload) + + +def _configure_json_logging(service_name: str) -> None: + handler = logging.StreamHandler(sys.stdout) + handler.setFormatter(JsonLogFormatter(service_name)) + logger = logging.getLogger("shop") + logger.handlers = [handler] + logger.setLevel(logging.INFO) + logger.propagate = False + + +def get_logger() -> logging.Logger: + return logging.getLogger("shop") diff --git a/tests/smoke/test_post_run.py b/tests/smoke/test_post_run.py index 486b597..a4b39b6 100644 --- a/tests/smoke/test_post_run.py +++ b/tests/smoke/test_post_run.py @@ -58,3 +58,40 @@ def test_full_flow_through_gateway(): r = httpx.get(f"{shop}/products") assert r.status_code == 200 assert "results" in r.json() + + +# --- M1 pattern demos (patterns 1, 2, 5, 6), through the gateway --------------------------------- + +def _require_stack(): + if not _is_up(GATEWAY_URL) or not all(_is_up(u) for u in URLS.values()): + pytest.skip("gateway or services not running — start them with `make run` first") + + +def test_each_service_owns_only_its_tables(): + _require_stack() + services = {s["service"]: s for s in httpx.get(f"{GATEWAY_URL}/api/patterns/databases").json()["services"]} + assert set(services) == set(URLS) + assert services["catalog"]["tables"] == ["product"] + assert services["inventory"]["tables"] == ["stock_item"] + assert "product" not in services["order"]["tables"] + + +def test_order_service_cannot_read_catalog_table(): + _require_stack() + body = httpx.get(f"{GATEWAY_URL}/api/patterns/isolation-test", params={"table": "product"}).json() + assert body["blocked"] is True + + +def test_bounded_context_shows_two_views_of_one_product(): + _require_stack() + body = httpx.get(f"{GATEWAY_URL}/api/patterns/bounded-context/1").json() + assert "price" in body["catalog"] and "on_hand" not in body["catalog"] + assert "on_hand" in body["inventory"] and "price" not in body["inventory"] + + +def test_one_request_is_traced_across_services(): + _require_stack() + r = httpx.get(f"{GATEWAY_URL}/api/patterns/bounded-context/1") + 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}