Notes d'ingénierie Naly : verrous cron machine et pipelines de publication observables

Résumé

TL;DRNaly utilise le cron machine comme un petit planificateur délibéré : des wrappers horodatés lancent les tâches de publication et de distribution, flock empêche les exécutions qui se chevauchent, l'amorçage en environnement épuré rend l'environnement explicite, et les journaux externes plus les artefacts déterministes transforment chaque exécution en preuve. La thèse est qu'une automatisation simple au niveau de l'hôte peut atteindre un niveau production lorsque la concurrence, la rejouabilité et l'observabilité sont conçues comme des sorties de premier ordre plutôt que comme des ajouts shell après coup.

Le cron machine n'est pas un moteur de workflow. Il ne sait pas si un article a été publié, si un blob a été téléversé, si une écriture en base de données était idempotente ou si une notification en aval pouvait être envoyée sans risque. Son rôle est plus étroit : se réveiller à une heure prévisible et exécuter une commande. La conception de Naly garde ce contrat réduit et construit la couche de fiabilité autour de lui.

Le schéma utile est schedule -> locked wrapper -> explicit runtime -> observable artifact. Cron fournit l'horloge. flock fournit la protection d'une exécution unique sur un hôte. Le wrapper fournit le chargement de l'environnement, le choix du mode, la journalisation et la discipline des codes de sortie. Le script applicatif fournit le comportement métier. Le répertoire d'artefacts fournit la piste d'audit.

Où il se situe dans Naly

Le pipeline de publication quotidienne de Naly fait partie du système de croissance utilisateur : il soutient les articles récurrents, les contrôles de distribution et la vérification en mode smoke pour les travaux qui doivent créer de la valeur d'acquisition ou de rétention. La planification elle-même est intentionnellement en dehors du chemin de requête Next.js. Le rendu d'une page ne devrait pas être responsable de décider que la tâche de publication d'aujourd'hui existe.

À haut niveau, le pipeline comporte cinq frontières :

L'entrée crontab contient la planification et nomme un wrapper.
Le wrapper crée un identifiant d'exécution, choisit le mode complet ou smoke, et lie les emplacements des journaux et des artefacts.
flock protège la section critique afin qu'une exécution lente ne puisse pas chevaucher le créneau planifié suivant.
L'environnement d'exécution TypeScript exécute la tâche versionnée avec un chargement explicite de l'environnement.
La tâche écrit les artefacts déterministes, l'état et les journaux en dehors de l'arborescence d'exécution du dépôt.

Le choix de la racine externe des journaux compte. Naly garde les journaux d'exécution hors du dépôt, avec NALY_LOG_ROOT=/tmp/logs par défaut et /data/logs pour les environnements persistants. Cela préserve le dépôt comme source et mémoire durable du projet, tandis que les journaux vivent dans un espace de noms opérationnel conçu pour la rotation, la rétention et l'inspection.

Le répertoire d'artefacts déterministes est la seconde moitié de l'observabilité. Une ligne de journal dit ce qui s'est passé ; un chemin d'artefact prouve quelle sortie a été produite. Pour une tâche quotidienne d'article, le répertoire d'artefacts devrait être indexé par nom de tâche, étiquette de date, créneau planifié et identifiant d'exécution, puis contenir les métadonnées de début, les métadonnées finales, stdout/stderr, les sorties de contenu, les sorties smoke et tout identifiant de publication.

Mécanisme technique

Le contrat Linux crontab(5) est direct : une crontab contient des instructions pour que le démon cron exécute une commande à une heure correspondante. Le manuel documente aussi des détails qui comptent en production : cron définit un environnement clairsemé comme SHELL, HOME, et LOGNAME; CRON_TZ peut définir l'interprétation de la planification ; les caractères pourcentage dans les commandes ont un comportement spécial avec stdin ; les transitions d'heure d'été peuvent ignorer ou dupliquer les tâches correspondantes ; et les entrées cron doivent se terminer par une nouvelle ligne correcte.

