Trois bugs discrets du gateway : une coquille qui a tué les réponses, un masque qui a avalé les job keys, et un remaniement de sys.path


Votre routeur d’alertes vous prévient qu’un job est arrivé dans la mauvaise file. Vous ouvrez le log pour retrouver la clé, et vous lisez ITEM-000042:***. C’est donc la redaction. Vous passez en revue security.redact_secrets, vos préfixes de fournisseur, les règles de bearer token, et tout paraît correct. Il faut une deuxième passe pour le voir : aucun secret n’a été trouvé. Le motif a démarré au milieu d’un identifiant ordinaire, a pris les chiffres de sa queue pour un identifiant d’authentification, et a masqué la clé entière avec eux.

Trois bugs, une seule couche

Le gateway est le processus derrière Desktop et derrière chaque intégration de plateforme de chat. Les adaptateurs de plateforme — Telegram, WhatsApp, Discord, Slack, Raft — sont de fins traducteurs entre ce processus et une API réseau précise. Ils lisent de la configuration dans l’environnement, ils écrivent des lignes de log qui traversent le filtre de redaction, et ils importent des modules voisins depuis le dépôt. Trois tâches ordinaires, trois bugs.

Les trois ont été corrigés dans la même pull request de la couche gateway (#151738, fusionnée le 2026-11-09). Ils semblent sans rapport, et d’une certaine manière ils le sont. Mais ils partagent une couche et un tempérament : chacun échoue ailleurs que là où se trouve le défaut, si bien qu’aucun ne remonte jamais comme une erreur que vous pourriez chercher.

C’est la première raison pour laquelle cette classe de défaut est difficile à trouver. Une régression d’adaptateur ne ressemble pas à un problème d’adaptateur : elle ressemble à une job key cassée, à un bot qui a cessé de répondre, ou à une bibliothèque qui annonce la mauvaise version. Vous passez la première heure dans le mauvais fichier.

Premier cas : un caractère de trop dans .env a tué la réponse

Le chemin « follow-up while busy » de Telegram doit savoir combien de temps attendre avant de décider qu’un message est un vrai suivi plutôt qu’une partie du run déjà en cours. Cette valeur vient de HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS, et le code la convertissait avec un appel float nu.

Ainsi une valeur comme abc — une coquille, un placeholder oublié, ou un 3s écrit parce que ça se lit mieux — levait ValueError: could not convert string to float: 'abc' à run_inbound.py:697. Cette exception n’était pas rattrapée à la frontière. Elle déroulait tout le inbound handler, ce qui veut dire que le message de l’utilisateur ne recevait aucune réponse. Pas un suivi en retard. Un tour mort.

Le correctif fait passer cette lecture par gateway.run._float_env, le même helper que les autres réglages de timeout de ce module utilisent déjà. Une entrée mauvaise ne lève plus : elle retombe sur 3 secondes, le suivi est mis en file, et l’agent continue de travailler.

# Faux — les trois sont des chaînes, pas des nombres
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3s
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=
# Juste — un nombre nu, en secondes
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3

Pourquoi ça se cachait : ce chemin ne s’exécute que lorsqu’un second message arrive pendant qu’un run est en vol, donc la plupart des tests n’y touchent jamais. Et quand il se déclenche, l’erreur se manifeste comme « le bot m’ignore », ce qui envoie les gens vers le token, puis le webhook, puis le réseau — pas vers une valeur de configuration tapée des semaines plus tôt. Les env vars n’ont pas de système de types, et rien ne les valide avant l’exécution de la ligne qui les parse.

Deuxième cas : la redaction s’est mise à correspondre au milieu d’un mot

La redaction, c’est du pattern matching avec une promesse attachée : trouve les secrets, laisse tout le reste tranquille. La seconde moitié est la partie qui casse en silence.

Un regex ne sait pas ce qu’est un mot. À moins de lui dire de ne commencer qu’à une frontière, il commencera volontiers à n’importe quel caractère qui satisfait le motif. L’ancien motif Telegram _TELEGRAM_RE acceptait de démarrer au milieu d’un identifiant ASCII, sur la suite de chiffres collée à sa queue. Une job key ordinaire — de la forme ITEM-000042:job-a12345678:q- suivie d’une longue suite de a — correspondait donc depuis le milieu et était remplacée, en entier, par ***.

Rien n’a levé. Rien n’a averti. La ligne de log a perdu sa clé et l’ingénieur d’astreinte a perdu vingt minutes.

Le correctif contraint l’endroit où une correspondance peut commencer : à une frontière d’identifiant, ou après l’un des séparateurs d’échappement à largeur fixe que l’adaptateur émet réellement (\n, \uXXXX, %XX et compagnie). Le lookbehind sur la suite de chiffres, qui empêche le scanner de reparcourir les mêmes chiffres, est toujours là — le retirer, c’est ainsi qu’une passe de redaction devient quadratique sur une longue chaîne numérique.

Une assertion de test a dû être assouplie, et la raison vaut la peine d’être connue : la gestion des noms de clés JSON sur main masque désormais les valeurs d’authentification avant que les noms de clés soient traités, donc une assertion qui attendait qu’un nom de clé apparaisse intact ne décrit plus ce que fait le code. C’est un test qui rattrape un changement délibéré, pas un trou qu’on rebouche.

La leçon se généralise : si vos règles de redaction sont une liste de regex et qu’aucune ne s’ancre à une frontière, vous avez un bug qui attend le premier identifiant se terminant par huit chiffres.

Troisième cas : importer un adaptateur remaniait le chemin d’import

sys.path en une phrase : la liste ordonnée de répertoires que Python parcourt, de l’avant vers l’arrière, quand vous écrivez import something, le premier répertoire contenant une correspondance l’emportant. La position zéro bat tout, y compris les paquets correctement installés dans l’environnement.

Installer n’importe quel adaptateur de plateforme — telegram, whatsapp, discord, slack, raft, plus gateway.platforms.base, cron.scheduler et tools.cronjob_tools — insérait auparavant le répertoire du dépôt à sys.path[0]. À partir de cet instant, tout nom de module existant à la fois dans le dépôt et dans l’environnement installé se résolvait vers la copie du dépôt.

La reproduction est inhabituellement propre. Importez le vrai paquet evals, puis un adaptateur, puis import evals à nouveau : il se lie désormais au répertoire evals du dépôt plutôt qu’à la distribution installée. Dix sur dix en rouge avant le correctif, dix sur dix en vert après, et les adaptateurs ne touchent plus du tout à l’ordre de sys.path.

C’est le plus silencieux des trois. Aucune exception, aucun avertissement, aucun avis de dépréciation. L’import réussit et renvoie un objet — juste un autre que celui que tous les autres chemins de code du processus attendent. Tout ce qui dépend de l’identité de la distribution installée (métadonnées de version, entry points, découverte de plugins) se met à renvoyer des réponses appartenant à un autre paquet, et le symptôme apparaît dans le sous-système qui a consulté ce module, très loin de l’adaptateur qui a déplacé le chemin.

Avant et après, en clair

Débarrassé du harnais de test, voilà ce qui a changé :

Sonde Avant Après
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc, message arrivant en cours de run ValueError tue la réponse La valeur mauvaise retombe sur 3 secondes ; le suivi est quand même mis en file
Une job key ordinaire comme ITEM-000042:job-a12345678:q- plus une longue suite de a La clé entière devient *** La clé survit telle quelle
Un vrai identifiant d’authentification dans le même flux de log Masqué Toujours masqué
import evals après un import d’adaptateur, evals installé depuis PyPI Se lie à la copie du dépôt, 10 sur 10 Se lie au paquet installé, 10 sur 10

Lisez la troisième ligne avant de faire confiance à un changement de redaction : resserrer un motif est facile ; le resserrer sans lâcher ce qu’il protégeait, c’est le travail.

Contrôler votre propre installation

Deux vérifications rapides, parce que les deux bugs restent invisibles jusqu’à ce qu’ils mordent.

# Vers quel `evals` cet interpréteur résout-il ?
python3 -c "import evals; print(evals.__file__)"

# Confirmer que la valeur de grâce est un nombre nu
grep -n FOLLOWUP_GRACE .env

Si la première affiche un chemin dans votre checkout plutôt que dans site-packages, vous regardez exactement la panne ci-dessus. Pour la seconde, une valeur non numérique dégrade désormais vers la valeur par défaut de 3 secondes au lieu de lever — mais un fallback silencieux reste une configuration erronée, donc corrigez la valeur au lieu de vous appuyer sur le fallback.

Pour la moitié redaction, cherchez *** dans vos propres logs et lisez les lignes autour. Un en-tête Authorization masqué, c’est le système qui fonctionne. Une job key, un request id ou un trace id masqué, c’est le système qui travaille trop, et aucune revue de configuration ne le révélera.

Qui a corrigé quoi

Trois correctifs, trois origines, fusionnés ensemble :

  • Le correctif de frontière de redaction (#145664) a été cherry-pické depuis @liuhao1024, avec un patch de @yuzilongleif-collab.
  • Le correctif de la grâce de suivi (#50120) a été cherry-pické depuis le #51324 de @Bartok9.
  • Le correctif de sys.path (#117698) s’appuie sur le #117699 de @beardthelion.

La version courte

Un bug est difficile à trouver à proportion de l’éloignement entre son symptôme et sa cause. Un float mal saisi dans une env var ressemble à un bot cassé. Un regex qui démarre au milieu d’un mot ressemble à un masque qui fonctionne. Un chemin d’import réordonné ressemble à un import qui fonctionne.

Retenez les réflexes de contrôle plutôt que les trois patches. Affichez __file__ pour les modules dont vous dépendez. Ne laissez jamais une valeur de configuration atteindre un parseur sans fallback. Ancrez chaque regex de redaction à une frontière et relisez ce qu’il a trouvé la dernière fois qu’il s’est déclenché. N’importe lequel de ces réflexes aurait attrapé les trois en quelques minutes.

Lectures liées : pourquoi un cookie dans une ligne de log est une connexion, ce que coûtait un 409 Telegram, comment des appels bloquants ont gelé la boucle d’événements du gateway, et la référence de configuration.