📖 Cómo funciona el Jobber

Servicio interno que ejecuta los jobs programados (cron jobs HTTP) de todos los proyectos.

Qué es

Un scheduler central: en vez de que cada proyecto maneje sus propios cron jobs, todos se registran acá y el Jobber los dispara por HTTP a la hora indicada. Cada ejecución queda registrada (éxito, error, duración) y si un job falla se avisa por correo.

• Los jobs viven en la base de datos (no en memoria): sobreviven reinicios y no se duplican.
• Reintenta 3 veces con backoff; cualquier respuesta que no sea 2xx cuenta como fallo.
• El historial de cada job se guarda 60 días.

El panel

• Proyectos: cada uno agrupa sus jobs. La columna Fallando (en rojo) te dice dónde mirar.
• Dentro de un proyecto: buscar por nombre/URL/descripción y filtrar por estado (Con error / OK / Pausados).
• Por cada job: ver historial, ejecutar ahora, pausar, editar, borrar y mover a otro proyecto.
• La URL refleja dónde estás (proyecto, filtro, búsqueda): al refrescar o compartir el link se conserva la vista.
• Los jobs con la etiqueta manifest vienen del jobs.json del repo y no se editan acá (su fuente de verdad es ese archivo; una edición manual la revierte el próximo sync).

Integrar un proyecto (modelo declarativo)

Cada proyecto declara sus jobs en un archivo jobs.json en su repo. El Jobber lo lee cada 30 minutos y se sincroniza solo (o al instante con el botón “Sincronizar manifests”): crea lo nuevo, actualiza lo cambiado, elimina lo que ya no está. Agregar o cambiar un job = editar ese archivo y deployar.

Son 2 pasos, una sola vez por proyecto:

1. El repo sirve su jobs.json en GET /.well-known/jobs.json, protegido con un secreto (x-job-secret).
2. Se registra el proyecto en el Jobber con esa URL y el secreto (hoy se hace por base de datos — ver el runbook técnico del repo job-backend).

Formato del jobs.json

{
  "baseUrl": "https://api.miproyecto.cl",
  "defaults": { "method": "POST", "timezone": "America/Santiago" },
  "jobs": [
    { "name": "sync-catalogo", "schedule": "0 3 * * *", "path": "/catalog/sync" },
    { "name": "reporte", "schedule": "0 9 * * 1", "path": "/reportes/semanal", "timeoutMs": 600000 }
  ]
}

name	Obligatorio. Identidad del job dentro del proyecto.
schedule o runAt	Cron (5–6 campos) o fecha ISO para una sola vez.
url o path	URL absoluta, o path relativo al baseUrl.
timeoutMs	Timeout por intento (para jobs lentos, hasta 15 min).
enabled	false pausa el job conservando su historial.

Los secretos no van en el jobs.json (es del repo): viven en el registro del proyecto en el Jobber, que los envía al leer el manifest y en cada ejecución.

Alertas

Cuando un job agota sus 3 intentos, llega un correo con el proyecto, el job, la URL y el error. También se avisa si el manifest de un proyecto deja de poder leerse (y cuando se recupera).

Estados de un job

• ✓ última corrida OK · ✗ última corrida falló · … aún no corre.
• La columna 24 h muestra éxitos/fallos del último día; Próxima, cuándo corre de nuevo.
• 401 en el historial = el endpoint exige el secreto y el job no lo manda (o está mal). 404 = revisar el prefijo /api.

Runbook técnico completo (operaciones por base de datos, config, troubleshooting): job-backend/docs/RUNBOOK.md en el repositorio.