Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 05

Cron, jobs y workers

Tres formas de hacer trabajar al sistema cuando nadie está mirando: un cron HTTP, una cola de jobs interna, un proceso de larga duración. Sirven para cosas distintas, y elegir el equivocado se paga.

1. Cuál de los tres

NecesidadHerramientaPor qué
"cada N minutos haz X"cron HTTP (§2)no requiere acceso shell: funciona en cualquier hosting con programador curl
"haz X, pero no ahora y no delante del usuario"cola de jobs (§4) o Jobs::asyncel usuario no espera; el efecto llega poco después
"estate siempre a la escucha / consulta un servicio externo con cadencia inferior al minuto"worker CLI (§5)el cron tiene granularidad de 1 minuto y paga el bootstrap en cada vuelta

Regla práctica: empezar por el cron. Un worker es un servicio que hay que instalar, vigilar y reiniciar; se introduce cuando el cron demuestra que no basta, no antes.

2. Cron HTTP: un job es una página

Los jobs programados son páginas como las demás (ver 02 §1):

contents/cronjob/<nombre>.php    →    GET /cronjob/<nombre>?key=<secret>

La carpeta contents/cronjob/ ya existe en el repo, vacía: es el lugar previsto.

Patrón para replicar:

<?php
use_cache(false);

// 1 — SECRET: el job es alcanzable por HTTP, así que por cualquiera
$cronSecret = (string) (defined("JC_CRON_SECRET") ? JC_CRON_SECRET : "");
if ($cronSecret === "" || !hash_equals($cronSecret, (string)($_GET["key"] ?? ""))) {
    http_response_code(403); echo "forbidden"; exit;
}

$db = ffDB_Sql::factory();

// 2 — LOCK: dos ejecuciones solapadas son la norma, no la excepción
$db->query("SELECT GET_LOCK('jc_coda', 0) AS l");
$db->nextRecord();
if ((int)$db->getField("l", "Number", true) !== 1) { echo "busy"; exit; }

try {
    // 3 — BATCH limitado: nunca "todo lo que hay"
    $limite = 200;
    // ... trabajo ...

    // 4 — LOG del resultado
    // INSERT INTO cm_jc_cron_log (job, esito, elementi, eseguito_il) VALUES (...)
} finally {
    $db->query("SELECT RELEASE_LOCK('jc_coda')");
}

echo "ok";
exit;

Las cuatro protecciones, y por qué

  1. Secret en la query string comparado con hash_equals. Un job sin secret es un endpoint de escritura público.
  2. GET_LOCK de MySQL con timeout 0. Si la vuelta anterior no ha terminado, la nueva sale enseguida en lugar de duplicar el trabajo. Un lock por job, no uno global: jobs distintos no deben competir.
  3. Batch limitado con LIMIT. Un job que intenta despachar todo el atraso entra en timeout, y el timeout lo deja a medias. Mejor N vueltas cortas.
  4. Log en tabla con resultado y recuento. Sin él, a la pregunta "¿el cron está funcionando?" no se sabe responder. SELECT * FROM <tabla_log> ORDER BY ID DESC LIMIT 20 debe bastar.

Otros trucos que se aprenden en producción

  • Salto explícito si la migración no está aplicada. Un job que funciona sobre un esquema viejo debe salir con "migración ausente", no caer en fatal cada minuto.
  • Degradar, no bloquear. Si un proveedor externo no responde, se registra y se reintenta en la vuelta siguiente.
  • Horas de silencio, si el job envía comunicaciones: no enviar a las 3 de la madrugada.
  • Interruptor de apagado en la configuración (abilitato on/off), que no requiera un despliegue.
  • Idempotencia: el job puede volver a ejecutarse sobre el mismo intervalo (reinicio, doble programación, reintento del programador). Un registro antiduplicados (una fila por (destinatario, tipo, periodo) con clave única) es más fiable que un "contar y comparar".

Programar

Desde el panel del hosting (cron vía curl):

*/5 * * * *  curl -fsS "https://TU-DOMINIO/cronjob/<nombre>?key=<secret>" > /dev/null

Documentar en una tabla, en el repo, qué jobs existen, con qué frecuencia y qué pasa si no se ejecutan: es la información que hace falta el día de la mudanza a otro hosting.

JobObjetivoFrecuenciaSi no se ejecuta
(ninguno en el repo base)

3. Los jobs de sistema heredados

conf/gallery/job/ contiene cuatro jobs del upstream VGallery:

JobQué haceEstado
pingnotifica a los buscadores la sitemap actualizadalegacy: bastantes de los servicios notificados ya no existen
updateconsulta el actualizador remotoinerte: MASTER_SITE está neutralizada
diagnosticverifica caché, diccionario, config, uploads, miniaturasútil como control manual
reset_cartslimpieza de carritos abandonadosrelevante solo con e-commerce activo

No están programados por defecto y escriben su resultado como notificación de backend (write_notification). Existe también un mecanismo de autoload por convención: check_function("job_<nombre>") carga library/gallery/job/<nombre>.php o bien modules/<modulo>/library/job/<nombre>.php (library/gallery/common.php, líneas ~138-146).

4. La cola de jobs interna (Jobs)