C'est pourquoi Naly traite les lignes cron comme des lanceurs étroits plutôt que comme de la logique applicative. La partie commande devrait être ennuyeuse : pointer vers un wrapper, ne pas contenir de TypeScript en ligne, ne pas faire d'acrobaties de quoting fragiles, et laisser le comportement applicatif aux scripts versionnés.

Un modèle mental utile est :

cron tick
  -> wrapper starts with sparse runtime
  -> run_id and artifact_dir are assigned
  -> log files are opened under NALY_LOG_ROOT
  -> local file lock is acquired
  -> environment is loaded explicitly
  -> checked-in TypeScript job runs
  -> manifest, status, outputs, and exit code are finalized

flock(1) est la primitive de concurrence. Son manuel décrit un outil en ligne de commande qui gère des verrous de fichiers depuis des scripts shell, en enveloppant l'exécution d'une autre commande. Il prend en charge les verrous exclusifs par défaut, l'acquisition non bloquante avec -n, l'attente bornée avec -w, les codes de sortie de conflit avec -E, et la propagation du code de sortie enfant lorsque la commande enveloppée s'exécute. Ces détails suffisent pour encoder une politique : ignorer, attendre ou échouer visiblement.

Pour Naly, la clé de verrou devrait correspondre au domaine d'idempotence. Un éditeur d'articles quotidiens et un expéditeur de distribution peuvent nécessiter des verrous séparés s'ils peuvent s'exécuter indépendamment sans risque. Deux éditeurs d'articles qui écrivent la même sortie étiquetée par date ont besoin du même verrou. Les noms de verrous doivent être stables et locaux à la machine, non stockés sur des chemins NFS ou CIFS, car le manuel flock signale un comportement limité sur certains systèmes de fichiers réseau.

L'observabilité suit alors la forme OpenTelemetry même lorsque l'implémentation est plus légère qu'un collecteur complet. OpenTelemetry définit les signaux comme des sorties système utilisées pour observer l'activité sous-jacente, notamment traces, métriques, journaux et baggage. Pour la publication cron, la trace est le cycle de vie de l'exécution, les métriques sont les durées et les décomptes, les journaux sont les enregistrements d'événements, et le contexte de type baggage est l'identifiant d'exécution, le mode, le créneau planifié, le répertoire d'artefacts et les métadonnées de version transmis à chaque étape.

Ce que dit la littérature

Des travaux récents sur arXiv sont directs quant au risque de l'automatisation de type cron. L'article de 2026 d'Agrawal et Jain sur les pipelines ELT résilients rapporte que les scripts d'ingestion ad hoc, y compris les tâches cron, ont produit des défaillances silencieuses et des lacunes de données qui ont érodé la confiance. Leur remède proposé repose sur une orchestration DAG plus lourde, un historique brut immuable et une gestion des dépendances fondée sur l'état. Naly n'a pas besoin de toute cette machinerie pour chaque tâche de publication quotidienne, mais adopte la leçon centrale : un pipeline planifié doit laisser un état durable qui rend le silence suspect.

Les travaux de 2025 d'Albuquerque et Correia sur les modèles de conception de tracing et de métriques soutiennent que les systèmes distribués deviennent plus difficiles à diagnostiquer à mesure que l'observabilité se fragmente. Ils séparent le tracing distribué, les métriques applicatives et les métriques d'infrastructure comme modèles de conception distincts. Pour les wrappers cron de Naly, cela se traduit par une règle pratique : ne pas laisser stdout être la seule preuve. Une exécution de publication a besoin d'une trace d'exécution, de compteurs au niveau applicatif et d'un contexte au niveau de l'hôte.

