feat: analisis NATS pub/sub con 3 notebooks

2026-06-03 19:53:43 +02:00
commit 595930f3c8
24 changed files with 6167 additions and 0 deletions
@@ -0,0 +1,57 @@
+---
+name: nats
+lang: py
+domain: datascience
+description: "Demostracion de envio de datos por pub/sub entre procesos con NATS (core pub/sub, wildcards, queue groups, request/reply, JetStream y procesos OS reales)"
+tags: [nats, pubsub, messaging, jetstream, asyncio, docker]
+uses_functions: []
+uses_types: []
+framework: "jupyterlab"
+entry_point: "notebooks/01_core_pubsub.ipynb"
+dir_path: "analysis/nats"
+repo_url: ""
+---
+
+## Notas
+
+Analisis didactico de **NATS** como sistema de mensajeria pub/sub entre procesos. El broker corre en Docker (`nats:latest -js`, puerto 4222) y el cliente es `nats-py` (asyncio). Tres notebooks progresivos:
+
+| Notebook | Contenido |
+|---|---|
+| `01_core_pubsub.ipynb` | Modelo base: conexion, publish/subscribe, fan-out a N subscribers, wildcards `*` y `>`. |
+| `02_queue_request_jetstream.ipynb` | Queue groups (reparto de carga), request/reply (RPC con inbox temporal), JetStream (stream persistente + consumer durable + replay). |
+| `03_procesos_reales.ipynb` | Publisher y subscribers como **procesos del SO independientes** (`subprocess`), cada uno con su PID. Demuestra el desacople real: el publisher no conoce a sus subscribers. |
+
+Los scripts `notebooks/procs/publisher.py` y `notebooks/procs/subscriber.py` son los programas que el notebook 03 lanza como procesos reales.
+
+### Como usar
+
+1. Requiere Docker disponible (con permisos para el usuario actual). La primera celda de cada notebook arranca el broker de forma idempotente con la funcion `ensure_nats`, asi que cada notebook funciona de forma aislada.
+2. Lanzar Jupyter del analisis: `cd analysis/nats && ./run-jupyter-lab.sh` (puerto 8890).
+3. Abrir cualquier notebook y ejecutar las celdas en orden.
+
+### Requisitos
+
+- `nats-py` (instalado en el `.venv` del analisis).
+- Imagen Docker `nats:latest` (se descarga con `docker pull nats:latest` la primera vez).
+- El broker comparte el contenedor `nats_demo` entre los tres notebooks.
+
+### Parar el broker
+
+Cuando termines, para y elimina el contenedor:
+
+```bash
+docker stop nats_demo && docker rm nats_demo
+```
+
+### Reproducir / regenerar los notebooks
+
+El script `build_notebooks.py` regenera los tres `.ipynb` desde cero con `nbformat` (sin ejecutar). La ejecucion se hace luego desde JupyterLab o via el MCP de Jupyter:
+
+```bash
+.venv/bin/python build_notebooks.py
+```
+
+### Nota tecnica sobre el MCP de Jupyter
+
+Si abres Claude desde la raiz de `fn_registry`, su MCP de Jupyter apunta al servidor global (puerto 8899, root `fn_registry`), no al servidor de este analisis (8890). Para usar el MCP contra este analisis con su propio `.venv`, abre Claude desde el directorio del analisis: `cd analysis/nats && claude` — el `.mcp.json` local enlaza el MCP al puerto 8890.