Eventos y tareas programadas

Las funciones en el borde no solo responden solicitudes HTTP. También pueden reaccionar a eventos, emitir los suyos y correr en un horario. Con eso se arman flujos del tipo “pedido creado → cobro → envío de comprobante” sin montar una cola propia.

Piezas

Pieza	Qué hace
Evento	Un mensaje con un tipo (pedido.creado), datos en JSON y, opcionalmente, una clave de orden
Suscripción	Asocia un patrón de tipo de evento a una función que lo procesa
Tarea programada	Ejecuta una función según una expresión cron
Ingreso de eventos	Un endpoint en tu propio dominio para que un sistema externo te envíe eventos

Emitir eventos desde una función

export default {
  async fetch(request) {
    const pedido = JSON.parse(request.body);
    Tero.emit("pedido.creado", { id: pedido.id, total: pedido.total }, { partitionKey: pedido.id });
    return new Response("ok", { status: 202 });
  }
};

Un evento emitido por una función puede disparar otras funciones, que a su vez pueden emitir. Las cadenas tienen una profundidad máxima para evitar ciclos.

Suscripciones

Una suscripción se define con un patrón sobre el tipo de evento, separado por puntos:

Patrón	Coincide con
pedido.creado	Solo ese tipo
pedido.*	pedido.creado, pedido.pagado (un nivel)
pedido.**	Cualquier tipo que empiece con pedido., a cualquier profundidad

Modos de entrega

Modo	Garantía	Cuándo usarlo
Duradero	Al menos una vez: el evento se guarda y se reintenta hasta que la función lo acepte	Todo lo que no se puede perder: cobros, comprobantes, altas
Inmediato	Sin persistencia: si la función falla, el evento se pierde	Notificaciones y efectos que se pueden descartar

En el modo duradero, la respuesta de la función decide qué pasa con el evento:

• 2xx: el evento se da por procesado.
• 4xx: el evento se descarta (el error es del evento, reintentar no lo arregla).
• 5xx o error de ejecución: se reintenta con espera creciente, hasta 5 intentos por defecto. Si se agotan, el evento pasa a la bandeja de fallidos, desde donde se puede reintentar a mano.

Orden por clave

Los eventos con la misma clave de orden (partitionKey) se procesan de a uno y en el orden en que se emitieron. Todos los eventos de un mismo pedido llegan en orden, mientras que los de pedidos distintos se procesan en paralelo.

Tu función tiene que tolerar duplicados

La entrega duradera garantiza al menos una vez: ante un corte, un evento puede llegar dos veces. Diseñá los handlers para que procesar dos veces el mismo evento no tenga efecto doble, por ejemplo guardando su identificador.

Tareas programadas

Una tarea programada ejecuta una función según una expresión cron de seis campos, con segundos al principio:

# segundo minuto hora día-del-mes mes día-de-la-semana
0 0 3 * * *        # todos los días a las 03:00:00
0 */15 * * * *     # cada 15 minutos

Las altas y bajas de tareas se aplican sin reiniciar el servicio.

Recibir eventos de sistemas externos

Una ruta puede habilitar el ingreso de eventos: un endpoint en tu propio dominio al que un sistema externo envía eventos, autenticado con un token propio de esa ruta.

POST https://app.miempresa.com/_tero/emit
Authorization: Bearer <token de ingreso de la ruta>
Content-Type: application/json

{ "type": "pago.acreditado", "key": "pedido-1042", "data": { "monto": 1500 } }

Respuesta	Significado
202	Evento aceptado
400	El cuerpo no es un evento válido
401	Token ausente o incorrecto
413	El evento supera el tamaño máximo
429	La cola está llena: reintentá más tarde

El evento queda asociado a la cuenta de la ruta que lo recibió: un emisor externo no puede enviarlo a nombre de otra cuenta. El endpoint pasa además por la limitación de tasa y el WAF de la ruta.

Qué definís

• Suscripciones: patrón, función, modo de entrega y política de reintentos.
• Tareas programadas: expresión cron y función.
• Ingreso de eventos por ruta, con su token.

Límites del modelo

Tero dispara y entrega eventos, pero no es la base de datos de tu negocio. Si un handler tiene que modificar datos de tu aplicación, que llame a tu API. La idempotencia y el orden de negocio (por ejemplo, la numeración de comprobantes) son responsabilidad del handler.