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
| Necesidad | Herramienta | Por 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::async | el 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é
- Secret en la query string comparado con
hash_equals. Un job sin secret es un endpoint de escritura público. GET_LOCKde MySQL con timeout0. 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.- 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. - 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 20debe 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 (
abilitatoon/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.
| Job | Objetivo | Frecuencia | Si no se ejecuta |
|---|---|---|---|
| (ninguno en el repo base) |
3. Los jobs de sistema heredados
conf/gallery/job/ contiene cuatro jobs del upstream VGallery:
| Job | Qué hace | Estado |
|---|---|---|
ping | notifica a los buscadores la sitemap actualizada | legacy: bastantes de los servicios notificados ya no existen |
update | consulta el actualizador remoto | inerte: MASTER_SITE está neutralizada |
diagnostic | verifica caché, diccionario, config, uploads, miniaturas | útil como control manual |
reset_carts | limpieza de carritos abandonados | relevante 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::asynces 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 incluyelibrary/gallery/common.php, que presupone una instancia decm. HTTP_HOSTdebe prepararse antes deconfig.php: es él quien decide si cargarconfig.local.phpoconfig.remote.php, y medio framework lee$_SERVERsin verificar las claves.FF_DISK_PATHes 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
cmal 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=alwayslo 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=55másflock -n.flockes 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_logno 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.