vendor/hcore/jobs/Jobs.php implementa una cola persistente con programación y repetición.

Jobs::getInstance()->add($source, $params, $schedule, $repeat, $priority);
Jobs::getInstance()->run();          // ejecuta los jobs pendientes
Jobs::getInstance()->ps();           // estado de la cola
Jobs::getInstance()->forceRun($kid); // fuerza un job
Jobs::setScript($callback, $schedule, $repeat);

Ejecutores por tipo: API interna, servicio, petición HTTP, script, función, objeto (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj).

Guardas en la clase: SOCKET = 10, TIMEOUT = 60, ANTIFLOOD = 4 segundos entre dos ejecuciones, DELAY_SCHEDULE = 3600 para reprogramar tras un error, REPEAT = "1week".

Y la primitiva fire-and-forget:

Jobs::async("/api/cache/refresh", array("url" => $_SERVER["HTTP_REFERER"]));

abre un socket hacia su propio host, escribe la petición y no espera la respuesta. En el repo la usan library/gallery/system/trace.php y el bus de servicios (ver 03 §4).

Cuándo usarla y cuándo no. Jobs::async es perfecta para "refresca la caché después de haber respondido". Para el trabajo que debe hacerse — envíos, cargos, notificaciones — hace falta algo que deje rastro y se pueda reintentar: la cola persistente, o una tabla de cola propia despachada por un cron. El socket fire-and-forget no garantiza nada: si el proceso llamado muere, nadie se da cuenta.

Está también library/rabbitMQ/ entre las librerías: broker externo, no conectado en este repo. Un proyecto que lo necesite de verdad lo engancha, pero para la gran mayoría de los casos una tabla de cola + cron es más sencilla de gestionar y más fácil de inspeccionar.

5. Worker de larga duración (CLI)

Cuando hace falta una cadencia inferior al minuto, o un estado en memoria entre una vuelta y otra, se sale de la web: un script PHP en bin/ arrancado por systemd (o por un cron de reserva).

Lecciones que valen para cualquier worker en este stack:

  • Un bootstrap CLI dedicado. Desde línea de comandos el ciclo de página no se ejecuta: las clases llegan del autoloader, pero las funciones de ff/common.php (ffCommon_dirname, ffCommon_jsonenc) no. Hay que incluirlas explícitamente. No se incluye library/gallery/common.php, que presupone una instancia de cm.
  • HTTP_HOST debe prepararse antes de config.php: es él quien decide si cargar config.local.php o config.remote.php, y medio framework lee $_SERVER sin verificar las claves.
  • FF_DISK_PATH es la ruta del servidor. El instalador escribe ahí /var/www/…, que en local no existe: un worker que construye rutas sobre esa constante falla fuera del servidor. Mejor una constante propia obtenida de __DIR__, preferida cuando existe.
  • Cargar solo el módulo que hace falta: los demás enganchan eventos al ciclo de página y desde CLI no encuentran un cm al que engancharse.
  • Las cachés estáticas deben descartarse periódicamente. Las clases de configuración están pensadas para la duración de una petición HTTP: en un proceso que vive una hora se quedarían congeladas en el valor leído al arrancar, y cambiar un umbral desde el backend no tendría efecto.
  • El worker sale por sí mismo tras un tiempo máximo (p. ej. una hora) y Restart=always lo vuelve a levantar. Una salida con código 0 cada hora es el comportamiento previsto: es la forma más sencilla de no tener un problema de memoria dentro de dos meses en un proceso PHP de larga duración.
  • No se ejecuta como root: necesita leer config.remote.php (0640, del usuario del sitio). Ejecutarlo como ese usuario hace cuadrar los permisos sin ampliarlos.
  • Reserva cron idéntica en el código: --durata=55 más flock -n. flock es la parte que cuenta: dos workers en paralelo duplican las llamadas.

Si el worker mantiene un estado leído por el front-end (caché de estado en tabla), dos trucos se amortizan enseguida:

  • latido y lectura en la misma llamada: un único endpoint que dice "esta pantalla está abierta" y devuelve el estado. Separarlos es el doble de tráfico para la misma información;
  • devolver siempre letto_il + ora_server: sin saber cuándo se ha leído, un dato de tres segundos antes es inutilizable para un cliente que debe interpolar.

6. Mantenimiento: qué se poda y qué no

Un sistema que funciona acumula. Merece la pena tener un job de mantenimiento que pode, con criterio:

  • se podan los logs de aplicación (desde el final, conservando las últimas N filas), los estados temporales caducados, los tokens OAuth caducados, las cachés de contenidos externos;
  • no se podan los registros antiduplicados (un email_log no es un histórico: es lo que impide volver a enviar la misma comunicación), las auditorías de movimientos y pagos, las filas a las que apunta otra tabla;
  • no se cierran de oficio los objetos en estado intermedio (pedidos abandonados, borradores): se cuentan y se muestran. La decisión es de quien gestiona, no del job.

⚠️ AUTO_INCREMENT: borrar filas no hace retroceder el contador. Una prueba que crea y borra mil filas deja el próximo ID en 1001. No es un problema, pero es una pregunta que tarde o temprano llega.