AgentTrace est pertinent parce que le pipeline de publication de Naly inclut des composants assistés par IA. AlSayyad, Huang et Pal présentent la journalisation structurée comme une couche de responsabilité à l'exécution pour les systèmes d'agents, capturant le comportement opérationnel et contextuel afin que l'exécution non déterministe puisse être auditée. La version de Naly devrait éviter de divulguer le raisonnement privé, mais elle devrait enregistrer la classe de prompt, les identifiants d'ensembles de sources, les métadonnées de modèle et d'environnement d'exécution, le mode de sûreté, les hachages d'artefacts et les décisions de publication.

OpsAgent, révisé en mai 2026, renforce le même point opérationnel depuis la gestion des incidents : les métriques, les journaux et les traces deviennent plus utiles lorsqu'ils sont convertis en descriptions structurées et auditables. Cela compte aussi pour un petit pipeline cron. L'objectif n'est pas de collecter plus de texte ; il est de rendre le prochain diagnostic plus rapide que la lecture d'une transcription de terminal.

Compromis de conception

Cron plus des verrous de fichiers est délibérément modeste. Il comporte moins de pièces mobiles qu'une plateforme de workflow, pas de base de données centrale de planificateur, pas d'interface web et pas de sémantique DAG intégrée. C'est une force lorsque la tâche est un éditeur quotidien sur une seule machine avec un contrat d'exécution clair. C'est une faiblesse lorsque les tâches deviennent distribuées, lourdes en dépendances ou ont besoin de politiques de nouvelle tentative à forte cardinalité.

Les verrous de fichiers sont aussi locaux par nature. Ils conviennent bien à un hôte et un système de fichiers. Ils remplacent mal les verrous consultatifs de base de données, les baux de file d'attente ou l'état d'orchestration si plusieurs machines peuvent exécuter le même éditeur. L'usage actuel de Naly relève de l'automatisation au niveau de l'hôte ; si la publication devient multi-runner, la frontière de verrouillage devrait passer dans un état durable partagé.

Les journaux externes échangent la commodité contre l'hygiène opérationnelle. Écrire les journaux dans le dépôt facilite le débogage local, mais pollue le contrôle de source et masque les problèmes de rotation. Utiliser /tmp/logs ou /data/logs force le système à déclarer quels journaux sont jetables et lesquels sont persistants.

Le mode smoke est un autre compromis. Une exécution smoke doit être peu coûteuse et non destructive, mais elle doit exercer le même wrapper, le même verrou, le même chargement d'environnement et le même code d'artefacts que l'exécution complète. Si le mode smoke contourne les parties difficiles, il devient un placebo.

Les artefacts déterministes coûtent de l'espace disque et du travail de nettoyage. Le gain est la rejouabilité : les opérateurs peuvent comparer deux exécutions, trouver la sortie générée exacte et distinguer une défaillance de publication d'une défaillance de distribution sans reconstruire l'état de mémoire.

Modes de défaillance

Le premier mode de défaillance est le chevauchement. Une tâche qui prend généralement trois minutes finit par en prendre trente, et le tick cron suivant lance une autre copie. flock ne l'empêche que si chaque entrée utilise la même clé de verrou, conserve le verrou sur toute la section critique et ne laisse pas accidentellement des enfants en arrière-plan continuer hors du cycle de vie protégé.

Le deuxième mode de défaillance est une planification trompeuse. Les transitions d'heure d'été peuvent ignorer ou dupliquer des tâches. La syntaxe de pas de champ peut être mal lue. Les caractères pourcentage peuvent modifier stdin de la commande. Une nouvelle ligne manquante peut laisser une crontab partiellement cassée. La posture défensive est une planification UTC, un texte de commande cron minimal et l'enregistrement du créneau planifié au niveau du wrapper.

Le troisième mode de défaillance est la dérive d'un environnement d'exécution clairsemé. Le shell non interactif de cron peut ne pas avoir le même PATH, la même version de Node, le même chemin de gestionnaire de paquets, les mêmes secrets ou la même locale qu'une session interactive. L'amorçage en environnement épuré de Naly rend cela explicite : charger l'environnement requis dans le wrapper, puis exécuter les scripts TypeScript versionnés via tsx, pas du code en ligne.

