learning: NATS 101 paper and pub/sub paper completed with estate mapping, goldfish boundary, drills

2026-11-06 15:30:58 +01:00
1 parent f6aad467e2
commit 90054b4329
@@ -0,0 +1,66 @@
+# NATS + JetStream 101
+
+Learning-gate paper for subject 1 of the curriculum
+(see [the curriculum](../README.md#learning-per-technology-resources)).
+We build ON knowledge, not around it.
+
+## 1. Source of truth
+
+Read these, in this order, and quote them back rather than paraphrase:
+
+- NATS core concepts: <https://docs.nats.io/nats-concepts/what-is-nats>
+- Subjects and wildcards: <https://docs.nats.io/nats-concepts/subjects>
+- JetStream overview: <https://docs.nats.io/nats-concepts/jetstream>
+- Durable consumers and replay semantics: <https://docs.nats.io/nats-concepts/jetstream/js_walkthrough>
+- Reference (for drills): <https://docs.nats.io/reference/reference-protocols/nats-protocol>
+
+No blogs, no tutorials, no chat summaries. If something is missing from
+the official sources, that is itself a finding worth recording here.
+
+## 2. Estate mapping (our reality, host-verified)
+
+| Item | Value | Truth of record |
+|------|-------|-----------------|
+| Host | `nats-dev.eachpath.local` (Saturn VM 122), `10.0.30.122` | [host record](../../eachpath.local/saturn.eachpath.local/vms/nats-dev.eachpath.local/nats-dev.eachpath.local.md) |
+| NATS server | v2.10.24, `/usr/local/bin/nats-server` | host record |
+| Ports | client `30000`, HTTP/monitoring `30001` | host record |
+| JetStream | enabled, file store `/var/lib/nats/jetstream` (max 10 GB file / 1 GB memory) | host record |
+| Streams | `REGISTER` -> `nimmerverse.register.>` (durable), `CYCLE` -> `nimmerverse.cycle.>` (100k msgs) | host record, 2026-11-06 |
+| First round-trip | `VM123 ALIVE 2026-11-06` published to `nimmerverse.register.pulse`, replayed by durable consumer `nyx-probe` | host record, 2026-11-06 |
+| Client library | `nats-py 2.16.0` in nimmer-lib venv (aynee) | verified 2026-11-06 |
+
+## 3. Drills
+
+Hands-on, on OUR estate, answers written into this paper:
+
+- D1: Is the server alive right now? Read its identity from the HTTP
+  monitoring port *without* a client library. (curl is a client too.)
+- D2: List the streams and their message counts, from the monitoring
+  port only.
+- D3: Publish one message of your own words and read it back via a
+  durable consumer. Prove the bus *remembers* after the publisher is
+  gone.
+- D4: Prove the bus *forgets on schedule*: find the retention setting
+  on `CYCLE` and show where 100k lives in `nats stream info`.
+- D5: Subjects are names, and names carry meaning: publish to
+  `nimmerverse.register.pulse` and subscribe `nimmerverse.register.*`.
+  Explain why the `*` matched and when you would use `>` instead.
+- D6: Replay from sequence 1 for a *second* durable consumer and watch
+  the first one's position remain untouched. Explain why two listeners
+  on the same bus can disagree about *where they are* without ever
+  corrupting each other.
+
+## 4. Understand-check (ten words)
+
+Said back, in our own words, before any primitive builds on this bus.
+
+> draft (nyx, 2026-11-06): *the bus keeps every message until retention says stop; consumers read independently.*
+> dafit's version: (to be said back)
+
+## 5. Open questions
+
+dafit's question log starts here. Every answer that teaches something
+gets written into this paper, dated, host-verified if it touches our
+estate.
+
+- (waiting for the first question)