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

Message Channel

A named address that a sender writes to and receivers read from, so neither has to know the other: usually one kind of message per channel, and a deliberate choice between giving each message to one receiver or to every subscriber.

Which service does a dock call?

A city bike-share has 400 docking stations. When a rider pushes a bike into a dock, the dock reports it to a dock gateway, and the first version of the gateway did the obvious thing: it called the rentals service's API to close the ride. Then the rebalancing team, whose vans move bikes from full stations to empty ones, asked for every return too. Then maintenance, which wanted to know when a bike flagged with a flat tyre was back in a dock.

Each request became one more call inside the gateway, and each call tied the gateway to something it had no reason to know: where the rentals service runs, what the rebalancing API expects, that maintenance exists at all. When rentals moved to a new cluster, the gateway needed a release. When the rebalancing API was slow, returns were slow. The question the gateway team kept asking, which service do we call next, had the wrong shape.

An address both sides agree on

The gateway does not need to call anyone. It needs to say "bike 4417 was returned to dock 12 at 08:14" somewhere that interested services can read it. A Message Channel is that somewhere: a named address inside a messaging system, which a sender writes messages to and receivers read messages from. The gateway sends every return to a channel called bikes.returned, and rentals, rebalancing and maintenance each read from it. The gateway knows the channel's name and the shape of the message, and nothing about who reads. Each reader knows the same two things, and nothing about who wrote.

One return, three readers

The gateway writes each return once. A fourth reader is a new subscription to bikes.returned, with no change to the gateway.

Rentals can now move to another cluster without the gateway noticing, and a slow reader no longer holds the gateway up: as long as the messaging system has room for the messages, the gateway's send is finished once the system has accepted it, whatever the readers are doing. The messaging system is usually a Message Broker, such as RabbitMQ, Kafka or a cloud service, and each product has its own word for a channel (a queue, a topic, a stream). What the channel does not remove is the dependency on the message itself: every reader relies on the fields the gateway puts in it.

One kind of message per channel

Six months in, someone proposes a single channel, bike-share, for everything the system says: returns, unlock commands, low-battery alerts from the e-bikes, price changes. One channel is less to set up, and every reader pays for it. Maintenance now receives price changes it has to recognise and skip. Rentals has to inspect every message to find the returns. The day the pricing team adds a new kind of message, every reader meets a shape it has never seen, and each one ignores it, logs it or fails on it, depending on how carefully it was written.

A channel that carries one kind of message works as a contract. A reader of bikes.returned knows that everything arriving there is a return, with a bike id, a dock id and a time, and it can be written for exactly that. The Enterprise Integration Patterns catalogue has a name for a channel kept to one message type: a Datatype Channel. When the message itself has to change, a new field or a renamed one, the gateway and the readers have to stay compatible with each other; Schema evolution: event formats & compatibility goes through how. When a mixed channel cannot be avoided and the messaging system supports it, a reader can ask for only the messages it wants, which is a Selective Consumer.

Every reader, or just one?

Returns are facts: a bike came back. Rentals, rebalancing and maintenance each need every one of them, so the channel gives each reader its own copy of each message. That kind is a publish-subscribe channel: each message goes to every subscriber. Publish / Subscribe looks at the same pattern from the publisher's side.

Charging for a ride is different. When rentals closes ride 88213, it works out the fare, €1.90 for 19 minutes, and sends the command "charge ride 88213" to a channel called billing.charge-ride. Billing runs three instances to keep up with the morning peak, and the charge is a job that one of them should do. That kind is a point-to-point channel: each message goes to one of the receivers, not to all of them.

Each charge to one instance

Three commands, three instances. The channel hands each command to one of them, not to all three.

Mixing the two kinds up is expensive. Put the charge commands on a publish-subscribe channel, with each billing instance subscribed on its own, and every ride is charged three times unless something catches the duplicates; the fourth instance added for the summer adds a fourth charge. Put the returns on a point-to-point channel shared by rentals, rebalancing and maintenance, and the three services compete for each return, so each sees only a share of them: rentals leaves most rides open and the rebalancing map shows full stations as half empty, while every service handles correctly each message it does get.

So the question to ask of each channel is what kind of message it carries, the distinction Command, Document & Event Messages draws in full. A fact that several services may care about goes on a publish-subscribe channel. A job that one receiver should do goes on a point-to-point channel, and the receivers sharing it are Competing Consumers, which also explains why "one receiver" is not "exactly once": when an instance crashes holding a command it has not yet acknowledged, a messaging system that redelivers unacknowledged messages hands it out again, often to another instance, and the job can run twice.

Many systems combine the two. Billing could read the returns from the publish-subscribe channel as one subscriber, with its three instances sharing that single subscription: billing as a whole gets every return, and inside billing each return goes to one instance, with the same caveat about redelivery. Kafka's consumer groups and Google Cloud Pub/Sub's subscriptions work this way, and Pub/sub: topics, subscriptions & replay shows the setup.

What a name says, and what it does not

Name a channel after the message, not after who sends or who reads it: bikes.returned still tells the truth when a fourth team subscribes, while dock-gateway-to-rentals ties the name to the very services the channel was meant to decouple. And a name is all a channel is by itself, an address and a contract. Whether a return sent at 08:14 survives the broker restarting at 08:15 depends on how the broker is set up, the subject of Guaranteed Delivery; a charge command that fails on every attempt needs a Dead Letter Channel; and when the city's transit authority, on another messaging system, wants the returns, a Messaging Bridge links a channel there to this one.

Name the pipes

The channel as a contract is what the Pipes and Filters Challenge practises: a source, steps that each do one transformation, and a channel between each pair of steps. Title every channel after the one kind of message it carries at that point, "raw dock pings" before the first step and "bike returns" after it, not after the steps on either side of it.

Practice this