Pourquoi un worker Messenger dédié et un verrou sur le planificateur¶
En production, Kirexo fait tourner deux services applicatifs sur la même image : php, qui sert HTTP, et worker, qui consomme les files Messenger. Le worker peut tourner en plusieurs instances, et le planificateur Symfony (Scheduler) porte un verrou et un état persistant. Cette page explique ces choix. Les gestes d'exploitation sont dans Déployer Kirexo en production, les valeurs exactes dans Worker Messenger et dans la référence de app:articles:purge-trashed.
Le problème de départ¶
Une bonne partie du travail de Kirexo ne se fait pas pendant la requête HTTP. Le serveur web dépose un message dans une file, et un autre processus le traite plus tard :
| Message | Transport | Effet si personne ne consomme |
|---|---|---|
SendEmailMessage |
async |
Aucun e-mail ne part : ni réinitialisation de mot de passe, ni invitation. |
ArticlePublished |
plugin_web |
La publication ne diffuse rien, le site public n'est jamais mis à jour. |
App\Message\AnalyzeArticle |
async |
L'analyse IA ne se termine jamais. |
Tâche #[AsPeriodicTask] de app:articles:purge-trashed |
scheduler_default |
La corbeille n'est jamais purgée. |
Ces échecs sont silencieux : les messages attendent dans RabbitMQ, et rien ne signale que personne ne les consomme. Tant que la production ne lançait que FrankenPHP, c'était son état permanent.
Le développement avait un worker, lancé par le supervisor du conteneur php, mais sa liste de transports par défaut (plugin_web async) ne comprenait pas scheduler_default. La purge ne tournait donc nulle part. Le défaut commun aux deux environnements vaut désormais scheduler_default plugin_web async.
Pourquoi un service Compose plutôt que le supervisor de développement¶
Réutiliser le supervisor de développement en production aurait été le chemin le plus court. Trois raisons l'écartent.
- Il est écrit en bash, et l'image de production n'embarque que
/bin/sh(BusyBox). L'ajouter, c'est ajouter une surface d'exécution qui ne sert qu'à ce script. - Il lance FrankenPHP avec
--watch, une option de développement qui recharge le serveur quand un fichier change. - Sa raison d'être disparaît. Le supervisor sert à faire vivre deux processus dans un même conteneur, avec une relance et un backoff pour chacun. Dès que le worker a son propre conteneur, la politique
restart:de Docker joue ce rôle. Le processusmessenger:consumeest le PID 1 du conteneurworker: s'il sort, le conteneur sort, etrestart: alwaysle relance.
De ce supervisor, compose.prod.yaml garde la ligne de commande et ses garde-fous : --time-limit=3600 recycle le kernel toutes les heures, --memory-limit=192M fait sortir le worker avant le memory_limit de PHP (512M), -vv trace chaque message dans docker compose logs worker. Il n'y a ni --all, qui consommerait aussi le transport failed et rejouerait en boucle les messages en échec, ni --failure-limit.
Même image, même environnement¶
Le worker exécute le même code que le serveur web : il envoie des e-mails, génère des liens hors HTTP, appelle l'API Claude, diffuse les articles. Il doit donc tourner sur la même version et recevoir les mêmes variables. compose.prod.yaml le garantit par deux ancres YAML partagées par php et worker : x-kirexo-prod-image pour l'image, x-kirexo-app-environment pour l'environnement.
Les ancres YAML ne traversent pas les fichiers. Les variables que compose.yaml donne au service php sont donc recopiées dans l'ancre de compose.prod.yaml. Une copie peut dériver : si TRUSTED_HOSTS changeait dans compose.yaml sans changer dans l'ancre, l'ancienne valeur, fusionnée après, écraserait la correction en production. Un test de cohérence, sous tests/Unit/Infra/, compare les deux valeurs brutes. Seules trois surcharges propres à la production y sont admises, listées explicitement : KIREXO_ONDEMAND_TLS_ENABLED, MERCURE_PUBLISHER_JWT_KEY et MERCURE_SUBSCRIBER_JWT_KEY.
Le service worker n'utilise pas extends: php, qui aurait évité la copie. extends recopierait aussi ce qui n'a pas de sens pour un worker : les volumes caddy_data et caddy_config (qui portent la clé de compte ACME), tty: true et le healthcheck Caddy. Pour retirer ces volumes, il faudrait !reset, dont l'application à extends n'est pas documentée par la spécification Compose. Une définition explicite protégée par un test est plus prévisible.
Le healthcheck hérité de l'image est désactivé sur le worker (healthcheck: disable: true). Il interroge l'endpoint admin de Caddy (:2019/metrics), et le worker ne lance pas Caddy : le conteneur serait unhealthy en permanence.
L'ordre de démarrage : les migrations d'abord¶
Le worker ne doit pas consommer de messages sur un schéma qui n'est pas encore migré. Le service php est le seul à jouer les migrations, dans son entrypoint, avant de lancer FrankenPHP (cf. Pourquoi les migrations sont jouées au démarrage du seul service applicatif). Son healthcheck ne passe au vert qu'une fois FrankenPHP lancé, donc après les migrations.
Le worker s'appuie sur ce signal : depends_on: php: condition: service_healthy. Il ne démarre que sur un schéma à jour, sans mécanisme d'attente propre. Si une migration échoue, php reste unhealthy, docker compose up -d échoue sur dependency failed to start, et le worker n'est jamais créé. restart: true sur cette dépendance fait aussi redémarrer le worker quand Compose redémarre php.
Le worker pose en plus RUN_MIGRATIONS: "0" dans son environnement, après la fusion de l'ancre. L'entrypoint ne migre déjà que pour frankenphp run. Cette ligne est une défense en profondeur : même si ce filtre disparaissait, aucun conteneur worker ne toucherait au schéma.
Un cas échappe à cet ordre : le redémarrage de l'hôte. Le démon Docker relance alors les conteneurs sans respecter depends_on. C'est sans conséquence, puisque le schéma a été migré au dernier déploiement.
Plusieurs workers : haute disponibilité, pas débit du planificateur¶
Le nombre d'instances est réglable (KIREXO_WORKER_REPLICAS, ou --scale worker=N). Pour les files RabbitMQ, plusieurs consommateurs se partagent les messages. Le planificateur pose un autre problème : chaque instance qui consomme scheduler_default calcule elle-même les échéances des tâches périodiques. Sans coordination, deux workers déclencheraient chacun la purge.
Le schedule default porte donc un verrou distribué, stocké dans Redis via LOCK_DSN (src/Scheduler/DefaultScheduleProvider.php). Le verrou couvre le schedule entier, pas chaque tâche :
- la première instance qui l'acquiert devient la seule à générer les messages du planificateur ;
- les autres échouent à l'acquérir à chaque tour de boucle, et n'émettent rien ;
- le verrou est prolongé jusqu'à la prochaine échéance, puis rendu quand son détenteur s'arrête proprement ;
- une instance en attente le prend alors et continue.
La documentation Symfony le résume ainsi : ajouter des workers apporte de la haute disponibilité, pas davantage de débit. Pour le planificateur, une deuxième instance est une instance de secours, qui prend le relais si la première s'arrête.
sequenceDiagram
autonumber
participant W1 as worker-1
participant W2 as worker-2
participant L as Redis — verrou kirexo_scheduler_default
participant S as Redis — pool scheduler.cache
W1->>L: acquire() → accordé
W1->>S: lit la date du dernier déclenchement
W1->>L: prolonge jusqu'à la prochaine échéance
loop chaque tour de boucle
W2->>L: acquire() → refusé, n'émet rien
end
Note over W1: échéance atteinte
W1->>W1: exécute app:articles:purge-trashed
W1->>S: enregistre le déclenchement
Note over W1: --time-limit ou SIGTERM → sortie propre
W1->>L: release()
W2->>L: acquire() → accordé
W2->>S: lit l'état → la purge déjà faite n'est pas rejouée
Pourquoi l'état persistant est obligatoire¶
Le verrou empêche deux instances d'émettre en même temps. Il ne dit pas quand la prochaine échéance tombe. Sans état partagé, une tâche every 1 day compte son premier jour à partir du démarrage du processus.
Or --time-limit=3600 fait sortir le worker toutes les heures, et Docker le relance. Chaque relance remettrait l'horloge à zéro : l'échéance serait repoussée à « démarrage + 1 jour » toutes les heures, et la purge ne tournerait jamais. Le problème existerait même avec une seule instance, sans aucun verrou.
Le schedule enregistre donc la date de son dernier déclenchement dans Redis (stateful, pool scheduler.cache déclaré dans config/packages/cache.yaml). Toutes les instances lisent cet état, qui survit aux recyclages, aux redémarrages et aux mises à jour d'image. Le pool est séparé de cache.app pour qu'un cache:pool:clear cache.app n'efface pas cette date.
Un réglage complète l'état : processOnlyLastMissedRun(true). Après un arrêt prolongé, le planificateur rattrape la dernière échéance manquée, pas toutes. Un worker coupé cinq jours lance une purge au redémarrage, pas cinq.
Pourquoi pcntl dans l'image de production¶
Un arrêt de conteneur (docker stop, docker compose down, mise à jour) envoie SIGTERM au PID 1. messenger:consume sait y répondre proprement : il finit le message en cours, puis sort. Pour cela, il doit installer un gestionnaire de signal, ce qui passe par l'extension PHP pcntl.
Dans le conteneur worker, le processus PHP est le PID 1. Le noyau ne délivre au PID 1 que les signaux pour lesquels un gestionnaire est installé. Sans pcntl, le SIGTERM serait ignoré. Docker attendrait la fin du délai de grâce, puis enverrait SIGKILL, au milieu d'un message. Le délai de grâce ne servirait à rien.
Le stage frankenphp_prod du Dockerfile installe donc pcntl, et castor docker:check-prod-image refuse une image qui ne la charge pas. Le service worker porte stop_grace_period: 120s au lieu des 10 s par défaut de Docker. Ce délai couvre le handler le plus long connu, l'appel à l'API Claude de l'analyse IA (timeout d'inactivité HttpClient de 60 s), avec de la marge.
Même sans arrêt propre, aucun message n'est perdu. Un message non acquitté est redélivré par RabbitMQ (livraison « au moins une fois »). L'arrêt propre évite qu'un handler soit interrompu à mi-course puis rejoué depuis le début.
L'extension n'est installée qu'en production. En développement, le worker n'est pas le PID 1 : il tourne sous le supervisor, qui le recycle par messenger:stop-workers, un mécanisme qui ne passe par aucun signal. Ajouter pcntl à l'image de développement obligerait aussi à la republier. Le détail est dans Relancer FrankenPHP ou le worker Messenger.
Reprise après un arrêt brutal¶
Si le détenteur du verrou est tué par SIGKILL (délai de grâce dépassé, OOM du noyau, hôte coupé), il ne rend pas le verrou. Le verrou n'est pas perdu pour autant : il expire à la fin de son TTL. Au pire, il se libère à la prochaine échéance plus 300 s, la durée initiale posée par la fabrique de verrous.
Une instance en attente l'acquiert alors, lit l'état persistant, constate l'échéance manquée et la rattrape une fois. Le retard est borné à quelques minutes, sans doublon.
La fenêtre résiduelle d'une mise à jour¶
Lors d'un docker compose up -d sur une nouvelle image, Compose recrée php, qui migre, puis worker. Entre les deux, l'ancien worker peut encore consommer des messages, avec l'ancien code, sur le schéma neuf.
Pour une migration additive (une table, une colonne nullable), c'est sans effet. Pour une migration destructive (colonne supprimée ou renommée), l'ancien code peut échouer. Aucun mécanisme Compose ne ferme cette fenêtre sans complexifier le démarrage. La procédure de déploiement arrête donc le worker avant pull et up -d, à chaque mise à jour et quelle que soit la migration : c'est plus simple que de juger, release par release, si la migration est sans risque. Les messages déposés pendant l'arrêt attendent dans RabbitMQ.
Ce que ce choix ne couvre pas¶
- Le verrou coordonne les instances qui partagent le même Redis. Deux déploiements branchés sur des Redis différents déclencheraient chacun la purge.
- En développement, chaque worktree a son propre index Redis (
REDIS_DB_INDEX, repris parREDIS_URLetLOCK_DSN). Verrou et état sont donc propres à chaque worktree, et chaque worktree purge sa propre base. - Aucun test ne prouve sur une pile réelle qu'une purge quotidienne n'a lieu qu'une fois avec deux workers : la première échéance tombe un jour après le démarrage. Cette preuve repose sur un test PHPUnit déterministe du provider, qui simule deux instances sur un verrou et un état partagés. Sur une pile réelle, on vérifie le nombre de détenteurs du verrou (cf. Vérifier qu'un seul worker détient le verrou).