Skip to content

M3a: Saga, Event-Driven Architecture, Containerization - #4

Merged
MAOFILHO merged 2 commits into
mainfrom
m3a/saga-events
Nov 15, 2026
Merged

MAOFILHO merged 2 commits into
mainfrom
m3a/saga-events

Conversation

@MAOFILHO

Copy link
Copy Markdown
Owner

Milestone M3a of docs/PLAN.md (see "M3 review"). 11 of 12 patterns are now live. CI-CD and the Azure run are M3b.

Patterns

  • 8 Saga: checkout is an orchestrated saga in the order service:
    • The steps run in order: price (catalog), hold stock (inventory), charge (payment, behind the M2 breaker), confirm.
    • A declined card, an open breaker or a payment error releases the hold and keeps the cart.
    • Only one checkout runs per order at a time.
    • The page has a "decline the card" switch and draws the step timeline.
  • 7 Event-Driven Architecture:
    • Each step writes an event to an outbox table, in the same transaction as the change.
    • A relay publishes the events to the Redis Stream shop.events.
    • Inventory reads them in its own consumer group and turns the hold into a sale on OrderConfirmed. It dedupes on the event id, and a failing event goes to a dead-letter stream after 5 tries.
    • The demo disconnects the bus: events wait in the outbox, the stock stays held, then everything settles on reconnect.
  • 9 Containerization:
    • 7 multi-stage Dockerfiles that run as uid 10001, each with a .dockerignore. Before this, local virtualenvs were uploaded with every cloud build.
    • Each image carries a GIT_SHA build arg.
    • A new CI job builds every image for linux/amd64, starts it, checks /health, and fails if it runs as root.

Found and fixed during the click-through

  • The 2 order replicas raced to create tables, and one crashed at startup.
  • Flask's reloader watcher process ran a second outbox relay that the bus switch could not reach.
  • 18 of the 24 catalog products had no stock record, so checkout would have refused them.

Code review (Matt Pocock code-review: standards and spec)

11 standards findings and 8 spec findings. All the bugs and behaviour gaps are fixed, each with a failing test first, except 2 concurrency fixes that need real concurrent database sessions (see the commit message). SHA tags on the Azure build path and the image size on the page move to M3b, as recorded in PLAN.md.

Tests

  • 98 unit tests across 8 suites. Contracts now cover order → inventory and a declined charge.
  • 23 smoke tests passed and 3 skipped (Azure only). They cover a sale that settles through Redis, a decline that leaves stock unchanged, and events waiting while the bus is down, then draining.
  • Browser click-through of the 3 new pages. Screenshots p07, p08 and p09 are in docs/screenshots/.

Notes

  • New local requirement: brew install redis. make run starts it in memory on port 6390 and stops it with the stack.
  • Nothing is deployed to Azure.

🤖 Generated with Claude Code

MAOFILHO and others added 2 commits November 15, 2026 16:19
…d containers

- Pattern 8: checkout is an orchestrated saga in the order service: price (catalog), hold stock
  (inventory), charge (payment), confirm. A decline, an open breaker or a payment error releases
  the hold; if that call fails, StockReleaseRequested goes through the outbox. Steps in saga_step.
- Pattern 7: OrderConfirmed is written to an outbox table in the same transaction as the order;
  a relay publishes to the Redis Stream shop.events; inventory consumes it in its own group and
  turns the hold into a sale, deduping on event id. A demo switch disconnects the bus.
- Pattern 9: multi-stage Dockerfiles running as uid 10001, .dockerignore everywhere (local venvs
  were being uploaded), GIT_SHA build arg, CI builds and runs all 7 images for linux/amd64.
- Fixes found on the way: two order replicas racing to create tables; Flask's reloader watcher
  process running a second, unswitchable outbox relay; 18 catalog products with no stock record.
- make run starts an in-memory Redis on 6390. Contracts add order -> inventory and a declined charge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two-axis review (Matt Pocock code-review: standards + spec). Each fix below has a failing test
first, except the two concurrency fixes (noted).

- Event reader: one failing event no longer blocks the ones behind it; it is retried between new
  reads and moved to shop.events.dead after 5 tries (Reader.read_once, tested with a fake Redis).
- Checkout: one saga per order at a time (checkout_lock, expires after 60 s), so a double click
  cannot hold stock or charge twice.
- Every saga step publishes an event: StockReserved, PaymentCharged, OrderConfirmed, CheckoutFailed.
- A timed-out stock hold is released through the bus (StockReleaseRequested).
- A payment timeout no longer tells the shopper "nothing was charged".
- The decline switch needs CHAOS_ENABLED=1; restock input is validated (400, 404).
- Concurrency, no unit test (needs 2 real DB sessions): stock rows locked in product id order;
  a duplicate hold insert returns the existing hold.
- Tidy-ups: seed_missing_stock rename, shared failure path in Saga.fail, imports, one fewer call.
- README, CLAUDE.md, .env.example and PLAN.md updated; build preference recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MAOFILHO
MAOFILHO merged commit 73c3b3e into main Nov 15, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant