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

Este laboratorio enseña desde cero la ejecución duradera, la idea que hay detrás de motores de flujos de trabajo como Temporal, Restate y DBOS. Cada estudiante tiene una base de datos PostgreSQL y un worker de Python con un motor de unas cien líneas: un paso se ejecuta una vez, su resultado se anota en una tabla de diario, y una nueva ejecución tras una caída repite las filas que encuentra y sigue.

Los estudiantes hacen caer flujos a propósito y los reanudan: un trabajo simple que cobra dos veces una tarjeta, un pedido que repite su diario, un cobro protegido por una clave de idempotencia, un calendario de reintentos, un temporizador duradero y un viaje reservado como saga. Acompaña al módulo de ejecución duradera. Ningún motor comercial se ejecuta en él; el módulo los compara con palabras.

Qué aprenden los estudiantes

Por qué un trabajo que muere a mitad repite sus efectos secundarios cuando se reintenta desde arriba; cómo un diario de pasos terminados permite a una nueva ejecución seguir; por qué una caída entre un efecto y su fila del diario sigue repitiendo el efecto, y cómo una clave de idempotencia cierra ese hueco; cómo los reintentos esperan cada vez más, con un tope, jitter y un límite; cómo un temporizador duradero espera como una fila y no como un proceso en marcha; y cómo una saga deshace los pasos terminados, del más reciente al más antiguo, cuando falla uno posterior. Leen el diario con SQL y ven por qué el código de un flujo debe pedir los mismos pasos en cada ejecución. Sirve para un curso de sistemas distribuidos o de ingeniería del software, o para un módulo sobre fiabilidad del back-end.

Ejecútalo en tu navegador

El laboratorio inicia dos servicios: db, PostgreSQL, y worker, Python con los archivos del laboratorio en /tmp. El worker arranca cuando la base de datos responde. El terminal de al lado no tiene Python propio, así que llega a ellos con docker exec. Cada Run imprime siempre lo mismo: nada lee el reloj y la única elección aleatoria tiene una semilla fija.

  1. Abre la página Contenedor. Abre «Crear» en la barra y elige «Ejecutar un contenedor». Cualquiera puede abrir la página, y el laboratorio de Git y el de SQL se inician sin cuenta. Todos los demás laboratorios necesitan una cuenta gratuita: crea una, inicia sesión y pulsa «Iniciar».
  2. Busca el laboratorio. La tarjeta «Laboratorios de ejemplo» lista todos los ejemplos. Busca Durable execution.
  3. Pulsa «Iniciar». «Iniciar» lo ejecuta tal cual, con una sola pulsación. «Editar el archivo primero» abre el archivo compose para que lo cambies antes de iniciarlo.
  4. Ábrelo. En la página del laboratorio, pulsa «Abrir el terminal». No hay ningún enlace en «En tu navegador» porque el laboratorio no tiene página web. Escribe docker exec worker python3 order.py order-7 --fresh --crash-after 2: ejecuta dos pasos y se detiene con una línea de caída. Después, docker exec worker python3 order.py order-7 repite esos dos pasos desde el diario y ejecuta los otros dos.

Qué pedir que entreguen los estudiantes

Un flujo propio escrito con engine.py, por ejemplo un alta que crea una cuenta, envía un correo de bienvenida y reserva una llamada, con la salida de una ejecución que hicieron caer con --crash-after, la salida de la ejecución que la reanudó y sus filas del diario sacadas con psql. Después, una frase sobre qué pasos se ejecutaron dos veces y cuáles no. Una buena respuesta pone cada efecto secundario dentro de un paso y da una clave de idempotencia a todo lo que cobre dinero.

Una lección básica sobre este laboratorio

Fundamentos de la ejecución duradera (Durable Execution Basics) es una lección pequeña hecha en este laboratorio. En ella un estudiante hace caer un trabajo simple y cuenta dos pagos, hace caer el flujo del pedido y lee su diario, lo reanuda, cobra una tarjeta una sola vez con una clave de idempotencia tras una caída dentro del cobro, y reserva un viaje cuyo coche falla, de modo que la saga cancela el hotel y el vuelo.

