<?xml version="1.0" encoding="utf-8" standalone="yes"?><?xml-stylesheet href="/feed_style.xsl" type="text/xsl"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="https://www.rssboard.org/media-rss"><channel><title>Arquitectura – El blog de Ignacio</title><link>https://www.igalvan.es/tags/arquitectura/</link><description>Entradas de Arquitectura en El blog de Ignacio</description><generator>Hugo -- gohugo.io</generator><language>es</language><copyright>Ignacio Galván Vitas</copyright><lastBuildDate>Wed, 18 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://www.igalvan.es/tags/arquitectura/index.xml" rel="self" type="application/rss+xml"/><icon>https://www.igalvan.es/logo.svg</icon><item><title>MCP desde cero: qué es y qué problema resuelve</title><link>https://www.igalvan.es/posts/2026/mcp-desde-cero-que-es/</link><pubDate>Wed, 18 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/mcp-desde-cero-que-es/</guid><description><![CDATA[<p>MCP es una sigla que veía pasar por todas partes sin saber bien qué había detrás. No había trabajado nunca con ello. Esta serie es lo que habría querido encontrar el primer día: empezar de cero, entender qué es, mirar el protocolo por dentro, montar un servidor de verdad sobre PostgreSQL, y después probarlo, romperle el diseño, atacarlo y publicarlo por HTTP.</p>
<p>Son siete entradas. Esta es la primera y es solo teoría, más un servidor de ocho líneas para que haya algo que ejecutar.</p>
<p>Una advertencia que me habría ahorrado una tarde: <strong>MCP ha cambiado mucho este año</strong>. La mayoría de tutoriales que encuentras en internet describen la versión anterior del protocolo (con un «apretón de manos» inicial y sesiones) y una API de Python que ya no existe con ese nombre. Esta serie usa la versión de protocolo <code>2026-07-28</code> y el SDK oficial de Python 2.3, que es lo vigente mientras escribo esto. Cuando algo difiera de lo que verás en otros sitios, lo digo.</p>
<p>El código está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-mcp" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-mcp</a>.</p>
<h2 id="el-problema-que-resuelve">El problema que resuelve <a class="ancla" href="#el-problema-que-resuelve" aria-label="Enlace a esta sección">#</a></h2>
<p>Un asistente de IA, por sí solo, solo sabe lo que sabe. No ve tu base de datos, ni tus ficheros, ni tu sistema de tickets. Para que pueda mirarlos (o hacer algo en ellos) alguien tiene que escribir la integración.</p>
<p>Sin un estándar, cada aplicación con un modelo necesita una integración propia con cada sistema: si hay M aplicaciones y N sistemas, son M × N trabajos. Si te dedicas a bases de datos esto te suena: es el problema que resolvieron ODBC y JDBC. Cada aplicación habla un protocolo común con un <em>driver</em>, y cada base de datos tiene su driver. Pasas de M × N a M + N.</p>
<p>MCP (<em>Model Context Protocol</em>) es eso mismo para asistentes de IA. Lo creó Anthropic y hoy se desarrolla como un proyecto abierto, con <a href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture" target="_blank" rel="noopener">especificación pública</a>, SDK en varios lenguajes y un proceso de propuestas de cambio. Si has usado un editor con autocompletado, la otra comparación útil es con el <em>Language Server Protocol</em>: mismo planteamiento (un protocolo estándar entre el editor y los servidores de cada lenguaje) y, de hecho, también va sobre JSON-RPC.</p>
<h2 id="los-tres-actores">Los tres actores <a class="ancla" href="#los-tres-actores" aria-label="Enlace a esta sección">#</a></h2>
<p>Hay tres piezas, y conviene no mezclar los nombres:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span> host (la aplicación con el modelo)
</span></span><span style="display:flex;"><span> ├── cliente MCP 1 ── stdio ──▶ servidor A   (un proceso en tu máquina)
</span></span><span style="display:flex;"><span> ├── cliente MCP 2 ── stdio ──▶ servidor B   (otro proceso en tu máquina)
</span></span><span style="display:flex;"><span> └── cliente MCP 3 ── HTTP  ──▶ servidor C   (remoto)</span></span></code></pre></div>
</div>
<ul>
<li><strong>Host</strong>: la aplicación donde vive el modelo. Un editor, un asistente de escritorio, una herramienta de línea de comandos, o un programa tuyo.</li>
<li><strong>Cliente MCP</strong>: la parte del host que habla el protocolo. El host crea <strong>uno por cada servidor</strong> al que se conecta; cada cliente mantiene su conexión con su servidor.</li>
<li><strong>Servidor MCP</strong>: un programa que ofrece capacidades. Eso es lo que vamos a escribir.</li>
</ul>
<p>«Servidor» aquí no quiere decir «máquina remota»: un servidor MCP puede ser un proceso que el host lanza en tu propio equipo. Que sea local o remoto depende solo del transporte, que veremos en un momento.</p>
<h2 id="qué-ofrece-un-servidor-tres-cosas">Qué ofrece un servidor: tres cosas <a class="ancla" href="#qu%c3%a9-ofrece-un-servidor-tres-cosas" aria-label="Enlace a esta sección">#</a></h2>
<p>Un servidor puede ofrecer tres tipos de cosas. La diferencia entre ellas no es técnica sino de <strong>quién decide usarlas</strong>, y es la mejor forma de recordarlas:</p>
<table>
  <thead>
      <tr>
          <th>Qué</th>
          <th>Para qué sirve</th>
          <th>Quién decide usarlo</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><strong>Tool</strong> (herramienta)</td>
          <td>Una función que el modelo puede llamar: buscar usuarios, crear un evento, consultar un pedido.</td>
          <td>El <strong>modelo</strong></td>
      </tr>
      <tr>
          <td><strong>Resource</strong> (recurso)</td>
          <td>Datos de solo lectura con una dirección (URI): un fichero, el esquema de una base de datos, una ficha.</td>
          <td>La <strong>aplicación</strong></td>
      </tr>
      <tr>
          <td><strong>Prompt</strong></td>
          <td>Una plantilla de instrucciones con parámetros, para tareas que se repiten.</td>
          <td>El <strong>usuario</strong></td>
      </tr>
  </tbody>
