# ADR 0003: Calificar fuera de la API, con una tabla de trabajos y workers

## Contexto

Reemplaza al ADR 0001. Desde el piloto cambiaron tres cosas. Yupana se usa en
6 cursos, con tareas de hasta 300 estudiantes. Las tareas de Algoritmos
tienen casos de prueba grandes, y calificar un envío tarda en promedio 12 s.
Y en los cierres la aplicación entera se vuelve lenta, porque la API compite
por los 4 núcleos con los compiladores y con los programas de los
estudiantes: es la consecuencia mala que el ADR 0001 dejó anotada.

El equipo sigue siendo de dos personas a tiempo parcial, y el servidor sigue
siendo una máquina virtual de la facultad.

**Escenario:** en los 30 minutos antes de un cierre llegan 600 envíos (20 por
minuto) que tardan en promedio 12 s en calificarse; la API confirma cada
envío en 1 s o menos (p95), el veredicto aparece en 2 min o menos (p95) y no
se pierde ningún envío.

A ese ritmo llegan 240 s de trabajo de calificación por cada minuto de reloj:
cuatro procesadores ocupados todo el tiempo, sin contar la API ni la base de
datos.

## Alternativas consideradas

### A. Seguir calificando en la API, con un tope de calificaciones a la vez

- **Gana:** no cambia la estructura del sistema, y el tope protege a los
  demás pedidos.
- **Cuesta:** cuando el tope se alcanza, cada envío espera su turno con la
  conexión HTTP abierta: la confirmación tarda lo que tarde la cola.
- **Por qué no:** el escenario pide confirmar en 1 s, y aquí confirmar y
  calificar son la misma respuesta.

### B. Tabla de trabajos en PostgreSQL y workers que la consultan

- **Gana:** confirmar un envío es insertar su fila y su trabajo, en la
  transacción que ya decidió el ADR 0002. La calificación sale del proceso de
  la API. Se agregan workers sin tocar la API. No agrega infraestructura.
- **Cuesta:** cada worker pregunta cada 2 s si hay trabajo: hasta 2 s de
  demora por envío y consultas constantes a la base de datos. La aplicación
  web tiene que volver a preguntar por el veredicto. Y una tabla usada como
  cola necesita reglas que hay que escribir: quién toma cada trabajo, qué
  pasa con uno que quedó a medias, en qué orden se atienden.

### C. Un broker de mensajes (NATS JetStream) y workers suscritos

- **Gana:** el broker entrega cada trabajo a un worker sin consultas
  periódicas, y vuelve a entregar el que no fue confirmado.
- **Cuesta:** un servicio más que instalar, vigilar y respaldar. Y el envío
  (en PostgreSQL) y su mensaje (en el broker) ya no se escriben en una
  transacción: un reinicio entre los dos deja un envío confirmado que nadie
  va a calificar.
- **Por qué no:** frente a una medida de 2 min, los 2 s de la consulta
  periódica no importan; el servicio adicional y la escritura en dos lugares
  sí, para un equipo de dos personas.

## Decisión

- **Alternativa elegida:** B

Vamos a separar recibir de calificar. La API guarda el envío y un trabajo
pendiente en una transacción y responde. Los workers de calificación son
procesos aparte: cada uno toma un trabajo pendiente, lo marca como suyo en
una transacción para que ningún otro lo tome, lo califica dentro del sandbox
y anota el veredicto.

Cuántos workers corren es configuración del despliegue y no forma parte de
esta decisión. Vamos a revisarla si la medida del veredicto baja de 2 min a
pocos segundos, o si el equipo llega a operar un broker por otra razón.

## Estado

Aceptado

## Consecuencias

- **Buena:** confirmar un envío ya no depende de cuánto tarde calificarlo.
- **Buena:** el código de los estudiantes ya no se ejecuta como hijo del
  proceso de la API.
- **Mala:** aparecen los estados "pendiente" y "en calificación". La
  aplicación web tiene que mostrarlos y preguntar por el veredicto.
- **Mala:** la tabla de trabajos trae decisiones que antes no existían y que
  este ADR no toma: cuántos workers, qué se hace con un trabajo que un worker
  tomó y no terminó, y si todos los trabajos valen lo mismo.
- **Neutra:** los workers necesitan una conexión a la base de datos para
  tomar trabajos, leer el código y anotar veredictos.
