Alarms: el objeto que se despierta a sí mismo

Hasta ahora un objeto solo actuaba cuando alguien lo llamaba: llegaba una petición, respondía, y volvía a dormir. Las alarmas le dan algo nuevo, casi inquietante: la capacidad de citarse consigo mismo en el futuro. Con setAlarm fija un instante; cuando ese instante llega, la plataforma materializa el objeto —aunque llevara horas dormido y descargado de memoria— e invoca su método alarm. No hace falta un cron externo, ni un proceso vigilando un reloj, ni una cola de trabajos diferidos: el propio objeto es quien recuerda que tenía algo pendiente y quien se despierta para hacerlo.

setAlarm y el manejador alarm

La alarma vive en el mismo almacén durable que el estado. Con state.storage.setAlarm fijas un único instante futuro, expresado en milisegundos desde la época Unix; con getAlarm consultas cuál hay pendiente, y con deleteAlarm la cancelas. Cada objeto tiene como mucho una alarma a la vez: fijar una nueva sustituye a la anterior. Cuando la hora llega, la plataforma invoca el método alarm de la clase, sin petición ni respuesta, igual que un fetch pero disparado por el tiempo y no por un cliente.

export class Recordatorio {
  constructor(private state: DurableObjectState, private env: Env) {}

  async programar(dentroDeMs: number, mensaje: string): Promise<void> {
    await this.state.storage.put("mensaje", mensaje);
    // citate contigo mismo en el futuro
    await this.state.storage.setAlarm(Date.now() + dentroDeMs);
  }

  // la plataforma llama a esto cuando llega la hora, aunque estuvieras dormido
  async alarm(): Promise<void> {
    const mensaje = await this.state.storage.get<string>("mensaje");
    await enviarNotificacion(mensaje ?? "");
  }
}

Observa que el mensaje se guardó en el almacén, no en un campo de memoria. Es deliberado: entre programar y alarm pueden pasar horas, el objeto puede reciclarse y perder todo su estado volátil, y aun así la alarma persiste junto a los datos que necesita. La alarma es durable como el resto del almacén.

Los otros dos métodos completan el juego. Con getAlarm consultas si hay una cita pendiente y a qué hora —devuelve el instante en milisegundos o null—, lo que te permite decidir si programar una nueva o respetar la que ya existe. Con deleteAlarm la cancelas cuando el trabajo que motivaba la cita deja de tener sentido. Entre los tres modelas todo el ciclo de vida de un temporizador: fijar, consultar, cancelar.

// consulta la cita pendiente y cancelala si el trabajo ya no hace falta
const cuando = await this.state.storage.getAlarm(); // instante en ms, o null
if (cuando !== null && this.trabajoYaResuelto) {
  await this.state.storage.deleteAlarm();
}

Durabilidad y reintentos

Una alarma no es un setTimeout de JavaScript, que muere con el proceso. Se persiste en el almacén y sobrevive a desalojos, reinicios y despliegues: si el objeto no está en memoria cuando llega la hora, la plataforma lo trae de vuelta a la existencia solo para ejecutar alarm. Y si el manejador lanza una excepción, no se pierde el evento: la plataforma lo reintenta con retroceso exponencial hasta que termina sin error.

Esa política de reintento tiene una consecuencia que conviene grabar desde ya: la alarma es una entrega al menos una vez, no exactamente una vez. Un fallo tras haber hecho parte del trabajo, o incluso tras haberlo hecho entero pero antes de confirmarlo, provocará una segunda ejecución. Por eso el manejador debe ser idempotente, y el almacén consistente del objeto es justo la herramienta para lograrlo, como vemos a continuación.

Alarmas periodicas por reprogramacion

La API da una sola alarma futura, no un horario que se repite. Para obtener trabajo periódico usas un patrón simple y muy potente: al final de alarm, vuelves a llamar a setAlarm para el siguiente instante. El objeto queda así latiendo por su cuenta, tick tras tick, y cada tick decide cuándo será el próximo.

async alarm(): Promise<void> {
  await this.hacerTrabajoPeriodico();

  const activo = (await this.state.storage.get<boolean>("activo")) ?? true;
  if (activo) {
    // vuelve a citarse: un latido cada minuto
    await this.state.storage.setAlarm(Date.now() + 60_000);
  }
  // si no se reprograma, el objeto vuelve a dormir sin gastar nada
}

Este autolatido tiene una virtud sobre un setInterval: como cada tick decide el siguiente, el intervalo puede cambiar con los datos —más frecuente cuando hay trabajo, más espaciado cuando el objeto está tranquilo— y, sobre todo, sobrevive a que el objeto se descargue entre tick y tick. No hay un temporizador vivo en memoria que un reinicio pueda matar; hay una cita persistida que la plataforma siempre honra.

flowchart LR
M[metodo llama setAlarm t mas 60s] --> P[alarma persistida en el almacen]
P --> W[el objeto duerme y se descarga]
W -.llega la hora.-> A[la plataforma invoca alarm]
A --> WORK[hace el trabajo diferido]
A -.setAlarm de nuevo.-> P
style A fill:#a6e3a1,color:#11111b

La diferencia con un cron global es de naturaleza, no de grado. Un cron vive en la configuración del Worker: es un puñado de horarios fijos, iguales para todos, escritos a mano. Una alarma vive en un objeto: hay una por entidad, se fija en tiempo de ejecución con precisión de milisegundos, y su instante puede depender de los datos de esa entidad concreta. Un cron te da unas pocas citas para todo el sistema; las alarmas te dan millones de temporizadores independientes, uno por cada objeto que los necesite, y solo cuestan cuando disparan.

Un temporizador por entidad

La verdadera potencia no es tener una alarma, sino tener una por objeto, a la escala de tus entidades. Modela un carrito de compra como un objeto: cada vez que el usuario añade algo, empujas hacia delante el instante de expiración; si la hora llega sin más actividad, el carrito se recuerda a sí mismo y avisa. No hay un proceso central escaneando carritos: cada uno lleva su propio temporizador.

export class Carrito {
  constructor(private state: DurableObjectState, private env: Env) {}

  async agregar(item: Item): Promise<void> {
    const items = (await this.state.storage.get<Item[]>("items")) ?? [];
    items.push(item);
    await this.state.storage.put("items", items);
    // reinicia el reloj de abandono: una hora desde el ultimo cambio
    await this.state.storage.setAlarm(Date.now() + 60 * 60 * 1000);
  }

  async alarm(): Promise<void> {
    const items = (await this.state.storage.get<Item[]>("items")) ?? [];
    if (items.length > 0) await recordarCarritoAbandonado(items);
  }
}

Fíjate en lo que no existe aquí: ninguna tabla de carritos que un cron recorra cada minuto preguntando cuáles llevan una hora quietos. Cada carrito porta su propio despertador, reiniciado en cada interacción, dormido y gratis hasta que suena. Multiplica eso por millones de carritos y sigues pagando solo por los que de verdad expiran, no por el barrido constante de todos.