`ctx.waitUntil`: prolongar la vida del evento

Cierras el handler, retornas, y el isolate se apaga: ese es el contrato tácito del edge, tu Worker vive lo justo para hacer su trabajo y desaparece. Pero, ¿qué ocurre con esa promesa que lanzaste y no esperaste —el registro de telemetría, la escritura diferida, la notificación— que aún no ha terminado cuando el handler retorna? Muere con él. ctx.waitUntil es la única forma de decirle al runtime «todavía no me apagues»: le entregas una promesa y él se compromete a mantener el evento vivo hasta que se resuelva. En fetch te deja responder ya y seguir trabajando en segundo plano; en scheduled, donde no hay respuesta que devolver, es lo que separa el trabajo que se completa del que se trunca a medias.

La promesa huérfana

El modelo del edge es implacable con el tiempo: un isolate se materializa para atender un evento y se descarta en cuanto ese evento concluye. El runtime considera concluido el evento cuando la promesa que devuelve tu handler se resuelve. Todo lo que quede pendiente y no esté enganchado a esa promesa se queda huérfano —no se rechaza, simplemente se congela— y su continuación puede no ejecutarse jamás.

export default {
  async scheduled(controller, env, ctx) {
    // MAL: promesa suelta, nadie la espera
    registrarMetrica(env, "cron-ok"); // devuelve una Promise ignorada
  },
};

El handler es async, pero retorna de inmediato tras disparar registrarMetrica sin aguardarla. Su promesa se resuelve, el runtime da por terminado el evento y el fetch o el put que vivían dentro de esa métrica pueden no completarse nunca. En un servidor de Node tradicional este «dispara y olvida» suele funcionar porque el proceso permanece vivo y absorbe el trabajo pendiente. En el edge el proceso es tu isolate, y se evapora. Lo insidioso es que en local, con wrangler dev, muchas veces sí termina —el servidor de desarrollo tarda más en apagarse— y llegas a producción convencido de que funciona. El fallo aflora solo bajo la disciplina real del runtime, cuando el isolate se descarta en cuanto tu handler retorna: entonces el trabajo huérfano se pierde de forma intermitente y dificilísima de reproducir.

waitUntil: el runtime se compromete a esperar

ctx.waitUntil recibe una promesa y la registra en el ExecutionContext. A partir de ahí, el runtime extiende la vida del evento hasta que esa promesa —y el propio handler— se asienten. Es la diferencia entre trabajo huérfano y trabajo garantizado.

export default {
  async scheduled(controller, env, ctx) {
    ctx.waitUntil(registrarMetrica(env, "cron-ok"));
  },
};

Puedes llamarlo tantas veces como quieras; cada promesa entregada se rastrea por separado. No devuelve nada útil y no lo esperas: aguardarlo anularía su propósito. En fetch esto habilita el patrón canónico —responder ya y seguir después—:

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const res = new Response("ok");
    ctx.waitUntil(auditar(env, request)); // sigue tras responder
    return res; // el cliente recibe la respuesta de inmediato
  },
};

Nada te obliga a un solo waitUntil: puedes registrar varias promesas —el runtime las rastrea todas— o agrupar el trabajo de fondo en una sola con Promise.all cuando quieres tratarlo como una unidad con un único punto de fallo.

ctx.waitUntil(
  Promise.all([
    auditar(env, request),
    invalidarCache(env),
    notificar(env),
  ]).catch((e) => console.error("trabajo de fondo fallo", e)),
);

flowchart LR
Trabajo[lanzas trabajo asincrono] --> WU[ctx.waitUntil lo registra]
WU --> Retorna[el handler retorna]
Retorna --> Espera[el runtime mantiene vivo el isolate]
Espera --> Fin[la promesa se resuelve y el isolate se descarta]

Visualmente, el patrón es una promesa que sobrevive al return: el handler ya retornó, pero el evento sigue vivo porque tú lo pediste, y solo entonces el isolate se apaga.

Conviene fijar la intuición correcta: waitUntil no lanza el trabajo —eso ya lo hiciste tú al invocar la función asíncrona—, solo le pide al runtime que no dé el evento por cerrado hasta que esa promesa se asiente. Es una declaración de pendientes, no un planificador de tareas.

await o waitUntil: cuándo cada uno

No compiten: cooperan. La regla es la dependencia. Si el paso siguiente necesita el resultado, lo esperas; si el trabajo es un satélite independiente cuyo desenlace te importa pero cuyo valor no consumes, lo entregas a waitUntil.

Así, un scheduled maduro suele hacer su trabajo esencial con await —porque debe terminar y porque los pasos se encadenan— y despacha lo accesorio con ctx.waitUntil, dejando que el runtime cargue con la espera de esos satélites sin frenar el hilo central.

async scheduled(controller, env, ctx) {
  const resumen = await procesarLote(env);       // esencial: se espera
  ctx.waitUntil(publicarMetricas(env, resumen)); // accesorio: en paralelo
}

El resultado es un handler que hace lo justo en su camino crítico y confía al runtime la finalización de todo lo demás: veloz donde importa, completo donde hace falta.

El techo de los quince minutos

Ese compromiso del runtime no es infinito. Toda invocación —lo que devuelve tu handler más todo lo registrado en waitUntil— consume del mismo presupuesto, y conviene distinguir dos relojes. El tiempo de CPU mide solo el cómputo activo; lo configuras con limits.cpu_ms y se agota en segundos o pocos minutos. El tiempo de reloj mide el total, incluidas las esperas de red a una API, a D1 o a KV, y para una invocación de scheduled ronda un techo de quince minutos que tú no fijas.

{
  "limits": { "cpu_ms": 300000 } // 5 min de CPU; el reloj sigue topado aparte
}

Un cron que pasa el noventa por ciento del tiempo esperando respuestas de red gasta muy poca CPU, pero puede acercarse peligrosamente al techo de reloj. Cuando la promesa registrada no se resuelve dentro de ese margen, el runtime corta la invocación y el trabajo pendiente se pierde. La consecuencia de diseño es directa: el cron sirve para lotes acotados; si el trabajo pudiera exceder los quince minutos, hay que trocearlo —paginar, encolar en Queues, o delegar en un Workflow—, tema que retomamos al elegir entre Workflow, Queue o cron. Y como el corte es abrupto y sin aviso, el diseño prudente asume que puede ocurrir: haz el trabajo idempotente y guarda tu avance —un cursor en KV o D1— para que la siguiente ejecución retome donde la anterior quedó, en lugar de empezar de cero o, peor aún, dejar el estado a medio escribir.

Un ejemplo aclara la distinción entre los dos relojes: si tu handler consume diez segundos de CPU pero espera catorce minutos a que una API lenta conteste, subir cpu_ms no te salva —el problema no es el cómputo, es el reloj de pared—; lo que te salva es partir el trabajo en piezas que quepan holgadas bajo el techo.