Le quatrième mode de défaillance est le succès silencieux. Un script peut sortir à zéro tout en produisant zéro artefact publiable. Le wrapper devrait traiter les décomptes de sorties attendus, la présence du manifeste final et les identifiants de publication comme des contrôles d'achèvement. Le succès n'est pas simplement l'absence d'exception ; le succès est un état final cohérent.

Le cinquième mode de défaillance est la publication partielle. Une ligne de base de données peut exister sans blob, un blob peut exister sans article public, ou un message de distribution peut référencer une URL non publiée. Les manifestes déterministes aident en séparant les états préparé, validé, publié et distribué.

Le sixième mode de défaillance est l'échec de l'observabilité elle-même. Si la racine des journaux est absente, pleine ou non inscriptible, le wrapper devrait échouer avant tout travail irréversible. Si la finalisation des artefacts échoue, cela devrait constituer une exécution échouée même si l'étape de contenu a réussi, car la piste d'audit fait partie de la surface produit.

Notes d'implémentation

Utilisez un wrapper par famille de tâches opérationnelles. L'entrée crontab devrait exprimer la planification, le fuseau horaire et le chemin du wrapper ; le wrapper devrait posséder toutes les autres préoccupations. Cela inclut run_id, mode, artifact_dir, log_path, l'acquisition du verrou, le chargement de l'environnement, le lancement de l'environnement d'exécution et l'état final.

Utilisez un verrou par frontière d'idempotence. Une tâche quotidienne d'article ne devrait pas partager un verrou avec des travaux de maintenance sans rapport, mais chaque chemin capable de publier le même article quotidien devrait partager un verrou. Préférez les attentes bornées ou les sorties non bloquantes à une mise en file sans borne, puis enregistrez si une exécution a été effectuée, ignorée ou a expiré.

Rendez les répertoires d'artefacts déterministes. Une forme pratique est job/YYYY-MM-DD/schedule-slot/run-id/. Placez started.json au début et finished.json à la fin. Incluez le mode, l'étiquette de date, l'identifiant de commit ou de build lorsqu'il est disponible, la famille de paquet ou d'environnement d'exécution, la durée, le code de sortie, les décomptes de sorties et les identifiants de publication.

Gardez les modes smoke et complet sur le même rail. Le mode smoke peut écrire dans un espace de noms dry-run et supprimer la distribution publique, mais il devrait quand même acquérir le verrou, charger l'environnement, initialiser l'accès Drizzle ou Neon lorsque nécessaire, vérifier les hypothèses d'écriture de blob le cas échéant, et rendre le markdown via le même chemin de contenu.

Utilisez des journaux structurés même lorsque vous écrivez des fichiers plats. Chaque événement important devrait inclure la tâche, l'identifiant d'exécution, le mode, le créneau planifié, le répertoire d'artefacts, la durée ou l'horodatage, et le résultat. Cela rend les fichiers journaux interrogeables plus tard et maintient la conception compatible avec une ingestion de style OpenTelemetry si Naly ajoute ensuite un collecteur.

La pile d'exécution actuelle correspond à ce schéma. tsx et TypeScript prennent en charge les scripts opérationnels versionnés. Drizzle ORM et Neon prennent en charge l'état durable de la base de données. Vercel Blob prend en charge les artefacts de publication durables. marked prend en charge les chemins de rendu markdown. Next.js et React présentent le résultat, mais cron devrait rester en dehors du cycle de vie des requêtes.

La leçon plus large est que cron n'est sûr que lorsqu'on ne lui demande pas de se souvenir. Naly fait réveiller le système par cron, flock sérialise la zone risquée, et les artefacts se souviennent de ce qui s'est passé.