3.2 KiB
3.2 KiB
NATS + JetStream 101
Learning-gate paper for subject 1 of the curriculum (see the curriculum). 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 |
| 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
CYCLEand show where 100k lives innats stream info. - D5: Subjects are names, and names carry meaning: publish to
nimmerverse.register.pulseand subscribenimmerverse.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)