¿Te resulta más fácil leer con fondo crema, un tono de color, más contraste o un texto más grande? Elige tus colores y tu texto una sola vez, para todas las páginas.

Lección gratuita

Claves de idempotencia y efectos únicos

Después de esta lección: Puedo hacer seguro un paso repetido con una clave de idempotencia.

Lección de 60 min6 comandosLaboratorio de ejecución duradera: haz caer un flujo a propósito y reanúdalo desde su diario

¿Qué es una clave de idempotencia?

Una clave de idempotencia es un nombre único que se envía con una petición, para que quien la recibe actúe una sola vez. Da igual cuántas veces le llegue. Cierra el último hueco de un diario de pasos: una caída tras un efecto pero antes de su fila.

Los proveedores de pago, los servicios de correo y las colas de mensajes aceptan estas claves justo por eso. Con un diario y una clave juntos, un efecto ocurre una vez.

Al final de esta lección

Nota

Puedo hacer seguro un paso repetido con una clave de idempotencia.

Palabras clave

PalabraQué significa
Idempotenteque tiene el mismo efecto se haga una vez o muchas
Clave de idempotenciaun nombre para una petición, para reconocer las repeticiones
Al menos una vezla promesa de que algo ocurre, quizá más de una vez
Exactamente una vezun efecto que ocurre una vez, nunca cero ni dos
Restricción de unicidaduna regla de la base de datos que rechaza otra fila con el mismo valor

Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.

Una caída puede caer entre efecto y fila

El motor ejecuta el trabajo de un paso y después escribe su fila en el diario. Entre esos dos momentos hay un hueco. Si el proceso muere en el hueco, el efecto ha ocurrido pero el diario no lo sabe.

Al reanudar no hay fila para ese paso, así que el motor lo ejecuta otra vez. El diario da al menos una vez, no exactamente una vez. La opción --crash-inside del laboratorio provoca la caída justo en ese hueco.

Caída dentro del cobro, sin clave

Comando
docker exec worker python3 order.py order-8 --fresh --crash-inside charge_card

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

Reanuda order-8

Comando
docker exec worker python3 order.py order-8

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

Cuenta los pagos de order-8

Comando
docker exec db psql -U durable -c "SELECT workflow, amount FROM payments WHERE workflow = 'order-8'"

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

La clave convierte una repetición en una respuesta

Con --keyed, el cobro lleva la clave order-9:charge_card. El proveedor del laboratorio guarda los pagos en una tabla donde la clave es única, e inserta con ON CONFLICT DO NOTHING.

El primer cobro añade una fila. La repetición encuentra la clave ya guardada, no añade nada y responde con "repeat": true. El flujo sigue con el mismo resultado en los dos casos.

Caída dentro del cobro, con clave

Comando
docker exec worker python3 order.py order-9 --fresh --keyed --crash-inside charge_card

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

Reanuda order-9 con su clave

Comando
docker exec worker python3 order.py order-9 --keyed

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

Cuenta los pagos de order-9

Comando
docker exec db psql -U durable -c "SELECT workflow, idem_key, amount FROM payments WHERE workflow = 'order-9'"

Se muestra aquí y no se ejecuta. Pulsa Iniciar laboratorio para escribirlo en el terminal de tu propio laboratorio.

Ejemplo resuelto: la misma caída, de dos maneras

PedidoClave enviadaQué recibió la reanudaciónPagos
order-8ningunaun segundo cobro2
order-9order-9:charge_carduna respuesta marcada como repetida1

Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.

Un error frecuente

Advertencia

Mucha gente genera una clave aleatoria nueva en cada llamada. Entonces la reanudación envía otra clave y el proveedor vuelve a cobrar. Una clave debe ser la misma en cada ejecución: constrúyela con el flujo y el paso, o guárdala en el diario.

Pruébalo: una clave que cambia

Código: python
import uuid

taken = {}   # el proveedor de tarjetas: un pago por clave

def charge(key, cents):
    if key in taken:
        return "repetido, no se cobra nada"
    taken[key] = cents
    return "cobrados " + str(cents)

def make_key(order):
    return order + ":charge_card"   # la misma en cada nueva ejecución

# El flujo envía el cobro, cae y lo envía otra vez.
for attempt in [1, 2]:
    print("intento", attempt, charge(make_key("order-3"), 2500))
print("pagos cobrados:", len(taken))
# Haz que make_key devuelva order + str(uuid.uuid4()) y vuelve a ejecutarlo.

Sobre este laboratorio y su código: Laboratorio de ejecución duradera: haz caer un flujo a propósito y reanúdalo desde su diario

¿Enseñas a una clase? Asigna este módulo a tus alumnos con guía del profesor, tareas con corrección automática y un laboratorio para cada alumno.