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

learning/Publish-Subscribe.md

@@ -0,0 +1,121 @@
+Publish-Subscribe
+
+Everything in NATS starts with publish-subscribe. A publisher sends a message to a subject, and every subscriber listening on that subject gets a copy. This is the foundation everything else builds on.
+
+How It Works
+
+    1.Publishers send messages to a subject — a simple string like orders.created
+    2.Subscribers express interest in subjects they care about
+    3.NATS delivers a copy of each message to every matching subscriber
+    4.No coupling — publishers don't know about subscribers, and subscribers don't know about publishers
+
+This decoupling gives you tremendous flexibility. Services can be added, removed, or restarted without coordinating with anyone else.
+
+
+Publishing Messages
+
+You publish a message by sending it to a subject:
+
+#!/bin/bash
+
+# Publish a message to the "weather.updates" subject
+nats pub weather.updates "Temperature: 72°F"
+
+Python:
+
+# Publish a message to the subject "weather.updates"
+await nc.publish("weather.updates", "Temperature: 72°F".encode())
+
+
+Key points:
+
+    1.Publishers don't wait for acknowledgments (fire-and-forget)
+    2.Messages are delivered to all active subscribers
+    3.If no subscribers exist, the message is simply discarded
+
+
+Subscribing to Subjects
+
+Subscribers express interest in subjects to receive messages:
+
+#!/bin/bash
+
+# Subscribe to messages on the "weather.updates" subject
+nats sub "weather.updates"
+
+Python:
+
+# Subscribe to 'weather.updates' synchronously
+sub = await nc.subscribe("weather.updates")
+
+# Process messages
+while True:
+    try:
+        msg = await sub.next(timeout=1)
+        print(f"Received: {msg.data.decode()}")
+    except TimeoutError:
+        break
+
+
+When to Use Pub/Sub
+
+Publish-subscribe is ideal when multiple services need to react to the same event:
+
+    1.Event broadcasting — notify services about user signups, order placements, deployments
+    2.Data distribution — send updates to multiple dashboards or monitoring services
+    3.Fan-out notifications — alert all interested parties about state changes
+    4.Audit logging — multiple services independently log the same events
+
+
+Real-world example
+
+Imagine an e-commerce system where an order is placed. You publish a single event:
+
+nats pub orders.created '{"orderId": "123", "total": 99.99}'
+
+Multiple services subscribe and each reacts differently:
+
+    1.Inventory Service updates stock levels
+    2.Email Service sends a confirmation email
+    3.Analytics Service records metrics
+    4.Shipping Service prepares the shipment
+
+One publish, four independent reactions — no coordination needed.
+
+---
+
+## The goldfish boundary (what this paper describes, precisely)
+
+Everything above is *core NATS*: fire-and-forget, delivered to active
+subscribers only, discarded if no one listens. No memory. We found this
+the live way on 2026-11-06: `nats sub "dev.>"` caught `dev.test.hello`
+while the terminal sat open, and the bus has no record of it since.
+
+JetStream adds the memory: streams claim subjects, messages are stored,
+durable consumers replay and each tracks its own position.
+
+## Estate mapping (our reality, host-verified)
+
+| Item | Value | Truth of record |
+|------|-------|-----------------|
+| Bus | `nats-dev.eachpath.local:30000` (VM 122) | [host record](../../eachpath.local/saturn.eachpath.local/vms/nats-dev.eachpath.local/nats-dev.eachpath.local.md) |
+| Streams | `REGISTER` -> `nimmerverse.register.>` (durable), `CYCLE` -> `nimmerverse.cycle.>` (100k msgs) | host record, 2026-11-06 |
+| Publisher hosts | aynee (nats-cli + nats-py 2.16.0 in nimmer-lib venv), nimmerworld-dev | both, 2026-11-06 |
+| Core-mode example | `dev.test.hello` = "Hello Nimmerverse!": live delivery only, in NO stream | verified 2026-11-06 |
+
+Note: the generic example `orders.created` has no stream here; on OUR
+estate, subjects without a stream are transient by design. Our persistent
+naming is `nimmerverse.*` under the two streams above.
+
+## Drills (run on our estate, record answers in section 5 of the 101 paper)
+
+1. Terminal A (nimmerworld-dev): `nats pub nimmerverse.cycle.hello "dafit was here"`
+   Terminal B (aynee): `nats sub "nimmerverse.cycle.*"` - watch the `*`
+   match exactly one token.
+2. `nats stream info CYCLE` - the bus has now *counted* the message.
+3. Kill both terminals, start a subscriber again: core-mode subject is
+   empty, stream subject replays its history. That contrast IS the lesson.
+
+## Understand-check (ten words, said back before any primitive builds on this)
+
+> dafit's version: (to be said back)