Cron, jobs et workers
Trois façons de faire travailler le système quand personne ne regarde : un cron HTTP, une file de jobs interne, un processus longue durée. Ils servent à des choses différentes, et choisir le mauvais se paie.
1. Lequel des trois
| Besoin | Outil | Pourquoi |
|---|---|---|
| « toutes les N minutes, fais X » | cron HTTP (§2) | ne demande pas d'accès shell : fonctionne sur n'importe quel hébergement avec un planificateur curl |
| « fais X, mais pas maintenant et pas devant l'utilisateur » | file de jobs (§4) ou Jobs::async | l'utilisateur n'attend pas ; l'effet arrive peu après |
| « reste toujours à l'écoute / interroge un service externe à une cadence inférieure à la minute » | worker CLI (§5) | le cron a une granularité d'1 minute et paie le bootstrap à chaque passage |
Règle pratique : partir du cron. Un worker est un service à installer, surveiller et redémarrer ; on l'introduit quand le cron montre qu'il ne suffit pas, pas avant.
2. Cron HTTP : un job est une page
Les jobs planifiés sont des pages comme les autres (voir 02 §1) :
contents/cronjob/<nom>.php → GET /cronjob/<nom>?key=<secret>
Le dossier contents/cronjob/ existe déjà dans le dépôt, vide : c'est l'endroit prévu.
Modèle à reproduire :
<?php
use_cache(false);
// 1 — SECRET : le job est accessible en HTTP, donc par n'importe qui
$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 : deux exécutions qui se chevauchent sont la norme, pas l'exception
$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 limité : jamais « tout ce qu'il y a »
$limite = 200;
// ... travail ...
// 4 — LOG du résultat
// INSERT INTO cm_jc_cron_log (job, esito, elementi, eseguito_il) VALUES (...)
} finally {
$db->query("SELECT RELEASE_LOCK('jc_coda')");
}
echo "ok";
exit;
Les quatre protections, et pourquoi
- Secret dans la query string comparé avec
hash_equals. Un job sans secret est un endpoint d'écriture public. GET_LOCKMySQL avec timeout0. Si le passage précédent n'a pas fini, le nouveau sort tout de suite au lieu de doubler le travail. Un lock par job, pas un global : des jobs différents ne doivent pas se disputer.- Batch limité avec
LIMIT. Un job qui essaie d'écouler tout l'arriéré part en timeout, et le timeout le laisse à moitié. Mieux vaut N passages courts. - Log en table avec résultat et comptage. Sans lui, on ne sait pas répondre à « le cron tourne-t-il ? ».
SELECT * FROM <table_log> ORDER BY ID DESC LIMIT 20doit suffire.
D'autres astuces qu'on apprend en exploitation
- Saut explicite si la migration n'est pas appliquée. Un job qui tourne sur un vieux schéma doit sortir avec « migration manquante », pas tomber en fatal chaque minute.
- Dégrader, ne pas bloquer. Si un fournisseur externe ne répond pas, on journalise et on réessaie au passage suivant.
- Heures calmes, si le job envoie des communications : ne pas envoyer à 3 heures du matin.
- Interrupteur d'arrêt dans la configuration (
abilitatoon/off), qui ne demande pas de déploiement. - Idempotence : le job peut être réexécuté sur le même intervalle (redémarrage, double planification, nouvelle tentative du planificateur). Un registre anti-doublon (une ligne par
(destinataire, type, période)avec clé unique) est plus fiable qu'un « compter et comparer ».
Planifier
Depuis le panneau de l'hébergement (cron via curl) :
*/5 * * * * curl -fsS "https://VOTRE-DOMAINE/cronjob/<nom>?key=<secret>" > /dev/null
Documenter dans un tableau, dans le dépôt, quels jobs existent, à quelle fréquence et ce qui se passe s'ils ne tournent pas : c'est l'information qu'il faut le jour du déménagement vers un autre hébergement.
| Job | But | Fréquence | S'il ne tourne pas |
|---|---|---|---|
| (aucun dans le dépôt de base) |
3. Les jobs système hérités
conf/gallery/job/ contient quatre jobs de l'upstream VGallery :
| Job | Ce qu'il fait | État |
|---|---|---|
ping | notifie les moteurs de recherche de la sitemap mise à jour | legacy : plusieurs des services notifiés n'existent plus |
update | interroge la mise à jour distante | inerte : MASTER_SITE est neutralisée |
diagnostic | vérifie cache, dictionnaire, config, uploads, miniatures | utile comme contrôle manuel |
reset_carts | nettoyage des paniers abandonnés | pertinent seulement avec l'e-commerce actif |
Ils ne sont pas planifiés par défaut et écrivent leur résultat comme notification de backend (write_notification). Il existe aussi un mécanisme d'autoload par convention : check_function("job_<nom>") charge library/gallery/job/<nom>.php ou bien modules/<module>/library/job/<nom>.php (library/gallery/common.php, lignes ~138-146).
4. La file de jobs interne (Jobs)
vendor/hcore/jobs/Jobs.php implémente une file persistante avec planification et répétition.
Jobs::getInstance()->add($source, $params, $schedule, $repeat, $priority);
Jobs::getInstance()->run(); // exécute les jobs dus
Jobs::getInstance()->ps(); // état de la file
Jobs::getInstance()->forceRun($kid); // force un job
Jobs::setScript($callback, $schedule, $repeat);
Exécuteurs par type : API interne, service, requête HTTP, script, fonction, objet (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj).
Gardes dans la classe : SOCKET = 10, TIMEOUT = 60, ANTIFLOOD = 4 secondes entre deux exécutions, DELAY_SCHEDULE = 3600 pour la replanification après erreur, REPEAT = "1week".
Et la primitive fire-and-forget :
Jobs::async("/api/cache/refresh", array("url" => $_SERVER["HTTP_REFERER"]));
ouvre un socket vers son propre hôte, écrit la requête et n'attend pas la réponse. Dans le dépôt elle est utilisée par library/gallery/system/trace.php et par le bus des services (voir 03 §4).
Quand l'utiliser et quand non.
Jobs::asyncest parfaite pour « rafraîchis le cache après avoir répondu ». Pour le travail qui doit être fait — envois, débits, notifications — il faut quelque chose qui laisse une trace et puisse être réessayé : la file persistante, ou une table de file propre écoulée par un cron. Le socket fire-and-forget ne garantit rien : si le processus appelé meurt, personne ne s'en aperçoit.
Il y a aussi library/rabbitMQ/ parmi les bibliothèques : broker externe, non câblé dans ce dépôt. Un projet qui en a vraiment besoin l'accroche, mais dans la grande majorité des cas une table de file + cron est plus simple à gérer et plus facile à inspecter.
5. Worker longue durée (CLI)
Quand il faut une cadence inférieure à la minute, ou un état en mémoire entre deux passages, on sort du web : un script PHP dans bin/ lancé par systemd (ou par un cron de repli).
Leçons qui valent pour tout worker sur cette stack :
- Un bootstrap CLI dédié. En ligne de commande le cycle de page ne tourne pas : les classes arrivent par l'autoloader, mais les fonctions de
ff/common.php(ffCommon_dirname,ffCommon_jsonenc) non. Il faut les inclure explicitement. On n'inclut paslibrary/gallery/common.php, qui suppose une instance decm. HTTP_HOSTdoit être préparé avantconfig.php: c'est lui qui décide de chargerconfig.local.phpouconfig.remote.php, et la moitié du framework lit$_SERVERsans vérifier les clés.FF_DISK_PATHest le chemin du serveur. L'installeur y écrit/var/www/…, qui n'existe pas en local : un worker qui construit des chemins sur cette constante échoue hors du serveur. Mieux vaut une constante propre dérivée de__DIR__, préférée quand elle existe.- Charger seulement le module nécessaire : les autres accrochent des événements au cycle de page et en CLI ne trouvent pas de
cmoù s'accrocher. - Les caches statiques doivent être jetés périodiquement. Les classes de configuration sont pensées pour la durée d'une requête HTTP : dans un processus qui vit une heure elles resteraient figées à la valeur lue au démarrage, et changer un seuil depuis le backend n'aurait aucun effet.
- Le worker sort de lui-même après une durée maximale (p. ex. une heure) et
Restart=alwaysle relance. Une sortie avec code 0 chaque heure est le comportement prévu : c'est le moyen le plus simple de ne pas avoir de problème de mémoire dans deux mois dans un processus PHP longue durée. - Il ne tourne pas en root : il doit lire
config.remote.php(0640, de l'utilisateur du site). Tourner sous cet utilisateur fait concorder les permissions sans les élargir. - Repli cron identique dans le code :
--durata=55plusflock -n.flockest la partie qui compte : deux workers en parallèle doublent les appels.
Si le worker maintient un état lu par le front-end (cache d'état en table), deux astuces paient tout de suite :
- battement et lecture dans le même appel : un seul endpoint qui dit « cet écran est ouvert » et renvoie l'état. Les séparer, c'est le double de trafic pour la même information ;
- toujours renvoyer
letto_il+ora_server: sans savoir quand il a été lu, une donnée de trois secondes plus tôt est inutilisable pour un client qui doit interpoler.
6. Maintenance : ce qu'on élague et ce qu'on n'élague pas
Un système qui tourne accumule. Il vaut la peine d'avoir un job de maintenance qui élague, avec discernement :
- on élague les logs applicatifs (par la fin, en gardant les N dernières lignes), les états temporaires expirés, les tokens OAuth expirés, les caches de contenus externes ;
- on n'élague pas les registres anti-doublon (un
email_logn'est pas un historique : c'est ce qui empêche de renvoyer la même communication), les audits de mouvements et de paiements, les lignes vers lesquelles pointe une autre table ; - on ne ferme pas d'office les objets en état intermédiaire (commandes abandonnées, brouillons) : on les compte et on les montre. La décision revient à qui gère, pas au job.
⚠️ AUTO_INCREMENT : supprimer des lignes ne fait pas revenir le compteur en arrière. Un test qui crée et supprime mille lignes laisse le prochain ID à 1001. Ce n'est pas un problème, mais c'est une question qui arrive tôt ou tard.