Trabajos durables y readiness

Opera la cola PostgreSQL, cron, reintentos, deduplicación y sondas de vida y preparación de dependencias.

Sincronizado con el commit e632762 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 usa el cron autenticado de cinco minutos; en VM, contenedores o Kubernetes usa el worker incluido. Un programador también puede ejecutar pnpm jobs:run --production una sola vez.
Mantén PostgreSQL mientras el volumen sea moderado. Worker y cron comparten reclamación, reintentos, mantenimiento y observabilidad. El worker permite configurar JOB_WORKER_HANDLER_TIMEOUT_MS y JOB_WORKER_DRAIN_DEADLINE_MS, con valores predeterminados de 20 y 40 segundos. Un presupuesto mayor exige probar la cancelación y mantenerse por debajo del lease de cinco minutos. Usar el worker no requiere cambiar el almacenamiento de la cola.
/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, ciclo de vida de cuenta, entrega de campañas de marketing y el flujo de imagen por cinco créditos.

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

Entorno	Recomendación
Local	`pnpm dev:all` inicia `pnpm jobs:work`
VM/contenedor/Kubernetes	`pnpm jobs:work --production`
Scheduler	`pnpm jobs:run --production`
Vercel	`/api/cron/jobs` autenticado

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.