# Idempotente

## Qué es

Una operación es idempotente cuando ejecutarla varias veces tiene el mismo efecto que hacerlo una sola vez; esa propiedad se llama idempotencia. El término procede de las matemáticas: una función es idempotente si aplicarla a su propio resultado no cambia nada, de modo que f(f(x)) es igual a f(x). Redondear hacia abajo un número ya redondeado hacia abajo da el mismo número.

En software, la prueba útil es una segunda ejecución. Asignar un valor es idempotente, porque la segunda ejecución escribe el valor que ya existe. Sumar a un valor no lo es, porque vuelve a sumar:

```sql
-- idempotent: a second run sets the same value
UPDATE accounts SET plan = 'pro' WHERE id = 42;

-- not idempotent: a second run adds ten more
UPDATE accounts SET credits = credits + 10 WHERE id = 42;
```

HTTP da al término su definición más precisa. RFC 9110 llama idempotente a un método de petición cuando varias peticiones idénticas están concebidas para producir el mismo efecto en el servidor que una sola, y enumera PUT, DELETE y los métodos seguros GET, HEAD, OPTIONS y TRACE. Dos detalles importan. La propiedad cubre el efecto solicitado por el cliente, por lo que el servidor puede registrar cada petición por separado. Además, la respuesta puede diferir: un segundo DELETE del mismo recurso puede responder 404 donde el primero respondió 200 y seguir siendo idempotente, porque el recurso ya no existe en ambos casos. PATCH queda fuera de la lista. RFC 5789 indica que no es seguro ni idempotente, aunque el cliente puede enviar un PATCH concreto de forma idempotente haciéndolo condicional, con un ETag fuerte en una cabecera If-Match, de modo que se rechace una copia repetida después de que la primera haya cambiado el recurso.

Ser seguro es la más estricta de las dos promesas. Un método seguro en el sentido de RFC 9110 es esencialmente de solo lectura: todo método seguro es idempotente, mientras que DELETE es idempotente sin ser seguro.

## Por qué importa

Las redes pierden respuestas. Cuando el cliente envía una petición y la conexión se corta antes de que llegue la respuesta, no puede saber si el servidor nunca la vio, la vio y se detuvo, o la ejecutó y perdió la respuesta. Repetirla es la recuperación evidente; la idempotencia hace inocua esa repetición. RFC 9110 basa precisamente en ello sus reglas de reintento. Una petición idempotente puede repetirse automáticamente tras un fallo de comunicación. El cliente no debería reintentar automáticamente una petición no idempotente, salvo si sabe que en la práctica sí lo es o puede determinar que la original nunca se aplicó; un proxy no debe reintentar una petición no idempotente por iniciativa propia en ningún caso.

Las colas plantean la misma cuestión a escala. Muchos sistemas de mensajes prometen entrega al menos una vez: un consumidor que falla después de hacer su trabajo, pero antes de confirmar el mensaje, vuelve a recibirlo. Prometer entrega exactamente una vez a través de una red es mucho más difícil; la respuesta práctica es un consumidor para el que una segunda entrega no cambie nada. La gestión de configuración también depende de esa propiedad. Una herramienta que lleva los servidores a un estado declarado se ejecuta una y otra vez, tras cada cambio y a menudo de forma programada; cada ejecución debe dejar un servidor correcto exactamente como lo encontró.

La decisión real es cómo obtener idempotencia cuando una operación no la tiene por naturaleza. Hay tres respuestas habituales. La primera es el diseño: expresar el cambio como estado objetivo, no como paso; «asegurar que esta línea esté en el archivo», en vez de «añadir esta línea al final». La segunda es una clave: el cliente adjunta un identificador único a la petición, el servidor lo registra con una restricción de unicidad y una repetición encuentra el registro y recibe el resultado original, en lugar de provocar una segunda acción. La tercera es comprobar antes de actuar, como hace la mayoría de los módulos de Ansible: comparan el estado actual con el deseado y terminan sin actuar si coinciden. Cada opción tiene un coste. Diseñar por estado objetivo exige un modelo claro del estado final; las claves necesitan almacenamiento y una regla de conservación, y comprobar primero requiere una forma fiable de leer el estado actual.

## Cómo se aplica en la práctica

Los servidores de la empresa se configuran con Ansible. En ese proyecto, [la idempotencia es un contrato: un host que ya ha convergido informa de cero cambios](/es/portfolio/servers-you-can-rebuild-from-scratch/). El aprovisionamiento sin argumentos lleva cada host a su estado declarado; un play que no pueda informar de cero cambios en un host ya correcto se considera inacabado. Así, cada ejecución mide la idempotencia en lugar de confiar en que exista.