</table>
<p>Para traducirlo a vocabulario de APIs (a medias, como todas las traducciones): una herramienta se parece a un endpoint RPC con parámetros tipados y un resultado; un recurso, a un <code>GET</code> sobre una URI; y un prompt, a una macro. En la práctica las herramientas son lo que más se usa, y lo que ocupa casi toda la serie.</p>
<p>Lo que hace especial a una herramienta, frente a un endpoint, es <strong>quién la llama y cómo se entera de que existe</strong>. A un endpoint lo llama un programa que escribió una persona leyendo la documentación. A una herramienta MCP la llama un modelo, que se entera de que existe porque el servidor se lo cuenta en tiempo de ejecución: el nombre, una descripción en lenguaje natural y un esquema JSON de los parámetros. El modelo decide si le sirve y con qué argumentos. Esa descripción forma parte de la interfaz, y de ahí sale casi todo lo interesante de las entradas 5 y 6.</p>
<h2 id="cómo-viaja-por-debajo">Cómo viaja por debajo <a class="ancla" href="#c%c3%b3mo-viaja-por-debajo" aria-label="Enlace a esta sección">#</a></h2>
<p>El mensaje es siempre <a href="https://www.jsonrpc.org/" target="_blank" rel="noopener">JSON-RPC 2.0</a>: peticiones con un <code>method</code> y unos <code>params</code>, y respuestas con un <code>result</code> o un <code>error</code>. Hay dos transportes:</p>
<ul>
<li><strong>stdio</strong>: el host lanza el servidor como proceso hijo y le habla por la entrada y la salida estándar. Es lo normal para servidores locales, sin red y sin puertos.</li>
<li><strong>Streamable HTTP</strong>: peticiones <code>POST</code> a una URL (por convención, <code>/mcp</code>). Es lo que se usa para servidores remotos, con autenticación HTTP normal.</li>
</ul>
<p>Y, desde la versión de protocolo <code>2026-07-28</code>, <strong>MCP no tiene estado</strong>. Cada petición lleva dentro todo lo necesario para procesarla: la versión del protocolo y las capacidades del cliente, en un campo <code>_meta</code>. No hay un <code>initialize</code> inicial ni una sesión. Un cliente puede preguntar qué ofrece el servidor con una petición <code>server/discover</code>, pero es opcional.</p>
<p>Que no haya sesión tiene una consecuencia práctica que se aprecia en la última entrada: un servidor remoto se puede repartir entre varias réplicas con un balanceador cualquiera, sin pegajosidad. Con la versión anterior, un cliente abría una sesión y todas sus peticiones tenían que llegar al mismo sitio.</p>
<p>El SDK actual atiende los dos mundos: un cliente moderno usa el protocolo nuevo, y uno antiguo hace su <code>initialize</code> de siempre y también funciona. En la <a href="/posts/2026/mcp-a-mano-json-rpc/">siguiente entrada</a> lo veremos con mensajes escritos a mano.</p>
<h2 id="un-primer-servidor">Un primer servidor <a class="ancla" href="#un-primer-servidor" aria-label="Enlace a esta sección">#</a></h2>
<p>El SDK oficial de Python 2.x se instala con <code>pip</code> (necesita Python 3.10 o posterior):</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>ignacio@localhost:~/lab-mcp$ python3 -m venv .venv &amp;&amp; source .venv/bin/activate
</span></span><span style="display:flex;"><span>ignacio@localhost:~/lab-mcp$ pip install &#34;mcp[cli]&gt;=2,&lt;3&#34;</span></span></code></pre></div>
</div>
<p>Ojo con el <code>&lt;3</code>: lo que instala <code>pip install mcp</code> es la serie 2.x, y conviene fijar el límite superior para que una versión mayor no te rompa los ejemplos.</p>
<p>El servidor mínimo, con una sola herramienta:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># hola/hola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> mcp.server <span style="color:#f92672">import</span> MCPServer
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>mcp <span style="color:#f92672">=</span> MCPServer(<span style="color:#e6db74">&#34;Hola&#34;</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@mcp.tool</span>()
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">sumar</span>(a: int, b: int) <span style="color:#f92672">-&gt;</span> int:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Suma dos números enteros.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> a <span style="color:#f92672">+</span> b
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">if</span> __name__ <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;__main__&#34;</span>:
</span></span><span style="display:flex;"><span>    mcp<span style="color:#f92672">.</span>run()</span></span></code></pre></div>
</div>
<p>Tres cosas, que se repetirán toda la serie:</p>
<ul>
<li><code>MCPServer(&quot;Hola&quot;)</code> crea el servidor. Ese nombre es el que verán los clientes. (Si has visto tutoriales con <code>FastMCP</code>, es el mismo concepto con otro nombre: en el SDK 2.x <code>FastMCP</code> ya no existe y se usa <code>MCPServer</code>.)</li>
<li><code>@mcp.tool()</code> convierte la función en herramienta. El <strong>nombre</strong> sale del nombre de la función, la <strong>descripción</strong> de la docstring y el <strong>esquema de los parámetros</strong> de las anotaciones de tipo. No hay que escribir ningún JSON Schema.</li>
<li><code>mcp.run()</code> arranca el servidor; por defecto, por stdio.</li>
</ul>
<p>Si lo ejecutas directamente se queda esperando mensajes por la entrada estándar, que no es muy interesante. Para hablar con él hace falta un cliente, y el SDK trae uno. Este lanza <code>hola.py</code> como proceso hijo, pregunta qué herramientas ofrece y llama a una:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># hola/cliente_hola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> sys
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> anyio
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> mcp <span style="color:#f92672">import</span> Client, StdioServerParameters
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">async</span> <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">main</span>() <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#75715e"># Lanza hola.py como proceso hijo y habla con él por stdin/stdout.</span>
</span></span><span style="display:flex;"><span>    params <span style="color:#f92672">=</span> StdioServerParameters(command<span style="color:#f92672">=</span>sys<span style="color:#f92672">.</span>executable, args<span style="color:#f92672">=</span>[<span style="color:#e6db74">&#34;hola.py&#34;</span>])
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">async</span> <span style="color:#66d9ef">with</span> Client(params) <span style="color:#66d9ef">as</span> client:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">&#34;servidor:&#34;</span>, client<span style="color:#f92672">.</span>server_info<span style="color:#f92672">.</span>name, <span style="color:#e6db74">&#34;| protocolo:&#34;</span>, client<span style="color:#f92672">.</span>protocol_version)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">for</span> herramienta <span style="color:#f92672">in</span> (<span style="color:#66d9ef">await</span> client<span style="color:#f92672">.</span>list_tools())<span style="color:#f92672">.</span>tools:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">&#34;herramienta:&#34;</span>, herramienta<span style="color:#f92672">.</span>name, <span style="color:#e6db74">&#34;-&#34;</span>, herramienta<span style="color:#f92672">.</span>description)
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">&#34;  parámetros:&#34;</span>, herramienta<span style="color:#f92672">.</span>input_schema[<span style="color:#e6db74">&#34;properties&#34;</span>])
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>        resultado <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> client<span style="color:#f92672">.</span>call_tool(<span style="color:#e6db74">&#34;sumar&#34;</span>, {<span style="color:#e6db74">&#34;a&#34;</span>: <span style="color:#ae81ff">2</span>, <span style="color:#e6db74">&#34;b&#34;</span>: <span style="color:#ae81ff">3</span>})
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">&#34;resultado:&#34;</span>, resultado<span style="color:#f92672">.</span>structured_content)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>anyio<span style="color:#f92672">.</span>run(main)</span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>ignacio@localhost:~/lab-mcp$ cd hola &amp;&amp; python cliente_hola.py
</span></span><span style="display:flex;"><span>servidor: Hola | protocolo: 2026-07-28
</span></span><span style="display:flex;"><span>herramienta: sumar - Suma dos números enteros.
</span></span><span style="display:flex;"><span>  parámetros: {&#39;a&#39;: {&#39;title&#39;: &#39;A&#39;, &#39;type&#39;: &#39;integer&#39;}, &#39;b&#39;: {&#39;title&#39;: &#39;B&#39;, &#39;type&#39;: &#39;integer&#39;}}
</span></span><span style="display:flex;"><span>resultado: {&#39;result&#39;: 5}</span></span></code></pre></div>
</div>
<p>El cliente ha descubierto la herramienta sin que se la hayamos descrito en ningún sitio: nombre, descripción y los dos parámetros enteros salieron de la función. Y el resultado vuelve como <code>{'result': 5}</code>: MCP envuelve en un objeto lo que no lo es.</p>
<h2 id="lo-que-mcp-no-es">Lo que MCP no es <a class="ancla" href="#lo-que-mcp-no-es" aria-label="Enlace a esta sección">#</a></h2>
<p>Para no esperar de él lo que no hace:</p>
<ul>
<li><strong>No decide cómo usa el modelo las herramientas.</strong> El protocolo solo define cómo se anuncian y cómo se llaman. Qué herramienta elige el modelo, con qué argumentos y cuándo, es cosa del modelo y del host. El servidor no controla eso.</li>
<li><strong>No es una capa de seguridad.</strong> El protocolo lleva cosas de autorización para servidores remotos, pero que un servidor sea MCP no lo hace seguro ni de fiar. Un servidor local es un proceso normal con tus permisos. De esto va la entrada 6.</li>
<li><strong>No es un framework de agentes.</strong> Un agente puede usar MCP para llegar a sus herramientas, pero MCP no orquesta nada.</li>
</ul>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Tenemos el vocabulario (host, cliente, servidor; herramientas, recursos, prompts), sabemos que va sobre JSON-RPC por stdio o HTTP, que ahora no tiene estado, y que un servidor mínimo son ocho líneas.</p>
<p>En la <a href="/posts/2026/mcp-a-mano-json-rpc/">siguiente entrada</a> quito el SDK de en medio y le hablo a este mismo servidor escribiendo los mensajes a mano, por stdio y por HTTP con <code>curl</code>. Es la forma más rápida de que el protocolo deje de parecer magia.</p>
<p>Para saber más, la <a href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture" target="_blank" rel="noopener">descripción de la arquitectura</a> en la documentación oficial y la <a href="https://py.sdk.modelcontextprotocol.io/" target="_blank" rel="noopener">documentación del SDK de Python</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_2701baec85c8552c.png"/></item><item><title>Al menos una vez, y lo que eso te obliga a hacer</title><link>https://www.igalvan.es/posts/2026/colas-al-menos-una-vez-idempotencia/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-al-menos-una-vez-idempotencia/</guid><description><![CDATA[<p>Tercera y última entrada. En la <a href="/posts/2026/colas-de-mensajes-para-gente-de-sincrono/">primera</a> saqué el correo del endpoint a una cola; en la <a href="/posts/2026/colas-cuando-el-consumidor-se-cae/">segunda</a> rompí el consumidor de cuatro formas y acabé con ack manual, reintentos con espera y una cola de fallidos. El sistema ya no pierde mensajes.</p>
<p>Lo que hace ahora, en cambio, es repetirlos. Y eso no es un bug: es la única garantía que una cola puede darte de verdad.</p>
<h2 id="fallo-5-el-correo-se-envía-dos-veces">Fallo 5: el correo se envía dos veces <a class="ancla" href="#fallo-5-el-correo-se-env%c3%ada-dos-veces" aria-label="Enlace a esta sección">#</a></h2>
<p>Vuelve al worker de la segunda entrada y fíjate en el orden de las cosas dentro de <code>procesar</code>: primero <code>enviar_correo</code>, después <code>basic_ack</code>. Entre una y otra hay un hueco. Lo voy a hacer más ancho para poder meter el dedo:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (modificado solo para el experimento)</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    intento <span style="color:#f92672">=</span> intentos_previos(propiedades) <span style="color:#f92672">+</span> <span style="color:#ae81ff">1</span>
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">, intento </span><span style="color:#e6db74">{</span>intento<span style="color:#e6db74">}</span><span style="color:#e6db74">, redelivered=</span><span style="color:#e6db74">{</span>metodo<span style="color:#f92672">.</span>redelivered<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">...</span>
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">3</span>)  <span style="color:#75715e"># el hueco entre hacer el trabajo y confirmarlo</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)</span></span></code></pre></div>
</div>
<p>Lanza un pedido, espera a ver la línea de <code>[correo] ... enviada</code>, y en los tres segundos siguientes, <code>pkill -9</code>:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] pedido 520, intento 1, redelivered=False
[correo] confirmación del pedido 520 enviada
Killed</code></pre>
</div>
<p>El correo ha salido. El ack no. RabbitMQ ve caer la conexión y devuelve el mensaje a la cola, como debe. Arranca el worker:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] pedido 520, intento 1, redelivered=True
[correo] confirmación del pedido 520 enviada</code></pre>
</div>
<p>Dos correos de confirmación del mismo pedido. El usuario tiene dos mensajes en su bandeja y, si en vez de un correo fuera un cargo en la tarjeta, dos cargos.</p>
<p>Y aquí va la frase que cuesta aceptar viniendo del mundo síncrono: <strong>esto no tiene arreglo en la cola.</strong> Si haces ack antes de enviar, el fallo 1 de la entrada anterior vuelve (el worker muere después del ack y antes del envío: correo perdido). Si haces ack después, el worker puede morir entre el envío y el ack: correo duplicado. No hay un tercer sitio donde poner el ack. Puedes elegir entre <em>como mucho una vez</em> (ack antes) y <em>al menos una vez</em> (ack después), y para un correo de confirmación, o un cargo, o cualquier cosa que no quieras perder, eliges al menos una vez y asumes el duplicado.</p>
<p>Hay brókers que anuncian &ldquo;exactamente una vez&rdquo;. Lo que dan, cuando lo dan, es exactamente una vez <em>dentro del bróker</em>; en cuanto el consumidor hace algo fuera (un correo, una llamada HTTP, un <code>INSERT</code> en otra base de datos), vuelves a tener el hueco.</p>
<h2 id="arreglo-5-que-repetir-no-haga-daño">Arreglo 5: que repetir no haga daño <a class="ancla" href="#arreglo-5-que-repetir-no-haga-da%c3%b1o" aria-label="Enlace a esta sección">#</a></h2>
<p>Si no puedes evitar que un mensaje llegue dos veces, haz que la segunda vez no haga nada. Eso es idempotencia, y se consigue apuntando lo que ya has hecho en un sitio que sobreviva a la muerte del worker. Tengo un PostgreSQL al lado; sirve.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#75715e">-- añadido a init.sql
</span></span></span><span style="display:flex;"><span><span style="color:#66d9ef">CREATE</span> <span style="color:#66d9ef">TABLE</span> correos_enviados (
</span></span><span style="display:flex;"><span>  pedido_id  int <span style="color:#66d9ef">PRIMARY</span> <span style="color:#66d9ef">KEY</span> <span style="color:#66d9ef">REFERENCES</span> pedidos(id),
</span></span><span style="display:flex;"><span>  enviado_en timestamptz <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span> <span style="color:#66d9ef">DEFAULT</span> now()
</span></span><span style="display:flex;"><span>);</span></span></code></pre></div>
</div>
<p>Y el worker, antes de enviar, intenta reservar el pedido:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (versión final)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> db <span style="color:#f92672">import</span> conectar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">reservar</span>(pedido_id: int) <span style="color:#f92672">-&gt;</span> bool:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;True si somos los primeros en ocuparnos de este pedido.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        fila <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO correos_enviados (pedido_id) VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ON CONFLICT (pedido_id) DO NOTHING
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING pedido_id
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (pedido_id,),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> fila <span style="color:#f92672">is</span> <span style="color:#f92672">not</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    intento <span style="color:#f92672">=</span> intentos_previos(propiedades) <span style="color:#f92672">+</span> <span style="color:#ae81ff">1</span>
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">, intento </span><span style="color:#e6db74">{</span>intento<span style="color:#e6db74">}</span><span style="color:#e6db74">, redelivered=</span><span style="color:#e6db74">{</span>metodo<span style="color:#f92672">.</span>redelivered<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> <span style="color:#f92672">not</span> reservar(pedido[<span style="color:#e6db74">&#34;id&#34;</span>]):
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> ya tratado, ignoro&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>        canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">...</span>  <span style="color:#75715e"># igual que en la segunda entrada</span>
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)</span></span></code></pre></div>
</div>
<p>El <code>INSERT ... ON CONFLICT DO NOTHING RETURNING</code> es el truco: si la fila no existía, la inserta y devuelve el id; si existía, no hace nada y no devuelve nada. Atómico, en una sola sentencia, sin ventana para que dos workers se cuelen. Repite el experimento del <code>pkill -9</code> tras el envío:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] pedido 521, intento 1, redelivered=True
[worker] pedido 521 ya tratado, ignoro</code></pre>
</div>
<p>Un correo. La reentrega llega, la reserva falla porque ya está hecha, y el worker se limita a confirmar el mensaje para que RabbitMQ lo olvide.</p>
<h3 id="el-hueco-se-ha-movido-no-ha-desaparecido">El hueco se ha movido, no ha desaparecido <a class="ancla" href="#el-hueco-se-ha-movido-no-ha-desaparecido" aria-label="Enlace a esta sección">#</a></h3>
<p>Sé honesto con esto o el lector lo descubrirá solo. Ahora el orden es: reservar, enviar, ack. Si el worker muere <strong>entre reservar y enviar</strong>, el pedido queda marcado como tratado y el correo no sale nunca. He cambiado un duplicado por una pérdida, en una ventana mucho más pequeña (unos milisegundos frente a los dos segundos del envío) y, sobre todo, <strong>detectable</strong>: la fila en <code>correos_enviados</code> existe, y el correo no. Un trabajo de limpieza que compare esa tabla con el registro del servidor de correo, o una columna <code>estado</code> (<code>reservado</code> → <code>enviado</code>) con un reintento para los que llevan demasiado tiempo en <code>reservado</code>, lo cierra del todo. Lo dejo fuera porque ya no es sobre colas, pero que conste que el circuito completo tiene una pieza más.</p>
<p>La regla general, que vale para cualquier cosa que haga efectos fuera de la base de datos: <strong>o la operación es naturalmente idempotente</strong> (poner <code>estado = 'enviado'</code> lo es; <code>saldo = saldo - 10</code> no), <strong>o le pones una clave que lo haga idempotente</strong> (el id del pedido, un UUID generado por el productor y viajando en el mensaje). Si no hay ninguna de las dos, el duplicado acabará ocurriendo.</p>
<h2 id="lo-mismo-del-lado-del-productor">Lo mismo, del lado del productor <a class="ancla" href="#lo-mismo-del-lado-del-productor" aria-label="Enlace a esta sección">#</a></h2>
<p>He hablado todo el rato del consumidor, pero el endpoint de la primera entrada tiene exactamente el mismo problema al revés:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        pedido <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(<span style="color:#e6db74">&#34;INSERT INTO pedidos ... RETURNING ...&#34;</span>)<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    publicar(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> pedido</span></span></code></pre></div>
</div>
<p>Si <code>publicar</code> falla (RabbitMQ caído, un corte de red), el pedido está en la base de datos y el mensaje no existe: un pedido sin correo. Si inviertes el orden y publicas antes de insertar, puedes tener un correo de un pedido que nunca se guardó. Es el mismo hueco de siempre, entre dos sistemas que no comparten transacción.</p>
<p>La solución tiene nombre, <em>transactional outbox</em>, y es más sencilla de lo que suena: en la misma transacción que inserta el pedido, insertas también una fila en una tabla <code>mensajes_pendientes</code>. Las dos filas se guardan o ninguna. Y un proceso aparte lee esa tabla, publica en RabbitMQ y borra la fila al conseguirlo. Ese proceso vuelve a ser un &ldquo;al menos una vez&rdquo; (puede publicar y morir antes de borrar), así que el consumidor tiene que ser idempotente. Que ya lo es. Todo encaja.</p>
<p>No lo implemento aquí porque son treinta líneas más y la entrada ya va larga, pero es la pieza que convierte el laboratorio en algo que pondrías en producción.</p>
<h2 id="cuándo-una-cola-es-demasiado">Cuándo una cola es demasiado <a class="ancla" href="#cu%c3%a1ndo-una-cola-es-demasiado" aria-label="Enlace a esta sección">#</a></h2>
<p>Tres entradas después, la pregunta que debería ir antes de instalar RabbitMQ: ¿lo necesito?</p>
<p>Un bróker de mensajes es un sistema más que mantener, monitorizar, actualizar y que puede caerse. Antes de meterlo, dos alternativas que resuelven una parte sorprendente de los casos:</p>
<ul>
<li><strong>Una tarea en segundo plano en el propio servidor web.</strong> FastAPI tiene <code>BackgroundTasks</code>: el endpoint responde y el correo se envía después en el mismo proceso. Resuelve el problema de la latencia (el primero de la serie) y nada más: si el proceso muere, la tarea se pierde, y no hay reintentos ni cola de fallidos. Para cosas que da igual perder, sobra.</li>
<li><strong>Una tabla de tareas en PostgreSQL.</strong> <code>INSERT INTO tareas</code> en la misma transacción que el pedido, y un worker que hace <code>SELECT ... FOR UPDATE SKIP LOCKED</code> para cogerlas de una en una. Tienes persistencia, reintentos (una columna <code>intentos</code>), fallidos (una columna <code>estado</code>), varios workers en paralelo, y la transacción con el pedido gratis, que es justo lo que el outbox intentaba conseguir. Lo que no tienes es un bróker que empuje los mensajes: el worker sondea cada segundo o cada cinco. Para la inmensa mayoría de sistemas que no son de alta frecuencia es más que suficiente, y es una dependencia menos.</li>
</ul>
<p>RabbitMQ (o cualquier bróker) empieza a compensar cuando hay varios productores y consumidores que son sistemas distintos, cuando el volumen hace que sondear una tabla sea un problema, cuando quieres enrutar un mismo mensaje a varios consumidores que no se conocen, o cuando necesitas que el bróker esté entre dos sistemas que no deben compartir una base de datos.</p>
<p>Y aun entonces, la cola es la fontanería. Lo que se ha visto en esta serie (ack, reintentos, fallidos, idempotencia, outbox) no lo resuelve el bróker: lo resuelves tú en el diseño de lo que viaja por la cola y de lo que hace quien lo recibe. Cambiar RabbitMQ por otro producto cambia los nombres de las piezas, no el trabajo.</p>
<h2 id="lo-que-ha-enseñado-la-serie">Lo que ha enseñado la serie <a class="ancla" href="#lo-que-ha-ense%c3%b1ado-la-serie" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li>Una cola desacopla en el tiempo: el productor termina sin esperar al consumidor, y el consumidor puede no existir en ese momento.</li>
<li><code>auto_ack</code> pierde mensajes; el ack manual los conserva, pero convierte las caídas en reentregas.</li>
<li>Reencolar a la misma cola es un bucle; rechazar hacia un DLX con una cola de espera son reintentos con pausa, y una cola de fallidos aparta lo irrecuperable.</li>
<li>Al menos una vez es lo único que hay. Idempotencia en el consumidor, con una clave en una tabla, es el precio.</li>
<li>El productor tiene el hueco simétrico; el outbox lo cierra.</li>
<li>Antes de un bróker, una tabla de tareas en la base de datos que ya tienes resuelve más de lo que parece.</li>
</ul>
<p>El código de las tres entradas está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_1ce61963e9c4a93f.png"/></item><item><title>Cuando el consumidor se cae: ack, reencolado y dead letter</title><link>https://www.igalvan.es/posts/2026/colas-cuando-el-consumidor-se-cae/</link><pubDate>Tue, 03 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-cuando-el-consumidor-se-cae/</guid><description><![CDATA[<p>En la <a href="/posts/2026/colas-de-mensajes-para-gente-de-sincrono/">entrada anterior</a> saqué el envío del correo del endpoint y lo mandé a una cola de RabbitMQ. El endpoint pasó de dos segundos a cuarenta milisegundos y un <code>worker.py</code> se encarga de los correos. Todo bonito mientras nada falla.</p>
<p>Esta entrada va de que algo falle. Cuatro veces, cada una peor que la anterior, y arreglándolas por orden.</p>
<h2 id="fallo-1-el-worker-muere-y-el-mensaje-desaparece">Fallo 1: el worker muere y el mensaje desaparece <a class="ancla" href="#fallo-1-el-worker-muere-y-el-mensaje-desaparece" aria-label="Enlace a esta sección">#</a></h2>
<p>El worker de la entrada anterior tenía esto:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p><code>auto_ack=True</code> significa que RabbitMQ da el mensaje por entregado en el momento en que lo manda al consumidor. Vamos a ver qué implica.</p>
<p>Arranca el worker, lanza un pedido, y en los dos segundos de <code>sleep</code> que simulan el envío del correo, mata el proceso sin contemplaciones:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 510
Killed</code></pre>
</div>
<p>(Desde otra terminal: <code>pkill -9 -f worker.py</code>. Tiene que ser <code>-9</code>; con un <code>Ctrl+C</code> pika cierra la conexión limpiamente y no es lo que quiero probar.)</p>
<p>Ahora mira la interfaz web, pestaña <em>Queues</em>, cola <code>correos</code>: <em>Ready</em> 0, <em>Unacked</em> 0, <em>Total</em> 0. Arranca el worker otra vez: no recibe nada. El pedido 510 está en la base de datos y su correo de confirmación no existe ni va a existir. Nadie se ha enterado.</p>
<p>Esto es lo que compra <code>auto_ack=True</code>: rendimiento a cambio de que cualquier caída del consumidor se lleve lo que tenía entre manos. Hay casos en que vale (métricas, logs, cosas que si se pierde una no pasa nada), pero un correo de confirmación no es uno de ellos.</p>
<h2 id="arreglo-1-ack-manual">Arreglo 1: ack manual <a class="ancla" href="#arreglo-1-ack-manual" aria-label="Enlace a esta sección">#</a></h2>
<p>El consumidor tiene que decirle a RabbitMQ &ldquo;ya he terminado con este&rdquo; <strong>después</strong> de haber terminado, no antes.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">...</span>
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_qos(prefetch_count<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)</span></span></code></pre></div>
</div>
<p>Dos cambios. <code>auto_ack=False</code> y el <code>basic_ack</code> explícito al final de <code>procesar</code>, con el <code>delivery_tag</code> que identifica esa entrega concreta. Y <code>basic_qos(prefetch_count=1)</code>: sin esto, RabbitMQ le manda al consumidor todos los mensajes que haya en la cola de golpe y los deja todos en <em>Unacked</em> mientras el worker los va procesando uno a uno; con <code>prefetch_count=1</code> le manda uno, espera el ack, y manda el siguiente. Para un worker que tarda dos segundos por mensaje es lo que quieres.</p>
<p>Repite el experimento. Lanza el pedido, y durante el <code>sleep</code> mira la interfaz: <em>Ready</em> 0, <strong>Unacked 1</strong>. El mensaje está entregado pero no confirmado. Ahora <code>pkill -9</code>:</p>
<p><em>Ready 1</em>, <em>Unacked 0</em>. RabbitMQ ha detectado que la conexión del consumidor se ha cerrado sin confirmar y ha devuelto el mensaje a la cola. Arranca el worker:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 511
[correo] confirmación del pedido 511 enviada</code></pre>
</div>
<p>El correo se envía. Con un detalle que importa y que dejo apuntado para la tercera entrada: en <code>metodo.redelivered</code> viene <code>True</code>. RabbitMQ sabe que este mensaje ya se entregó una vez, y te lo dice.</p>
<h2 id="fallo-2-el-correo-falla-y-el-worker-se-cae">Fallo 2: el correo falla y el worker se cae <a class="ancla" href="#fallo-2-el-correo-falla-y-el-worker-se-cae" aria-label="Enlace a esta sección">#</a></h2>
<p>Hasta ahora el worker moría por causas externas. Vamos a que falle por las suyas. Hago que el servidor de correo simulado rechace los pedidos grandes:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> float(pedido[<span style="color:#e6db74">&#34;total&#34;</span>]) <span style="color:#f92672">&gt;</span> <span style="color:#ae81ff">1000</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">raise</span> <span style="color:#a6e22e">RuntimeError</span>(<span style="color:#e6db74">&#34;el servidor de correo ha rechazado el mensaje&#34;</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p>Lanza un pedido de 2000 euros:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 512
Traceback (most recent call last):
  ...
RuntimeError: el servidor de correo ha rechazado el mensaje</code></pre>
</div>
<p>El worker se ha caído entero. Como no había hecho ack, el mensaje vuelve a <em>Ready</em>. Arranca el worker: recibe el 512, falla, se cae. Y así hasta que alguien edite el código. Mientras tanto, todos los demás correos, los que sí se podrían enviar, están detrás del 512 esperando.</p>
<p>Un mensaje que tumba al consumidor cada vez que lo intenta tiene nombre: <em>poison message</em>. Y la solución ingenua lo empeora.</p>
<h2 id="arreglo-2-malo-capturar-la-excepción-y-reencolar">Arreglo 2 (malo): capturar la excepción y reencolar <a class="ancla" href="#arreglo-2-malo-capturar-la-excepci%c3%b3n-y-reencolar" aria-label="Enlace a esta sección">#</a></h2>
<p>Lo primero que se le ocurre a cualquiera:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">, reencolando&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>        canal<span style="color:#f92672">.</span>basic_nack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag, requeue<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)</span></span></code></pre></div>
</div>
<p><code>basic_nack</code> con <code>requeue=True</code> es &ldquo;no he podido, devuélvelo a la cola&rdquo;. Y RabbitMQ lo devuelve, al principio de la cola, y se lo vuelve a entregar al mismo worker, que vuelve a fallar:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] recibido pedido 512
[worker] error: el servidor de correo ha rechazado el mensaje, reencolando
[worker] recibido pedido 512
[worker] error: el servidor de correo ha rechazado el mensaje, reencolando
[worker] recibido pedido 512
...</code></pre>
</div>
<p>El worker ya no se cae, pero está en un bucle infinito con el mismo mensaje, cada dos segundos, para siempre, y en la interfaz ves el contador de <em>Redelivered</em> subir sin parar. Los demás correos siguen sin salir. Hemos cambiado un proceso muerto por un proceso ocupado haciendo nada.</p>
<h2 id="arreglo-2-bueno-reintentos-con-espera-y-una-cola-de-fallidos">Arreglo 2 (bueno): reintentos con espera y una cola de fallidos <a class="ancla" href="#arreglo-2-bueno-reintentos-con-espera-y-una-cola-de-fallidos" aria-label="Enlace a esta sección">#</a></h2>
<p>Lo que quiero es: si el correo falla, esperar un poco y volver a intentarlo, porque igual el servidor de correo estaba saturado y a la tercera va. Y si tras unos cuantos intentos sigue fallando, apartar el mensaje a un sitio donde alguien pueda mirarlo, y seguir con los demás.</p>
<p>RabbitMQ tiene la pieza para esto: el <strong>dead letter exchange</strong> (DLX). Es un atributo de la cola que dice &ldquo;cuando un mensaje de esta cola sea rechazado o caduque, en vez de tirarlo, mándalo a este exchange con esta clave&rdquo;. Con eso y una cola intermedia con caducidad se monta el circuito entero sin escribir ningún temporizador:</p>
<div class="codeblock"><pre tabindex="0"><code>correos ──(nack)──▶ correos.reintentos ──(caduca a los 5 s)──▶ correos
   │
   └──(tras 3 intentos, el worker lo publica)──▶ correos.fallidos</code></pre>
</div>
<p>Las declaraciones:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># cola.py (modificado)</span>
</span></span><span style="display:flex;"><span>COLA <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos&#34;</span>
</span></span><span style="display:flex;"><span>COLA_REINTENTOS <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos.reintentos&#34;</span>
</span></span><span style="display:flex;"><span>COLA_FALLIDOS <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos.fallidos&#34;</span>
</span></span><span style="display:flex;"><span>MAX_INTENTOS <span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">declarar_colas</span>(canal) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(
</span></span><span style="display:flex;"><span>        queue<span style="color:#f92672">=</span>COLA,
</span></span><span style="display:flex;"><span>        durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>,
</span></span><span style="display:flex;"><span>        arguments<span style="color:#f92672">=</span>{
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-exchange&#34;</span>: <span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-routing-key&#34;</span>: COLA_REINTENTOS,
</span></span><span style="display:flex;"><span>        },
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(
</span></span><span style="display:flex;"><span>        queue<span style="color:#f92672">=</span>COLA_REINTENTOS,
</span></span><span style="display:flex;"><span>        durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>,
</span></span><span style="display:flex;"><span>        arguments<span style="color:#f92672">=</span>{
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-message-ttl&#34;</span>: <span style="color:#ae81ff">5000</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-exchange&#34;</span>: <span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-routing-key&#34;</span>: COLA,
</span></span><span style="display:flex;"><span>        },
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA_FALLIDOS, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p><code>correos</code> manda sus rechazados a <code>correos.reintentos</code>. Esa cola no tiene consumidores; los mensajes se quedan ahí cinco segundos (<code>x-message-ttl</code>), caducan, y al caducar su propio DLX los devuelve a <code>correos</code>. <code>correos.fallidos</code> es una cola normal donde van a parar los que se rinden.</p>
<p>Un aviso antes de ejecutar nada: <code>correos</code> ya existe de la entrada anterior, declarada sin argumentos, y RabbitMQ no deja cambiar los argumentos de una cola existente. El <code>queue_declare</code> nuevo falla con un <code>PRECONDITION_FAILED</code>. Hay que borrarla primero, desde la interfaz web o con:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ podman compose exec rabbitmq rabbitmqctl delete_queue correos</code></pre>
</div>
<p>(Y que <code>publicar()</code> en <code>cola.py</code> llame a <code>declarar_colas(canal)</code> en vez de a su <code>queue_declare</code> suelto, para que productor y consumidor declaren lo mismo.)</p>
<p>Ahora el worker. ¿Cómo sabe cuántas veces ha fallado ya un mensaje? RabbitMQ lo apunta por él: cada vez que un mensaje pasa por un DLX, le añade (o actualiza) una cabecera <code>x-death</code> con la cola de origen, el motivo y un contador.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (versión final)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> COLA, COLA_FALLIDOS, MAX_INTENTOS, URL, declarar_colas
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> float(pedido[<span style="color:#e6db74">&#34;total&#34;</span>]) <span style="color:#f92672">&gt;</span> <span style="color:#ae81ff">1000</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">raise</span> <span style="color:#a6e22e">RuntimeError</span>(<span style="color:#e6db74">&#34;el servidor de correo ha rechazado el mensaje&#34;</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">intentos_previos</span>(propiedades) <span style="color:#f92672">-&gt;</span> int:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Cuántas veces ha sido rechazado este mensaje desde la cola principal.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    muertes <span style="color:#f92672">=</span> (propiedades<span style="color:#f92672">.</span>headers <span style="color:#f92672">or</span> {})<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;x-death&#34;</span>, [])
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> sum(m[<span style="color:#e6db74">&#34;count&#34;</span>] <span style="color:#66d9ef">for</span> m <span style="color:#f92672">in</span> muertes <span style="color:#66d9ef">if</span> m[<span style="color:#e6db74">&#34;queue&#34;</span>] <span style="color:#f92672">==</span> COLA <span style="color:#f92672">and</span> m[<span style="color:#e6db74">&#34;reason&#34;</span>] <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;rejected&#34;</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    intento <span style="color:#f92672">=</span> intentos_previos(propiedades) <span style="color:#f92672">+</span> <span style="color:#ae81ff">1</span>
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">, intento </span><span style="color:#e6db74">{</span>intento<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">if</span> intento <span style="color:#f92672">&gt;=</span> MAX_INTENTOS:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">; me rindo, va a fallidos&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_publish(
</span></span><span style="display:flex;"><span>                exchange<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>                routing_key<span style="color:#f92672">=</span>COLA_FALLIDOS,
</span></span><span style="display:flex;"><span>                body<span style="color:#f92672">=</span>cuerpo,
</span></span><span style="display:flex;"><span>                properties<span style="color:#f92672">=</span>propiedades,
</span></span><span style="display:flex;"><span>            )
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">else</span>:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">; reintento en 5 s&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_nack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag, requeue<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>declarar_colas(canal)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_qos(prefetch_count<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)
</span></span><span style="display:flex;"><span>print(<span style="color:#e6db74">&#34;[worker] esperando mensajes&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>start_consuming()</span></span></code></pre></div>
</div>
<p>La diferencia clave con el arreglo malo está en una palabra: <code>requeue=False</code>. Antes el nack devolvía el mensaje a la misma cola; ahora lo rechaza, y rechazarlo activa el DLX, que lo manda a la cola de reintentos. El worker no sabe nada de esperas ni de temporizadores; solo cuenta cuántas veces ha pasado por ahí y decide.</p>
<p>Cuando se rinde, publica el mensaje tal cual (mismo cuerpo, mismas cabeceras, incluida <code>x-death</code>, que es útil para quien lo examine después) en <code>correos.fallidos</code>, y entonces sí hace ack del original.</p>
<p>Lanza el pedido de 2000 euros y otro normal justo detrás:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] pedido 513, intento 1
[worker] error: el servidor de correo ha rechazado el mensaje; reintento en 5 s
[worker] pedido 514, intento 1
[correo] confirmación del pedido 514 enviada
[worker] pedido 513, intento 2
[worker] error: el servidor de correo ha rechazado el mensaje; reintento en 5 s
[worker] pedido 513, intento 3
[worker] error: el servidor de correo ha rechazado el mensaje; me rindo, va a fallidos</code></pre>
</div>
<p>El 514 ha salido mientras el 513 esperaba su reintento: ya no bloquea a los demás. Tras tres intentos, el 513 está en <code>correos.fallidos</code>, donde en la interfaz web puedes abrirlo con <em>Get messages</em> y ver el cuerpo y la cabecera <code>x-death</code> con el historial. Lo que hagas con esa cola (una alerta, un reintento manual, un informe) ya es cosa de tu aplicación; lo importante es que el mensaje no se ha perdido y no está molestando.</p>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Cuatro fallos y lo que se ha aprendido de cada uno:</p>
<ul>
<li><code>auto_ack=True</code> pierde mensajes si el consumidor muere. Ack manual, después de hacer el trabajo.</li>
<li>Una excepción sin capturar tumba al worker y bloquea la cola con el mismo mensaje.</li>
<li>Capturar y reencolar en la misma cola es un bucle infinito.</li>
<li>Rechazar sin reencolar, con un DLX hacia una cola de espera que devuelve el mensaje a los pocos segundos, da reintentos con pausa gratis; y una cola de fallidos aparta lo que no tiene remedio.</li>
</ul>
<p>Queda un problema que se ha colado dos veces en esta entrada sin que lo señalara: con ack manual, el mensaje del fallo 1 se volvió a entregar con <code>redelivered=True</code>. ¿Y si el correo <strong>sí</strong> se había enviado y el worker murió justo antes del ack? Entonces se envía dos veces. Eso es la <a href="/posts/2026/colas-al-menos-una-vez-idempotencia/">tercera entrada</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_9eeff6b6d153a2e8.png"/></item><item><title>Colas de mensajes para gente de síncrono</title><link>https://www.igalvan.es/posts/2026/colas-de-mensajes-para-gente-de-sincrono/</link><pubDate>Sun, 01 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-de-mensajes-para-gente-de-sincrono/</guid><description><![CDATA[<p>Toda mi vida profesional ha sido síncrona: alguien pide, yo respondo, y hasta que no respondo nadie hace nada. HTTP, SQL, una llamada a función. Las colas de mensajes me parecieron durante mucho tiempo una complicación para gente con problemas que yo no tenía.</p>
<p>El problema sí lo tenía. Lo que no tenía era el vocabulario para reconocerlo. Esta serie es para quien esté en ese punto: tres entradas, la primera de teoría y montaje, y las otras dos rompiendo cosas a propósito para ver qué pasa, que es la única forma de entender para qué sirve una cola.</p>
<p>Reutilizo el laboratorio de la <a href="/series/graphql-para-gente-de-rest/">serie de GraphQL</a>: PostgreSQL en Podman con una tabla de usuarios y otra de pedidos, y una API REST en FastAPI. Si no la has leído no pasa nada; lo que hace falta está aquí.</p>
<p>El código está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas</a>.</p>
<h2 id="el-problema-sin-colas">El problema, sin colas <a class="ancla" href="#el-problema-sin-colas" aria-label="Enlace a esta sección">#</a></h2>
<p>Un endpoint que crea un pedido. Al crearlo hay que mandar un correo de confirmación al usuario.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (añadido)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> pydantic <span style="color:#f92672">import</span> BaseModel
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">NuevoPedido</span>(BaseModel):
</span></span><span style="display:flex;"><span>    usuario_id: int
</span></span><span style="display:flex;"><span>    total: float
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Simula un servidor de correo lento.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.post</span>(<span style="color:#e6db74">&#34;/pedidos&#34;</span>, status_code<span style="color:#f92672">=</span><span style="color:#ae81ff">201</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">crear_pedido</span>(nuevo: NuevoPedido):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        pedido <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO pedidos (usuario_id, fecha, total, estado)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, CURRENT_DATE, </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, &#39;pendiente&#39;)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING id, usuario_id, fecha, total, estado
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (nuevo<span style="color:#f92672">.</span>usuario_id, nuevo<span style="color:#f92672">.</span>total),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> pedido</span></span></code></pre></div>
</div>
<p><code>enviar_correo</code> no manda nada: duerme dos segundos y escribe una línea. Es a propósito. Un servidor SMTP de verdad tarda, falla y a veces no contesta, y para el laboratorio quiero controlar todo eso con un <code>sleep</code> y, más adelante, con un <code>random()</code>.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~$ time curl -s -X POST localhost:8000/pedidos \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{&#34;usuario_id&#34;: 42, &#34;total&#34;: 19.9}&#39;
{&#34;id&#34;:501,&#34;usuario_id&#34;:42,&#34;fecha&#34;:&#34;2026-11-02&#34;,&#34;total&#34;:19.9,&#34;estado&#34;:&#34;pendiente&#34;}

real    0m2.031s</code></pre>
</div>
<p>Dos segundos. El pedido estaba guardado en la base de datos a los pocos milisegundos; el resto del tiempo el cliente ha estado esperando a que el correo saliera. Y hay un segundo problema peor que el primero: si <code>enviar_correo</code> lanza una excepción, el endpoint devuelve un 500 <strong>con el pedido ya insertado</strong>. El cliente ve un error, reintenta, y tienes dos pedidos.</p>
<p>Esto es lo que una cola resuelve: separar &ldquo;lo que tiene que pasar ahora&rdquo; (guardar el pedido y contestar) de &ldquo;lo que tiene que pasar, pero no necesariamente ahora ni necesariamente bien a la primera&rdquo; (el correo). Lo segundo se apunta en una cola y otro proceso lo hace cuando puede.</p>
<h2 id="las-piezas-traducidas">Las piezas, traducidas <a class="ancla" href="#las-piezas-traducidas" aria-label="Enlace a esta sección">#</a></h2>
<p>RabbitMQ tiene más vocabulario del que necesitas el primer día. Lo mínimo:</p>
<p><strong>Mensaje.</strong> Unos bytes y unas cabeceras. RabbitMQ no mira dentro; tú decides el formato. Aquí será JSON, igual que en HTTP.</p>
<p><strong>Cola.</strong> Una lista de mensajes esperando a que alguien los lea. Tiene nombre. Si vienes de HTTP, piensa en ella como una bandeja de entrada.</p>
<p><strong>Productor y consumidor.</strong> Quien escribe en la cola y quien lee de ella. No se conocen, no se esperan, pueden no estar vivos al mismo tiempo. Esto último es el punto: el productor publica aunque no haya ningún consumidor, y el consumidor lee lo que se publicó mientras estaba apagado.</p>
<p><strong>Exchange.</strong> La pieza que despista. Un productor nunca escribe en una cola directamente; escribe en un exchange con una clave (<code>routing_key</code>), y el exchange decide a qué colas va el mensaje según unas reglas (<em>bindings</em>). Sirve para repartir un mensaje a varias colas, o para enrutar por patrón. Hoy no vamos a usar nada de eso: el exchange por defecto (nombre vacío) entrega el mensaje a la cola que se llame igual que la <code>routing_key</code>. Es la forma de usar RabbitMQ como una cola simple, y es perfectamente legítima.</p>
<p><strong>Ack.</strong> La confirmación del consumidor de que ha terminado con un mensaje. Es la pieza más importante de toda la serie, y hoy la voy a usar mal a propósito.</p>
<p>Todo lo demás (exchanges de tipo <em>topic</em>, <em>fanout</em>, colas con TTL, <em>dead letter</em>, <em>quorum queues</em>) existe y es útil, pero no hace falta para entender para qué sirve una cola.</p>
<h2 id="rabbitmq-en-podman">RabbitMQ en Podman <a class="ancla" href="#rabbitmq-en-podman" aria-label="Enlace a esta sección">#</a></h2>
<p>Al <code>compose.yaml</code> del laboratorio le añado un servicio:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#75715e"># compose.yaml (añadido)</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">rabbitmq</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">image</span>: <span style="color:#ae81ff">docker.io/library/rabbitmq:4-management</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">environment</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">RABBITMQ_DEFAULT_USER</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">RABBITMQ_DEFAULT_PASS</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ports</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;5672:5672&#34;</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;15672:15672&#34;</span></span></span></code></pre></div>
</div>
<p>La etiqueta <code>-management</code> trae la interfaz web, que va a ser nuestro instrumento de medida en esta serie, como lo fue <code>log_statement</code> en la anterior. El usuario <code>lab</code> lo defino yo porque el <code>guest</code> que viene de serie solo acepta conexiones desde <code>localhost</code> <em>del contenedor</em>, y con <a href="/posts/2026/podman-rootless-sin-sudo-ni-docker/">Podman rootless</a> las conexiones desde el anfitrión no cuentan como tal; es la primera piedra con la que tropieza todo el mundo.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ podman compose up -d rabbitmq
ignacio@zeus:~/lab-colas$ podman compose logs rabbitmq | grep -i &#39;server startup complete&#39;
rabbitmq  | 2026-11-02 17:40:12.118 [info] &lt;0.690.0&gt; Server startup complete; 4 plugins started.</code></pre>
</div>
<p>Y la interfaz, en <code>http://localhost:15672</code>, con <code>lab</code>/<code>lab</code>. Déjala abierta en la pestaña <em>Queues</em>.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ pip install pika</code></pre>
</div>
<p><code>pika</code> es el cliente de Python que mantiene el propio equipo de RabbitMQ. Es síncrono y bloqueante, que es exactamente lo que quiero para que el código se lea de arriba abajo.</p>
<h2 id="el-productor">El productor <a class="ancla" href="#el-productor" aria-label="Enlace a esta sección">#</a></h2>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># cola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>URL <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;amqp://lab:lab@localhost:5672/&#34;</span>
</span></span><span style="display:flex;"><span>COLA <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">publicar</span>(mensaje: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>    canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_publish(
</span></span><span style="display:flex;"><span>        exchange<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>        routing_key<span style="color:#f92672">=</span>COLA,
</span></span><span style="display:flex;"><span>        body<span style="color:#f92672">=</span>json<span style="color:#f92672">.</span>dumps(mensaje, default<span style="color:#f92672">=</span>str),
</span></span><span style="display:flex;"><span>        properties<span style="color:#f92672">=</span>pika<span style="color:#f92672">.</span>BasicProperties(delivery_mode<span style="color:#f92672">=</span><span style="color:#ae81ff">2</span>),
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    conexion<span style="color:#f92672">.</span>close()</span></span></code></pre></div>
</div>
<p>Línea a línea:</p>
<ul>
<li><code>queue_declare</code> crea la cola si no existe y no hace nada si existe. Es idempotente, y es costumbre que tanto el productor como el consumidor la declaren, para que dé igual cuál arranca primero. <code>durable=True</code> hace que la cola sobreviva a un reinicio de RabbitMQ.</li>
<li><code>exchange=&quot;&quot;</code> es el exchange por defecto, y <code>routing_key=COLA</code> hace que el mensaje caiga en la cola <code>correos</code>.</li>
<li><code>delivery_mode=2</code> marca el mensaje como persistente: se escribe a disco. Sin esto, un reinicio del bróker se lleva los mensajes aunque la cola sea durable. Cola durable y mensaje persistente son dos cosas distintas, y hacen falta las dos.</li>
<li><code>default=str</code> en el <code>json.dumps</code> es para que el <code>date</code> y el <code>Decimal</code> que vienen de PostgreSQL no rompan la serialización.</li>
</ul>
<p>Abrir y cerrar una conexión por mensaje es un despilfarro; en un servidor de verdad la conexión se mantiene abierta. Lo dejo así para que no haya nada que explicar sobre el ciclo de vida de la conexión.</p>
<p>Y el endpoint, en vez de enviar el correo, publica:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> publicar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.post</span>(<span style="color:#e6db74">&#34;/pedidos&#34;</span>, status_code<span style="color:#f92672">=</span><span style="color:#ae81ff">201</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">crear_pedido</span>(nuevo: NuevoPedido):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        pedido <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO pedidos (usuario_id, fecha, total, estado)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, CURRENT_DATE, </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, &#39;pendiente&#39;)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING id, usuario_id, fecha, total, estado
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (nuevo<span style="color:#f92672">.</span>usuario_id, nuevo<span style="color:#f92672">.</span>total),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    publicar(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> pedido</span></span></code></pre></div>
</div>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~$ time curl -s -X POST localhost:8000/pedidos \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{&#34;usuario_id&#34;: 42, &#34;total&#34;: 19.9}&#39;
{&#34;id&#34;:502,&#34;usuario_id&#34;:42,&#34;fecha&#34;:&#34;2026-11-02&#34;,&#34;total&#34;:19.9,&#34;estado&#34;:&#34;pendiente&#34;}

real    0m0.047s</code></pre>
</div>
<p>De dos segundos a cuarenta y pico milisegundos. El correo no se ha enviado todavía; lo que se ha hecho es dejar constancia de que hay que enviarlo. En la interfaz web, la cola <code>correos</code> tiene un mensaje en <em>Ready</em>.</p>
<p>Lanza cuatro o cinco pedidos más. Se van acumulando. No hay nadie leyendo, y a RabbitMQ le da igual: ese es el desacoplamiento del que hablaba. El productor ha terminado su trabajo aunque el consumidor no exista aún.</p>
<h2 id="el-consumidor">El consumidor <a class="ancla" href="#el-consumidor" aria-label="Enlace a esta sección">#</a></h2>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> COLA, URL
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>print(<span style="color:#e6db74">&#34;[worker] esperando mensajes&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>start_consuming()</span></span></code></pre></div>
</div>
<p><code>basic_consume</code> registra <code>procesar</code> como la función que RabbitMQ llamará por cada mensaje, y <code>start_consuming</code> se queda en bucle esperando. <code>auto_ack=True</code> le dice a RabbitMQ que dé el mensaje por entregado en cuanto lo manda al consumidor, antes de que <code>procesar</code> haga nada. Guárdate esa frase.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 502
[correo] confirmación del pedido 502 enviada
[worker] recibido pedido 503
[correo] confirmación del pedido 503 enviada
[worker] recibido pedido 504
...</code></pre>
</div>
<p>Los mensajes que se acumularon mientras no había consumidor salen todos seguidos, de dos en dos segundos, y en la interfaz web la cola vuelve a cero. Si ahora lanzas otro pedido con el worker vivo, aparece en el log del worker medio segundo después y el <code>curl</code> sigue tardando cuarenta milisegundos.</p>
<p>Dos terminales más y tienes dos workers consumiendo de la misma cola: RabbitMQ reparte los mensajes entre ellos por turnos. Escalar el envío de correos es arrancar otro proceso; el endpoint ni se entera.</p>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Hemos separado el pedido del correo, el endpoint responde en milisegundos, los correos se envían cuando se puede y añadir capacidad es arrancar otro worker. Todo lo que promete la portada de cualquier bróker de mensajes.</p>
<p>Y hay un <code>auto_ack=True</code> ahí en medio que lo echa todo a perder, pero solo cuando algo falla. En la <a href="/posts/2026/colas-cuando-el-consumidor-se-cae/">siguiente entrada</a> mato al worker a mitad de un correo y miro qué ha pasado con el mensaje.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_77670c3fdda90729.png"/></item><item><title>GraphQL explicado a alguien que lleva años haciendo REST</title><link>https://www.igalvan.es/posts/2026/graphql-para-gente-de-rest/</link><pubDate>Tue, 27 Oct 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/graphql-para-gente-de-rest/</guid><description><![CDATA[<p>Llevo muchos años consumiendo y diseñando APIs REST. Suficientes como para que GraphQL me pareciera, durante bastante tiempo, una moda de frontends. Esta entrada es lo que me habría gustado leer entonces: sin evangelizar, con las pegas delante, y partiendo de lo que ya sé de REST.</p>
<p>Es la primera de una serie de tres. Esta es la teoría; en las dos siguientes monto un laboratorio con PostgreSQL y expongo los mismos datos por REST y por GraphQL para ver con un log delante todo lo que aquí cuento de palabra.</p>
<h2 id="el-cambio-de-mentalidad-en-una-frase">El cambio de mentalidad en una frase <a class="ancla" href="#el-cambio-de-mentalidad-en-una-frase" aria-label="Enlace a esta sección">#</a></h2>
<p>En REST el servidor decide la forma de la respuesta. En GraphQL la decide el cliente.</p>
<p>Eso es todo. El resto son consecuencias.</p>
<p>En REST expones recursos (<code>/usuarios/42</code>, <code>/usuarios/42/pedidos</code>) y cada uno devuelve lo que tú decidiste que devuelve. Si el cliente necesita el nombre del usuario y la fecha de sus tres últimos pedidos, hace dos peticiones y se trae de paso veinte campos que no quería. Si eso duele, acabas creando <code>/usuarios/42?fields=nombre</code> o, peor, <code>/pantalla-inicio-movil</code>, un endpoint hecho a medida de una pantalla concreta. Todos lo hemos hecho.</p>
<p>GraphQL ataca exactamente ese problema. Hay un único endpoint (normalmente <code>POST /graphql</code>) y el cliente manda una descripción de lo que quiere:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-graphql" data-lang="graphql"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  usuario(id: <span style="color:#a6e22e">42</span>) {
</span></span><span style="display:flex;"><span>    nombre
</span></span><span style="display:flex;"><span>    pedidos(ultimos: <span style="color:#a6e22e">3</span>) {
</span></span><span style="display:flex;"><span>      fecha
</span></span><span style="display:flex;"><span>      total
</span></span><span style="display:flex;"><span>    }
</span></span><span style="display:flex;"><span>  }
</span></span><span style="display:flex;"><span>}</span></span></code></pre></div>
</div>
<p>Y recibe exactamente eso, con la misma forma:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;data&#34;</span>: {
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">&#34;usuario&#34;</span>: {
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;nombre&#34;</span>: <span style="color:#e6db74">&#34;Ignacio&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">&#34;pedidos&#34;</span>: [
</span></span><span style="display:flex;"><span>        { <span style="color:#f92672">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-10-20&#34;</span>, <span style="color:#f92672">&#34;total&#34;</span>: <span style="color:#ae81ff">31.5</span> },
</span></span><span style="display:flex;"><span>        { <span style="color:#f92672">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-10-12&#34;</span>, <span style="color:#f92672">&#34;total&#34;</span>: <span style="color:#ae81ff">8.0</span> },
</span></span><span style="display:flex;"><span>        { <span style="color:#f92672">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-09-30&#34;</span>, <span style="color:#f92672">&#34;total&#34;</span>: <span style="color:#ae81ff">120.0</span> }
</span></span><span style="display:flex;"><span>      ]
</span></span><span style="display:flex;"><span>    }
</span></span><span style="display:flex;"><span>  }
</span></span><span style="display:flex;"><span>}</span></span></code></pre></div>
</div>
<p>Una petición, ni un byte de más, y el cliente puede cambiar lo que pide sin que nadie toque el servidor.</p>
<h2 id="las-piezas-traducidas-a-vocabulario-rest">Las piezas, traducidas a vocabulario REST <a class="ancla" href="#las-piezas-traducidas-a-vocabulario-rest" aria-label="Enlace a esta sección">#</a></h2>
<p><strong>El esquema (schema).</strong> Es el contrato, y es obligatorio. Si en REST te apoyas en OpenAPI, aquí el esquema no es documentación: es lo que el servidor valida contra cada petición. Se escribe en un lenguaje propio (SDL) y está tipado:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-graphql" data-lang="graphql"><span style="display:flex;"><span><span style="color:#66d9ef">type</span> <span style="color:#a6e22e">Usuario</span> {
</span></span><span style="display:flex;"><span>  id: <span style="color:#a6e22e">ID</span>!
</span></span><span style="display:flex;"><span>  nombre: <span style="color:#a6e22e">String</span>!
</span></span><span style="display:flex;"><span>  email: <span style="color:#a6e22e">String</span>
</span></span><span style="display:flex;"><span>  pedidos(ultimos: <span style="color:#a6e22e">Int</span> = 10): [<span style="color:#a6e22e">Pedido</span>!]!
</span></span><span style="display:flex;"><span>}
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">type</span> <span style="color:#a6e22e">Pedido</span> {
</span></span><span style="display:flex;"><span>  id: <span style="color:#a6e22e">ID</span>!
</span></span><span style="display:flex;"><span>  fecha: <span style="color:#a6e22e">String</span>!
</span></span><span style="display:flex;"><span>  total: <span style="color:#a6e22e">Float</span>!
</span></span><span style="display:flex;"><span>}
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">type</span> <span style="color:#a6e22e">Query</span> {
</span></span><span style="display:flex;"><span>  usuario(id: <span style="color:#a6e22e">ID</span>!): <span style="color:#a6e22e">Usuario</span>
</span></span><span style="display:flex;"><span>}</span></span></code></pre></div>
</div>
<p>El <code>!</code> significa &ldquo;no nulo&rdquo;. <code>[Pedido!]!</code> es una lista no nula de pedidos no nulos. Esta precisión sobre la nulabilidad es una de las cosas que más echo de menos cuando vuelvo a JSON &ldquo;a pelo&rdquo;.</p>
<p><strong>Query y Mutation.</strong> Las queries son tus <code>GET</code>: leer. Las mutations son tus <code>POST</code>/<code>PUT</code>/<code>DELETE</code>: todo lo que escribe. GraphQL no distingue entre crear y modificar; eso lo defines tú en el nombre (<code>crearPedido</code>, <code>cancelarPedido</code>). Hay un tercer tipo, <code>Subscription</code>, para recibir datos en tiempo real, normalmente sobre WebSocket; lo dejo fuera de aquí.</p>
<p><strong>Resolvers.</strong> Es donde vive el código. Cada campo del esquema tiene (o hereda) una función que sabe obtener su valor. <code>Query.usuario</code> va a la base de datos a por el usuario; <code>Usuario.pedidos</code> va a por los pedidos <em>de ese usuario</em>. El servidor recorre la petición del cliente campo a campo llamando al resolver que toque.</p>
<p>Si vienes de REST esto se parece a tener un controlador por campo en vez de uno por endpoint. Y es la fuente del problema más famoso de GraphQL, que viene ahora.</p>
<h2 id="lo-que-se-pierde-y-nadie-te-cuenta-en-la-demo">Lo que se pierde (y nadie te cuenta en la demo) <a class="ancla" href="#lo-que-se-pierde-y-nadie-te-cuenta-en-la-demo" aria-label="Enlace a esta sección">#</a></h2>
<h3 id="la-caché-http">La caché HTTP <a class="ancla" href="#la-cach%c3%a9-http" aria-label="Enlace a esta sección">#</a></h3>
<p>En REST, <code>GET /usuarios/42</code> es cacheable por cualquier intermediario que entienda HTTP: navegador, CDN, proxy inverso. Es gratis y es enorme.</p>
<p>En GraphQL todo va por <code>POST</code> al mismo endpoint, con la consulta en el cuerpo. Para un proxy, todas las peticiones son iguales y ninguna es cacheable. Las soluciones existen (consultas persistidas con <code>GET</code>, caché normalizada en el cliente, caché de respuestas en el servidor), pero hay que montarlas y ninguna es tan simple como un <code>Cache-Control</code>.</p>
<h3 id="el-problema-n1">El problema N+1 <a class="ancla" href="#el-problema-n1" aria-label="Enlace a esta sección">#</a></h3>
<p>Vuelve a mirar la consulta del principio. El resolver de <code>usuario</code> hace una consulta SQL. Después, para <code>pedidos</code>, otra. Bien. Ahora imagina esta:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-graphql" data-lang="graphql"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  usuarios(primeros: <span style="color:#a6e22e">100</span>) {
</span></span><span style="display:flex;"><span>    nombre
</span></span><span style="display:flex;"><span>    pedidos(ultimos: <span style="color:#a6e22e">3</span>) { total }
</span></span><span style="display:flex;"><span>  }
</span></span><span style="display:flex;"><span>}</span></span></code></pre></div>
</div>
<p>Un resolver ingenuo hace una consulta para los 100 usuarios y luego <strong>100 consultas más</strong>, una por usuario, para sus pedidos. 101 viajes a la base de datos para algo que en SQL se resuelve con un <code>JOIN</code> y un <code>LIMIT</code> por ventana.</p>
<p>La solución estándar se llama <em>DataLoader</em> y consiste en agrupar: en lugar de resolver los pedidos usuario a usuario, el servidor acumula los 100 ids y lanza una sola consulta <code>WHERE usuario_id IN (...)</code>. Funciona, pero es una capa más que tienes que escribir y entender. En REST el N+1 también existe, pero lo ves venir porque tú escribiste el endpoint; en GraphQL lo provoca el cliente con una consulta que tú nunca anticipaste.</p>
<h3 id="el-código-de-estado-es-siempre-200">El código de estado es siempre 200 <a class="ancla" href="#el-c%c3%b3digo-de-estado-es-siempre-200" aria-label="Enlace a esta sección">#</a></h3>
<p>Una petición GraphQL con errores devuelve, casi siempre, <code>200 OK</code> con un bloque <code>errors</code> en el JSON:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-json" data-lang="json"><span style="display:flex;"><span>{
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;data&#34;</span>: { <span style="color:#f92672">&#34;usuario&#34;</span>: <span style="color:#66d9ef">null</span> },
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">&#34;errors&#34;</span>: [
</span></span><span style="display:flex;"><span>    { <span style="color:#f92672">&#34;message&#34;</span>: <span style="color:#e6db74">&#34;Usuario no encontrado&#34;</span>, <span style="color:#f92672">&#34;path&#34;</span>: [<span style="color:#e6db74">&#34;usuario&#34;</span>] }
</span></span><span style="display:flex;"><span>  ]
</span></span><span style="display:flex;"><span>}</span></span></code></pre></div>
</div>
<p>Además, los errores son parciales: puede venir la mitad de los datos y errores en la otra mitad. Esto desmonta cualquier monitorización que cuentes por códigos HTTP, y los clientes tienen que mirar siempre <code>errors</code>, no solo el estado.</p>
<h3 id="no-hay-recurso-al-que-apuntar">No hay &ldquo;recurso&rdquo; al que apuntar <a class="ancla" href="#no-hay-recurso-al-que-apuntar" aria-label="Enlace a esta sección">#</a></h3>
<p>En REST, la URL identifica al recurso. Sirve para enlazar, para registrar en logs, para permisos por ruta, para rate limiting por endpoint. En GraphQL nada de eso aplica tal cual: la autorización pasa a ser por tipo o por campo, el rate limiting por <em>coste</em> de la consulta, y los logs tienen que registrar la consulta entera para servir de algo.</p>
<h3 id="el-cliente-puede-pedir-demasiado">El cliente puede pedir demasiado <a class="ancla" href="#el-cliente-puede-pedir-demasiado" aria-label="Enlace a esta sección">#</a></h3>
<p>Si tu esquema tiene relaciones circulares (usuario → pedidos → usuario → pedidos…), un cliente malintencionado o simplemente torpe puede pedir una consulta de profundidad 50 y tumbarte el servidor. Hay que poner límites de profundidad y de complejidad, y desactivar la introspección (la capacidad de preguntarle al servidor por su propio esquema) en producción si la API no es pública. En REST este problema no existe porque el servidor acota lo que devuelve cada endpoint.</p>
<h2 id="lo-que-se-gana-de-verdad">Lo que se gana (de verdad) <a class="ancla" href="#lo-que-se-gana-de-verdad" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li><strong>Un esquema vivo y tipado.</strong> Las herramientas (GraphiQL, generadores de clientes) se construyen sobre él. Autocompletado real contra la API, clientes generados con tipos correctos, documentación que no se desactualiza porque <em>es</em> el contrato.</li>
<li><strong>Evolución sin versiones.</strong> Añades campos y nadie se entera; marcas los viejos como <code>@deprecated</code> y puedes medir quién los sigue usando porque el servidor ve exactamente qué campos pide cada cliente. El <code>/v2/</code> desaparece.</li>
<li><strong>Agregación de fuentes.</strong> Un esquema puede resolver <code>usuario</code> contra una base de datos y <code>usuario.saldo</code> contra otro servicio. El cliente ve un grafo; el servidor esconde la fontanería. Esto es lo que antes hacía el <em>backend for frontend</em>, pero sin escribir uno por pantalla.</li>
<li><strong>Varios clientes distintos sobre la misma API.</strong> Web, móvil, un panel interno: cada uno pide lo suyo. Este es el caso de uso original (Facebook, 2012) y sigue siendo el más sólido.</li>
</ul>
<h2 id="cuándo-no-merece-la-pena">Cuándo no merece la pena <a class="ancla" href="#cu%c3%a1ndo-no-merece-la-pena" aria-label="Enlace a esta sección">#</a></h2>
<p>Mi lista, sin pretensiones:</p>
<ul>
<li>Una API interna sencilla con dos o tres consumidores que controlas tú. REST, y a otra cosa.</li>
<li>Integración máquina a máquina con operaciones fijas (&ldquo;envíame este fichero&rdquo;, &ldquo;dame el estado de esta transacción&rdquo;). No hay nada que el cliente necesite moldear.</li>
<li>Cuando la caché HTTP es lo que te salva la vida: contenido público, muy leído, poco cambiante.</li>
<li>Cuando el equipo no va a tener tiempo de montar DataLoader, límites de complejidad y autorización por campo. GraphQL sin eso es una API REST peor, con un agujero de rendimiento y seguridad.</li>
<li>Si lo que de verdad quieres es &ldquo;dame solo estos campos&rdquo;, bastante gente resuelve eso con un parámetro <code>fields</code> en REST y duerme tranquila.</li>
</ul>
<h2 id="cuándo-sí">Cuándo sí <a class="ancla" href="#cu%c3%a1ndo-s%c3%ad" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li>Varios clientes con necesidades distintas sobre los mismos datos.</li>
<li>Datos muy relacionados, donde la pantalla típica cruza cuatro o cinco entidades.</li>
<li>Una capa de agregación delante de servicios heterogéneos.</li>
<li>Equipos de frontend que avanzan más rápido que los de backend y necesitan dejar de pedir endpoints.</li>
</ul>
<h2 id="resumen-para-quien-no-haya-bajado-hasta-aquí">Resumen para quien no haya bajado hasta aquí <a class="ancla" href="#resumen-para-quien-no-haya-bajado-hasta-aqu%c3%ad" aria-label="Enlace a esta sección">#</a></h2>
<p>GraphQL no sustituye a REST; cambia quién manda sobre la forma de la respuesta. A cambio de flexibilidad para el cliente, pagas con la caché HTTP, con el N+1, con errores que no son errores HTTP y con una superficie de ataque que tienes que acotar a mano. Si esos cuatro problemas tienen nombre en tu cabeza antes de empezar, GraphQL puede ser una muy buena herramienta. Si no, probablemente no la necesitas todavía.</p>
<h2 id="lo-que-viene">Lo que viene <a class="ancla" href="#lo-que-viene" aria-label="Enlace a esta sección">#</a></h2>
<p>En la <a href="/posts/2026/graphql-laboratorio-rest-vs-graphql/">segunda entrada</a> monto el laboratorio: PostgreSQL en Podman, una API REST y una API GraphQL en Python sobre las mismas dos tablas, y la primera pantalla comparada. En la <a href="/posts/2026/graphql-n-mas-1-dataloader-cache/">tercera</a> pido cien usuarios de golpe, enseño el N+1 en el log de la base de datos, lo arreglo con DataLoader y cierro con la caché. Que es donde todo esto se entiende de verdad.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_a0df0b547810cc66.png"/></item></channel></rss>