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 0000000..2612b21 Binary files /dev/null and b/docs/screenshots/p01-database-per-service.jpg differ diff --git a/docs/screenshots/p02-bounded-context.jpg b/docs/screenshots/p02-bounded-context.jpg new file mode 100644 index 0000000..8939e7b Binary files /dev/null and b/docs/screenshots/p02-bounded-context.jpg differ diff --git a/docs/screenshots/p05-api-gateway.jpg b/docs/screenshots/p05-api-gateway.jpg new file mode 100644 index 0000000..18892d8 Binary files /dev/null and b/docs/screenshots/p05-api-gateway.jpg differ diff --git a/docs/screenshots/p06-observability.jpg b/docs/screenshots/p06-observability.jpg new file mode 100644 index 0000000..8165965 Binary files /dev/null and b/docs/screenshots/p06-observability.jpg differ diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 361b5d9..136d3e2 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -3,6 +3,7 @@ import NavBar from "./components/NavBar"; import Home from "./pages/Home"; import Shop from "./pages/Shop"; import Patterns from "./pages/Patterns"; +import PatternPage from "./pages/PatternPage"; export default function App() { return ( @@ -13,6 +14,7 @@ export default function App() { } /> } /> } /> + } /> 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 ( +
+
+

+ Patterns / Pattern {pattern.n} +

+

{pattern.name}

+

{pattern.what}

+

The problem it solves

+

{pattern.problem}

+
+ +
+
+

How this project does it

+
    + {pattern.inThisProject?.map((line) =>
  • {line}
  • )} +
+
+
+

When not to use it

+
    + {pattern.whenNotToUse?.map((line) =>
  • {line}
  • )} +
+ {pattern.source && ( +

+ Source:{" "} + + {pattern.source.label} + +

+ )} +
+
+ +
+

Live demo

+ {DEMOS[pattern.slug]?.()} +
+
+ ); +} 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}