9 Part IX — MQTT
9.1 What the filesystem taught, and what it is not for
The filesystem taught publication boundaries, directories as addresses, observation, independent processes, independent languages, synchronisation latency, runtime wiring, State, Intent, Events, mediator costs, service ownership and transformer services. It was a good teacher and it is not an elegant message broker: by the end the architecture was clean and the transport was a pile of .tmp files, atomic moves, rescanning, shared paths and replication delay.
The conclusion is not “files bad, MQTT good”. The filesystem has an advantage MQTT cannot match — it routinely stores gigabytes or terabytes, while brokers and clients are built for small messages, and chunking a huge payload over MQTT means inventing a file-transfer protocol inside a message protocol. So:
Use messages for coordination and events. Use an appropriate file or object store for large data. A message can carry the location, identity and metadata of that data instead of the terabytes themselves.
A replicated filesystem also gives every machine a local copy, which is a genuine strength — though replication is not a backup: deletion and corruption replicate too, unless versioning preserves older copies.
9.2 MQTT should look familiar
| filesystem / Syncthing | MQTT |
|---|---|
| synchronised message-board root | broker / namespace |
| directory path | topic |
.msg file |
publication |
| file contents | payload |
WatchService |
subscription |
| dynamic directory | topic / filter |
| control directory | I |
| state directory | S/… |
| event directory | E/… |
The reaction the material is after: “Oh. We already know this architecture.” MQTT is a transport change, not an architectural claim.
Two things a directory could not do, both visible in a minute at the command line. A publication made before a subscriber exists never reaches it — the stranded-message problem for the third time, now with an answer the filesystem never had. And a filter like test/# matches test/a and test/a/b/c but not testing/x, because # works on levels, not string prefixes; test/+ would match only one level down.
The deeper correction: a topic is not a container. There is no object called test/a on the broker. A topic is a routing key carried by each publication and matched against the filters of whoever is subscribed at that instant. Directories hold messages; topics match them. One subscription therefore covers topics that do not exist yet — where a message board needed a new directory and a new registration.
9.3 The library, the client id and the broker address
Java has no MQTT client in its standard library, so Paho arrives now — after the need, like the mediator in step 7 and Jackson in step 64. Four things are needed from it: connect, publish, subscribe, callback. Connecting is deliberately anticlimactic: “Nothing architectural happened here. We merely attached our process to the transport.”
Two details of connecting carry weight:
- the client id is not merely a uniqueness token. The broker recognises a returning client by it and keeps session state for it: subscriptions, messages queued at QoS > 0, and the association with its Last Will. A directory never knew who was watching, which is exactly why a restarted watcher’s backlog was never replayed.
- the broker address is deployment configuration: every runnable reads
System.getProperty("mqtt.broker", "tcp://localhost:1883"). It is also the one piece of configuration that cannot arrive as Intent, because Intent travels through the broker. Topology can be published; the address of the thing that publishes it cannot.
Subscribing costs one packet, and the broker keeps the subscription list. There is no standard way to ask it what another client subscribed to — which is why S/subscriptions exists: a component’s own declaration of its wiring, published so the architecture can know what the transport keeps private. Only its owner may publish it, by the one-writer rule, because only its owner knows what it accepted.
9.4 Structured Intent, and two object mappers
TOPIC some/path has one field and one meaning. It cannot say which kind of Intent this is, carry a second parameter, nest, or be extended; and there is nothing for a receiver to validate against. Richer Intent wants structure:
subscribe:
topic: Demo/ConsoleIn/U/alice/E/textOnly then does a serialisation library have a clear job. JsonTools keeps two mappers, and the asymmetry is deliberate:
- reading uses a YAML factory with
FAIL_ON_UNKNOWN_PROPERTIESoff — JSON is a subset of YAML, so hand-typed Intent is accepted, and a newer configurator can send fields an older service ignores; - writing uses plain JSON with
INDENT_OUTPUTon, so published payloads are strict and readable.
Tolerant in, strict out. A single shared mapper would have to give up one of those.
9.5 DUISE, and rewiring a running system
The naming scheme finally gets its name: Description (what contracts this service understands and publishes), Unit (which instance), Intent (requested behaviour), Status (what is true now), Event (what happened).
Demo/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
U/<unit> is what the filesystem never needed: each machine had its own replica of the same relative path, so instance identity was implicit. MQTT has one shared namespace, so a topic must say which copy. Hard-coding U/alice in a capability is therefore worse than hard-coding consoleIn.outbox ever was: it binds the build to one deployment. Configured by Intent, one build serves everyone — which is why MqttConfigure takes three unit names as arguments. The unit names are the topology.
Rewiring, observed on a running system: publish a new Intent naming a different source topic, and the service unsubscribes from the old one, subscribes to the new one, and republishes S/subscriptions to match. No restart, no edit. Send an invalid filter instead — Demo/#/E/text, where # is not the last level — and MqttTools.isValidFilter rejects it; the old subscription stands and the Status still tells the truth.
That rejection exposes a real gap, worth naming rather than hiding: it is logged locally only. The configurator cannot tell whether its Intent was applied or refused, and a monitor cannot distinguish “refused” from “not yet processed”. In this design a sender learns the outcome by reading Status and comparing it with what it asked for. Publishing refusals as an Event, or a last-error Status, would close that gap; neither is in the material, so it is a design decision to justify.
9.6 What a new subscriber learns, and what a dead one admits
Subscribing to Demo/# for three seconds, with nothing being published, returns this:
Demo/ROT13/U/nitro5/S/online {"value":true}
Demo/ROT13/U/nitro5/S/subscriptions/text "Demo/ConsoleIn/U/nitro5/E/text"
Demo/ConsoleOut/U/nitro5/S/online {"value":true}
Demo/ConsoleOut/U/nitro5/S/subscriptions/text "Demo/ROT13/U/nitro5/E/crypted"
A late arrival learns the entire current wiring of the system, instantly, without asking anyone and without any component knowing a monitor exists. That is retained Status. No Events arrive, because Events are published non-retained — “retained State, non-retained Events”. It is also the proper answer to the instinct of asking a service what it is doing: nobody asks; the service states it, once, and the broker keeps it for whoever turns up.
Retained Status alone would lie, though. Kill a service with Ctrl+C and its S/online = true stays on the broker forever. Hence the Last Will, registered at connect time:
var will = new MqttMessage("{\"value\":false}".getBytes(UTF_8), 1, true, new MqttProperties());
options.setWill(lastWillTopic, will);The will is retained, so when the broker publishes it on the client’s behalf it replaces the stale true. The component that fails is not the component that reports the failure — which is the only arrangement that can work. One caveat: a clean DISCONNECT does not trigger a will, so a well-behaved service publishes online=false itself on the way out, and the will covers the ugly deaths.
9.7 What survived the transport, and what coupling remains
The lower half of the filesystem→MQTT table is the point: I, S, E, egoistic services, runtime topology and “transformer if needed” are unchanged. The architecture survived the transport replacement, and that is the strongest available evidence that the architecture was never about the transport.
Loose coupling does not mean nothing knows anything. What remains, necessarily, is agreement on: message syntax, message semantics, topic contracts, Intent, ownership, the meaning of State and the meaning of Events. The goal is not to eliminate coupling but to eliminate unnecessary knowledge. Concretely, in this system each service must understand exactly one foreign Event contract — ROT13 understands ConsoleIn’s E/text, ConsoleOut understands ROT13’s E/crypted — plus the Intent schema it accepts on its own I. That list is the irreducible minimum.
Separately, the broker is a shared infrastructure dependency: everyone needs its address and nothing works without it. Real, but a different kind of thing from one component knowing another.
The step-78 checklist is the tool to keep. Twelve questions, of which these six carry the argument for this system:
| question | answer here |
|---|---|
| does a capability contain a hard-coded producer identity? | no — it arrives as Intent |
| which foreign contracts must it understand? | one Event contract each, plus its own Intent schema |
| where is topology defined? | in the configurator, outside the data path |
| can topology change without recompiling? | yes — demonstrated on a running system |
| could the transport be replaced? | yes — demonstrated, filesystem then MQTT |
| does every mediator do something that needs mediation? | yes, vacuously: TEXT → TEXT needs none, and none exists |
The material’s own caution applies: the answers need not all be “no”. They need to be intentional.
9.8 The whole journey
The program never changed: a line goes in, the same line comes out rotated by 13 letters. What changed, eleven times, is how the parts are joined and who holds the knowledge of how they are joined.
| stage | how the parts are joined | where the topology lives | in the data path besides the capabilities |
|---|---|---|---|
| 1 procedural | direct calls | inside the capability code | — |
| 2 egoistic services | not joined at all | nowhere — that is the problem | — |
| 3 static mediation, one JVM | mailboxes, copied by mediators | the mediators, started in main() |
two mediators |
| 4 static mediation, filesystem | directories, copied by mediator processes | the operator’s command lines | two mediator processes |
| 5 static mediation, Syncthing | replicated directories | the operator’s command lines | two mediator processes, plus replication delay |
| 6 named, configurable mediators | ROUTE Intent from an orchestrator |
the orchestrator, outside the path | the mediators, still |
| 7 dynamic, one JVM | services listen, told by TOPIC Intent |
the configurator | nothing |
| 8 dynamic, filesystem | the same, over directories | the configurator | nothing |
| 9 dynamic, Syncthing | the same, over replicated directories | the configurator | nothing — transport hops only |
| 10 contracts | compatible: direct; incompatible: a transformer | the configurator | a transformer, only where contracts differ |
| 11 MQTT | topics on a broker | the configurator | nothing — the broker is transport |
Read the third column from top to bottom: the topology moves outward, one stage at a time, until no capability holds any of it. Read the last one: the price of that move falls to zero at stage 7 and stays there while the transport changes underneath three times. Same architecture, better transport.
9.9 The sentences to remember
- Event-driven describes how information and control flow.
- Loose coupling describes how much participants need to know about one another.
- Publish what happened.
- Declare what you want.
- Publish your own State.
- Keep capabilities egoistic.
- Keep topology out of capabilities.
- Do not pay for a mediator unless it actually mediates something.
And whenever an architecture becomes confusing, go back to the first question of this book: who knows whom?