MODULE 02 OF 12 · RELEASE 1 · OUTLINE
Event-Driven Agent Infrastructure
Take the order first, cook it after — so a slow kitchen never turns customers away at the door.
This module is an outline. The plain-language explanation and the lab specification below are final. The full written lesson and its runnable lab repository are still being prepared, and enrolment is not open.
A busy café takes your order, hands you a numbered stand, and you sit down. They do not make you stand at the counter until the food is ready. If the coffee machine breaks, your order still exists on the ticket rail — someone picks it up when the machine is fixed.
So what is this really about?
Software that receives work from elsewhere should do the same. Write the order down straight away, say "got it", and do the slow part afterwards. If the slow part breaks, the order is still on the rail. The alternative — making the sender wait while you do everything — means a slow step turns into a lost order.
QUICK CHECK
The kitchen crashes halfway through making an order. What should happen?
The words you will hear
- Event
- A message from somewhere else saying something happened. Your order ticket.
- Ingress
- The counter where orders are taken. Fast, and it only writes things down.
- Worker
- The kitchen. Picks tickets off the rail and does the actual work.
- Idempotent
- Handing in the same ticket twice still gets you one coffee, not two.
- Dead letter
- The tray for tickets that failed repeatedly, so someone can look at them instead of them vanishing.
By the end you will be able to
- Separate taking work in from doing the work.
- Make repeated deliveries harmless.
- Recover cleanly when the slow part fails after you already said "got it".
How it is put together
An ingress endpoint verifies, validates and durably records an event, then returns. A separate worker picks the record up and does the expensive work. The two are joined by state in a database rather than by a function call, which is what lets the second one fail and retry without the first one knowing.
Where you start
The Free Foundations webhook, which does everything inline in the request handler.
The lab
- Split acceptance from processing, with an explicit state column on the event record.
- Add an idempotency key with a uniqueness constraint so duplicate delivery is a no-op.
- Add a claim step so two workers cannot process the same record.
- Add a dead-letter state for records that fail repeatedly, with the failure reason attached.
- Add a replay path that reprocesses a dead-lettered record after a fix.
What goes wrong, on purpose
The scenario. The worker crashes mid-processing, after the model call and before the result is written.
What should happen. The record remains claimed but unfinished, is reclaimed after a visibility timeout, and reprocessing does not duplicate the external effect.
How you prove it works
- A test delivering the same event twice concurrently, asserting one record and one effect.
- A test killing a worker mid-run and asserting recovery on the next pass.
- A test asserting a repeatedly failing record lands in the dead-letter state rather than retrying forever.
What you walk away with
An ingress that responds in single-digit milliseconds, a worker that survives being killed, and a dead-letter queue you can inspect and replay.