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:
1 parent
01f681165f
commit
f047b9c7ae
128 files changed
+18893
-7591
No files matched your search
+24
-24
@@ -140,7 +140,7 @@ Abonnieren kostet ein Paket, und **der Broker führt die Abonnementliste**. Es g
|
||||
|
||||
```yaml
|
||||
subscribe:
|
||||
topic: Tutorial/ConsoleIn/U/alice/E/text
|
||||
topic: Demo/ConsoleIn/U/alice/E/text
|
||||
```
|
||||
|
||||
Only then does a serialisation library have a clear job. `JsonTools` keeps **two** mappers, and the asymmetry is deliberate:
|
||||
@@ -156,7 +156,7 @@ Tolerant in, strict out. A single shared mapper would have to give up one of tho
|
||||
|
||||
```yaml
|
||||
subscribe:
|
||||
topic: Tutorial/ConsoleIn/U/alice/E/text
|
||||
topic: Demo/ConsoleIn/U/alice/E/text
|
||||
```
|
||||
|
||||
C'est seulement là qu'une bibliothèque de sérialisation a une tâche claire. `JsonTools` garde **deux** mappeurs, et l'asymétrie est voulue :
|
||||
@@ -172,7 +172,7 @@ Tolérant en entrée, strict en sortie. Un mappeur unique devrait renoncer à l'
|
||||
|
||||
```yaml
|
||||
subscribe:
|
||||
topic: Tutorial/ConsoleIn/U/alice/E/text
|
||||
topic: Demo/ConsoleIn/U/alice/E/text
|
||||
```
|
||||
|
||||
Erst dann hat eine Serialisierungsbibliothek eine klare Aufgabe. `JsonTools` hält **zwei** Mapper, und die Asymmetrie ist Absicht:
|
||||
@@ -189,12 +189,12 @@ Tolerant hinein, streng hinaus. Ein einziger Mapper müsste auf eines davon verz
|
||||
The naming scheme finally gets its name: **D**escription (what contracts this service understands and publishes), **U**nit (which instance), **I**ntent (requested behaviour), **S**tatus (what is true now), **E**vent (what happened).
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
|
||||
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 — `Tutorial/#/E/text`, where `#` is not the last level — and `MqttTools.isValidFilter` rejects it; the old subscription stands and the Status still tells the truth.
|
||||
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.
|
||||
:::
|
||||
@@ -203,12 +203,12 @@ That rejection exposes a real gap, worth naming rather than hiding: it is logged
|
||||
Le schéma de nommage reçoit enfin son nom : **D**escription (quels contrats ce service comprend et publie), **U**nit (quelle instance), **I**ntent (comportement demandé), **S**tatus (ce qui est vrai maintenant), **E**vent (ce qui est arrivé).
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
|
||||
Demo/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
|
||||
```
|
||||
|
||||
`U/<unit>` est ce dont le système de fichiers n'avait pas besoin : chaque machine avait sa réplique du même chemin relatif, l'identité d'instance était implicite. MQTT a un espace de noms partagé : un sujet doit donc dire *quelle* copie. Coder en dur `U/alice` dans une capacité est donc pire que de coder en dur `consoleIn.outbox` : cela lie la compilation à un déploiement. Configuré par Intent, **une seule compilation sert tout le monde** — d'où les trois noms d'unité en arguments de `MqttConfigure`. Les noms d'unité *sont* la topologie.
|
||||
|
||||
Recâblage observé sur un système en marche : publiez un nouvel Intent nommant une autre source, et le service se désabonne de l'ancienne, s'abonne à la nouvelle et republie `S/subscriptions` en conséquence. Sans redémarrage, sans édition. Envoyez au contraire un filtre invalide — `Tutorial/#/E/text`, où `#` n'est pas le dernier niveau — et `MqttTools.isValidFilter` le rejette ; l'ancien abonnement demeure et le Status continue de dire vrai.
|
||||
Recâblage observé sur un système en marche : publiez un nouvel Intent nommant une autre source, et le service se désabonne de l'ancienne, s'abonne à la nouvelle et republie `S/subscriptions` en conséquence. Sans redémarrage, sans édition. Envoyez au contraire un filtre invalide — `Demo/#/E/text`, où `#` n'est pas le dernier niveau — et `MqttTools.isValidFilter` le rejette ; l'ancien abonnement demeure et le Status continue de dire vrai.
|
||||
|
||||
Ce rejet révèle une vraie lacune, à nommer plutôt qu'à cacher : il n'est journalisé que localement. Le configurateur ne peut savoir si son Intent a été appliqué ou refusé, et un moniteur ne peut distinguer « refusé » de « pas encore traité ». Dans cette conception, l'émetteur apprend le résultat en lisant le Status et en le comparant à sa demande. Publier les refus comme Event, ou un Status de dernière erreur, combleraient la lacune ; ni l'un ni l'autre n'est dans le matériel : c'est une décision de conception à justifier.
|
||||
:::
|
||||
@@ -217,12 +217,12 @@ Ce rejet révèle une vraie lacune, à nommer plutôt qu'à cacher : il n'est jo
|
||||
Das Namensschema erhält endlich seinen Namen: **D**escription (welche Verträge dieser Dienst versteht und veröffentlicht), **U**nit (welche Instanz), **I**ntent (gewünschtes Verhalten), **S**tatus (was jetzt gilt), **E**vent (was geschehen ist).
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
|
||||
Demo/ROT13/U/alice/{I, S/online, S/subscriptions/text, E/crypted}
|
||||
```
|
||||
|
||||
`U/<unit>` brauchte das Dateisystem nie: jede Maschine hatte ihr eigenes Replikat desselben relativen Pfades, Instanzidentität war implizit. MQTT hat einen gemeinsamen Namensraum, ein Topic muss also sagen, *welche* Kopie. `U/alice` in einer Fähigkeit festzuschreiben ist daher schlimmer, als `consoleIn.outbox` es je war: es bindet das Build an ein Deployment. Per Intent konfiguriert, **dient ein Build allen** — daher die drei Unit-Namen als Argumente von `MqttConfigure`. Die Unit-Namen *sind* die Topologie.
|
||||
|
||||
Umverdrahten, am laufenden System beobachtet: einen neuen Intent mit anderer Quelle veröffentlichen, und der Dienst kündigt die alte, abonniert die neue und veröffentlicht `S/subscriptions` passend neu. Kein Neustart, keine Änderung. Schickt man stattdessen einen ungültigen Filter — `Tutorial/#/E/text`, wo `#` nicht die letzte Ebene ist — weist `MqttTools.isValidFilter` ihn ab; das alte Abonnement bleibt, und der Status sagt weiter die Wahrheit.
|
||||
Umverdrahten, am laufenden System beobachtet: einen neuen Intent mit anderer Quelle veröffentlichen, und der Dienst kündigt die alte, abonniert die neue und veröffentlicht `S/subscriptions` passend neu. Kein Neustart, keine Änderung. Schickt man stattdessen einen ungültigen Filter — `Demo/#/E/text`, wo `#` nicht die letzte Ebene ist — weist `MqttTools.isValidFilter` ihn ab; das alte Abonnement bleibt, und der Status sagt weiter die Wahrheit.
|
||||
|
||||
Diese Abweisung legt eine echte Lücke offen, die man benennen und nicht verstecken sollte: sie wird nur lokal protokolliert. Der Konfigurator erfährt nicht, ob sein Intent angewandt oder abgelehnt wurde, und ein Monitor kann „abgelehnt" nicht von „noch nicht verarbeitet" unterscheiden. In diesem Entwurf erfährt ein Sender das Ergebnis, indem er den Status liest und mit seiner Anfrage vergleicht. Abweisungen als Event zu veröffentlichen oder ein Letzter-Fehler-Status würden die Lücke schliessen; beides steht nicht im Material — es ist eine zu begründende Entwurfsentscheidung.
|
||||
:::
|
||||
@@ -230,13 +230,13 @@ Diese Abweisung legt eine echte Lücke offen, die man benennen und nicht verstec
|
||||
## [What a new subscriber learns, and what a dead one admits]{.en}[Ce qu'un nouvel abonné apprend, et ce qu'un mort avoue]{.fr}[Was ein neuer Abonnent erfährt und was ein Toter zugibt]{.de} {#sec-retained-and-will}
|
||||
|
||||
::: {.en}
|
||||
Subscribing to `Tutorial/#` for three seconds, with nothing being published, returns this:
|
||||
Subscribing to `Demo/#` for three seconds, with nothing being published, returns this:
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ROT13/U/nitro5/S/subscriptions/text "Tutorial/ConsoleIn/U/nitro5/E/text"
|
||||
Tutorial/ConsoleOut/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ConsoleOut/U/nitro5/S/subscriptions/text "Tutorial/ROT13/U/nitro5/E/crypted"
|
||||
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.
|
||||
@@ -252,13 +252,13 @@ The will is **retained**, so when the broker publishes it on the client's behalf
|
||||
:::
|
||||
|
||||
::: {.fr}
|
||||
S'abonner à `Tutorial/#` pendant trois secondes, sans que rien ne soit publié, renvoie ceci :
|
||||
S'abonner à `Demo/#` pendant trois secondes, sans que rien ne soit publié, renvoie ceci :
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ROT13/U/nitro5/S/subscriptions/text "Tutorial/ConsoleIn/U/nitro5/E/text"
|
||||
Tutorial/ConsoleOut/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ConsoleOut/U/nitro5/S/subscriptions/text "Tutorial/ROT13/U/nitro5/E/crypted"
|
||||
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"
|
||||
```
|
||||
|
||||
Un arrivant tardif apprend instantanément tout le câblage actuel du système, sans rien demander et sans qu'aucun composant sache qu'un moniteur existe. C'est le **Status** retenu. Aucun Event n'arrive, car les Events sont publiés non retenus — « State retenu, Events non retenus ». C'est aussi la bonne réponse à l'instinct de *demander* à un service ce qu'il fait : personne ne demande ; le service le déclare, une fois, et le courtier le garde pour quiconque se présente.
|
||||
@@ -274,13 +274,13 @@ Elle est **retenue** : quand le courtier la publie au nom du client, elle rempla
|
||||
:::
|
||||
|
||||
::: {.de}
|
||||
Drei Sekunden `Tutorial/#` abonnieren, ohne dass etwas veröffentlicht wird, ergibt dies:
|
||||
Drei Sekunden `Demo/#` abonnieren, ohne dass etwas veröffentlicht wird, ergibt dies:
|
||||
|
||||
```text
|
||||
Tutorial/ROT13/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ROT13/U/nitro5/S/subscriptions/text "Tutorial/ConsoleIn/U/nitro5/E/text"
|
||||
Tutorial/ConsoleOut/U/nitro5/S/online {"value":true}
|
||||
Tutorial/ConsoleOut/U/nitro5/S/subscriptions/text "Tutorial/ROT13/U/nitro5/E/crypted"
|
||||
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"
|
||||
```
|
||||
|
||||
Ein Spätankömmling erfährt augenblicklich die gesamte aktuelle Verdrahtung des Systems, ohne jemanden zu fragen und ohne dass eine Komponente von einem Monitor weiss. Das ist retained **Status**. Keine Events kommen an, denn Events werden nicht retained veröffentlicht — „retained State, nicht retained Events". Es ist auch die richtige Antwort auf den Reflex, einen Dienst zu *fragen*, was er tut: niemand fragt; der Dienst erklärt es einmal, und der Broker bewahrt es für jeden, der kommt.
|
||||
|
||||
Reference in new issue
Block a user