Trabajos durables y readiness

Sincronizado con el commit 2a1a04a del starter.

Usa esta página cuando un trabajo deba terminar aunque la petición del navegador ya haya respondido: enviar correo, conceder créditos, borrar un objeto o completar una solicitud de privacidad. El starter incluye una cola ligera sobre PostgreSQL, suficiente para que muchos equipos lancen sin operar una cola Redis ni un servicio worker independiente.

Decide cómo ejecutar y vigilar el trabajo en segundo plano

• En Vercel conserva el cron incluido de cinco minutos. En otro proveedor, llama al mismo endpoint autenticado desde su programador.
• Mantén la cola PostgreSQL mientras el volumen sea moderado y cada trabajo quepa en el presupuesto de 20 segundos. Migra cargas largas o de alto rendimiento solo cuando lo exijan, conservando deduplicación e idempotencia.
• /api/health responde “el proceso contesta”; /api/ready responde “esta versión puede recibir tráfico de producción”. No son intercambiables.

Está listo para producción cuando: un trabajo de prueba se procesa; un fallo forzado reintenta y se hace visible; dos ejecuciones cron solapadas no duplican el efecto; y tus alertas detectan readiness fallido y una cola de fallos creciente.

Por qué el trabajo se persiste

Una instancia serverless puede congelarse al devolver la respuesta. El trabajo que debe completarse—emails, créditos, borrado de objetos, exportación y eliminación de cuentas—se escribe en jobs, no en promesas sin esperar.

Los tipos actuales cubren emails, invitaciones, créditos de alta, Slack, eliminación de almacenamiento, reservas y ciclo de vida de cuenta.

Encolar

await enqueueJob("welcome_email", { email, name, userUuid }, {
  dedupeKey: `welcome:${userUuid}`,
  subjectUserUuid: userUuid
});

dedupeKey hace idempotente el alta. Los UUID de sujeto permiten cancelar o limpiar trabajos durante un proceso de privacidad. Los handlers también deben ser idempotentes.

Elige un runner predeterminado

La página admin /jobs muestra estado, intentos, antigüedad, sujeto y error seguro sin exponer payload JSON. admin_rw puede reintentar jobs idempotentes fallidos o cancelar notificaciones pendientes con nota auditada; créditos, storage, lifecycle y campañas se cancelan desde su workflow.

Ejecución

GET /api/cron/jobs exige Authorization: Bearer $CRON_SECRET. Vercel lo llama cada cinco minutos; fuera de Vercel debes programarlo.

El runner reclama un trabajo con FOR UPDATE SKIP LOCKED, permite llamadas solapadas, usa leases de cinco minutos, limita cada handler a 20 segundos y el drenaje a 40, reintenta cinco veces por defecto con backoff desde 30 segundos y conserva resultados 14 días. También limpia subidas incompletas y eventos Stripe atascados.

Vida y preparación

/api/health es una sonda barata del proceso. /api/ready verifica configuración, base de datos y migraciones, Redis distribuido y salud de la cola. Un fallo crítico devuelve 503; una cola degradada se informa sin retirar la web del servicio.

Usa health para sondeos frecuentes y ready antes de enviar tráfico a una versión nueva. Alerta por readiness no-200 y por crecimiento de trabajos fallidos. Mantén los payloads compatibles hacia atrás.

Antes de programar cron y enrutar tráfico: completa Despliegue y seguridad.