La misma idea, aplicada a los datos, sustenta [una prueba que ejecuta dos veces la cadena de construcción de diecinueve pasos](/es/portfolio/held-the-generator-to-981-tests-and-92-coverage/). La página nombra el fallo que pretende detectar: un generador que funciona la primera vez y corrompe los datos la segunda, mediante pasos que insertan sin comprobar o dependen del orden de la salida de un paso anterior. La prueba construye la base de datos desde un archivo vacío, toma una instantánea, vuelve a ejecutar toda la cadena sobre el resultado y exige que la segunda pasada no cambie nada, incluidos los recuentos, contenidos e identificadores de las filas. La prueba aporta evidencia sobre las ejecuciones repetidas con las entradas y el estado de la base de datos que comprueba.

Para vender existencias limitadas, la nota sobre [vender la última entrada exactamente una vez](/es/notes/selling-limited-stock-without-overselling/) combina una clave con escrituras condicionales. Cada proceso de compra lleva una clave de idempotencia y la tabla de reservas tiene `UNIQUE (tenant_id, idempotency_key)`: un clic reintentado devuelve la reserva existente, no una segunda unidad. Una liberación que se ejecuta dos veces, por ejemplo por un tiempo de espera agotado y un botón de cancelación, devuelve la unidad una sola vez, porque solo repone existencias cuando su propia actualización cambió exactamente una fila. Más adelante, cada consumidor de mensajes es idempotente y usa el pedido como clave: los mensajes llegan al menos una vez y la idempotencia hace que su efecto se produzca una sola vez en la práctica.

## Dónde surgen los problemas

**Una petición reintentada cobra dos veces.** Un POST que crea un pago, un pedido o un correo no es idempotente de forma predeterminada; un cliente o proxy que lo reintenta tras un tiempo de espera agotado crea otro. Asigne a estas peticiones una clave de idempotencia que el servidor almacene con una restricción de unicidad y devuelva el resultado guardado si recibe la misma clave.

**Un resultado vacío se interpreta como error.** En PostgreSQL, `INSERT ... ON CONFLICT DO NOTHING` omite una fila que infringiría una restricción de unicidad y `RETURNING` solo devuelve filas realmente insertadas o actualizadas. Repetir la inserción de la misma fila no devuelve nada: es el resultado correcto de una segunda ejecución. Tratarlo como fallo convierte un reintento inocuo en una página de error; el código debería consultar la fila existente.

**Una tarea de comando cambia el host en cada ejecución.** La documentación de Ansible dice que la mayoría de los módulos comprueban si ya se alcanzó el estado deseado y que «no todos los playbooks ni todos los módulos se comportan así». Una tarea que ejecuta un comando es la excepción habitual: el comando es arbitrario y Ansible no puede saber qué hace. La opción `creates` del módulo command omite el paso si ya existe un archivo dado; `removes` lo ejecuta solo mientras el archivo siga presente, y `changed_when` define qué resultado cuenta como cambio. Sin ninguna de ellas, la tarea se ejecuta otra vez en cada convergencia, sea cual sea el estado del host.

**Un contador cuenta el reintento.** Con entrega al menos una vez, un consumidor que incrementa un contador o envía una notificación por mensaje lo hace dos veces si recibe dos veces un mensaje. Guarde la clave de negocio del mensaje junto con el efecto, en la misma transacción, y omita las claves ya almacenadas.

**La segunda ejecución corrompe lo construido por la primera.** Un paso puede ser correcto en una base de datos vacía e incorrecto en una llena, al insertar un duplicado, renumerar identificadores o depender de un orden dejado por la primera ejecución. Una prueba que parte de cero y ejecuta una sola vez pasará igualmente. Ejecute todo el trabajo dos veces y exija que la segunda no cambie nada, como hace la prueba anterior.

## Lecturas adicionales

- [RFC 9110, sección 9.2.2: métodos idempotentes](https://www.rfc-editor.org/rfc/rfc9110#name-idempotent-methods)
  — Definición HTTP, métodos idempotentes y reglas de reintento automático.
- [RFC 5789: método PATCH para HTTP](https://www.rfc-editor.org/rfc/rfc5789) — Por qué PATCH no es seguro ni idempotente y cómo una petición condicional permite repetirlo sin efectos adicionales.
- [Ansible: introducción a los playbooks](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)
  — Estado deseado, idempotencia y modo de comprobación explicados por Ansible.
- [Ansible: módulo command](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/command_module.html)
  — Opciones `creates` y `removes` para poder repetir un comando sin efectos adicionales.
- [PostgreSQL: INSERT](https://www.postgresql.org/docs/current/sql-insert.html)
  — `ON CONFLICT` y lo que devuelve `RETURNING` si ya existe una fila.

<https://engineer.company/es/glossary/idempotent/>
