mqtt-5-learning/lessons/README.md

# MQTT in Go: lessons and concept coverage

Begin with [Lesson 0 — The broker, Go backend, and device lifecycle](00-system-lifecycle.md) for the complete system story. Lessons 1–8 open with a lifecycle question and diagram where useful, then provide a guiding question before each implementation step.

Broker deployment and administration are part of the learning goals. Read [Broker operations](broker-operations.md) alongside Lesson 1; it explains lifecycle, credential maintenance, backup/restore, upgrades, and remote-deployment preparation. Commands are explained in the lesson that introduces them.

Follow these lessons in order from the learning project root. Read the concept and packet flow first, predict the experiment, then implement and compare the result. Go and basic Docker syntax are assumed; explanations focus on MQTT behavior and operational consequences. Full early examples remain available as reference solutions.

1. [Set up the broker and MQTT 5 lab](01-lab-setup.md)
2. [Write and understand a Go MQTT 5 connection](02-go-connection.md)
3. [Add typed TOML and koanf configuration](03-typed-configuration.md)
4. [Publish, subscribe, and build a device simulator](04-publish-subscribe-simulator.md)
5. [Design contracts and validate inbound messages](05-contracts-validation.md)
6. [Manage callbacks, concurrency, and cancellation](06-concurrency-cancellation.md)
7. [Build reliable command and response behavior](07-command-response.md)
8. [Expose device commands through HTTP](08-http-commands.md)
9. [Learn MQTT 5 sessions through failure experiments](09-sessions-recovery.md)
10. [Expiry, presence, and retained state](10-expiry-presence-state.md)
11. [MQTT security boundaries](11-security-boundaries.md)
11B. [Provision device ACLs with Mosquitto Dynamic Security](11b-dynamic-security.md) — optional implementation extension to Section 11

Continue with course Sections 12–15 after the security lessons, then implement [Section 16 — MQTT 5 controls](16-mqtt5-controls.md). Course sections 12–15 and 17–18 remain guided checklists, not complete reference programs.

Paho is pinned to **v0.23.0**, the selected course baseline. Use the matching checkout under `references/paho.golang-v0.23.0/`. This release requires Go 1.24 or newer; the lessons' Go 1.25 baseline is compatible.

The files are learning instructions and reference solutions. Application code has not been installed into the learning project: create it yourself as each lesson directs. Section 2 supplies the first backend program; Section 3 adds configuration; Section 4 replaces the backend program and adds shared transport plus a simulator. Do not combine both versions of `main.go` in the same package.

## Previously recorded verification (before this review)

The complete Go examples were extracted into a separate temporary module and checked with Go 1.27.1 against the pinned dependencies. They passed compilation, `go vet`, and configuration precedence/validation tests, including a race-enabled test run. Smaller explanatory fragments are identified as fragments and require their surrounding program or test.

An isolated temporary Mosquitto 2.0.22 lab verified the documented Compose configuration, password-file permissions, ACL file loading, initial subscriptions, Go heartbeats, QoS 1 ping/pong, incorrect-password rejection, and subscription restoration after broker restart. The temporary broker and clients were removed afterward. The lesson exercises still require you to verify behavior in your own implementation; this check does not prove production reliability.

Sections 5–11 and 16 are guided exercises, not complete tested reference programs. Their implementation checks are for you to run after writing the code.

## Verification for the 2026-10-08 teaching review

Extracted the complete Lesson 2–4 programs and the new Paho/TLS fragments into a temporary module. They passed `go build -buildvcs=false ./...` and `go vet -buildvcs=false ./...` against the pinned dependencies. The flag disables Git revision stamping because this environment cannot read usable repository metadata; it does not change MQTT behavior. Fragment wrappers supply their surrounding variables/imports for type checking.

Checked local Markdown links, source paths, code fences, and expandable answer blocks. Reviewed protocol explanations against official MQTT/Mosquitto documentation and the matching local Paho source. No live broker, TLS, failure-injection, or load experiments were run in this review, and Mermaid rendering was not verified. The earlier runtime results above are historical records, not fresh results for the revised examples.

## Coverage map: explain it, then prove it

| Concept | Where it is explained | Evidence you should produce |
| --- | --- | --- |
| Broker routing, topic names/filters, wildcards | 1 and 4 | Trace CLI packets and change one topic filter |
| CONNECT/CONNACK, identity, Keep Alive, reconnect | 2 and 3 | Explain connection versus subscription/device readiness |
| QoS 0/1/2, per-hop acknowledgements, DUP and business IDs | 4 and 7 | Predict no-subscriber, lower-QoS, and duplicate outcomes |
| Callback/ACK order, manual acknowledgement, bounded queues | 6 | Show the RAM loss window and measurable overload |
| Payload validation, Content Type, Payload Format | 5 | Reject valid-looking but invalid messages before state changes |
| Response Topic, Correlation Data, timeouts, idempotency | 7 and 8 | Match concurrent results and retry without another effect |
| Clean Start, Session Expiry, Session Present, recovery stores | 9 | Predict network versus process restart outcomes |
| Message Expiry, retained deletion, Will/Will Delay, freshness | 10 | Observe stale command suppression and presence limitations |
| TLS, authentication, ACLs, identity and response destinations | 1 and 11 | Fail each security boundary deliberately |
| Live per-device provisioning and revocation | 11B (optional) | Deny cross-device topics, then disable a connected client |
| Subscription options, unsubscribe, shared consumers | 16 | Compare live/replayed messages and consumer distribution |
| Receive Maximum, packet size, properties, aliases, capabilities | 16 | Record packet direction, negotiated limit, and measured behavior |
| Docker mount/volume identity, recreation, overrides, crashes | Broker operations | Explain exactly which state survives each command |

Coverage means these concepts are explained and have exercises. It does not mean you have completed the experiments or that this course implements every optional MQTT extension. Enhanced authentication is introduced conceptually; broker-specific authentication plugins and bridges are outside the lab's implementation scope.

For each experiment, write: **prediction → operation and reason → observed packet/application evidence → explanation → restoration step**. Expand the answer blocks only after explaining the outcome yourself.

See [COURSE.md](../COURSE.md) for the complete sequence and the connection to Robot Market's backend.