El `scheduled` handler: un Worker sin cliente

Un Worker que ya conoces es reactivo: duerme hasta que alguien llama a su puerta con una Request, y su vida entera consiste en devolver una Response. Pero existe una segunda puerta, y no la abre un cliente: la abre el reloj de Cloudflare. El scheduled handler es la función que la plataforma invoca cuando un cron trigger se dispara —sin petición que atender y sin respuesta que devolver—. Entenderlo como el gemelo de fetch es aceptar que un Worker también puede ser un sujeto que actúa por su cuenta, no solo un objeto al que se le pide algo.

Un evento que nadie pide

El runtime invoca fetch una vez por cada petición HTTP: hay un cliente al otro lado esperando bytes. El scheduled handler rompe esa premisa. Lo invoca el programador interno de Cloudflare cuando llega la hora marcada por un cron trigger, y no hay ningún cliente: no recibes una Request y no devuelves una Response. Su tipo de retorno es Promise<void>, porque no hay nadie a quien contestar.

export default {
  async scheduled(controller, env, ctx) {
    console.log("cron procesado");
  },
};

Ese handler mínimo ya es un Worker de cron completo. Fíjate en lo que no hay: ni request, ni un new Response(...), ni un valor de vuelta. La plataforma no juzga el éxito por lo que devuelves —no devuelves nada—, sino por si tu handler y sus promesas se resuelven o lanzan una excepción.

La firma, campo por campo

Escrita con todos sus tipos, la firma revela tres argumentos, los mismos tres que ya viste en un fetch moderno pero con el primero cambiado:

export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<void> {
    const cuando = new Date(controller.scheduledTime);
    console.log(`disparado por ${controller.cron} el ${cuando.toISOString()}`);
  },
} satisfies ExportedHandler<Env>;

Donde fetch recibía una Request, scheduled recibe un ScheduledController: el objeto que describe el evento de reloj. Sus campos son pocos y precisos.

fetch y scheduled en el mismo Worker

Un mismo Worker puede exportar los dos handlers a la vez: mismo archivo, mismo modelo de isolate, mismos bindings, dos puntos de entrada. También puede exportar solo scheduled —un Worker de fondo sin superficie HTTP—; en ese caso, una petición web no encuentra fetch que la atienda y termina en error.

export default {
  async fetch(request, env, ctx): Promise<Response> {
    return new Response("sirvo HTTP");
  },
  async scheduled(controller, env, ctx): Promise<void> {
    // corro en el horario, sin nadie que pida nada
    await env.KV.put("ultimo-cron", new Date().toISOString());
  },
};

Cuando varios horarios apuntan al mismo Worker, todos invocan la misma función scheduled. Para ejecutar lógica distinta según el que se disparó, ramificas con controller.cron:

async scheduled(controller, env, ctx) {
  switch (controller.cron) {
    case "*/5 * * * *":
      await sincronizar(env);
      break;
    case "0 0 * * *":
      await limpiezaDiaria(env);
      break;
  }
}

flowchart TB
Cliente -->|Request| Fetch[handler fetch]
Fetch -->|Response| Cliente
Reloj[programador de Cloudflare] -->|cron dispara| Scheduled[handler scheduled]
Scheduled -->|sin respuesta| Fin[trabajo terminado]

Los dos handlers comparten la naturaleza del Worker —una función en el edge, efímera y sin estado entre invocaciones— pero difieren en su causa: a fetch lo causa un usuario, a scheduled lo causa el tiempo.