Las cuentas personales gratuitas la tienen en el módulo Basics, que está en Inicio, cada centro puede copiarla de la carpeta Basics de la Biblioteca, y un centro nuevo se abre con ella en un módulo llamado Data Labs (Sample). Es pequeña a propósito: muestra a un docente qué es una lección hecha en un laboratorio, y el laboratorio hace el resto. Cópiala en un módulo propio para cambiarla.

El código en GitHub

El archivo compose no tiene Dockerfile: ejecuta dos imágenes públicas estándar, postgres y python, cada una fijada a una versión exacta, con 256 MB y 128 MB de memoria. PostgreSQL tiene la PostgreSQL License y Python la PSF License; no distribuimos ninguna de las dos. El worker se ejecuta con una cuenta sin privilegios. Sus archivos los escribe el propio archivo compose, incluido pg.py, un pequeño cliente del protocolo de PostgreSQL, porque una imagen estándar de Python no trae ningún controlador de base de datos. La base de datos no pide contraseña, ya que nada de fuera del laboratorio puede llegar a ella, y el laboratorio no tiene salida a internet. Nada se conserva cuando el laboratorio se detiene.

Asígnalo como trabajo

Indica en la tarea qué hay que entregar.

  1. Crea el laboratorio. En tu módulo añade una tarea y elige la tarjeta «Laboratorio de contenedores», y después «En un repositorio de GitHub». Indica https://github.com/mitsurutech/lab-durable-lab con la rama main. El archivo compose es el predeterminado, compose.yaml. Haz un fork del repositorio antes si quieres modificarlo.
  2. Publica y pruébalo. «Publicar» fija el commit que te mostraron, así que un cambio posterior en el repositorio no altera un laboratorio que ya has asignado. Inicia primero tu propia copia.
  3. Asígnalo. Asígnalo como cualquier tarea, con una fecha de entrega si quieres, e indica en la tarea qué hacer y qué entregar.
  4. Califica lo entregado. Abre la copia de un alumno y el trabajo que ha entregado, califícalo y devuélvelo con un motivo si necesita más.

Prueba este laboratorio, y lo que cuesta

Con una cuenta personal gratuita puedes seguir las lecciones básicas de este laboratorio, con crédito gratuito suficiente cada mes para seguir la mayoría de las lecciones y sin tarjeta. Para una clase, un centro tiene gratis sus primeros 365 días, hasta 50 alumnos, y después paga por alumno y año, con todos los laboratorios incluidos y el profesorado gratis.

Preguntas frecuentes

¿Es esto Temporal, Restate o DBOS?
No. Es un motor de unas cien líneas escrito para el laboratorio, con la idea que comparten esos motores: un diario de pasos terminados que una nueva ejecución repite. Los motores reales añaden muchos workers, colas, herramientas para cambiar el código y una página web. El módulo de ejecución duradera los compara con palabras.
¿Cómo hace caer un Run el flujo?
Las opciones --crash-after y --crash-inside hacen que el worker detenga su propio proceso en un punto concreto, con el código de salida 3, así que la caída es real y siempre la misma. El siguiente Run, sin la opción, reanuda desde el diario.
¿Por qué un segundo Run imprime a veces líneas distintas?
Porque el diario sigue ahí. Reanudar un flujo que ya terminó repite todos los pasos y no hace nada nuevo. Cada Run que empieza un flujo lleva --fresh, que lo olvida primero, así que se puede pulsar otra vez.
¿Qué queda después de detener e iniciar el laboratorio?
Nada. El diario, los pagos y cualquier archivo que escribiera un estudiante se olvidan, y el laboratorio vuelve a escribir sus propios archivos al arrancar. Copia desde el terminal lo que haya que entregar antes de detenerlo.