Parts V to IX in the book, extension 2.9.1, Demo topics

Add chapters 05-08 to the three language profiles: the published book
stopped at Part IV because only 00-04 were listed.

Rename the MQTT topic root Tutorial/ to Demo/ in Part IX (code and
output included).

Shared notes extension 2.9.1: dependency folders are named after the
extension version, so browsers stop serving stale scripts after an
update.

Full rebuild of _book/ (HTML and PDF, three languages); remove the stray
site_libs/ that the last Deploy commit had added at the project root.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
MatsuneMikuroiandClaude Fable 5.1 committed 2026-10-16 09:44:27 +02:00
1 parent 01f681165f
commit f047b9c7ae
128 files changed
+18893 -7591

No files matched your search

+231 -1
View File
@@ -324,11 +324,241 @@
"href": "04-part-iv-rewind.html#sec-route-topic-intent",
"title": "5  Part IV — Rewind",
"section": "5.4 ROUTE and TOPIC are Intent",
"text": "5.4 ROUTE and TOPIC are Intent\nApply two tests to TOPIC consoleIn.outbox. Does it describe something that happened? No. Something currently true? No. It says please begin listening here — desired behaviour, which is Intent. The mediator’s ROUTE is the same kind of message: please forward from here to there.\nOne trap worth naming, because it is tempting in a defence: publishing an Intent is of course something that happened. Classification follows what the message says, not the fact that it exists.\nAnd one condition, which returns later: the dynamic version is not automatically superior. It makes sense only if the consumer actually understands the producer’s message contract.\nSTATIC MEDIATED DYNAMIC DIRECT\nProducer → Mediator → Consumer Intent → (Producer ──► Consumer)",
"text": "5.4 ROUTE and TOPIC are Intent\nApply two tests to TOPIC consoleIn.outbox. Does it describe something that happened? No. Something currently true? No. It says please begin listening here — desired behaviour, which is Intent. The mediator’s ROUTE is the same kind of message: please forward from here to there.\nOne trap worth naming, because it is tempting in a defence: publishing an Intent is naturally something that happened. Classification follows what the message says, not the fact that it exists.\nAnd one condition, which returns later: the dynamic version is not automatically superior. It makes sense only if the consumer actually understands the producer’s message contract.\nSTATIC MEDIATED DYNAMIC DIRECT\nProducer → Mediator → Consumer Intent → (Producer ──► Consumer)",
"crumbs": [
"<span class='chapter-number'>5</span>  <span class='chapter-title'>[Part IV — Rewind]{.en}[Partie IV — Rembobinage]{.fr}[Teil IV — Zurückspulen]{.de}</span>"
]
},
{
"objectID": "05-part-v-subscriptions.html",
"href": "05-part-v-subscriptions.html",
"title": "6  Part V — Replay the dynamic idea across processes",
"section": "",
"text": "6.1 One blocking watch is not enough\nSteps 35 to 38 take the subscription idea out of the single JVM. The services become separate programs again, but instead of mediators copying files, each service watches the mailbox it was told to watch. One assumption of the first filesystem helper does not survive the move, and fixing it is what this part is really about.\nFileMessageBoard.watch(topic, receiver) registers one directory and blocks forever. That was enough while every process watched one fixed mailbox. A dynamically wired service needs more:\nThe old signature cannot express that, and the consequence was already visible earlier: the configurable mediator accepted exactly one ROUTE, because the moment it began watching its source it went deaf to its own control inbox. The limitation was never whose directory — it was one, fixed, forever.",
"crumbs": [
"<span class='chapter-number'>6</span>  <span class='chapter-title'>[Part V — Replay the dynamic idea across processes]{.en}[Partie V — Rejouer l'idée dynamique entre processus]{.fr}[Teil V — Die dynamische Idee über Prozesse hinweg wiederholen]{.de}</span>"
]
},
{
"objectID": "05-part-v-subscriptions.html#sec-watch-limit",
"href": "05-part-v-subscriptions.html#sec-watch-limit",
"title": "6  Part V — Replay the dynamic idea across processes",
"section": "",
"text": "always watch its own control inbox\nAND\nadd a watched directory at runtime\nAND\npossibly remove it later",
"crumbs": [
"<span class='chapter-number'>6</span>  <span class='chapter-title'>[Part V — Replay the dynamic idea across processes]{.en}[Partie V — Rejouer l'idée dynamique entre processus]{.fr}[Teil V — Die dynamische Idee über Prozesse hinweg wiederholen]{.de}</span>"
]
},
{
"objectID": "05-part-v-subscriptions.html#sec-filesubscriptions",
"href": "05-part-v-subscriptions.html#sec-filesubscriptions",
"title": "6  Part V — Replay the dynamic idea across processes",
"section": "6.2 The helper: FileSubscriptions",
"text": "6.2 The helper: FileSubscriptions\nOne WatchService can serve many directories. register(...) returns a WatchKey identifying one of them, watcher.take() returns whichever key has events, and key.cancel() deregisters it. The helper keeps both directions, name → key and key → name, so an event can be traced back to the mailbox it came from.\nEvents do not reach a callback directly. They go onto a queue, read with take(), carrying\nrecord IncomingMessage(String mailbox, Message message) {}\nTwo reasons, and order of arrival is only the third. First, the observing thread must stay responsive for every subscribed directory: a callback that transformed, published or blocked would stall the observation of all the others. Second, the mailbox name travels with the message, so one loop in the service can decide what a message means — control inbox, so this is Intent to act on; subscribed source, so this is data to transform — and that same loop is free to add or remove subscriptions, because it is not sitting inside a callback.",
"crumbs": [
"<span class='chapter-number'>6</span>  <span class='chapter-title'>[Part V — Replay the dynamic idea across processes]{.en}[Partie V — Rejouer l'idée dynamique entre processus]{.fr}[Teil V — Die dynamische Idee über Prozesse hinweg wiederholen]{.de}</span>"
]
},
{
"objectID": "05-part-v-subscriptions.html#sec-two-publications",
"href": "05-part-v-subscriptions.html#sec-two-publications",
"title": "6  Part V — Replay the dynamic idea across processes",
"section": "6.3 Two publications instead of four",
"text": "6.3 Two publications instead of four\nRun SensorService, DynamicProcessorService and DynamicActuatorService — and no mediators — then let Configure.java publish the two TOPIC messages. A line typed afterwards leaves exactly two application publications in the board:\n\n\n\nmailbox\ncontent\nwhat it is\n\n\n\n\nconsoleIn/outbox\nTEXT hello\nthe input\n\n\nrot13/outbox\nTEXT uryyb\nthe result\n\n\nrot13/inbox\nTOPIC consoleIn/outbox\nIntent, published once\n\n\nconsoleOut/inbox\nTOPIC rot13/outbox\nIntent, published once\n\n\n\nconsoleOut/inbox holds no payload at all: ConsoleOut takes straight from rot13/outbox. Its inbox changed job, from carrying messages to carrying wiring.\nA line typed before Configure.java ran stays in consoleIn/outbox forever. A subscription that does not exist yet misses what came before it — exactly what the restarted mediator showed when it delivered nothing.\n\n\n\nversion\napplication publications\nprocesses in the data path\n\n\n\n\nmediated (step 18)\n4\n5\n\n\nconfigurable mediator (step 27)\n4\n5\n\n\ndynamic (step 38)\n2\n3",
"crumbs": [
"<span class='chapter-number'>6</span>  <span class='chapter-title'>[Part V — Replay the dynamic idea across processes]{.en}[Partie V — Rejouer l'idée dynamique entre processus]{.fr}[Teil V — Die dynamische Idee über Prozesse hinweg wiederholen]{.de}</span>"
]
},
{
"objectID": "06-part-vi-vocabulary.html",
"href": "06-part-vi-vocabulary.html",
"title": "7  Part VI — Replay it over Syncthing, and name the messages",
"section": "",
"text": "7.1 The distributed dynamic run\nSteps 39 to 47 distribute the dynamic version across two machines, say precisely what “direct” means, and then — only now, after the ideas have been used — give the three kinds of message their names: Intent, Status, Event.\nSensor on one machine, ROT13 and the actuator on the other, no mediator anywhere. After the two TOPIC Intents had replicated, a typed line produced the result on the other machine — and the board shows what that cost:\nThe timing was the interesting part. The input was published at 02:35:12 and the results appeared on the first machine at 04:11:28.797 and .893 — 96 ms apart, long after the input. Syncthing had been saturated overnight, so the batch arrived when the queue drained. The chain was correct throughout; the transport’s latency is simply not something the architecture controls. Compare 24 ms for the same chain on one machine.",
"crumbs": [
"<span class='chapter-number'>7</span>  <span class='chapter-title'>[Part VI — Replay it over Syncthing, and name the messages]{.en}[Partie VI — Rejouer sur Syncthing, et nommer les messages]{.fr}[Teil VI — Über Syncthing wiederholen und die Nachrichten benennen]{.de}</span>"
]
},
{
"objectID": "06-part-vi-vocabulary.html#sec-distributed-dynamic",
"href": "06-part-vi-vocabulary.html#sec-distributed-dynamic",
"title": "7  Part VI — Replay it over Syncthing, and name the messages",
"section": "",
"text": "consoleIn/outbox: the input;\nrot13/outbox: the result, written by the service that produced it;\nconsoleOut/inbox: Intent only, where the mediated version held a full copy of every message.",
"crumbs": [
"<span class='chapter-number'>7</span>  <span class='chapter-title'>[Part VI — Replay it over Syncthing, and name the messages]{.en}[Partie VI — Rejouer sur Syncthing, et nommer les messages]{.fr}[Teil VI — Über Syncthing wiederholen und die Nachrichten benennen]{.de}</span>"
]
},
{
"objectID": "06-part-vi-vocabulary.html#sec-direct-precisely",
"href": "06-part-vi-vocabulary.html#sec-direct-precisely",
"title": "7  Part VI — Replay it over Syncthing, and name the messages",
"section": "7.2 What “direct” means, exactly",
"text": "7.2 What “direct” means, exactly\nTwo hops that look alike are architecturally opposite:\n\na transport hop — Syncthing on each side, possibly a relay in between — adds no participant that knows the topology and nothing reacts to it. If the packets detoured through another continent, no claim here would be contradicted.\nan architectural hop — a mediator copying consoleIn/outbox → rot13/inbox — adds a component that must know both names, sits in the availability chain, and republishes the message.\n\nSo the defensible claim is: ROT13 reacts to ConsoleIn’s publication with no component of ours in between, and without containing ConsoleIn’s identity. Not: the data goes straight from A to B. The architecture controls which messages a service reacts to, not the transport’s routing.",
"crumbs": [
"<span class='chapter-number'>7</span>  <span class='chapter-title'>[Part VI — Replay it over Syncthing, and name the messages]{.en}[Partie VI — Rejouer sur Syncthing, et nommer les messages]{.fr}[Teil VI — Über Syncthing wiederholen und die Nachrichten benennen]{.de}</span>"
]
},
{
"objectID": "06-part-vi-vocabulary.html#sec-ise",
"href": "06-part-vi-vocabulary.html#sec-ise",
"title": "7  Part VI — Replay it over Syncthing, and name the messages",
"section": "7.3 Intent, Status, Event",
"text": "7.3 Intent, Status, Event\nThree kinds of message, named only after being used:\n\n\n\n\n\n\n\n\n\nsays\nour examples\n\n\n\n\nE — Event\nsomething happened\nTEXT hello as ConsoleIn/E/text; TEXT uryyb as ROT13/E/crypted\n\n\nS — Status/State\nsomething is currently true\nROT13/S/subscriptions — not published by our system yet\n\n\nI — Intent\nwhat should happen\nTOPIC consoleIn/outbox, ROUTE … …\n\n\n\nPast tense is a useful hint for Events. For Intent the test is two questions: does the message report something that happened? No. Something currently true? No. Then it requests behaviour.\nOne trap: publishing an Intent is naturally something that happened. Classify by what the message says, not by the fact that it exists — otherwise every message becomes an Event and the vocabulary stops being useful.\nStatus deserves its own note, because the instinct is to ask for it: “what are your subscriptions?” But asking is a call, and a call needs the asker to know the component, to know it is up, and to wait. Status is published: ROT13 publishes ROT13/S/subscriptions whenever its wiring changes, and anyone interested reads it. The reader then needs a topic, not a component, and ROT13 never learns who audits it. Each kind answers a different question:\n\nan Event is only useful if you were listening — our stranded messages, three times over;\na Status is what a newcomer needs: the current value, without replaying history;\nan Intent asks for a change.\n\nAnd commands are not forbidden. Sending ROT13/I with ACTION Hello is command-like, and the material’s verdict is “Fine.” The component performs its capability and publishes its Events and its Status. The flow it endorses is Intent → component → State + Events.",
"crumbs": [
"<span class='chapter-number'>7</span>  <span class='chapter-title'>[Part VI — Replay it over Syncthing, and name the messages]{.en}[Partie VI — Rejouer sur Syncthing, et nommer les messages]{.fr}[Teil VI — Über Syncthing wiederholen und die Nachrichten benennen]{.de}</span>"
]
},
{
"objectID": "06-part-vi-vocabulary.html#sec-one-writer",
"href": "06-part-vi-vocabulary.html#sec-one-writer",
"title": "7  Part VI — Replay it over Syncthing, and name the messages",
"section": "7.4 The one-writer rule",
"text": "7.4 The one-writer rule\n\nEvery writable resource has exactly one writer authority.\n\nDo not confuse that with the UUID in a message filename. The UUID prevents two publications from choosing the same physical name; writer authority says which component owns a logical Event or Status resource. Two writers never collide on a filename, and that is exactly why the problem is easy to miss.\nWhat a second writer costs: the mailbox name was the only provenance marker, so rot13/outbox stops meaning “ROT13 transformed this” and a subscriber can no longer trust the contract it built on. For Status it is worse — two components each claiming to publish the current value of one fact simply contradict each other, with no ordering guarantee across machines to break the tie. For append-only Events many publications coexist by design; the question is semantic ownership, not collision. When two authorities appear, ask why there are two rather than reaching for a lock.",
"crumbs": [
"<span class='chapter-number'>7</span>  <span class='chapter-title'>[Part VI — Replay it over Syncthing, and name the messages]{.en}[Partie VI — Rejouer sur Syncthing, et nommer les messages]{.fr}[Teil VI — Über Syncthing wiederholen und die Nachrichten benennen]{.de}</span>"
]
},
{
"objectID": "07-part-vii-mediation.html",
"href": "07-part-vii-mediation.html",
"title": "8  Part VII — Now merge the two architectural ideas",
"section": "",
"text": "8.1 A transformer earns its existence\nTwo mediators were removed and the gain was measured. Steps 48 to 52 answer the obvious next question: does that make mediation wrong? No — and the distinction that decides it is sharp enough to apply to a design you have never seen.\nWhat was removed was a mediator computing A → A: an expensive identity function, in the availability chain, copying every message without adding meaning.\nNow take a producer publishing {\"value\":\"Hello\"} and a consumer expecting a display structure. A TextToDisplayTransformer between them contributes schema transformation, semantic adaptation, possibly unit conversion, possibly aggregation. That is work neither side should own: ROT13 is not meant to decide terminal colours, and the console is not meant to understand ROT13’s payload shape.\nThe line is drawn by contract compatibility, not by whether something is added. A mediator converting Celsius to Fahrenheit changes rather than adds and has earned its place; one appending a timestamp to a message the consumer already understands has added something and is still suspicious. The question is always: could the consumer read the producer’s message as it stands?",
"crumbs": [
"<span class='chapter-number'>8</span>  <span class='chapter-title'>[Part VII — Now merge the two architectural ideas]{.en}[Partie VII — Fusionner les deux idées architecturales]{.fr}[Teil VII — Die zwei architektonischen Ideen zusammenführen]{.de}</span>"
]
},
{
"objectID": "07-part-vii-mediation.html#sec-transformer",
"href": "07-part-vii-mediation.html#sec-transformer",
"title": "8  Part VII — Now merge the two architectural ideas",
"section": "",
"text": "If a consumer semantically understands a producer’s publication, direct subscription is often sufficient. If the contracts are incompatible, introduce a transformer that performs an actual adaptation.\nA mediator that merely forwards compatible data is suspicious. A mediator that adds necessary semantics has earned its existence.",
"crumbs": [
"<span class='chapter-number'>8</span>  <span class='chapter-title'>[Part VII — Now merge the two architectural ideas]{.en}[Partie VII — Fusionner les deux idées architecturales]{.fr}[Teil VII — Die zwei architektonischen Ideen zusammenführen]{.de}</span>"
]
},
{
"objectID": "07-part-vii-mediation.html#sec-egoistic-transformer",
"href": "07-part-vii-mediation.html#sec-egoistic-transformer",
"title": "8  Part VII — Now merge the two architectural ideas",
"section": "8.2 The transformer is egoistic too",
"text": "8.2 The transformer is egoistic too\nInserted into the chain, the transformer subscribes to rot13/outbox and publishes to its own outbox; ConsoleOut then subscribes to the transformer’s outbox instead of ROT13’s. Note what that costs in code: nothing. ConsoleOut receives a different Intent — TOPIC display/outbox rather than TOPIC rot13/outbox — and the chain is rewired. ROT13 never learns the transformer exists; the transformer never learns ConsoleOut exists.\nWhy not let it publish straight into consoleOut/inbox, saving a mailbox? Four reasons:\n\nknowledge — it would contain ConsoleOut’s name, which is topology inside a service, the relapse of step 28;\nownership — that inbox is ConsoleOut’s control channel, written by the configurator; payload from the transformer would give it two authorities;\nreach — its own outbox can be read by a logger, a web view or a second display at no cost, while one inbox serves exactly one consumer;\nmutability — an aggregator can later be inserted after it by sending one different Intent, with no component edited.",
"crumbs": [
"<span class='chapter-number'>8</span>  <span class='chapter-title'>[Part VII — Now merge the two architectural ideas]{.en}[Partie VII — Fusionner les deux idées architecturales]{.fr}[Teil VII — Die zwei architektonischen Ideen zusammenführen]{.de}</span>"
]
},
{
"objectID": "07-part-vii-mediation.html#sec-complete-filesystem",
"href": "07-part-vii-mediation.html#sec-complete-filesystem",
"title": "8  Part VII — Now merge the two architectural ideas",
"section": "8.3 The complete filesystem architecture",
"text": "8.3 The complete filesystem architecture\nEvery mailbox with exactly one writer:\n\n\n\n\n\n\n\nmailbox\nsingle writer\n\n\n\n\nconsoleIn/outbox\nSensorService\n\n\nrot13/outbox\nProcessorService\n\n\ndisplay/outbox\nthe transformer\n\n\nevery control inbox\nthe configurator — the one designated Intent authority\n\n\nthe terminal\nActuatorService, which writes no mailbox at all\n\n\n\nEgoistic capabilities, Intent from one authority, a transformer only where contracts differ, one writer per resource, and the topology nowhere in the capabilities. That is the design the filesystem was good enough to teach — and the next part asks what the filesystem itself is no longer good enough for.",
"crumbs": [
"<span class='chapter-number'>8</span>  <span class='chapter-title'>[Part VII — Now merge the two architectural ideas]{.en}[Partie VII — Fusionner les deux idées architecturales]{.fr}[Teil VII — Die zwei architektonischen Ideen zusammenführen]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html",
"href": "08-part-ix-mqtt.html",
"title": "9  Part IX — MQTT",
"section": "",
"text": "9.1 What the filesystem taught, and what it is not for\nThe 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.\nThe 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:\nA 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-filesystem-verdict",
"href": "08-part-ix-mqtt.html#sec-filesystem-verdict",
"title": "9  Part IX — MQTT",
"section": "",
"text": "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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-mqtt-mapping",
"href": "08-part-ix-mqtt.html#sec-mqtt-mapping",
"title": "9  Part IX — MQTT",
"section": "9.2 MQTT should look familiar",
"text": "9.2 MQTT should look familiar\n\n\n\nfilesystem / Syncthing\nMQTT\n\n\n\n\nsynchronised message-board root\nbroker / namespace\n\n\ndirectory path\ntopic\n\n\n.msg file\npublication\n\n\nfile contents\npayload\n\n\nWatchService\nsubscription\n\n\ndynamic directory\ntopic / filter\n\n\ncontrol directory\nI\n\n\nstate directory\nS/…\n\n\nevent directory\nE/…\n\n\n\nThe reaction the material is after: “Oh. We already know this architecture.” MQTT is a transport change, not an architectural claim.\nTwo 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.\nThe 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-paho",
"href": "08-part-ix-mqtt.html#sec-paho",
"title": "9  Part IX — MQTT",
"section": "9.3 The library, the client id and the broker address",
"text": "9.3 The library, the client id and the broker address\nJava 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.”\nTwo details of connecting carry weight:\n\nthe 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 &gt; 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.\nthe 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.\n\nSubscribing 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-structured-intent",
"href": "08-part-ix-mqtt.html#sec-structured-intent",
"title": "9  Part IX — MQTT",
"section": "9.4 Structured Intent, and two object mappers",
"text": "9.4 Structured Intent, and two object mappers\nTOPIC 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:\nsubscribe:\n topic: Demo/ConsoleIn/U/alice/E/text\nOnly then does a serialisation library have a clear job. JsonTools keeps two mappers, and the asymmetry is deliberate:\n\nreading uses a YAML factory with FAIL_ON_UNKNOWN_PROPERTIES off — JSON is a subset of YAML, so hand-typed Intent is accepted, and a newer configurator can send fields an older service ignores;\nwriting uses plain JSON with INDENT_OUTPUT on, so published payloads are strict and readable.\n\nTolerant in, strict out. A single shared mapper would have to give up one of those.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-duise",
"href": "08-part-ix-mqtt.html#sec-duise",
"title": "9  Part IX — MQTT",
"section": "9.5 DUISE, and rewiring a running system",
"text": "9.5 DUISE, and rewiring a running system\nThe 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).\nDemo/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}\nU/&lt;unit&gt; 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.\nRewiring, 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.\nThat 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-retained-and-will",
"href": "08-part-ix-mqtt.html#sec-retained-and-will",
"title": "9  Part IX — MQTT",
"section": "9.6 What a new subscriber learns, and what a dead one admits",
"text": "9.6 What a new subscriber learns, and what a dead one admits\nSubscribing to Demo/# for three seconds, with nothing being published, returns this:\nDemo/ROT13/U/nitro5/S/online {\"value\":true}\nDemo/ROT13/U/nitro5/S/subscriptions/text \"Demo/ConsoleIn/U/nitro5/E/text\"\nDemo/ConsoleOut/U/nitro5/S/online {\"value\":true}\nDemo/ConsoleOut/U/nitro5/S/subscriptions/text \"Demo/ROT13/U/nitro5/E/crypted\"\nA 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.\nRetained 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:\nvar will = new MqttMessage(\"{\\\"value\\\":false}\".getBytes(UTF_8), 1, true, new MqttProperties());\noptions.setWill(lastWillTopic, will);\nThe 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-coupling-remains",
"href": "08-part-ix-mqtt.html#sec-coupling-remains",
"title": "9  Part IX — MQTT",
"section": "9.7 What survived the transport, and what coupling remains",
"text": "9.7 What survived the transport, and what coupling remains\nThe 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.\nLoose 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.\nSeparately, 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.\nThe step-78 checklist is the tool to keep. Twelve questions, of which these six carry the argument for this system:\n\n\n\n\n\n\n\nquestion\nanswer here\n\n\n\n\ndoes a capability contain a hard-coded producer identity?\nno — it arrives as Intent\n\n\nwhich foreign contracts must it understand?\none Event contract each, plus its own Intent schema\n\n\nwhere is topology defined?\nin the configurator, outside the data path\n\n\ncan topology change without recompiling?\nyes — demonstrated on a running system\n\n\ncould the transport be replaced?\nyes — demonstrated, filesystem then MQTT\n\n\ndoes every mediator do something that needs mediation?\nyes, vacuously: TEXT → TEXT needs none, and none exists\n\n\n\nThe material’s own caution applies: the answers need not all be “no”. They need to be intentional.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-whole-journey",
"href": "08-part-ix-mqtt.html#sec-whole-journey",
"title": "9  Part IX — MQTT",
"section": "9.8 The whole journey",
"text": "9.8 The whole journey\nThe 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.\n\n\n\n\n\n\n\n\n\nstage\nhow the parts are joined\nwhere the topology lives\nin the data path besides the capabilities\n\n\n\n\n1 procedural\ndirect calls\ninside the capability code\n—\n\n\n2 egoistic services\nnot joined at all\nnowhere — that is the problem\n—\n\n\n3 static mediation, one JVM\nmailboxes, copied by mediators\nthe mediators, started in main()\ntwo mediators\n\n\n4 static mediation, filesystem\ndirectories, copied by mediator processes\nthe operator’s command lines\ntwo mediator processes\n\n\n5 static mediation, Syncthing\nreplicated directories\nthe operator’s command lines\ntwo mediator processes, plus replication delay\n\n\n6 named, configurable mediators\nROUTE Intent from an orchestrator\nthe orchestrator, outside the path\nthe mediators, still\n\n\n7 dynamic, one JVM\nservices listen, told by TOPIC Intent\nthe configurator\nnothing\n\n\n8 dynamic, filesystem\nthe same, over directories\nthe configurator\nnothing\n\n\n9 dynamic, Syncthing\nthe same, over replicated directories\nthe configurator\nnothing — transport hops only\n\n\n10 contracts\ncompatible: direct; incompatible: a transformer\nthe configurator\na transformer, only where contracts differ\n\n\n11 MQTT\ntopics on a broker\nthe configurator\nnothing — the broker is transport\n\n\n\nRead 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.",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "08-part-ix-mqtt.html#sec-sentences",
"href": "08-part-ix-mqtt.html#sec-sentences",
"title": "9  Part IX — MQTT",
"section": "9.9 The sentences to remember",
"text": "9.9 The sentences to remember\n\nEvent-driven describes how information and control flow.\nLoose coupling describes how much participants need to know about one another.\nPublish what happened.\nDeclare what you want.\nPublish your own State.\nKeep capabilities egoistic.\nKeep topology out of capabilities.\nDo not pay for a mediator unless it actually mediates something.\n\nAnd whenever an architecture becomes confusing, go back to the first question of this book: who knows whom?",
"crumbs": [
"<span class='chapter-number'>9</span>  <span class='chapter-title'>[Part IX — MQTT]{.en}[Partie IX — MQTT]{.fr}[Teil IX — MQTT]{.de}</span>"
]
},
{
"objectID": "glossary.html",
"href": "glossary.html",