Trabajo en segundo plano: sacar peso del camino crítico

Hay una pregunta que ordena por sí sola la arquitectura de cualquier aplicación seria y que casi nadie se hace de forma explícita: qué tiene que haber terminado antes de responder al usuario. La respuesta honesta suele ser mucho menos de lo que el código hace en realidad. Cuando alguien sube una factura, lo único que debe ser cierto antes del 200 es que la factura está guardada de forma durable; que se haya generado la miniatura, notificado al contable, recalculado el panel y avisado al webhook del cliente no forma parte de la promesa, aunque el código actual lo haga todo en fila antes de contestar. Este nivel trata de esa frontera: cómo se traza, con qué herramienta se cruza y qué precio se paga al cruzarla, porque sacar trabajo del camino crítico no es gratis y quien lo hace sin entender el precio termina con un sistema rápido que a veces cobra dos veces.

Dónde está la frontera

El criterio es una sola pregunta, formulada desde el punto de vista del usuario: si esto no ocurre, ¿mi respuesta se convierte en mentira? Guardar la factura sí, porque si falla y he respondido que se guardó, he mentido. Enviar el correo de confirmación no, porque el correo puede tardar treinta segundos sin que nadie considere rota la promesa. Esa distinción entre lo que constituye la verdad de la respuesta y lo que es consecuencia de ella es más fiable que cualquier heurística sobre duración, y tiene la ventaja de que se puede discutir con producto en lugar de con el equipo de plataforma.

Una vez trazada la frontera aparece la segunda pregunta, que es de qué tipo es el trabajo desplazado. Aquí sí importan la duración, la tolerancia a la pérdida y si el proceso necesita recordar por dónde iba. Las cuatro herramientas responden a combinaciones distintas de esas tres variables y no son intercambiables, aunque las cuatro produzcan el mismo alivio inmediato en el percentil de respuesta.

La confusión más habitual es tratar waitUntil como si fuera una cola. No lo es: es una promesa de que el runtime no matará tu isolate mientras esa tarea siga viva, y nada más. No hay reintento, no hay persistencia, no hay visibilidad. Es perfecta para escribir una métrica o refrescar una entrada de cache, y es una elección negligente para cobrar una tarjeta.

Las cuatro herramientas en código

El productor es siempre trivial y esa es justamente la señal de que la frontera está bien puesta: el handler de la petición hace lo imprescindible, encola un hecho y responde. Fíjate en que lo que se encola es un hecho ocurrido, no una orden pendiente; ese matiz de vocabulario evita la mitad de los acoplamientos futuros.

app.post("/api/facturas", async (c) => {
  const datos = await c.req.json<NuevaFactura>();
  const id = crypto.randomUUID();

  await c.env.DB.prepare("INSERT INTO facturas (id, usuario, total) VALUES (?, ?, ?)")
    .bind(id, c.get("usuario")!.id, datos.total)
    .run();

  await c.env.TAREAS.send(
    { tipo: "factura.emitida", id, usuario: c.get("usuario")!.id },
    { contentType: "json" },
  );

  return c.json({ id }, 201);
});

El consumidor recibe lotes, no mensajes sueltos, y ese detalle cambia su forma. Confirmar o reintentar mensaje a mensaje permite que un fallo aislado no arrastre a sus compañeros de lote, que es exactamente lo que ocurre si dejas que la excepción se propague sin capturar.

export default {
  async queue(lote: MessageBatch<Tarea>, env: Env): Promise<void> {
    for (const mensaje of lote.messages) {
      try {
        await procesar(mensaje.body, env);
        mensaje.ack();
      } catch (error) {
        if (mensaje.attempts >= 3) mensaje.ack();
        else mensaje.retry({ delaySeconds: 2 ** mensaje.attempts * 10 });
      }
    }
  },
};

Cuando el trabajo deja de ser un mensaje y pasa a ser un proceso con varias etapas, esperas largas y necesidad de retomar donde se quedó, la herramienta cambia. Un Workflow no es una cola con esteroides: es una máquina que memoriza el resultado de cada paso, de modo que un reinicio no repite lo ya hecho y una espera de tres días no consume nada mientras tanto.

export class AltaDeCliente extends WorkflowEntrypoint<Env, Alta> {
  async run(evento: WorkflowEvent<Alta>, step: WorkflowStep) {
    const cuenta = await step.do("crear cuenta", async () => crearCuenta(evento.payload));

    await step.do(
      "provisionar recursos",
      { retries: { limit: 5, delay: "10 seconds", backoff: "exponential" } },
      async () => provisionar(cuenta.id, this.env),
    );

    await step.sleep("periodo de prueba", "14 days");
    await step.do("primer cobro", async () => cobrar(cuenta.id, this.env));
  }
}

El impuesto de la idempotencia

Toda entrega con garantía de al menos una vez implica que algún día un mensaje se procesará dos veces, y no por un fallo exótico sino por el funcionamiento normal del sistema: un reintento tras un tiempo de espera agotado en el que la operación sí había terminado. Quien no diseña para eso no tiene un sistema asíncrono, tiene una bomba de relojería con muy buen rendimiento.

flowchart LR
P[peticion del usuario] --> W[worker]
W --> D[d1 escribe lo imprescindible]
W --> R[respuesta inmediata]
W --> Q[queue con el hecho ocurrido]
Q --> C[consumidor por lotes]
C --> M[miniatura en r2]
C --> N[notificacion al tercero]
C --> F[cola de fallidos]
F --> O[panel de revision manual]
style R fill:#a6e3a1,color:#11111b
style F fill:#f38ba8,color:#11111b

Observar lo que ya nadie ve

El coste oculto de sacar trabajo del camino crítico es que desaparece del sitio donde mirabas. Una ruta lenta se nota porque alguien se queja; una cola que crece no la nota nadie hasta que la reserva de mensajes es de horas y un cliente pregunta por qué su informe de ayer sigue sin llegar. Por eso el trabajo diferido exige su propia instrumentación, con cuatro señales que son casi siempre suficientes.

La primera es la profundidad de la cola, que dice si el consumidor sigue el ritmo del productor. La segunda es la edad del mensaje más antiguo sin procesar, que es la métrica que de verdad se corresponde con la experiencia del usuario. La tercera es la tasa de reintentos, que se dispara mucho antes de que nada se rompa del todo y funciona como aviso temprano. Y la cuarta es el tamaño de la cola de fallidos, que nunca debería ser distinto de cero sin que alguien lo sepa. Un sistema que publica esas cuatro cifras es un sistema que puedes desplazar trabajo con confianza; uno que no las publica está acumulando deuda invisible.