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

Recipient List

A router that works out, for each message, which set of receivers needs it and sends each one a copy, so the audience can change from one message to the next without the sender knowing any of them.

Who needs to hear about this one?

An airline's duty controller asks that about every schedule change, several hundred times a day. Flight 612 from Lisbon to Hamburg moves from 14:10 to 16:45 because its aircraft is late off the previous leg. Crew scheduling needs to hear, because the later finish may take the crew past their duty limit. The passenger notification service needs to hear, so it can message the 174 people booked. Ground handling in Hamburg needs to hear, because the stand and the turnaround team were planned for the old arrival. Catering in Lisbon needs to hear only if the meal service changes, and this time it does: under the airline's own rule, a departure after 15:00 gets a snack service instead of lunch.

An hour later flight 340 to Madrid changes gate. The passengers need to hear, and so do the ground staff in Lisbon who move the boarding team. Crew scheduling does not, catering does not, and nobody in Madrid does. Every change has its own audience.

The first version of the schedule system answered the question in its own code: after saving a change, it called the crew system, then the passenger service, then the ground handler of the arrival airport, then catering, each call behind its own if. Every new party meant a change to the schedule system, and its team owned four integrations it understood less every year.

A router whose answer is a set

The fix moves the question out of the sender and into a router of its own, a Recipient List. The schedule system publishes one message, ScheduleChanged, carrying the flight's whole current schedule (times, gate, airports, aircraft) and the old value of each field that changed. The recipient list reads it, computes which receivers this particular message needs, and sends each of them its own copy. For flight 612 the set has four members; for flight 340 it has two. The schedule system knows none of them.

Four copies for flight 612

The list is computed for each change. Flight 340's gate change produces two copies, and catering gets none.

It reads the message the way a Content-Based Router does, but where that router sends each message to exactly one destination, a recipient list sends to as many as the message needs. That can be one. It can also be none: a change to an internal remarks field interests no receiver, and an empty list is expected and worth counting, not an error to raise.

Three ways to build the list

The four receivers of flight 612 were chosen in three different ways, and one recipient list can mix all three.

  • From one field of the message. Crew scheduling gets every change to a departure or arrival time, and the message says whether a time changed.
  • From a rule that needs more than one field. Catering gets a copy only when the meal service changes, so the list applies the airline's service rule to both the old and the new departure time, and sends a copy only when the two answers differ.
  • From a lookup table. Which company handles flights at the arrival airport is not in the message. The list looks the arrival airport up in a table where each ground handler is registered against the airports it serves. When the airline starts flying to Porto, the Porto handler is added as a row, with no change to the schedule system or to the router's code.

That table is also where a Recipient List differs from publish-subscribe, though both deliver copies. On a Publish / Subscribe channel the subscribers choose themselves: each subscribes and receives what is published there, and nothing on the publishing side decides, message by message, who that is. With a recipient list, receivers may register in a table, but the router applies the rules to each message and decides the audience.

Three copies delivered, one failed

At 14:32 the recipient list computes the set for flight 612 and sends four copies. Crew scheduling, passenger notices and Hamburg ground handling accept theirs. Catering's endpoint is down for a deploy, and the fourth copy fails.

The message is now partly delivered, and treating it as one thing that either succeeded or failed is wrong both ways. Resending the whole message gives three receivers a second copy of a change they have already acted on, and a passenger service that is not careful texts 174 people twice. Marking the whole message as failed hides the fact that three parties already acted. What works is tracking delivery per recipient: the list durably records, for each message, which copies were accepted, and retries only catering's, with spaced attempts, until it goes through or is set aside on a Dead Letter Channel, labelled with the one recipient it was meant for so a replay goes only there.

Retrying one copy does not rule out duplicates. If catering's endpoint received the first copy and only its acknowledgement was lost, the retry is a second copy. If the recipient list crashes after sending two copies and before recording them, it sends them again when it restarts. So each receiver has to recognise a schedule change it has already applied, for example by the change's id, and treat the repeat as done; building a receiver that way is what Idempotent Consumer walks through.

A retried copy can also arrive after a newer change: if flight 612 moves again, to 14:50 and back to lunch, while catering's 16:45 copy is still being retried, catering could apply them in the wrong order. A version number per flight keeps a late copy harmless: each copy carries the whole current schedule, and a receiver that compares the version and updates in one atomic step ignores a copy older than the one it holds.

Copies out, nothing back

A recipient list sends its copies and is done. It does not wait for crew scheduling to say whether the crew can still legally fly. When a change needs answers from several parties combined into one, that is Scatter-Gather, which can use a recipient list for its scatter half. Nor does the list message the 174 passengers: it hands one copy to the passenger service, and how that service spreads one event across many users, by pushing to each or letting them pull, is Fan-out: push vs pull.

Where to practise

No Challenge has a Recipient List at its centre yet. The closest is Multi-Channel Notification Service, where each notification goes to the set of channels, push, email or SMS, that the user's preferences allow, and failed deliveries are retried and deduplicated. Its palette has no Recipient List node, so draw the list inside the notification service, with the preference lookup on an edge and one queue per channel.

Practice this