Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 05

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

BesoinOutilPourquoi
« 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::asyncl'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

  1. Secret dans la query string comparé avec hash_equals. Un job sans secret est un endpoint d'écriture public.
  2. GET_LOCK MySQL avec timeout 0. 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.
  3. 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.
  4. 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 20 doit 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 (abilitato on/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.

JobButFréquenceS'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 :

JobCe qu'il faitÉtat
pingnotifie les moteurs de recherche de la sitemap mise à jourlegacy : plusieurs des services notifiés n'existent plus
updateinterroge la mise à jour distanteinerte : MASTER_SITE est neutralisée
diagnosticvérifie cache, dictionnaire, config, uploads, miniaturesutile comme contrôle manuel
reset_cartsnettoyage des paniers abandonnéspertinent 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::async est 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 pas library/gallery/common.php, qui suppose une instance de cm.
  • HTTP_HOST doit être préparé avant config.php : c'est lui qui décide de charger config.local.php ou config.remote.php, et la moitié du framework lit $_SERVER sans vérifier les clés.
  • FF_DISK_PATH est 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 cm où 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=always le 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=55 plus flock -n. flock est 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_log n'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.