nats/analysis.md

name, lang, domain, description, tags, uses_functions, uses_types, framework, entry_point, dir_path, repo_url

name	lang	domain	description	tags	uses_functions	uses_types	framework	entry_point	dir_path	repo_url
nats	py	datascience	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)	nats pubsub messaging jetstream asyncio docker			jupyterlab	notebooks/01_core_pubsub.ipynb	analysis/nats

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.

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:

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:

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