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

Messaging Gateway

Give application code a typed method in place of the messaging API, and make its contract say what the call promises: when it returns, which errors and timeouts it raises, and whether a retry can send the message twice.

Forty lines to say a box has left

The line the order service needed was notifyShipment(order). What a mail-order plant nursery had instead, inside the method that marks an order as shipped, was forty lines: open a connection to the broker, serialise the order to JSON, set a content type and a message id, publish to the channel shipments.dispatched, wait for the broker to confirm it has the message, and catch the broker client's own exceptions, from a refused connection to a closed channel. Two of the forty, marking the order shipped, were the business. The rest existed so that the notifications service could email the customer a tracking link.

Every other place that sent a message repeated those lines with small differences: one used another serialiser, one never waited for the confirmation. The broker client's types had spread through code with no reason to know a broker existed, and testing that a shipped order tells the customer needed a running broker or a mock of the client library.

A method that means one thing

A Messaging Gateway gives application code a typed method in place of the messaging API. The order service calls notifyShipment(order), and a small class behind that method does the forty lines: it builds the message, picks the channel, sets the headers and sends. The order code knows that a shipment notice exists and what it carries. It does not know there is a broker, which channel the notice goes to, or what format it travels in.

Typed call in, message out

The order service sees one method. The broker, the channel name and the message format live behind the gateway.

The gateway is one kind of Message Endpoint. The gateway in this example wraps sending, and a gateway can wrap receiving too; a Service Activator is the receiving endpoint that turns a message into a call to an existing service method. A gateway is not a Channel Adapter, which plugs an existing system that knows nothing about messaging into a channel. A gateway is code in your own application, written so that the rest of it has a typed way in.

What the method promises

Hiding the messaging API does not hide what messaging does, and the method's contract is where the gateway has to say it. notifyShipment(order) returns nothing, so what does "it returned" mean? For this gateway, that the broker has confirmed it accepted the notice on shipments.dispatched. Not that notifications has read it, and not that the customer has an email. The contract answers three questions:

  • When does the call return? Once the channel has accepted the message, or only once a reply has come back.
  • What can it raise? The broker refused the message or could not be reached; no confirmation arrived within, say, two seconds; for a method that waits for an answer, no reply arrived in time. The gateway raises its own errors for these, such as ShipmentNoticeFailed, not the broker client's exceptions, so the caller never imports the client library to catch them.
  • What does a timeout mean? Not that the message was lost. The broker may have stored the notice and the confirmation may be what went missing, so after a timeout the outcome is unknown.

That last answer is why a retry inside the gateway has a price: resent after a lost confirmation, the notice can reach the channel twice, and the customer gets two emails. A gateway that retries says so in its contract and reuses the message id on every attempt, so the receiver can tell the copy from a new notice. Spacing the attempts is what Retry is about; dropping the copy is what an Idempotent Consumer does.

Methods that wait for an answer

Some calls need an answer. Before printing a label, the order service needs a courier booking from the carrier-booking service: bookCourier(parcel) has to come back with a pickup slot and a tracking number. A booking request and a shipment notice are different kinds of message, told apart in Command, Document & Event Messages. For the gateway, what changes is the method's shape: bookCourier returns at once with a Future / Promise of a booking, and the caller waits on it, or attaches what to do next, while the request travels. Behind it, the gateway stamps the request with a Correlation Identifier and a Return Address and completes the future when the matching reply comes back; how the matching works, late replies included, belongs to Correlation Identifier.

The contract gains two lines: how long the future waits before it fails with a timeout (picking that number is what Timeout is for), and what that failure tells the caller, which is less than it seems. Carrier booking may still process the request, so a courier can turn up for a parcel that has no label, and calling bookCourier again books a second one unless carrier booking recognises the repeat.

Changing the transport underneath

Because callers see only the method, the transport behind it can change without touching them, and this is a promise easy to overstate. Replace the broker with a call to the notifications service's HTTP API and notifyShipment(order) still compiles. But the broker accepted notices while notifications was down for a deploy; the HTTP call fails until it is back, and takes as long as notifications takes to answer.

Callers stay unchanged only if the contract stays the same. A buffered queue and a synchronous HTTP call differ in latency, in whether the receiver has to be up, and in how a reply comes back, so design the contract for the weakest transport you expect to use, from the start: the notice may arrive late, the call can fail, and a timeout leaves the outcome unknown.

Where tests cut the wire

The same interface is where tests leave messaging out: the shipping code's tests hand it a fake gateway that records its calls, and check that notifyShipment was called once, with the right order. In Hexagonal (Ports & Adapters) terms, the interface is a port and the gateway one adapter behind it.

The seam holds only while the gateway does messaging and nothing else. Choosing the channel, setting headers from the message type and mapping an order to the message format belong in it. Deciding there that wholesale orders skip the notice is business logic: the tests that fake the gateway stop exercising it, and replacing the gateway quietly drops it. Once the gateway makes business decisions from the payload, it has stopped being a messaging-only seam.

Writing the promise down

In the Messaging Endpoints & Broker Challenge the gateway is the application's only way into messaging, and the edge into it carries a method the business would recognise, notifyShipment(order), not "publish". Before drawing it, write the method's promise in one line, as a caller would need it: returns when the channel accepts the notice; fails if the broker refuses it or two seconds pass without a confirmation; may resend, with the same message id. A method that waits for an answer adds its reply deadline, and its request gets a Return Address. Then ask whether that line would survive another broker, or HTTP, behind the gateway; where it would not, changing the transport means changing the promise and checking its callers.

Practice this