Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Event Bus

One shared routing point that every module publishes to and subscribes through: a registry of handlers by event type, what an in-process bus does and does not promise when a handler throws or the process dies, what changes when a broker sits underneath, and why the registry is worth reading.

A cycle in the imports

A hotel group's property-management system is one application, deployed as one unit, with modules for the front desk, housekeeping, billing, keycards and the loyalty programme. The build broke on a Tuesday with a circular dependency. Loyalty imported the front desk, because it registered itself there as a listener to hear about check-outs and credit the guest's nights. The front desk had just started importing Loyalty, to show a guest's points balance at check-in. Each module now needed the other to load first.

The listener list was the cause. With Observer, each module that announces something keeps its own list of listeners, and here each listener imported the module it listened to, in order to join that list. The teams had already chosen to announce facts and let others react, the trade described in Publish / Subscribe. What they lacked was a place for the announcing that belonged to neither side.

One registry for the whole application

An Event Bus is one shared routing point that every module publishes to and subscribes through. In its simplest, in-process form it is a registry: a map from event type to the handlers registered for that type. At start-up, Loyalty calls bus.subscribe("GuestCheckedOut", creditNights). At check-out, the front desk calls bus.publish(guestCheckedOut), and the bus looks up the type and calls each handler registered for it. Loyalty now imports only the bus and the event's definition, and so does the front desk for check-outs. The front desk still imports Loyalty to show the points balance, but Loyalty no longer imports the front desk, so the cycle is gone.

Check-out through the bus

The front desk publishes GuestCheckedOut to the bus, which calls every handler registered for that type. The front desk does not know which modules handle it.

What publish() does on a busy Sunday

In-process buses differ most in what happens inside publish, and the hotel group learned what its own did from an incident. Its bus called the handlers on the publishing thread, one after another, in the order they had registered. Room 412 checks out:

  1. The front desk closes the stay and calls bus.publish with GuestCheckedOut for room 412.
  2. The bus calls housekeeping's handler, which queues the room for cleaning.
  3. The bus calls keycards' handler, which revokes the guest's two cards.
  4. The bus calls loyalty's handler, which throws: a long-running report has locked the promotions table.
  5. The exception comes back out of publish, billing's handler never runs, and the receptionist sees the check-out fail for a guest whose cards no longer open the room.

Which outcome you get depends on the bus you use. Spring's default synchronous event publishing behaves like the trace above: the exception reaches the publisher and the remaining listeners are skipped. Guava's EventBus catches a subscriber's exception, logs it and carries on, so the check-out succeeds and nothing calls loyalty's handler again: the nights are never credited, and a log line is the only trace. Neither choice is wrong, but a team has to know which one it has. A handler that must not be skipped needs its own error handling, or a retry that someone added on purpose, because the bus has none.

Synchronous dispatch has a second cost: publish returns only when every handler has finished, so a slow loyalty handler makes check-out slow. Handing the handlers to a thread pool, with publish returning once they are queued, takes their time out of check-out and changes the promises again. The front desk no longer hears about a handler's failure at all, two events about the same room can be handled in a different order from the one they were published in, and events still waiting in the pool's queue live only in memory, so a deploy or a crash loses them. An in-process bus offers no durability, no retry and no ordering beyond what its code provides; a team that assumes otherwise finds out when a restart drops the events that were in flight. Whether handlers run before or after the database commit is a further choice, made in Domain Event.

The same publish(), with a broker underneath

Later the group moved loyalty into a separate service shared by all its hotels, so loyalty's handler could no longer run inside the application. The team kept the bus's interface and changed its implementation: for GuestCheckedOut, the bus now also hands the event to a Message Broker, a separate process that holds it until the loyalty service takes it, which is where the decoupling in time comes from. The call looks the same; the promises do not. Loyalty's handler no longer runs inside the front desk's call, so the nights may not be credited yet when publish returns. The event can now outlive a crash of the hotel application, once the broker has stored it durably, which is what Guaranteed Delivery asks of each hop. And most brokers redeliver a message whose acknowledgement never arrived, so the loyalty service can receive the same check-out twice and credit the nights twice unless it is an Idempotent Consumer.

Going through the code for the move, the team found a line that only worked by luck. Check-out printed the final bill straight after publish, relying on billing's handler having added the minibar charges, which it always had, because it ran synchronously. Had billing moved behind the broker with loyalty, guests would have left with bills missing their last charges. Check-out now calls billing directly. A step that needs a handler's result is not reacting to an announcement; it is making a call, and a bus is the wrong tool for it.

Drawing the bus in a Challenge

The Publish / Subscribe Challenge asks for an Event Bus that distributes events to subscribers, publishers and subscribers that do not know each other, and a clear many-to-many intent. Draw the hotel: the front desk and housekeeping as Publisher nodes (housekeeping publishes RoomInspected), one Event Bus node that every edge passes through, and housekeeping, keycards, loyalty and room availability as Subscriber nodes, each edge labelled with the event type it carries. Housekeeping plays both roles, so it gets a node for each; billing stays off the bus, since check-out now calls it directly. Then decide what your bus is and put it in its title, "In-process bus" or "Broker-backed bus", and check each subscriber against that choice: which ones would lose an event if the application restarted mid-dispatch, and which ones could receive one twice.

Read the registry

A bus that every module talks through also hides who reacts to what: no single file shows that a check-out ends with a credited stay and a cleaned room. The registry can show it. Generate a catalogue from it, each event type with the handlers registered for it, and carry a correlation id from the first event into any event a handler publishes, so one check-out can be followed through the logs, or across services with Distributed tracing. When handlers start publishing events that trigger other handlers, the flow exists only as a chain of reactions, and whether to leave it that way or give it one owner is the question Choreography answers.

Practice this