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 Endpoint

The code inside an application that connects it to one messaging channel, so the rest of the application deals in domain objects and calls, not in the messaging API: one endpoint per channel, sending or receiving, and on the receiving side a choice between polling for messages and being called with them.

Nine files that import the broker client

A freight forwarder's declarations app files a customs declaration for each shipment it moves, then waits for the customs authority's decision on it: cleared, or held for inspection. Declarations go out and decisions come back over RabbitMQ. When the company decides to move to a managed cloud broker, a developer searches the codebase for the RabbitMQ client library before estimating the work, and finds it imported in nine files.

Two of them are what you would expect: code that opens connections and declares queues. The other seven are business code. The duty calculator builds the message body itself, sets a shipment-id header and catches the client's connection exception. The code that decides whether a held shipment can go to the warehouse reads each decision straight from the library's delivery object and acknowledges it halfway through a business rule. Changing the transport means editing the duty rules, and the estimate grows by weeks.

A seam for each channel

The way out is to give messaging a place of its own. A Message Endpoint is the code, part of the application, that connects it to one channel. Connections, wire formats, headers and broker exceptions live inside it; the rest of the application deals in shipments and declarations and makes ordinary calls. After the change, the declarations app has two endpoints:

  • A sending endpoint for customs.declarations. The duty calculator hands it a Declaration object. The endpoint turns it into a message, a JSON body plus the headers the receiver needs, sends it, and reports success or failure in the application's own terms rather than as a library exception.
  • A receiving endpoint for customs.decisions. It takes each message from the channel, turns it into a CustomsDecision object and passes it to the release logic, which never sees a delivery object or an acknowledgement.
Two channels, two endpoints

The app hands objects to the sending endpoint and receives objects from the receiving one; only the endpoints touch the channels.

Now the RabbitMQ client is imported in the two endpoints and the connection setup, and the move to the new broker rewrites those. The duty calculator does not change, as long as the endpoints can keep the same promises on the new broker.

Why two endpoints and not one MessagingService with a method per channel? Because each channel brings its own message type, its own failures and, on the receiving side, its own pace, and a class that serves every channel grows a branch for each, and the mess the nine files made moves into one class with a branch per channel. The Enterprise Integration Patterns catalogue draws the line the same way: an endpoint is specific to one channel, and one endpoint either sends or receives, so an application that talks on four channels has at least four.

Sending is a call, receiving is a schedule

The two endpoints are not mirror images. Sending starts when the application decides to send: the duty calculator calls the endpoint, which in this app returns once the broker confirms it has the message; another endpoint may return as soon as the client library has the message, and what each return promises is the contract Messaging Gateway spells out. Receiving starts when a message exists, and the application does not choose when that is. Customs releases decisions as its officers and systems get to them, a trickle through the day and several thousand in the hour after its overnight run. Something has to decide when the receiving endpoint takes the next one, and there are two ways to arrange it.

A polling consumer asks. The endpoint runs a loop: request the next message, or the next batch, from the channel, process it, ask again. When nothing is waiting, the request comes back empty, or waits a bounded time for something to arrive. A Kafka consumer works this way, calling poll for the next batch of records, and so does an Amazon SQS client calling ReceiveMessage, which returns at most ten messages per call and, with long polling, waits up to 20 seconds for one to arrive. The asking has a cost: an empty poll is a request that returns nothing, which SQS bills like any other, and a message that arrives just after a poll waits for the next one.

An event-driven consumer is called. The endpoint registers a handler with the messaging client, and the client invokes it each time a message arrives. A JMS MessageListener, whose onMessage method is called once per message, is the classic shape; a RabbitMQ consumer subscribed with basic.consume has messages pushed to it by the broker.

The difference that matters is who sets the pace. A polling endpoint takes a message only when it asks, so after the overnight run it works through the backlog at the speed the release logic can sustain, and when the warehouse system it calls is down it can stop asking. An event-driven endpoint reacts as soon as a decision arrives, with no loop to write, but the client library decides when to call it, so its pace is set in configuration instead. In RabbitMQ, a consumer that acknowledges manually sets that pace with the prefetch limit, the most unacknowledged messages it can hold at once; with automatic acknowledgement, or with no limit in effect, the broker can push the whole backlog into the endpoint's memory.

Some event-driven APIs are a polling loop the library runs for you; from the application's side, the question is still whether the endpoint asks for the next message or is handed it. Two other decisions on the receiving endpoint matter as much as its style, and each has its own article: how many threads or instances share customs.decisions, a trade between throughput and the order customs sent the decisions in that Competing Consumers weighs, and when the endpoint acknowledges a message, which decides whether a crash can lose a decision and belongs to Guaranteed Delivery.

Two endpoints with names of their own

Two specialised endpoints get articles of their own: a Messaging Gateway, used here on the sending side to give the application a typed method such as fileDeclaration(declaration), though a gateway can wrap receiving too, and a Service Activator, the receiving endpoint that turns each message into a call to an existing service method. Service Activator, polling consumer and event-driven consumer are all kinds of message endpoint, and they combine: an activator still polls or is called.

An application that cannot be changed at all, a packaged product that only knows its database, connects through a Channel Adapter outside it instead. In Hexagonal (Ports & Adapters) terms, the endpoint is the adapter on the messaging side.

What leaks past the endpoint

The seam holds only while the library's types stay behind it. A receiving endpoint that hands the release logic the delivery object "for convenience" puts the broker back in the business code, and swapping brokers later means rewriting business logic again. Where the line runs between translation and business rules on each side, the two specialised endpoints spell out: Messaging Gateway for sending, as these examples use it, Service Activator for receiving.

Polling or called, and no shortcuts

The Messaging Endpoints & Broker Challenge asks for Message Endpoints connecting application code to channels. Put the declarations app's decisions channel behind a receiving Message Endpoint and write on its edge which style it uses, polling or called, and why that style suits a burst of several thousand decisions after the overnight run. Then look for any arrow from the application node straight to a channel or to the broker: each one is a place where the move to a new broker would reach the business code.

Practice this