---
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. |
| `04_jetstream_benchmark.ipynb` | **JetStream a fondo** (storage/retention/limits, consumers durables + ack + cursor, dedup por `Nats-Msg-Id`, retención `workqueue`, deliver policies) + **simulador de rendimiento interactivo**: un botón `ipywidgets` que lanza 1 publisher → N subscribers con miles de mensajes y una gráfica en movimiento (acumulado pub vs subs + throughput instantáneo). |

Los scripts `notebooks/procs/publisher.py` y `notebooks/procs/subscriber.py` son los programas que el notebook 03 lanza como procesos reales.

El notebook 04 requiere `ipywidgets` (incluido en el `.venv` del análisis). El simulador del notebook es interactivo: al abrir el notebook en JupyterLab, ejecuta sus celdas hasta el widget y pulsa **▶ Ejecutar benchmark** (los sliders ajustan número de mensajes y de subscribers). La gráfica se anima mientras corre.

> Si al abrir el notebook el widget muestra `Error displaying widget: model not found`, **re-ejecuta la celda del widget** en tu kernel (los modelos de `ipywidgets` no se rehidratan desde un kernel anterior). Para una versión interactiva más robusta y sin depender de Jupyter, usa el **playground** (ver abajo).

## Playground: simulador de rendimiento (webapp)

`playground/` es una webapp standalone equivalente al simulador del notebook 04, pero sin `ipywidgets`: sirve una página con un botón y unos sliders, y al pulsarlo lanza el benchmark en el servidor y transmite las muestras por WebSocket a un canvas que dibuja la gráfica en movimiento en el navegador. Reutiliza el `.venv` del análisis (con `nats-py` y `websockets`); no tiene dependencias ni repo propios.

```bash
cd analysis/nats/playground
../.venv/bin/python server.py
# abrir http://127.0.0.1:7788   (WebSocket en 7879)
```

Pulsa **▶ Ejecutar benchmark**: un publisher envía N mensajes (slider, hasta 200.000) a M subscribers (slider, hasta 12) y la gráfica muestra en vivo los acumulados de enviados vs recibidos. Verificado: 100.000 msgs → 4 subs = 400.000 entregas en ~1,1 s (fan-out ×4 exacto, ~367.000 entregas/s).

Archivos: `playground/server.py` (servidor WebSocket + HTTP estático + benchmark NATS) y `playground/index.html` (UI con canvas, sin librerías externas).

### 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.