SXN Labs

Ce que l'IA n'a pas rendu plus rapide

2026-10-22T09:00:00+02:00

Depuis que l’IA écrit une bonne part de mon code, mes journées ne sont pas plus courtes. Elles ont changé de contenu : écrire le code prend beaucoup moins de temps, et tout ce qui l’entoure a pris la place.

Ce qui est allé plus vite

Le premier jet d’un écran, une migration, les tests d’une règle métier déjà claire, une traduction, la documentation d’une API, la lecture d’un repo qu’on n’a pas ouvert depuis six mois. Sur ces tâches, le gain est net, parfois du simple au triple à vue de nez. Mais c’est la partie du métier qu’on voit, et la facture se remplit ailleurs.

L'IA a raccourci une étape sur cinq, celle qu'on voit.

Décider

Sur mon outil de prospection, un modèle note les entreprises selon la probabilité qu’elles m’achètent un logiciel. Il donnait presque la même note haute à tout le monde. Réécrire le prompt m’a pris une soirée.

Le reste a pris des jours : choisir quelle erreur me coûte le plus, un bon prospect jamais vu ou un mauvais qui me fait perdre une heure, puis trier à la main des dizaines de sociétés pour avoir de quoi mesurer. Aucun assistant ne prend cette décision, parce qu’il ne sait pas ce qui vous coûte.

Spécifier

Sur un logiciel de gestion, une entreprise de démonstration voyait s’afficher « votre abonnement est résilié », parce que le code ne distinguait pas « démo » de « arrêté ». La modification tenait en une condition et un message, cinq minutes.

La demi-heure d’avant a servi à répondre à ce que le code ne demande pas. Que doit lire une entreprise en démonstration ? Qui peut changer ce statut ? Que voit un administrateur qui usurpe le compte d’un collègue ? L’IA écrit très bien le comportement qu’on lui décrit, pas celui dont vous avez besoin.

Vérifier

Un assistant produit du code qui a l’air juste, et c’est ce qui le rend trompeur.

Une pull request corrige un bug et cite deux issues voisines comme dettes non traitées, avec un lien vers chacune. Une automatisation qui ferme « les issues liées » les ferme toutes les deux, et deux bugs toujours présents disparaissent du suivi.

Une version de ma gem de facturation électronique passait ses 317 tests et ne se chargeait pas chez qui n’avait pas déjà deux de ses dépendances. Aucun outil ne m’a signalé le contrôle qui manquait. Il fallait savoir que les tests tournent dans le repo, et que l’utilisateur installe le package.

Sécuriser

Cet été, les fuites se sont enchaînées. La DGFiP a confirmé des accès illégitimes à son système d’information entre juin et août, avec des identifiants usurpés, et 678 000 personnes seraient concernées selon le ministère. L’Éducation nationale a subi une intrusion dans sa plateforme de formation des personnels, qui a pu exposer les données de ses agents en poste depuis 2001. SFR a prévenu en août des clients Fibre dont les coordonnées ont été lues via un outil interne. Sur l’année 2025, la CNIL a reçu 6 167 notifications de violations de données, 9,5 % de plus qu’en 2024.

Beaucoup de ces fuites ne demandent aucun talent. Au printemps, 11,7 millions de comptes de l’ANTS ont été exposés par une faille attribuée à une IDOR : il suffisait de changer le numéro d’un dossier dans l’URL pour lire celui de quelqu’un d’autre, parce que le serveur ne vérifiait pas à qui il appartenait.

C’est exactement le genre de code qui a l’air juste. L’écran fonctionne, les tests passent, et la faille ne se voit qu’une fois exploitée. Relire chaque changement en cherchant qui pourrait en abuser prend autant de temps qu’avant, et produire plus de code en produit davantage à relire.

Répondre de la production

Lors d’un audit récent sur un logiciel, les corrections de code ont pris une fraction du temps d’il y a deux ans. Ce qui reste sur ma liste, ce sont des opérations d’exploitation qu’on ne rejoue pas, faites à la main par quelqu’un qui en répond. Et quand la production tombe un samedi soir, le modèle n’est pas d’astreinte.

Ce que ça change quand on commande un logiciel

Ran Craycraft, chez thoughtbot, pose bien la question : faire construire un prototype par une IA ne coûte presque plus rien, donc autant s’en servir pour vérifier qu’une idée mérite un vrai investissement. Il ajoute que le moment dangereux arrive quand le prototype marche et qu’on croit la production à portée de main. Un prototype sert à apprendre vite. Une application en production doit protéger des données, contrôler des accès et tenir quand quelque chose tombe.

Le code était rarement le poste le plus cher d’un projet, seulement le plus visible. Quand vous payez un prestataire, vous payez surtout les décisions qu’il prend avec vous, ce qu’il vérifie avant de livrer, sécurité comprise, et le fait qu’il réponde de ce qui tourne chez vous. Un devis « trois fois plus rapide grâce à l’IA » suppose que le projet se résumait à écrire du code : demandez ce que deviennent les décisions, les vérifications, la sécurité et la production.

Senko Rašić rappelle que dire « le code n’a jamais été la partie difficile » méprise un métier entier. Écrire du code demande toujours un savoir-faire. Son coût a baissé, celui du reste non.

Si vous hésitez entre un prototype et un vrai projet, on peut regarder votre contexte ensemble.

Le popover qui clignote au survol, ce petit bug qui trahit tout le reste

2026-10-15T09:00:00+02:00

Sur une application métier que je développe, des cartes de réglages affichent chacune un petit badge « ? » qui ouvre une bulle d’aide au survol. Rien d’exotique, un pattern qu’on voit sur la moitié des interfaces web. Sauf que la bulle clignotait. On approchait la souris du badge, l’aide apparaissait, disparaissait, réapparaissait, dans un scintillement nerveux qui donnait l’impression que l’écran buggait. Et il buggait, un peu.

Ce genre de détail ne casse aucune fonctionnalité. On peut le laisser traîner pendant des mois, personne n’ouvre de ticket pour ça. Mais c’est exactement le genre de scintillement qui, chez l’utilisateur, installe un doute diffus : « ce logiciel n’est pas fini ». La perception de qualité d’un produit métier se joue autant sur ces micro-détails que sur les grosses features. C’est la vitre brisée appliquée au logiciel : un défaut visible qu’on laisse en l’état signale que personne ne regarde le reste de près, et il finit par en autoriser d’autres.

Pourquoi la bulle clignote

Le réflexe naïf pour ce genre de bulle : on ouvre au mouseenter du badge, on ferme au mouseleave. Ça marche tant que le curseur reste sur le badge. Le problème surgit dès qu’il y a un espace, même d’un pixel, entre le badge et la bulle, ce qui est presque toujours le cas puisque la bulle s’affiche à côté du badge, pas dessus.

Quand la souris quitte le badge pour se diriger vers la bulle, elle traverse ce vide. Le navigateur émet un mouseleave sur le badge → on ferme. La bulle disparaît sous le curseur → le badge se retrouve à nouveau sous la souris → mouseenter → on rouvre. mouseleave → on referme. À la fréquence de rafraîchissement de l’écran, ça donne un stroboscope. Le pointeur oscille sur une frontière instable, et chaque franchissement déclenche un événement contradictoire.

Deux pixels de vide suffisent à faire osciller le pointeur entre deux états contradictoires.

Le second problème apparaît quand on empile plusieurs cartes côte à côte : en balayant la grille avec la souris, on ouvrait trois bulles d’un coup, qui se chevauchaient. Deux bugs distincts, une seule cause de fond : on traite le survol comme un signal binaire instantané, alors que l’intention de l’utilisateur, elle, a une durée et un contexte.

Interpréter une intention plutôt que des événements

La bonne abstraction s’appelle hover intent. On ne réagit pas à chaque mouseenter/mouseleave isolé ; on interprète une intention : « l’utilisateur veut lire cette aide » (il s’attarde), « il a fini » (il s’éloigne pour de bon).

Un délai de grâce à la fermeture. Au mouseleave, on ne ferme pas tout de suite : on arme un timer de ~120 ms. Si le curseur arrive sur la bulle pendant ce délai, on annule le timer. Le petit vide entre badge et bulle devient franchissable.

La bulle fait partie de la zone sensible. Le mouseenter sur la bulle elle-même annule toute fermeture en cours ; son mouseleave réarme le timer. Badge et bulle forment une seule zone logique, même s’ils sont visuellement séparés.

Une seule bulle ouverte à la fois. Avant d’ouvrir, on ferme celle qui traîne. Un simple registre partagé au niveau du module suffit, pas besoin d’un state manager pour ça.

Voici le tout dans un contrôleur Stimulus, sans dépendance :

import { Controller } from "@hotwired/stimulus"

// Registre partagé : une seule bulle ouverte à la fois.
let openController = null

export default class extends Controller {
  static targets = ["content"]

  connect() {
    // Sur écran tactile, pas de survol : on repassera au tap.
    this.hoverable = window.matchMedia("(hover: hover)").matches
    this.closeTimer = null
  }

  open() {
    if (!this.hoverable) return
    clearTimeout(this.closeTimer)
    if (openController && openController !== this) openController.hide()
    this.contentTarget.hidden = false
    openController = this
  }

  scheduleClose() {
    if (!this.hoverable) return
    this.closeTimer = setTimeout(() => this.hide(), 120)
  }

  cancelClose() {
    clearTimeout(this.closeTimer)
  }

  hide() {
    this.contentTarget.hidden = true
    if (openController === this) openController = null
  }
}

Et le HTML, où le badge et la bulle sont tous deux câblés sur les mêmes actions :

<div data-controller="popover">
  <button type="button"
          data-action="mouseenter->popover#open mouseleave->popover#scheduleClose
                       focus->popover#open blur->popover#hide"
          aria-describedby="help-<%= card.id %>">?</button>

  <div id="help-<%= card.id %>" role="tooltip" hidden
       data-popover-target="content"
       data-action="mouseenter->popover#cancelClose mouseleave->popover#scheduleClose">
    <%= card.help_text %>
  </div>
</div>

Le cancelClose sur la bulle est la pièce maîtresse : c’est lui qui rend le vide entre badge et bulle franchissable. Retirez-le et le délai de grâce ne sert plus qu’à retarder le clignotement.

Deux détails qui font la différence

Le tactile n’a pas de survol. Sur téléphone ou tablette, mouseenter se déclenche au premier tap et ne repart jamais tant qu’on ne touche pas ailleurs, et la bulle reste collée. Le garde matchMedia("(hover: hover)") neutralise la logique de survol sur ces appareils ; là, un simple tap qui bascule l’affichage est plus honnête. Tester une interaction de survol uniquement à la souris est un piège classique : ça marche parfaitement sur le poste du développeur et casse sur le terrain, là où beaucoup d’utilisateurs métier sont sur tablette ou sur téléphone.

Le clavier et les lecteurs d’écran. J’ai câblé focus/blur en plus du survol, et lié le badge à sa bulle via aria-describedby. Une aide contextuelle qui n’existe qu’à la souris n’existe pas pour qui navigue au clavier. C’est peu de code, et ça évite d’exclure une partie des utilisateurs sans même s’en rendre compte.

Ce que je retiens

Le correctif tient en trois idées (délai de grâce, zone sensible étendue à la bulle, une seule ouverte) et une trentaine de lignes. Aucune librairie, aucun composant lourd. La difficulté était de voir le problème et de refuser de le laisser passer.

Un logiciel métier se juge à l’usage, dans les mille micro-frictions du quotidien plutôt que pendant la démo. Absorber ces frictions côté prestataire relève du travail invisible : ça ne remonte dans aucun cahier des charges, et l’utilisateur ne le remarque qu’en creux, le jour où l’outil cesse de se mettre en travers.

Si vous avez un outil interne qui « marche » mais que vos équipes trouvent vaguement pénible sans savoir dire pourquoi, c’est souvent une accumulation de ces détails-là. On peut regarder ensemble lesquels valent vraiment la peine d’être corrigés.

Un carnet manuscrit hors-ligne dans le navigateur, sans app native

2026-10-08T09:00:00+02:00

Une application métier que je développe propose un carnet de notes manuscrites sur tablette. Ses utilisateurs travaillent sur le terrain, souvent là où le réseau est mauvais ou absent, et ils écrivent au stylet comme sur un bloc papier. Deux exigences qui réclament d’ordinaire une application native.

Je ne suis pas parti sur du natif. Une PWA (une page web installable, servie par un Rails classique) fait le travail, à condition de respecter trois réalités de l’appareil : il n’y a pas toujours de réseau, le stylet est un vrai stylet, et il crache des données beaucoup plus vite qu’on ne l’imagine. Chacune cache un piège que les tutoriels ne mentionnent pas.

La mise à jour qui efface les notes hors ligne

Le offline-first repose sur un service worker qui met les pages en cache et les ressert quand le réseau tombe. Le schéma est connu. On nomme un cache, on y stocke les pages consultées, et au déploiement suivant on renomme le cache pour invalider l’ancien contenu.

C’est exactement ce renommage qui crée une panne silencieuse. Quand on passe carnet-v2 à v3, l’événement activate du nouveau service worker supprime l’ancien cache. Tout son contenu part avec, y compris les notes que l’utilisateur avait déjà consultées hors ligne. Résultat, quelqu’un installe la mise à jour le matin au dépôt, part sur le terrain, perd le réseau, ouvre ses notes… et tombe sur la page « pas de connexion ». Ses données existaient, on venait juste de les jeter.

Le renommage du cache est ce qui invalide l'ancien contenu, et c'est aussi ce qui jette les notes déjà consultées.

Le correctif est de migrer les entrées de l’ancien cache vers le nouveau avant que activate ne fasse le ménage :

self.addEventListener("install", (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open(CACHE_NAME)
    // Reprendre les entrées des caches précédents avant qu'`activate`
    // ne les purge, sinon renommer CACHE_NAME efface les pages /admin/notes
    // déjà en cache, et l'utilisateur qui passe hors ligne juste après la
    // mise à jour atterrit sur une page d'erreur sans issue.
    for (const name of await caches.keys()) {
      if (name === CACHE_NAME) continue
      const previous = await caches.open(name)
      for (const request of await previous.keys()) {
        if (await cache.match(request)) continue
        const response = await previous.match(request)
        if (response) await cache.put(request, response)
      }
    }
    await cache.add(OFFLINE_URL) // la page offline, elle, est toujours rafraîchie
  })())
  self.skipWaiting()
})

Dans la foulée, la page offline cesse d’être un cul-de-sac : si les notes sont en cache, un script la fait rebondir dessus au lieu d’annoncer un échec.

Le stylet qui écrit « trop épais »

Pour le rendu du trait, j’utilise perfect-freehand, qui transforme une suite de points en un contour lissé à largeur variable. Par défaut, la librairie simule la pression à partir de la vitesse du geste : on va vite, le trait s’affine ; on va lentement, il s’épaissit.

Excellent pour un dessin. Catastrophique pour de l’écriture manuscrite. Quand on écrit, on va lentement et avec application, exactement le régime où la simulation gonfle le trait. Résultat, des lettres pâteuses qui ne ressemblent pas à ce que la main fait sur l’écran.

La tablette a un vrai stylet, qui rapporte une vraie pression via PointerEvent.pressure. La bonne réponse est donc d’éteindre la simulation et de n’utiliser que la pression matérielle quand elle existe :

export const FREEHAND_PEN_OPTS = Object.freeze({
  smoothing: 0.45,
  streamline: 0.2,
  // La largeur vient de la pression réelle du stylet, jamais de la vitesse :
  // la simulation épaississait le trait aux vitesses lentes de l'écriture.
  simulatePressure: false,
  // Peu de modulation : à forte pression, le trait redevenait pâteux.
  thinning: 0.2,
  // Sans ça, le lissage rattrape aussi le dernier point. Voir plus bas.
  last: true,
})

Avec une subtilité : PointerEvent.pressure vaut 0.5 quand l’appareil ne rapporte rien, souris et doigt compris. On détecte donc une fois par tracé si une valeur sort de ce 0.5 constant, et la largeur ne varie que dans ce cas.

Le trait qui ne colle pas à la pointe

Le symptôme était difficile à qualifier. Pas de lenteur visible, pas d’à-coup franc, seulement l’impression que le trait suivait le stylet au lieu de sortir de sa pointe. J’ai donc mesuré avant de toucher au code, avec deux scripts qui rejouent des tracés réels, l’un pour l’écart géométrique entre la pointe et le trait, l’autre pour le coût du pipeline dans Chromium. Deux causes sont sorties.

La pointe était filtrée. L’option streamline lisse chaque point vers le précédent, et sans last: true elle lisse aussi le dernier, celui qui est censé se trouver sous le stylet. Sur 67 tracés réels, 3497 échantillons, la pointe rendue traînait de 6,1 px en moyenne et jusqu’à 75,8 px sur les gestes rapides. Un booléen ramène l’écart à zéro et ne laisse le lissage qu’au sillage.

Le thread gelait au pire moment. Chaque pointerup programmait un instantané bitmap de la note en requestIdleCallback. Comme la lettre suivante arrive une centaine de millisecondes plus tard, le rappel tombait en plein tracé : recalcul de tous les contours, remplissage d’un canvas 2D et encodage WebP synchrone. Le trait se figeait de 150 à 950 ms avant de rattraper le stylet d’un coup.

Le correctif ne doit rien à un algorithme. L’instantané attend une pause d’une seconde et demie, ne part jamais pendant un geste et encode hors du thread principal ; le trait en cours a quitté le SVG des tracés persistés, où sa réécriture à chaque image faisait recalculer toute la scène, pour un canvas dédié en desynchronized: true. La pire image pendant l’écriture est passée de 199 à 34 ms sur une note légère, et de 935 à 21 ms sur une note de 370 tracés.

Reste le débit brut. À 500 Hz, la plupart des échantillons tombent à moins d’un pixel du précédent, sans ajouter de détail visible. Un filtrage par distance en espace écran les écarte.

const dx = ev.clientX - this.lastSampleClient.x
const dy = ev.clientY - this.lastSampleClient.y
if (dx * dx + dy * dy < MIN_SAMPLE_DIST_SQ) continue // < 1,2 px : on jette
this.lastSampleClient = { x: ev.clientX, y: ev.clientY }

La distance se mesure en pixels écran et non en coordonnées document, pour que la densité tienne à tous les zooms, et on compare son carré pour éviter une racine par point. Le filtre dédoublonne au passage les pointerrawupdate et pointermove qui décrivent le même point.

Les échantillons jetés ne portaient aucun détail visible, seulement du calcul par image.

getCoalescedEvents() et getPredictedEvents() étaient en place bien avant ce diagnostic et n’y étaient pour rien. La liste des bonnes pratiques était cochée, et le trait décrochait quand même.

Ce que j’en retiens

Aucun de ces correctifs n’est sophistiqué : une boucle, deux booléens, une comparaison de distances. Ce qui coûte, c’est d’identifier le bon problème. Le cache qui s’efface demande une vraie mauvaise connexion, le trait pâteux un vrai stylet en main, la pointe qui décroche un instrument de mesure. Rien de tout ça ne se manifeste sur un MacBook en Wi-Fi pendant le développement.

Le navigateur est largement capable d’une expérience proche du natif, sans le coût d’une application à maintenir, à signer et à faire passer par un store. Ce qu’il demande en échange, c’est un banc de test qui ressemble au terrain : une vraie tablette, un vrai stylet, et le mode avion.

Si ce sujet vous parle

Carnet hors ligne, synchronisation qui survit à une connexion pourrie, application terrain qui doit tenir sur un iPad qui s’endort : c’est exactement le genre de friction que je débloque chez SXN Labs. Si vous avez un usage métier coincé entre « il faudrait une app native » et « le web n’y arrivera pas », on peut regarder ce que ça demande vraiment.

Connecter un logiciel Rails à l'ordonnance numérique via Ordoclic

2026-10-01T09:00:00+02:00

ORIGAMI, le logiciel métier que je développe et maintiens en production pour la régulation médicale, propose désormais l’ordonnance numérique à ses prescripteurs. Le branchement n’a pas été fait en direct contre les téléservices de l’Assurance Maladie, mais via Ordoclic, qui expose ses services e-santé par API à des éditeurs intégrateurs. La certification CNDA Ordonnance numérique, elle, est portée par ORIGAMI : nous avons passé les pré-séries en notre nom, avec Ordoclic comme socle technique.

Je documente ce chemin parce qu’il est mal connu, et que des éditeurs de taille modeste y renoncent en croyant devoir tout absorber.

Un logiciel métier qui doit prescrire

ORIGAMI est une application Rails utilisée par des praticiens en activité. À un moment, la prescription électronique cesse d’être une option : le papier devient un irritant pour le médecin, qui veut transmettre directement au pharmacien, et pour le patient, qui ne veut pas balader une feuille. Il faut générer des prescriptions structurées, signées, déposées dans la base sécurisée hébergée par la CNAM, et interrogeables par le pharmacien à partir d’un identifiant.

Deux chemins, deux surfaces réglementaires

Le chemin direct. L’éditeur s’enregistre auprès de l’ANS, monte sa chaîne PKI, gère ses certificats serveur et logiciel, intègre Pro Santé Connect ou les cartes CPS pour authentifier les professionnels, dialogue avec le téléservice de l’ordonnance numérique, développe et fait certifier son propre LAP (Logiciel d’Aide à la Prescription) auprès de la HAS, avec base médicamenteuse agréée, contrôles d’interactions, contre-indications et posologies, puis passe le dossier CNDA pour son propre compte. C’est la voie des gros éditeurs historiques, et elle a sa cohérence : la chaîne est contrôlée de bout en bout, sans dépendance. Son coût d’entrée et de maintenance déforme le produit d’une structure d’un ou deux développeurs.

Le chemin de l’API intégrateur. L’éditeur s’appuie sur un partenaire déjà raccordé aux téléservices et déjà certifié LAP, qui factorise la plomberie réglementaire derrière une API. Le logiciel métier consomme les services et passe sa propre certification CNDA en s’appuyant sur ce socle. Pour le médecin, l’expérience est celle d’un éditeur en raccordement direct : il prescrit, ça part, le pharmacien interroge la base.

Le choix se joue sur la surface réglementaire portée en interne. La certification CNDA reste dans les deux cas au nom de l'éditeur.

Ce qu’Ordoclic prend en charge

Le raccordement aux téléservices CNAM et à l’écosystème ANS, avec les certificats serveur et la chaîne IGC-Santé associés.
L’authentification du professionnel via Pro Santé Connect, e-CPS et lecture de carte CPS, sans manipuler ces flux bas niveau côté éditeur.
La signature de la prescription et son dépôt dans la base sécurisée, au format attendu par les pharmaciens, avec QR code unique.
L’interrogation côté dispensateur à partir de l’identifiant d’ordonnance.
Le LAP lui-même : moteur certifié HAS V2 en ambulatoire, marqué CE comme dispositif médical, agréé CNDA pour l’ordonnance numérique, adossé à une base médicamenteuse actualisée (Vidal) avec alertes d’interactions, contre-indications et posologies. C’est le morceau le plus lourd à porter seul : référentiel HAS exigeant, base agréée à intégrer, revalidation à chaque évolution.
L’accompagnement aux pré-séries CNDA, étape obligatoire pour que l’éditeur intégrateur obtienne sa certification.

Ce qui reste à l’éditeur

La prescription n’a pas lieu dans ORIGAMI. Le médecin clique sur un bouton qui ouvre le LAP d’Ordoclic avec le contexte déjà posé, et c’est là qu’il prescrit, devant les alertes d’interaction et de contre-indication de la base médicamenteuse. Quand il a terminé, ORIGAMI reçoit par webhook l’ordonnance sécurisée au format PDF, la rattache au dossier et la transmet au patient par un canal sécurisé.

Ce découpage pousse le travail de l’éditeur aux deux extrémités. En amont, transmettre le bon contexte : quel praticien agit, sous quel numéro RPPS, dans quel contexte d’exercice, pour quel patient. Cette cinématique se cale à la configuration du compte du médecin et doit rester à jour à chaque prescription. En aval, recevoir les webhooks : un endpoint qui répond vite, qui supporte d’être rejoué sans créer de doublon, et qui trace ce qu’il a rattaché.

La responsabilité clinique du prescripteur, elle, ne se délègue nulle part. Le LAP affiche les alertes, le médecin tranche, et l’ordonnance qui revient dans le dossier porte sa décision.

Quand le partenaire est indisponible

C’est le coût de ce chemin : si Ordoclic ne répond pas, personne ne prescrit par voie électronique. Aucun mode dégradé ne produira l’ordonnance en différé, puisque la signature et le dépôt dans la base CNAM passent par le partenaire. Le repli est l’ordonnance papier.

Autant le dire aux prescripteurs avant la mise en service. INSi encaissait mieux la panne : l’acte continuait, seule la vérification d’identité restait en suspens. Ici la fonctionnalité s’arrête net, et la disponibilité annoncée aux médecins est celle du partenaire, pas la vôtre.

Le branchement côté Rails

Le code n’a rien d’exotique : des appels HTTP authentifiés contre l’API intégrateur depuis une couche service dédiée, et un endpoint qui reçoit les webhooks. Les patterns du reste du logiciel s’appliquent sans changement.

Le webhook est la pièce qui demande le plus de soin. Il arrive après coup, sur un serveur qui n’a pas suivi la session de prescription : il faut retrouver le dossier concerné, vérifier que l’ordonnance n’a pas déjà été rattachée, et répondre assez vite pour ne pas provoquer un rejeu inutile.

Une ordonnance numérique au sens du téléservice est un jeu de données structurées, signées et déposées dans la base CNAM, que le pharmacien interroge par identifiant. Le PDF que le patient reçoit en est la copie, et aucun pharmacien ne le lit.

Transmettre cette copie reste à la charge de l’éditeur. ORIGAMI envoie un email portant un lien à jeton, et le patient confirme son identité avec ses initiales avant que le document s’ouvre. Les laboratoires d’analyses et Doctolib ont déjà installé ce geste chez les patients, ce qui épargne un mode d’emploi.

L'éditeur tient les deux extrémités, le bouton qui ouvre le LAP et le webhook qui ramène l'ordonnance. L'acte lui-même se passe ailleurs.

La certification CNDA, portée par l’éditeur

La certification CNDA Ordonnance numérique obtenue dans ce cadre appartient à l’éditeur intégrateur, ORIGAMI en l’occurrence, pour une version donnée du logiciel. Elle s’obtient en passant les pré-séries CNDA en s’appuyant sur le LAP et le moteur d’Ordoclic comme socle conforme, et elle autorise la diffusion de cette version auprès des professionnels de santé.

Ce n’est donc ni un agrément obtenu seul en raccordement direct, ni un agrément hérité passivement du partenaire. Elle est tracée, attachée à une version précise, et rejouée à chaque évolution significative.

Le pattern, pour d’autres éditeurs métier

S’appuyer sur un partenaire intégrateur plutôt que viser un raccordement direct et un LAP maison, sauf à vouloir devenir éditeur PKI et LAP à plein temps.
Garder l’éditeur responsable de ce qui entoure l’acte (contexte transmis au LAP, réception des webhooks, rattachement au dossier, transmission sécurisée du PDF au patient, traçabilité) et déléguer la plomberie réglementaire, la base médicamenteuse et la prescription elle-même.
Prévoir le repli papier et l’annoncer aux prescripteurs, parce que la disponibilité de la fonctionnalité devient celle du partenaire.
Traiter la certification CNDA comme un état attaché à une version, rejoué à chaque évolution significative.

Si vous avez ça dans votre boîte

Si vous éditez un logiciel métier de santé et que l’ordonnance numérique est sur votre roadmap, la voie de l’API intégrateur existe et fonctionne. C’est le genre de sujet que je traite chez SXN Labs : cadrer le besoin, intégrer le partenaire dans une application Rails, accompagner les pré-séries CNDA, et laisser derrière un système exploitable et agréable à maintenir.

Le code était juste, le package livré ne l'était pas

2026-09-24T09:00:00+02:00

Fin août, j’ai publié la version 0.9.3 d’einvoicing, ma gem de facturation électronique. Elle n’ajoute ni ne corrige aucune fonctionnalité. La 0.9.2 ne se chargeait pas dans un projet qui n’avait pas déjà bigdecimal, alors que ses 317 tests passaient chez moi.

Chez moi, ça marche

La gem utilise bigdecimal pour les montants et rexml pour lire le XML. Ruby les installait autrefois avec lui, il faut maintenant les déclarer comme dépendances, et je ne l’avais pas fait. Sur mon poste, d’autres gems les installaient déjà. Ailleurs, require "einvoicing" échouait immédiatement, et la validation Peppol dès qu’elle lisait du XML.

Les tests tournent dans le repo. Le package publié ne contient que les fichiers listés dans le gemspec et les dépendances déclarées, et il s’installe sur un Ruby que je ne contrôle pas. Aucun test ne regardait ce package.

Les tests vérifient le repo, l'utilisateur installe le package.

Trois écarts entre le repo et le package

Une dépendance présente sur le poste, absente chez l’utilisateur. C’est l’écart qui a été publié.
Un fichier lu à l’exécution mais absent du gemspec. La gem embarque un profil sRGB dans chaque PDF/A-3 : retiré de la liste, tous les tests restent verts et la gem publiée ne produit plus de facture conforme. Je l’ai provoqué exprès, et aucun contrôle ne le voyait.
Un lockfile résolu sur Ruby 4.0, qui retient des versions exigeant Ruby 3.3 alors que la gem promet de tourner sur 3.2.

Les contrôles ajoutés

Le premier construit la gem comme pour une publication, l’installe dans un environnement vide et la charge. Il compare ensuite, fichier par fichier, ce que le repo utilise à l’exécution et ce que le package contient. Une dépendance non déclarée fait échouer le chargement, un fichier manquant est identifié.

Le second parcourt le lockfile et vérifie que chaque version accepte Ruby 3.2. Une gem qu’il n’a pas pu vérifier, par exemple quand RubyGems limite les requêtes, compte comme un échec.

Ces contrôles avaient eux-mêmes des trous, signalés en relecture. Le premier chargeait le package sans regarder son contenu, si bien que retirer un fichier de traduction laissait tout au vert. Corrigé, il vérifiait qu’un glob du gemspec trouvait quelque chose au lieu de vérifier chaque fichier attendu. J’ai reproduit chaque trou en cassant le package exprès avant de le corriger.

Au-delà de Ruby

Le même écart existe partout où l’on teste une chose et en livre une autre : un installeur essayé sur la machine qui l’a compilé, une image Docker construite avec un cache local, une application mobile validée sur le téléphone du développeur.

Si vous faites développer un logiciel, demandez sur quoi tourne la dernière vérification avant livraison. Si elle tourne sur la machine du prestataire plutôt que sur ce qui vous est livré, elle ne couvre pas ce que vous recevez.

La 0.9.3 et la 0.4.0 d’einvoicing-connect sont en ligne depuis le 31 août. Leur intégration continue lance désormais les tests sur Ruby 3.2 et 4.0, l’installation du package dans un environnement vide sur ces deux versions et la vérification du lockfile.

La TVA n'est pas un taux, c'est un régime

2026-09-03T09:00:00+02:00

Sur un PDF, la TVA tient dans deux colonnes : un taux et un montant. Quand le taux est à zéro, on écrit la raison en bas de page, en français, et la personne qui reçoit la facture comprend. En facture électronique structurée, cette ligne de texte n’existe pas. Il faut déclarer un code de régime, et si ce régime n’appelle pas de TVA, un motif lui aussi codé. Sans ça, le flux est rejeté à l’entrée.

Je maintiens einvoicing, une gem Ruby open source qui génère des factures Factur-X, UBL et CII conformes à la norme EN 16931. Récemment, je lui ai fait passer un lot de quinze factures volontairement hostiles : multi-taux, autoliquidation, cinq cents lignes, taux d’outre-mer, devise étrangère. Le lot est passé au schéma XSD, aux contrôles du conteneur PDF/A-3 et à un jeu de règles EN 16931 recalculé à la main.

Le lot a sorti quatre défauts, tous dans ma gem.

La même exonération, écrite pour un lecteur à gauche et pour un validateur à droite.

Sept régimes, pas un taux

La norme ne connaît pas « une facture à 0 % ». Elle connaît sept catégories de TVA, et le zéro peut venir de cinq d’entre elles pour des raisons juridiques différentes :

Code	Régime	Cas courant
S	Taux normal ou réduit	La facture ordinaire
Z	Taux zéro	Certaines livraisons taxées à 0 %
E	Exonéré	Franchise en base, acte médical, formation
AE	Autoliquidation	Sous-traitance dans le bâtiment
K	Livraison intracommunautaire	Client européen avec numéro de TVA valide
G	Export hors UE	Vente à un client suisse ou américain
O	Hors champ de la TVA	Certaines indemnités, subventions

Ma gem s’arrêtait à trois : standard, taux zéro, autoliquidation. Tout le reste ressortait en « standard », sans bruit et sans erreur visible.

Le champ que le papier ne demandait pas

Quand une catégorie n’appelle pas de TVA, la norme exige un motif : un texte lisible et, selon les cas, un code européen. Cinq règles de conformité le vérifient, une par catégorie.

Ma gem n’en écrivait aucun. Conséquence : toutes les factures en autoliquidation qu’elle émettait étaient non conformes. Elles produisaient un PDF correct et un XML valide au schéma, tout en étant rejetables par la règle métier.

Pour l’autoliquidation, l’intracommunautaire, l’export et le hors champ, le motif est mécanique : il existe un code européen dédié. Pour l’exonération simple, non. Le motif dépend de l’article invoqué, et une TPE en franchise en base n’est pas exonérée pour la même raison qu’un cabinet médical.

Einvoicing::LineItem.new(
  description: "Prestation de conseil",
  quantity:    1,
  unit_price:  BigDecimal("2500.00"),
  vat_rate:    0,
  category:    :exempt,
  exemption_reason:      "TVA non applicable, art. 293 B du CGI",
  exemption_reason_code: Einvoicing::Tax::VATEX_FR_FRANCHISE
)

C’est trois lignes de configuration. Encore faut-il que le logiciel qui émet la facture ait un endroit où les stocker, ce qui suppose qu’il modélise le régime et pas seulement le taux.

Trois centimes d’écart, et la facture est refusée

Deuxième défaut, plus sournois. Le total de TVA d’une catégorie peut se calculer de deux façons : en additionnant la TVA arrondie de chaque ligne, ou en appliquant le taux à la base imposable de la catégorie.

Sur une facture de cinq lignes, les deux méthodes donnent le même chiffre. Sur cinq cents lignes, elles divergent : trois centimes d’écart sur une catégorie, quinze sur une autre. La règle de contrôle se vérifie au centime près, et une facture « presque bonne » est refusée comme les autres.

Les deux méthodes sont défendables. Le contrôle, lui, se vérifie au centime près.

La norme tranche pour la seconde méthode : le montant de TVA d’une catégorie se déduit de sa base agrégée, et non de la somme des lignes. Une multiplication, un arrondi, à la fin.

# EN 16931, BR-CO-17 : TVA de la catégorie = base de la catégorie x taux,
# arrondi au centime. Les bases s'additionnent donc en BigDecimal, sans
# arrondi intermédiaire, et l'arrondi ne tombe qu'après la multiplication.
base = lines.sum(&:net_amount)      # BigDecimal, aucun arrondi ici
vat  = (base * rate).round(2)       # rate vaut 0.20 pour 20 %, comme dans la gem

Tout arrondi placé plus haut dans la chaîne rouvre l’écart, ce qui explique que le défaut résiste au débogage ligne à ligne : prises une par une, les lignes sont justes.

Et il ne se voit jamais en recette, parce que personne ne teste une facture de cinq cents lignes.

Les taux qui existent quand même

20, 10, 5,5 et 0. Ma liste de taux français s’arrêtait là, comme dans à peu près tous les tutoriels. Elle refusait donc 2,1 %, le taux de la presse et des médicaments remboursables. Elle refusait 8,5 %, le taux normal en Guadeloupe, en Martinique et à La Réunion. Elle refusait les taux corses. Tous parfaitement légaux.

Même famille d’erreur sur les numéros de TVA. Mon validateur imposait le format français à tout le monde, acheteur compris. Une facture intracommunautaire vers l’Allemagne échouait donc sur le numéro de TVA du client, qui était pourtant valide.

Le point commun de ces deux bugs est un référentiel écrit depuis le cas courant. Ça tient jusqu’au jour où un utilisateur vend en Corse ou achète depuis Munich.

Pourquoi ça devient un problème d’entreprise

Aucun de ces cas n’est exotique. La franchise en base concerne des centaines de milliers de très petites entreprises. L’autoliquidation est la règle en sous-traitance du bâtiment. Les taux d’outre-mer, ce sont plusieurs régions. La devise étrangère arrive au premier client hors zone euro.

Chacun de ces cas est le quotidien de quelqu’un.

Aujourd’hui, ces factures partent sans que personne ne se plaigne, parce qu’un humain les lit à l’arrivée et corrige mentalement ce qui manque. À partir du moment où c’est une machine qui les reçoit, il n’y a plus de correction mentale. Il y a un rejet, un retard de paiement, et un client qui vous demande de renvoyer.

La réception devient obligatoire en septembre 2026, l’émission en septembre 2027 pour les TPE et PME. Le premier rejet, lui, arrivera avant l’échéance qui figure au calendrier.

La question à poser à son éditeur

Pas « serez-vous prêts pour 2027 ? ». Tout le monde répond oui.

Plutôt : « qu’est-ce que votre logiciel écrit dans le champ motif d’exonération quand j’émets une facture en autoliquidation ? ». S’il n’y a pas de réponse, c’est qu’il n’y a pas de champ.

Et pour lever le doute sur une facture précise, il y a plus rapide que la théorie : la passer dans un validateur, analyse locale, sans upload. Si vous voulez faire le tour de votre chaîne complète, la page facturation électronique 2026 décrit le diagnostic que je propose.

Ce que j’en retiens

Ma conclusion est un peu inconfortable. J’écris cette gem depuis des mois, je connais la norme, et j’ai quand même émis des factures non conformes pendant tout ce temps sans qu’aucun test ne bronche.

La norme n’est pas piégeuse en elle-même : un XML valide au schéma peut être invalide au métier, et rien ne vous le dira tant que personne n’aura écrit les factures qui font mal. Le lot de quinze factures hostiles a coûté une demi-journée. Il aurait coûté beaucoup plus cher en septembre 2027.

Tout est corrigé dans la version 0.9.0 de la gem, publiée dans la foulée.

Quand le code décrit une fonction qui n'existe pas

2026-08-24T09:00:00+02:00

Lors de l’audit d’une application Rails, j’ai examiné son parcours de partage de rapports. L’application générait une URL que l’utilisateur pouvait transmettre à un destinataire pour lui donner accès au document. Si cette URL partait au mauvais destinataire ou si l’accès devait prendre fin, il fallait pouvoir l’invalider.

Le projet semblait avoir prévu le cas. Un commentaire présentait le lien comme révocable et une méthode régénérait son token, ce qui devait rendre l’ancienne URL inutilisable. Pourtant, le produit ne proposait aucun bouton de révocation et rien ne déclenchait la méthode.

En lisant seulement le code, la conclusion paraissait évidente : la révocation était cassée. En suivant le produit, une autre hypothèse apparaissait : cette fonction n’avait peut-être jamais existé.

Une fonction présente uniquement dans le dépôt

J’ai repris le parcours depuis son point d’entrée. Une route créait le partage, le contrôleur préparait le lien et l’interface permettait de le transmettre. Le chemin s’arrêtait là, sans action pour invalider l’URL ni écran pour en produire une nouvelle.

La méthode de régénération ne complétait donc aucun parcours utilisateur. Son nom et son commentaire décrivaient une fonction cohérente, mais elle restait isolée du produit. Cette différence importe pendant un audit : signaler une révocation défectueuse suppose qu’un utilisateur ait pu compter sur elle, tandis qu’une implémentation orpheline indique une fonction abandonnée ou jamais terminée.

L’explication la plus probable était une demande client prise trop littéralement. « Il faut pouvoir révoquer un lien » ressemble à un besoin, mais décrit déjà une solution. Le problème réel pouvait être un lien envoyé au mauvais destinataire, un accès trop long ou des droits mal définis. Aucun de ces cas n’avait été cadré, la méthode était restée après l’abandon du sujet.

Le même écart fausse ensuite les estimations. Une équipe qui découvre le dépôt peut chiffrer une évolution comme si la révocation existait déjà, puis apprendre trop tard qu’il reste à concevoir les droits, l’interface et le comportement des liens envoyés.

Prouver que le code est inaccessible

Une recherche sans appelant ne suffit pas toujours dans une application Rails. Une méthode peut être invoquée par un callback, un nom construit dynamiquement, un public_send ou une tâche éloignée de son modèle. J’ai donc vérifié le code depuis les points d’entrée réellement utilisés.

reproduire la création et l’utilisation du lien depuis l’interface ;
suivre la route, le contrôleur, les vues et les traitements différés ;
chercher les références directes à la méthode et au nom du token ;
examiner les appels dynamiques capables d’échapper à la recherche textuelle ;
instrumenter temporairement la méthode si le trafic de production laisse encore un doute.

Cette preuve permet une suppression limitée : la méthode, son commentaire et les tests qui ne couvrent qu’elle peuvent disparaître ensemble. Les tests du parcours de partage vérifient ensuite que la création et l’ouverture d’un lien continuent de fonctionner. Git conserve l’ancienne implémentation si l’enquête se révèle incomplète, sans obliger le dépôt à la présenter comme du code actuel.

Supprimer le code, conserver le besoin

La méthode morte ne rendait pas la révocation disponible, mais le besoin restait valable. Le supprimer avec son implémentation aurait confondu deux décisions différentes : nettoyer le dépôt maintenant et choisir si le produit doit permettre la révocation.

Un vrai ticket de fonctionnalité doit encore préciser qui peut révoquer un lien, ce que voit son destinataire après l’invalidation, si un nouveau lien est créé automatiquement et comment l’interface confirme l’opération. Garder une méthode sans appelant ne répond à aucune de ces questions et donne seulement l’impression que le travail est presque terminé.

Le code orphelin peut donc être supprimé immédiatement, tandis que le besoin rejoint la roadmap avec son périmètre réel. Si la révocation est priorisée plus tard, son implémentation partira du parcours attendu plutôt que d’une méthode retrouvée par hasard.

Ce que l’audit doit conclure

Le rapport ne devait annoncer ni une faille corrigée ni une fonction réparée. Il devait établir que les liens n’avaient jamais été révocables, que la méthode de régénération n’avait aucun appelant et que sa suppression ne modifiait pas le comportement du produit.

Cette conclusion laisse deux éléments exploitables : la preuve qui autorise le nettoyage et un besoin produit qui peut être arbitré séparément. Le prochain lecteur ne confondra plus une intention abandonnée avec une capacité disponible.

Turbo n’a pas trois outils, il a trois scopes

2026-08-06T09:00:00+02:00

La documentation de Turbo a la réputation d’être incomplète. Elle ne l’est pas vraiment : chaque page dit à peu près ce qu’elle doit dire. Le problème est ailleurs. Drive, Frames et Streams y sont documentés côte à côte, comme trois produits distincts, sans que rien ne dise ce qui les relie ni comment choisir. On apprend la syntaxe de chacun, et on reste bloqué sur la question qui compte au moment d’écrire : lequel, ici, maintenant.

Pour choisir, je regarde deux choses : la portion du document qui change et le moment où sa cible est décidée. Drive vise implicitement la page entière. Un frame nomme son fragment avant l’envoi de la requête. Un stream laisse le serveur désigner ses cibles dans la réponse. Cette lecture donne trois périmètres de mutation : la page entière, un fragment nommé, ou un ensemble d’éléments désignés dans une réponse.

remove, refresh, les actions personnalisées et les broadcasts ne sont pas littéralement des remplacements, mais la grille reste utile. Le morphing change la manière d’appliquer la mutation, pas son périmètre.

J’aurais aimé disposer de cette grille il y a trois ans. Le modèle et le tableau suffisent pour choisir ; la checklist et l’index servent au diagnostic. Le reste documente Turbo 8.0.23.

Versions et niveau de garantie

Cet article cible Turbo 8.0.23 et turbo-rails 2.0.23, publiés le 29 janvier 2026, avec Rails 8. Les détails ci-dessous viennent surtout du code et des tests de ces versions épinglées. Les encadrés qui s’appuient sur une garantie particulière utilisent les étiquettes suivantes :

API. Documenté sur turbo.hotwired.dev. Vous pouvez compter dessus : le modifier de façon incompatible constituerait un breaking change assumé.
Vérifié. Présent dans le code ou les tests de la version épinglée, mais absent de l'API publique. À couvrir chez vous et à revalider après une montée de version.
Interne. Détail d'implémentation. Précieux pour comprendre un bug, dangereux comme fondation. Ne bâtissez rien dessus.

Les liens vers le code de Turbo et turbo-rails pointent sur les tags v8.0.23 et v2.0.23, donc sur des lignes figées : elles diront toujours ce que je leur fais dire, même quand la branche main aura bougé.

Au programme

Le modèle en une pageles trois scopes, et qui désigne la cible
Quelle primitive choisir ?le tableau de décision, et les deux tests qui tranchent
Turbo Drivece qui est intercepté, le cycle de vie, le cache, la config
Turbo Framesla règle d’identifiant, le layout, les attributs qui comptent
Turbo Streamsles deux mondes, le trajet controller-vue, les huit actions
Le statut HTTP, et pourquoi 422
Le morphingce qu’il enlève, idiomorph, la pantry, la valeur des champs
Les broadcastsles macros, le request-id, le debounce, la sécurité des flux
Stimulus et les bibliothèques tierces
Réseau et hors-ligneéchecs de fetch, service workers, Action Cable
Checklist de debugdans cet ordre, avant d’ouvrir un ticket
Index par symptômevous avez un bug, vous partez d’ici
Ce qui a changé récemment

Si vous êtes ici parce que quelque chose ne marche pas, allez directement aux points 11 et 12, puis remontez vers la section concernée.

Le modèle en une page

La même mécanique, trois scopes. Ce qui change d'une colonne à l'autre : l'étendue du remplacement, qui en désigne la cible, et à quel moment.

Avec Drive, la cible est implicite : c’est le <body>. Elle n’est jamais négociée, il n’y a donc aucun contrat d’identifiant à respecter. Le client décide de naviguer, le serveur répond une page, Turbo échange le corps et fusionne l’en-tête.

Avec Frames, la cible est décidée par le client avant même que la requête parte. Le frame à l’origine de la requête envoie son identifiant dans le header Turbo-Frame. Sur le chemin d’extraction normal, Turbo n’accepte que l’élément portant ce même identifiant, directement ou au bout d’un frame recurse. Le serveur ne peut pas rediriger le contenu vers un autre frame. Il peut seulement court-circuiter l’extraction avec turbo-visit-control: reload, qui transforme la réponse en visite pleine page.

Avec Streams, la cible est écrite dans la réponse, donc décidée au dernier moment, par le serveur. Il dit remplace l'élément qui a cet id, ajoute ceci à la fin de celui-là, supprime cet autre. Il peut viser plusieurs endroits non contigus, et il peut le faire sans que personne n’ait rien demandé, via un WebSocket.

À retenir

Deux des trois primitives passent un contrat avec le DOM. Pour un frame, le chemin d’extraction normal doit trouver l’identifiant attendu, directement ou via recurse ; sinon Turbo émet turbo:frame-missing puis, par défaut, affiche « Content missing » et lève une erreur. Un listener peut annuler l’événement pour prendre le relais. turbo-visit-control: reload contourne entièrement ce chemin avec une visite pleine page. Pour un stream, le contrat est la cible doit exister dans le document au moment où l’ordre arrive ; une cible absente est, elle, un no-op silencieux.

Quelle primitive choisir ?

Le tableau ci-dessous est la version courte. Il ne classe pas les outils du plus simple au plus avancé. Partez de l’origine de l’état, puis choisissez la première ligne qui décrit réellement le besoin.

Votre besoin	La primitive	Pourquoi ce choix
L’état est purement client et le serveur n’a rien à en savoir	Stimulus, sans Turbo	Un aller-retour réseau pour ouvrir un menu est un aller-retour de trop
L’URL et la page entière représentent le nouvel état	Drive, c’est-à-dire rien à écrire	C’est déjà actif et fournit l’historique ainsi que le bouton retour
Une seule zone change, et une URL répond avec un `<turbo-frame>` de même identifiant	Frame	Turbo gère nativement le lazy loading (`loading="lazy"`), le loading state et la navigation interne. `data-turbo-action` peut promouvoir cette navigation dans l’historique
Plusieurs zones non contiguës changent en réponse à une action de l’utilisateur	Réponse `.turbo_stream`	Un frame ne peut viser qu’un fragment. Découper la page en cinq frames pour simuler un stream multiplie les requêtes
Le changement doit atteindre un navigateur qui n’a pas lancé la requête courante	Broadcast	Le destinataire n’a pas de réponse HTTP à appliquer. Lorsque Turbo rend lui-même le HTML du broadcast, son renderer synthétique n’a ni session ni `current_user` exploitable

Reste le cas où les deux semblent possibles.

Le test de l’URL, pour les frames. S’il n’existe pas d’URL dont la réponse contient ce fragment sous un <turbo-frame> de même identifiant, ce n’est probablement pas un frame que vous voulez. Un frame est un contexte de navigation : les liens et formulaires qu’il capture ont une URL et un loading state ; l’historique reste optionnel via data-turbo-action.

Le test du destinataire, pour les streams. Si seul l’onglet qui vient d’agir doit changer, c’est une réponse .turbo_stream. Si d’autres onglets doivent recevoir la mutation sans avoir lancé cette requête, c’est un broadcast. Ce sont deux usages très différents qui partagent un format, et les confondre est une source classique de HTML diffusé au mauvais utilisateur.

Turbo Drive

Drive est actif dès que vous chargez @hotwired/turbo. Il n’y a rien à écrire pour en profiter et, contrairement à ce que suggère l’ordre des chapitres de la documentation, c’est là que doit s’arrêter la majorité des besoins.

Ce qui est intercepté, et ce qui ne l’est pas

Drive intercepte les clics principaux sans touche de modification sur les <a href> navigables, ainsi que les form submissions navigables, tant que leur destination est visitable. Une URL visitable reste sous le <meta name="turbo-root"> de la page (/ par défaut) et son extension ne figure pas dans Turbo.config.drive.unvisitableExtensions (une cinquantaine d’extensions, dont .pdf, .zip, .csv, .jpg). Les URL cross-origin sont donc exclues avec le turbo-root par défaut. Cette liste d’extensions est configurable et n’est documentée nulle part sur le site officiel.

Turbo laisse aussi le browser gérer les liens download, tous les liens dont target diffère de _self, ainsi que les formulaires en method="dialog".

Vous coupez ponctuellement avec data-turbo="false" sur l’élément ou n’importe lequel de ses ancêtres. Un data-turbo="true" imbriqué plus bas le réactive.

Le cycle de vie

Il n’existe pas de séquence universelle. Le tableau suit un link en advance qui ouvre une visite Drive avec un fetch. Il suppose que le document de départ est cacheable et qu’aucun snapshot de preview n’existe. Une form submission pleine page effectue d’abord sa propre requête, tandis qu’une restauration depuis le cache saute les événements de fetch. Au chargement initial, turbo:load est émis sans turbo:render. Les render hooks peuvent aussi s’exécuter deux fois lors d’une preview. La dernière colonne reste la plus utile, parce que plusieurs noms sont trompeurs.

Événement	Émis sur	Annulable	Ce qu’il permet vraiment
`turbo:click`	le `<a>` cliqué	✓	Annuler pour laisser le navigateur faire une navigation classique
`turbo:before-visit`	`<html>`	✓	Le dernier endroit où l’on peut refuser la visite
`turbo:before-fetch-request`	`<html>` sur une visite, le frame ou le formulaire concerné, le `<a>` sur un prefetch ou un preload	✓	`preventDefault()` ne bloque pas la requête, il la met en pause jusqu’à l’appel de `detail.resume()`
`turbo:visit`	`<html>`	✕	Informatif. `detail.action` vaut `advance`, `replace` ou `restore`
`turbo:before-fetch-response`	`<html>` sur une visite, le frame ou le formulaire concerné, le `<a>` sur un prefetch ou un preload	✓	Annuler empêche le delegate Visit/Frame/FormSubmission de traiter la réponse. Cela ne bloque pas à lui seul un turbo-stream : `StreamObserver` ignore `defaultPrevented` et peut l’appliquer depuis ce même événement
`turbo:before-cache`	`<html>`	✕	Nettoyer le DOM avant le cache. Le clone est différé au prochain event loop tick
`turbo:before-render`	`<html>`	✓	Même sémantique de pause. `detail.newBody` est modifiable avant rendu, `detail.renderMethod` vaut `replace` ou `morph`
`turbo:render`	`<html>`	✕	Le nouveau corps est en place
`turbo:load`	`<html>`	✕	Fin de la visite. Au premier chargement, Turbo l’émet quand `readystatechange` passe à `interactive` ou `complete` ; un bundle async chargé après `DOMContentLoaded` peut démarrer trop tard et le manquer

Première surprise, turbo:before-fetch-request précède turbo:visit. Visit#start() appelle this.adapter.visitStarted(this), qui prépare la requête, avant this.delegate.visitStarted(this), qui émet turbo:visit (visit.js#L114-L118). Le fetch() effectif attend encore la fin de l’interception, mais un listener installé depuis turbo:visit a déjà manqué turbo:before-fetch-request. Instrumentez cet événement directement si vous devez observer ou modifier toutes les requêtes.

L’autre surprise tient à un défaut de dispatch() : sans target explicite, il émet sur document.documentElement, pas sur document (util.js#L29-L44). Avec l’event bubbling, écouter sur document fonctionne, mais event.target vaut <html>, ce qui compte si vous filtrez dessus. C’est le cas des deux événements de fetch d’une visite Drive. Un fetch de frame cible le frame, celui d’une form submission cible le <form>, et ceux du prefetch ou du preload ciblent le <a>.

Et les événements propres aux frames et aux formulaires, qui s’intercalent dans la même séquence :

Événement	Émis sur	Annulable	Ce qu’il permet vraiment
`turbo:before-frame-render`	le frame	✓	Pause, et `detail.render` est remplaçable : c’est le point d’entrée officiel pour brancher un autre moteur de rendu
`turbo:frame-render`	le frame	✕	Déclaré `cancelable: true`, mais la valeur de retour du dispatch est jetée : l’annuler ne produit rien
`turbo:frame-load`	le frame	✕	Le frame a fini
`turbo:submit-start`	le `<form>`	✕	`detail.formSubmission`
`turbo:submit-end`	le `<form>`	✕	Toujours `detail.formSubmission`. Une réponse traitée par `FormSubmission` ajoute `success` et `fetchResponse` ; une network error ajoute `success: false` et `error`. Ces clés restent absentes après un abort, ainsi qu’après le guard `Form responses must redirect` d’une réponse unsafe 200 non redirigée.

Sous le capot vérifié

turbo:before-fetch-request fait une chose de plus que ce que son nom laisse croire. Sa mise en pause est documentée dans le handbook, mais pas le fait que Turbo relise l’URL après coup : this.url = event.detail.url (fetch_request.js#L183-L199), et c’est bien ce this.url qui part au fetch juste après. Réécrire event.detail.url depuis un listener change donc réellement l’URL appelée, ce qui est le moyen le plus court d’ajouter un préfixe de tenant à toutes les requêtes Turbo d’un coup.

Encore faut-il le faire de façon synchrone dans le listener : l’affectation a lieu avant le await de la pause, donc modifier detail.url après un preventDefault() et avant resume() n’a aucun effet. Et affectez un objet URL, pas une chaîne : Turbo lit this.url.href, une chaîne donne undefined. Ce n’est pas dans le handbook, mais c’est couvert par la suite de tests du dépôt (form_submission_tests.js#L191-L204), ce qui en fait une garantie plus solide qu’il n’y paraît.

Le reste des bugs de cycle de vie vient presque toujours du snapshot ou de la preview.

Le snapshot vient de la page qu’on quitte, pas de celle qu’on charge. turbo:before-cache se déclenche sur le document courant, puis PageView#cacheSnapshot() attend le prochain event loop tick avant le cloneNode(true). Le nettoyage synchrone dans ce hook reste le chemin déterministe. En revanche, la visite n’attend pas la fin de cacheSnapshot() : le remplacement du <body> et un disconnect() Stimulus peuvent donc modifier l’ancien DOM avant le clone. Un disconnect() n’arrive pas nécessairement trop tard pour nettoyer le cache.

Le clone perd les listeners mais garde le DOM injecté qui existe encore à cet instant. C’est ainsi qu’une bibliothèque peut se retrouver initialisée deux fois au retour arrière ; on y revient plus loin.

Le clone remet aussi la sélection des <select> (que cloneNode perd), vide la valeur de tous les input[type=password], et supprime les <noscript>.

Une preview depuis le cache peut déclencher turbo:render deux fois, mais pas sur le retour arrière. Sur une visite advance ou replace, Turbo utilise un snapshot en cache seulement s’il est previewable et, en présence d’une ancre, s’il contient cette ancre. Il le rend pendant que le fetch continue ; si la réponse fraîche est elle-même rendue, un second turbo:render suit. Pendant le premier render, <html> porte l’attribut data-turbo-preview.

La nuance compte, et je l’ai eue fausse pendant longtemps. Une visite de restauration avec un snapshot utilisable n’émet aucune requête et rend une seule fois. Sans snapshot utilisable, elle repart sur le network. advance et replace décrivent des actions d’historique, pas seulement des clics de lien ou des form submissions : Turbo.visit() et un page refresh peuvent aussi les produire.

Sous le capot interne

Tout tient dans une méthode de six lignes : shouldIssueRequest() renvoie !this.hasCachedSnapshot() quand this.action == "restore", et this.willRender sinon (visit.js#L377-L383). Or loadCachedSnapshot calcule sa preview par const isPreview = this.shouldIssueRequest() (visit.js#L245-L265). Pas de requête, donc pas de preview, donc un seul rendu.

En pratique, la guard clause à écrire dans un contrôleur Stimulus reste la même :

connect() {
  if (document.documentElement.hasAttribute("data-turbo-preview")) return
  this.initExpensiveWidget()
}

Le cache, en chiffres

Le cache Drive est un LRU de dix snapshots, en mémoire, dans l’onglet. Pas de localStorage, pas d’IndexedDB, pas de Cache API. Il meurt à la fermeture de l’onglet et au rechargement. Chaque entrée conserve un clone du <body> et un index du <head>, y compris les balises <img>, <link> et <script>. Elle ne conserve pas les octets des images, stylesheets ou scripts : leur réutilisation relève du cache HTTP du browser.

À retenir

Le cache de Turbo est une optimisation de latence perçue, pas une stratégie hors ligne. Une visite de restauration peut afficher un snapshot déjà présent sans requête, même après une coupure réseau, mais ce cache ne survit ni au rechargement ni à la fermeture de l’onglet et ne garantit pas que la page voulue y soit encore. N’en faites pas un mécanisme de persistance.

On lit souvent que le cache est vidé « à chaque soumission de formulaire non-GET ». C’est vrai pour la moitié des cas seulement, et l’autre moitié surprend.

Sous le capot interne

Le vidage est asymétrique. Sur le chemin de succès pleine page, clearSnapshotCache() n’est appelé que si !formSubmission.isSafe, et seulement à l’intérieur du if (responseHTML) : une soumission non-GET dont la réponse n’est pas du HTML ne vide rien (navigator.js#L71-L90). Sur le chemin d’échec pleine page, le cache n’est vidé que si responseHTML existe, y compris pour un formulaire GET qui revient en HTML 4xx ou 5xx (navigator.js#L92-L107). Dans un frame, les callbacks de form submission diffèrent : un succès non-GET et toute réponse HTTP en échec vident le cache, même sans HTML (frame_controller.js#L246-L260). Une network error passe par formSubmissionErrored() et ne le vide pas ; un échec de navigation par link ou src non plus.

Concrètement, un formulaire de recherche en GET vide tout le cache s’il renvoie un 4xx ou 5xx HTML en pleine page, ou n’importe quel 4xx ou 5xx dans un frame. Rien ne vous le dira.

Reste ce que vous pouvez régler vous-même :

Ce que vous voulez	Comment
Ne jamais mettre cette page en cache	`<meta name="turbo-cache-control" content="no-cache">`
La mettre en cache mais ne jamais l’afficher en preview	`<meta name="turbo-cache-control" content="no-preview">`
Retirer un élément avant la mise en cache	`data-turbo-temporary` sur l’élément

data-turbo-cache="false" a été supprimé en 8.0.21, en janvier 2026, après trois ans de dépréciation. Turbo.clearCache() aussi, remplacé par Turbo.cache.clear(). Les deux traînent encore dans un paquet de billets, et dans les réponses Stack Overflow, ce site où des humains écrivaient de la documentation les uns pour les autres.

Turbo.config

Depuis 8.0.6, la configuration passe par un objet unique. L’ancienne API de configuration (setProgressBarDelay, setConfirmMethod, setFormMode) existe toujours mais émet un avertissement en console.

Turbo.config.drive.progressBarDelay = 500          // ms avant la barre de progression
Turbo.config.drive.enabled          = true
Turbo.config.forms.mode             = "on"         // on | off | optin
Turbo.config.forms.submitter        = "disabled"   // disabled | aria-disabled
Turbo.config.forms.confirm          = async (message) => window.confirm(message)

Sous le capot vérifié

Sur ces cinq lignes, deux sont documentées sur la page Drive de la référence : Turbo.config.drive.progressBarDelay et Turbo.config.forms.confirm. drive.enabled, forms.mode et forms.submitter n’apparaissent nulle part sur turbo.hotwired.dev. Les trois modes se déduisent des deux comparaisons d’égalité de Session#submissionIsNavigatable plus le défaut "on" ; il n’y a pas d’énumération dans le code.

Un détail qui va avec, et qui mord : set submitter(value) { this.#submitter = submitter[value] || value } (config/forms.js#L33-L35). Une chaîne non reconnue est stockée telle quelle, sans erreur, et explose plus tard sur config.forms.submitter.beforeSubmit(...). Une faute de frappe ne se voit qu’à la première soumission qui possède un submitter ; une soumission déclenchée sans submitter ne passe pas par cet appel.

forms.submitter mérite un mot. Par défaut, Turbo pose disabled sur le submitter pendant la soumission. Le contrôle sort alors du tab order et, s’il l’avait, perd son focus ; selon le browser et l’assistive technology, le focus peut retomber sur <body> et désorienter la personne qui navigue au clavier ou avec un screen reader. Avec "aria-disabled", Turbo pose aria-disabled="true" et intercepte les click sur le submitter, qui reste focusable. Cela bloque un second click traité par Turbo, pas une submission déclenchée directement par du code.

Turbo.config.forms.submitter = "aria-disabled"

Si votre interface doit conserver le focus pendant la submission, cette ligne dans application.js est un meilleur default. Il faut simplement prévoir le style visuel de aria-disabled.

Prefetch et preload

Depuis Turbo 8, le prefetch au survol est actif par défaut. Pour un link éligible, Turbo attend 100 ms après le mouseenter, envoie un GET avec l’en-tête X-Sec-Purpose: prefetch, et garde la réponse dans un cache d’une seule entrée pendant 10 secondes par défaut. La meta turbo-prefetch-cache-time permet de modifier ce TTL en millisecondes. Si le pointer quitte le link avant la fin du délai, la requête ne part pas.

Le prefetch ne s’applique pas à tous les links. Il faut notamment une URL HTTP(S) same-origin et visitable, sans target, download, data-turbo="false", méthode unsafe, stream, confirmation ni attribut UJS ; le link vers la page courante est également exclu. turbo:before-prefetch peut encore annuler. Les autres survols éligibles déclenchent bien une requête chez vous. Si vos actions GET ne sont pas idempotentes, ou si votre serveur n’aime pas le trafic gratuit, coupez :

<meta name="turbo-prefetch" content="false">     <%# global %>
<a href="/x" data-turbo-prefetch="false">…</a>   <%# ponctuel %>

À ne pas confondre avec data-turbo-preload, qui ne s’applique qu’aux <a> et qui est scanné après le chargement initial puis après chaque rendu de vue, plutôt qu’au survol. Le mécanisme diffère : le preload alimente le même cache LRU de snapshots que Drive ; seul le prefetch au survol possède son cache séparé d’une entrée pendant dix secondes.

Turbo Frames

Tout tient dans un identifiant

Après turbo-visit-control, Turbo cherche le frame directement ou via recurse. Sans correspondance, il émet turbo:frame-missing.

La règle de correspondance, littéralement, est container.querySelector("turbo-frame#" + CSS.escape(id)). Pas de correspondance approchée, pas de sélecteur configurable. En pratique, laissez le serveur reprendre l’identifiant envoyé par le client avec le helper turbo_frame_request_id de turbo-rails :

<%= turbo_frame_tag turbo_frame_request_id || "invoice_detail" do %>
  …
<% end %>

Ce fallback n’est pas décoratif. Sur une visite pleine page, l’en-tête est absent et turbo_frame_tag nil produit id="", ce qui casse sans un mot toute navigation ultérieure vers ce frame.

L’attribut recurse offre une seconde chance, peu utilisée. Si aucun frame de même id n’est trouvé mais qu’un <turbo-frame src="/fragment" recurse="mon-id"> est présent, Turbo attend son chargement puis va chercher dedans. Le ~= que vous verrez dans le sélecteur interne de Turbo appartient à CSS ; ce n’est pas une syntaxe d’attribut HTML.

Et si rien ne correspond, le déroulé est le suivant :

complete est posé sur le frame, avant l’événement.
turbo:frame-missing est émis sur le frame, annulable, avec detail.response (une Response brute) et detail.visit(urlOuResponse, options).
Si personne n’annule, le frame affiche <strong class="turbo-frame-error">Content missing</strong> et Turbo lève une TurboFrameMissingError.

L’expiration de session donne un cas classique. La requête part du frame, le serveur redirige vers /login, et la page de login ne contient évidemment pas votre frame. Plutôt que d’intercepter l’événement, marquez la page de login :

<%= turbo_page_requires_reload %>

qui pose <meta name="turbo-visit-control" content="reload">. Turbo saute alors complètement l’extraction du frame et fait une visite pleine page. C’est l’échappatoire prévue, et elle est bien meilleure qu’un listener turbo:frame-missing global.

Un piège au passage, et il vaut aussi pour turbo_refreshes_with qu’on verra plus loin : ce helper appelle provide :head. Il n’écrit rien à l’endroit de l’appel, malgré le <%= %>. Sans <%= yield :head %> dans votre layout, la balise meta ne sort jamais et rien ne se passe. La variante turbo_page_requires_reload_tag rend la balise sur place si vous préférez la placer vous-même.

Le layout, et le piège du layout statique

turbo-rails installe ceci dans ActionController::Base :

layout -> { "turbo_rails/frame" if turbo_frame_request? }
etag   { :frame if turbo_frame_request? }

Le layout turbo_rails/frame est minimal (juste csrf_meta_tags et yield :head), pas absent, pour que content_for :head et le CSRF continuent de fonctionner.

Le piège vient de layout "admin" dans un contrôleur, qui écrase cette lambda. Les requêtes de frame rendront alors le layout complet. Ça fonctionne quand même, parce que Turbo extrait le frame de toute façon, mais vous payez le rendu serveur, le transfert et le parsing du layout entier à chaque requête. Le <head> est parsé hors DOM puis jeté, donc ses scripts ne sont pas réévalués. Les scripts du frame extrait sont activés au render, sauf ceux marqués data-turbo-eval="false". Il faut convertir la déclaration en méthode :

layout :layout_for_request

private

def layout_for_request
  turbo_frame_request? ? "turbo_rails/frame" : "admin"
end

Piège

Aucune erreur, aucun avertissement, et le frame s’affiche parfaitement. Juste du rendu, des octets et du parsing inutiles à chaque requête. C’est le genre de régression qui n’apparaît qu’en profilant.

Les attributs qui comptent

Attribut	Effet
`src`	Charge cette URL dans le frame. Dans le helper `turbo_frame_tag`, la valeur passe par `url_for`, donc un modèle fonctionne.
`loading="lazy"`	Diffère le premier chargement du `src` jusqu’à l’entrée dans le viewport. Dans un même `FrameController`, les changements de `src` suivants chargent immédiatement. Après une restauration Drive, le controller est recréé et ce flag interne repart à zéro : un nouveau `src` hors viewport peut attendre à nouveau.
`target`	Cible par défaut des liens et formulaires descendants.
`data-turbo-frame`	Sur un lien, un formulaire ou un bouton de soumission. Écrase `target`. Le bouton gagne sur le formulaire.
`_top`	Sort du frame : Drive traite la navigation comme une visite pleine page.
`_parent`	Vise le frame ancêtre le plus proche. Ajouté en 8.0.21.
`busy`	Posé par Turbo pendant le chargement, avec `aria-busy="true"`. Utile en CSS.
`complete`	Posé après le render d’un frame correspondant, mais aussi avant `turbo:frame-missing`. Sur un frame connecté, un changement de `src` ou `reload()` le retire. La propriété JS `frame.complete` expose l’état de chargement courant et ne lit pas cet attribut.
`disabled`	Annule le fetch `src` en cours et empêche le frame d’intercepter de nouvelles navigations. Un link ou un formulaire descendant peut alors retomber sur Drive et naviguer en pleine page ; une form submission déjà partie n’est pas annulée.
`autoscroll`	Appelle `scrollIntoView()` sur `firstElementChild` après le render ; un frame vide ne bouge pas. `data-autoscroll-block` vaut `end` par défaut et `data-autoscroll-behavior`, `auto`.
`refresh="morph"`	Fait morpher le contenu chargé par `reload()`. Lors d’un page refresh rendu par morph, Turbo conserve un frame `src` compatible, hors d’une zone `data-turbo-permanent`, puis appelle automatiquement ce reload.

Le tableau ne dit pas tout de la façon dont un frame traite une réponse.

Pour une navigation par link ou src, une fois qu’une réponse HTML ordinaire atteint FrameController, le statut HTTP ne choisit pas le renderer du frame. Les callbacks directs requestSucceededWithResponse et requestFailedWithResponse appellent tous deux loadResponse(). Un 4xx ou 5xx avec du HTML non vide et un frame correspondant peut donc être rendu comme un 2xx. Un Content-Type turbo-stream est intercepté plus tôt par StreamObserver. Les autres Content-Types non HTML et les bodies vides ne produisent ni frame render, ni turbo:frame-render, turbo:frame-load ou turbo:frame-missing, même si turbo:before-fetch-response a déjà été émis. Annuler cet événement bloque le chemin de FrameController, avec l’exception stream décrite dans le tableau. Avec turbo-visit-control: reload, Turbo abandonne l’extraction et lance une visite pleine page avec un warning en console ; sans frame correspondant, il suit le chemin turbo:frame-missing décrit plus haut.

Une réponse HTML ordinaire à une form submission suit un autre chemin. Si turbo:before-fetch-response n’est pas annulé, un 4xx ou 5xx donne detail.success === false dans turbo:submit-end, vide le cache de snapshots et appelle loadResponse() sur le frame d’origine. Si le formulaire ciblait un autre frame, cette cible est donc ignorée pour l’échec et Turbo cherche l’id du frame d’origine dans la réponse. Un succès utilise au contraire la cible résolue ; il ne vide le cache que pour une méthode unsafe.

Sous le capot interne

Une précision, parce que « le statut n’est jamais consulté » est légèrement faux. loadResponse lit bien deux propriétés dérivées du statut, mais pour une seule chose, mettre à jour src.
if (fetchResponse.redirected || (fetchResponse.succeeded && fetchResponse.isHTML)) {
  this.sourceURL = fetchResponse.response.url
}
(frame_controller.js#L132-L135) Après une navigation par link ou une affectation directe de src, le frame pointe déjà vers l’URL demandée : si elle répond avec un 404 HTML, reload() rejoue cette URL en erreur. Une form submission ne copie pas son action dans src. Sur un échec non redirigé, le frame d’origine garde donc son ancien src, s’il en avait un, et reload() peut revenir à cette URL ; sans src, il ne charge rien. Après une redirection, src prend toujours l’URL finale, même si son statut est un échec.

Une form submission dans un frame n’a pas besoin de rediriger. L’erreur Form responses must redirect to another location n’est déclenchée que pour une submission pleine page en méthode unsafe dont la réponse finale est exactement 200 OK sans redirection. Les submissions GET n’ont pas cette contrainte, et le guard ne vise pas les autres statuts 2xx. Dans un frame, mustRedirect vaut false : un 200 OK avec un frame correspondant est valide.

Turbo Streams

Un <turbo-stream> est une enveloppe. Elle porte une action, une cible, et un <template> :

<turbo-stream action="replace" target="invoice_42">
  <template><div id="invoice_42">…</div></template>
</turbo-stream>

Il y a deux mondes derrière ce format, et les confondre explique une bonne partie des erreurs.

Le format est identique et l'onglet ne peut pas les distinguer. Toute la différence s'est jouée avant, au moment du rendu côté serveur.

Le premier monde est une réponse HTTP : l’utilisateur fait une action, le serveur répond du text/vnd.turbo-stream.html, l’onglet qui a fait la requête l’applique. C’est synchrone, ça vit dans le contexte de la requête, current_user existe, le HTML est rendu pour cette personne-là.

Le second est un broadcast : le serveur publie sur un canal Action Cable, tous les onglets abonnés le reçoivent. Les variantes _later_ et la plupart des callbacks de modèle rendent dans un job ; les variantes synchrones, ainsi que certaines suppressions installées par les macros, restent dans le thread appelant. Quand turbo-rails doit rendre le HTML, son renderer synthétique n’a ni session ni Warden exploitable comme une requête normale. Un appel synchrone, perform_now ou l’adapter :inline peut néanmoins encore voir un Current.* thread-local ; un job réellement pris par la queue ne l’hérite pas. Un appel qui reçoit déjà html: ou content: saute ce renderer, et un refresh ne rend aucun HTML. Quand turbo-rails rend le partial, il produit un seul payload HTML, envoyé à l’identique à tous les abonnés. On y revient plus bas, parce que c’est là que se cachent les vrais problèmes.

À retenir

Le format ne dit rien du contexte. Un <turbo-stream> reçu par un onglet ne porte aucune trace de son origine, et le code d’application est le même dans les deux cas. Tout ce qui distingue les deux mondes s’est joué côté serveur, au rendu, donc au moment où vous décidez quoi mettre dans le <template>.

Frames ou Streams ? Ce qui les sépare vraiment

Les deux savent remplacer un morceau de page, et c’est là que la confusion s’installe.

Critère	Turbo Frame	Turbo Stream
Qui désigne la cible	Le client, avant l’envoi	Pour une action ciblée, le serveur, dans la réponse
Combien de zones	Une seule, celle du frame	Par `<turbo-stream>` : zéro ou une avec `target`, toutes les correspondances avec `targets`. Une réponse peut contenir plusieurs éléments
La mutation est-elle une navigation	Oui : une URL répond avec le frame attendu	Non : le stream décrit une mutation, même si sa requête a une URL
Historique et bouton retour	Optionnels, avec `data-turbo-action`	Non
Lazy loading	Oui, `loading="lazy"`	Non
Peut-il partir sans requête	Non	Oui, c’est le broadcast
Ce qui se passe si la cible manque	Sur le chemin direct, `turbo:frame-missing`, puis « Content missing » par défaut ; `recurse` peut encore charger le frame attendu, et `turbo-visit-control: reload` contourne l’extraction	Pour une action ciblée, rien du tout, en silence
Ce que le serveur doit savoir	L’identifiant attendu, souvent repris depuis l’en-tête `Turbo-Frame`	Pour une action ciblée, l’`id` via `target` ou le sélecteur CSS via `targets`. `refresh` n’a pas de cible

La dernière ligne est celle qui devrait décider. Sur le chemin direct normal, un frame limite le contrat à un fragment portant le même identifiant : le serveur peut rendre une page complète, mais elle doit contenir l’identifiant demandé. recurse permet de le trouver dans une seconde réponse, tandis que turbo-visit-control: reload abandonne ce contrat pour une visite pleine page. Une action de stream ciblée est plus couplée : le serveur doit savoir adresser ses cibles dans le DOM affiché, sans aucun moyen de vérifier ce contrat. refresh fait exception puisqu’il ne désigne aucune cible.

Si vous avez connu Rails avant 2021, ce premier cas vous rappellera quelque chose. Répondre à une soumission par un document qui décrit des mutations du DOM, c’est exactement ce que faisait le create.js.erb de l’époque UJS. La différence tient au format et au vocabulaire : le serveur renvoie du HTML plutôt qu’une réponse JavaScript applicative, et Turbo fournit huit actions intégrées. Les actions personnalisées étendent ce vocabulaire explicitement, au lieu d’ouvrir la porte à « tout ce que jQuery sait faire ». On gagne surtout des réponses lisibles et une intention bornée. Ce n’est pas une frontière de sécurité : Turbo active explicitement les <script> présents dans les templates de streams, et une faille XSS reste une faille XSS.

Le trajet complet, du controller à la vue

Un controller classique suffit :

# app/controllers/invoices_controller.rb
def create
  @invoice = Invoice.new(invoice_params)

  if @invoice.save
    respond_to do |format|
      format.turbo_stream                                    # -> create.turbo_stream.erb
      format.html { redirect_to @invoice, status: :see_other }
    end
  else
    respond_to do |format|
      format.turbo_stream do
        render turbo_stream: turbo_stream.replace(
          "invoice_form", partial: "invoices/form", locals: { invoice: @invoice }
        ), status: :unprocessable_entity
      end
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end

Le format.turbo_stream nu rend un template ; utilisez-le quand plusieurs zones changent. Le render turbo_stream: inline accepte aussi plusieurs tags concaténés, mais il évite surtout un fichier pour les réponses simples.

Le template est un simple fichier ERB qui appelle le builder :

<%# app/views/invoices/create.turbo_stream.erb %>
<%= turbo_stream.prepend "invoices", @invoice %>
<%= turbo_stream.update "invoices_count", Invoice.count %>
<%= turbo_stream.replace "invoice_form" do %>
  <%= render "invoices/form", invoice: Invoice.new %>
<% end %>

Ces trois lignes condensent presque toute l’API, et chacune cache quelque chose.

turbo_stream.prepend "invoices", @invoice ne prend pas de partial : passer un record suffit, le builder appelle to_partial_path et rend invoices/_invoice.html.erb. C’est aussi la raison pour laquelle ce partial doit rendre un élément avec id="<%= dom_id(invoice) %>", sans quoi les helpers basés sur le record ne pourront plus le cibler directement.

turbo_stream.update accepte une chaîne brute comme contenu, ce qui évite un partial d’une ligne pour un compteur.

La forme à bloc capture ce que vous écrivez dans le view context courant. Dans une réponse HTTP, elle voit donc les ivars du controller, y compris celles posées par les before_action. Le contexte synthétique décrit plus haut ne concerne que le rendu d’un broadcast.

Et côté vue appelante, la règle est la même que partout. Ce que le stream vise doit exister avec le bon id.

<%# app/views/invoices/index.html.erb %>
<div id="invoices_count"><%= @invoices.count %></div>

<div id="invoices">
  <%= render @invoices %>
</div>

<div id="invoice_form">
  <%= render "invoices/form", invoice: Invoice.new %>
</div>

<%# app/views/invoices/_invoice.html.erb %>
<div id="<%= dom_id(invoice) %>" class="invoice">
  <%= invoice.reference %>
  <%= button_to "Supprimer", invoice, method: :delete, form: { data: { turbo_confirm: "Sûr ?" } } %>
</div>

Notez data-turbo-confirm sur le formulaire du button_to, successeur direct du data-confirm de rails-ujs. La différence est que sa fonction est remplaçable : Turbo.config.forms.confirm accepte votre propre fonction, ce qui permet enfin de remplacer la boîte native par votre propre modale sans réécrire le mécanisme.

Huit actions, et `morph` n’en est pas une

Action	Ce qu’elle fait	Cible requise
`append`	Ajoute à la fin du contenu de la cible	✓
`prepend`	Ajoute au début	✓
`before`	Insère avant la cible	✓
`after`	Insère après la cible	✓
`replace`	Remplace la cible elle-même	✓
`update`	Remplace le contenu de la cible	✓
`remove`	Supprime la cible. Pas de `<template>`	✓
`refresh`	Lance un refresh Turbo sur l’URL courante, sous forme de visite `replace`. Pas de `<template>`	✕

C’est tout. Il n’y a pas d’action morph. Le morphing est un attribut method="morph", et parmi les actions ciblées, seuls replace et update le lisent. Écrire turbo_stream.append("x", method: :morph) produit bien l’attribut dans le HTML, et le handler JavaScript de append l’ignore purement et simplement. refresh lit aussi method, mais pour une autre raison : choisir le mode de rendu de ce refresh, broadcast par broadcast.

La référence documente la déduplication de append et prepend : si un enfant direct de la cible porte le même id qu’un élément entrant de premier niveau, l’ancien est retiré. append se comporte donc comme un upsert. Depuis 8.0.21, before et after appliquent la même règle aux frères de la cible ; cette extension n’apparaît pas encore dans la référence.

refresh porte aussi un attribut request-id. Il sert à ignorer, dans l’onglet qui l’a émise, une requête récente déjà appliquée ; le debounce client qui fusionne des refresh rapprochés est indépendant de cet identifiant. La section sur les broadcasts détaille les deux mécanismes.

`target` et `targets` ne sont pas la même chose

turbo_stream.replace     "invoice_42"        # target  => getElementById
turbo_stream.replace_all ".invoice-row"      # targets => querySelectorAll

target prend un identifiant DOM nu, pas un sélecteur, et résout au plus un élément. targets prend un sélecteur CSS et applique l’action à toutes les correspondances. Si les deux sont présents, target gagne.

Côté Ruby, cette différence de nature est absorbée pour vous. Si vous passez un record plutôt qu’une chaîne, le helper met le dièse au bon endroit :

turbo_stream.replace     @invoice   # target="invoice_42"    <- dom_id nu
turbo_stream.replace_all @invoice   # targets="#invoice_42"  <- dom_id avec le #

Le piège n’apparaît donc que le jour où vous écrivez le sélecteur à la main, parce que là plus personne ne le corrige : turbo_stream.replace_all "invoice-row" sans le point ou le dièse ne matche rien, et ne dira rien.

Le silence quand la cible n’existe pas

Si document.getElementById(target) retourne null, le getter retourne un tableau vide, et chaque action itère sur ce tableau vide. Aucun avertissement, à aucun niveau de log. Le stream arrive, il est visible dans l’onglet Réseau, il est visible dans les logs Rails, et il ne se passe rien.

Les causes classiques sont un dom_id mal orthographié ou mis au pluriel, une cible qui vit à l’intérieur d’un <template> ou d’une <iframe> (explicitement non supportés), ou une cible qui est dans un frame loading="lazy" pas encore chargé.

Debug interne

Le silence total ne vaut que pour une cible présente mais introuvable. Si l’attribut lui-même manque, get targetElements() lève "target or targets attribute is missing", et get performAction() lève "unknown action" ou "action attribute is missing" (stream_element.js#L95-L120). Ces exceptions sont attrapées par le try/catch de connectedCallback et ressortent en console.error (stream_element.js#L33-L41), donc visibles, mais sans événement et sans rien à l’écran.

Regardez d’abord la console : si elle reste vide malgré un stream reçu, cherchez une cible absente ; si elle affiche console.error, cherchez un attribut manquant ou une action inconnue.

Un autre piège, plus fourbe, concerne les requêtes GET. Turbo n’envoie l’en-tête Accept: text/vnd.turbo-stream.html que si le lien ou le formulaire porte data-turbo-stream. Sans cet attribut, la négociation habituelle retombe sur HTML, sauf si l’URL ou les params imposent explicitement le format turbo_stream.

Ajouter vos propres actions

Le mécanisme est plus simple qu’il n’y paraît et c’est un bon investissement dès que vous vous surprenez à empiler des streams pour exprimer une seule intention.

Côté Ruby, un load hook :

# config/initializers/turbo.rb
ActiveSupport.on_load :turbo_streams_tag_builder do
  def highlight(target)       = action     :highlight, target
  def highlight_all(targets)  = action_all :highlight, targets
end

Côté JavaScript, une entrée dans Turbo.StreamActions, où this est l’élément <turbo-stream> :

Turbo.StreamActions.highlight = function () {
  this.targetElements.forEach((el) => {
    el.animate([{ backgroundColor: "#FFD83F" }, { backgroundColor: "transparent" }],
               { duration: 1200 })
  })
}

Et depuis un modèle, sans passer par le builder :

after_update_commit -> {
  broadcast_action_to "plannings", action: :highlight, target: "gantt", html: ""
}

Si l’action n’est pas enregistrée côté JavaScript, l’élément lève unknown action. Turbo est rarement aussi bruyant.

Le statut HTTP, et pourquoi 422

Turbo ne choisit pas le renderer en relisant les en-têtes de la requête. Le delegate du fetch est connu avant son départ : FrameController pour une navigation de frame, Visit ou FormSubmission pour une navigation pleine page. La réponse suit ensuite ce chemin :

Si le Content-Type commence par text/vnd.turbo-stream.html, StreamObserver intercepte la réponse et applique les <turbo-stream>, quel que soit le statut.
Sinon, la réponse revient à ce delegate. L’en-tête Turbo-Frame sert au serveur pour rendre le bon fragment ; Turbo ne l’utilise pas comme aiguillage au retour.
Sur le chemin pleine page, le statut participe alors au choix entre le renderer normal, le renderer d’erreur ou le refus de rendre.

Un formulaire Hotwire qui paraît figé tient souvent à cette ligne de Turbo :

responseSucceededWithoutRedirect(response) {
  return response.statusCode == 200 && !response.redirected
}

Pour une soumission pleine page non-GET, si vous répondez 200 avec du HTML sans redirection, Turbo affiche console.error("Form responses must redirect to another location") et ne rend rien. La page paraît figée. Le formulaire est parti, la barre de progression est allée au bout, et les messages d’erreur ne sont jamais apparus. Une soumission dans un frame ne passe pas par ce guard.

La raison est donnée dans le manuel, et elle est bonne. Les navigateurs ont un comportement natif pour le rechargement d’une page issue d’un POST, cette boîte de dialogue « voulez-vous renvoyer le formulaire ? », que Turbo ne peut pas reproduire. Plutôt que de mentir sur l’URL, il refuse.

D’où la convention Rails, que le générateur de scaffold applique déjà :

render :new, status: :unprocessable_entity  # 422 : la réponse est rendue, l'URL ne bouge pas
redirect_to @invoice, status: :see_other    # 303 : après update et destroy

Le 303 n’est pas une lubie de Rails : il exprime sans ambiguïté « cette mutation est terminée, récupère maintenant la ressource cible en GET ». Dans Fetch :

303 remplace toute méthode autre que GET ou HEAD par GET.
301 et 302 ne forcent le passage en GET que pour une requête HTTP POST. Une vraie requête HTTP DELETE redirigée en 302 serait rejouée en DELETE sur l’URL cible.
307 et 308 préservent toujours la méthode.

Mais turbo-rails 2.0.23 n’envoie pas ces méthodes comme telles. Son listener encodeMethodIntoRequestBody transforme toute méthode non-GET en requête HTTP POST et place la méthode logique dans _method (fetch_requests.js#L1-L18). Cela vaut pour data-turbo-method="delete" comme pour button_to method: :delete. Dans cette configuration, un 302 dégrade donc bien le POST réseau en GET ; il ne rejoue pas DELETE /invoices.

Gardez tout de même status: :see_other. Le 303 documente l’intention, fonctionne avec Turbo sans l’adaptateur Rails et évite que le comportement dépende de l’encodage _method ou d’un autre client HTTP. C’est une convention robuste, pas le correctif d’un DELETE rejoué par turbo-rails.

Une réponse turbo-stream court-circuite le choix du renderer. render turbo_stream: …, status: :unprocessable_entity s’applique donc parfaitement. Le statut reste observable : sur une soumission, turbo:submit-end.detail.success vaut false pour un 422 et true pour un 2xx. Il conserve aussi son sens pour les tests et les clients non-Turbo.

Petit détail amusant, le test porte sur statusCode == 200 exactement. Un 201 Created passe à travers le garde-fou et, si la réponse contient un body HTML non vide, poursuit vers une visite. Sans ce body, Navigator n’en propose aucune.

4xx et 5xx : deux chemins de rendu, pas un

C’est le point sur lequel je m’étais trompé, et il traîne dans beaucoup d’articles. On lit partout qu’un 4xx est rendu par le renderer de page normal et qu’un 5xx passe par le renderer d’erreur. Ce n’est vrai que pour les soumissions de formulaire.

Ce que vous avez fait	2xx HTML	4xx HTML	5xx HTML
Soumettre un formulaire pleine page	`PageRenderer`, sauf le 200 non redirigé d’une méthode non-GET, qui est refusé	`PageRenderer`	`ErrorRenderer`
Cliquer un lien, ou `Turbo.visit()`	`PageRenderer`	`ErrorRenderer`	`ErrorRenderer`

Le tableau suppose une réponse HTML exploitable. Pour une soumission réussie, Navigator ne propose la visite que si responseHTML contient quelque chose ; une réponse vide ou non-HTML ne passe donc pas dans PageRenderer. Sur une visite, une réponse non-HTML prend le chemin d’erreur.

Sous le capot interne

Sur une visite, le test est binaire : if (isSuccessful(statusCode) && responseHTML != null) rend normalement, else part sur this.view.renderError(...) (visit.js#L203-L223), avec isSuccessful défini comme statusCode >= 200 && statusCode < 300 (visit.js#L417-L419). La distinction 4xx/5xx n’existe que dans Navigator#formSubmissionFailedWithResponse (navigator.js#L92-L107).

Ça mérite mieux qu’une note de bas de page, parce que ErrorRenderer est nettement plus brutal que PageRenderer :

Il fait un replaceChild sur le <head> entier, au lieu de le fusionner.
Il parcourt tous les <script> du document, y compris ceux du <head> (error_renderer.js#L36-L38), puis réactive ceux qui n’ont pas data-turbo-eval="false" (util.js#L1-L15).
Il ne fait pas tourner Bardo, la machinerie qui transplante les éléments persistants. data-turbo-permanent n’est pas honoré sur une page d’erreur.

Et symétriquement, comme un 4xx de formulaire passe par PageRenderer, il est soumis à shouldRender : une divergence data-turbo-track="reload" sur votre page d’erreur transformera l’affichage des erreurs de validation en rechargement complet du navigateur.

Piège

Si votre page d’erreur 500 est un template minimal qui ne charge pas les mêmes assets que le reste du site, alors chaque erreur serveur sur un clic de lien vous rejoue les scripts du <head> qui n’ont pas data-turbo-eval="false" et jette vos éléments permanents. Les rapports d’utilisateurs ressemblent alors à « l’appli devient bizarre après une erreur », ce qui est un symptôme atroce à reproduire.

Le morphing

Turbo 8 a introduit les page refreshes avec morphing. L’idée est de comparer l’ancien arbre et le nouveau plutôt que de remplacer le <body>, puis de ne modifier que ce qui diffère. Le scroll peut être conservé ; le focus, la sélection de texte et l’état des transitions survivent quand le même nœud DOM reste en place.

On l’active dans le layout :

<%= turbo_refreshes_with method: :morph, scroll: :preserve %>

Et voici le premier piège, responsable d’une bonne part des « le morphing ne marche pas chez moi » : turbo_refreshes_with appelle provide :head. Il n’écrit rien à l’endroit où vous l’appelez. Sans <%= yield :head %> dans votre layout, les balises meta ne sortent jamais, et Turbo continue de faire des remplacements classiques, sans rien signaler. Les valeurs acceptées sont :replace ou :morph pour method:, :reset ou :preserve pour scroll:, tout le reste lève une ArgumentError.

Ce qui déclenche réellement un morph

Un morph de page n’a lieu que pour un page refresh. Quand PageView reçoit une Visit, le test exact tient en deux clauses : même pathname (la query string et le fragment ne comptent pas) et action === "replace". Sans Visit, isPageRefresh() renvoie directement true ; une réponse 4xx à une full-page form submission passe notamment par ce chemin et peut morpher si la méthode effective vaut morph.

Sans action explicite, une soumission non-GET ne prend replace que si la réponse a redirigé vers l’URL exacte de la page qui portait le formulaire. Turbo compare l’URL finale à history.location, pas à l’action du formulaire (navigator.js#L158-L166). Depuis /invoices/42, un PATCH /invoices/42 qui redirige vers /invoices/42 morphe. Depuis /invoices, un POST /invoices qui redirige vers /invoices/42 prend advance. Un formulaire GET prend lui aussi advance, sauf si sa réponse est redirigée vers l’URL exacte de la page de départ.

data-turbo-action="replace" sur le formulaire ou son bouton force toutefois cette action. Un formulaire GET qui passe de /search?q=old à /search?q=new peut donc morpher : seul le pathname doit rester identique. La même règle vaut pour un lien data-turbo-action="replace" de /invoices?page=2 vers /invoices?page=3.

Deux déclencheurs courants sont un formulaire qui redirige vers la page dont il est parti et un broadcast <turbo-stream action="refresh">.

Ce que le morphing change, ligne à ligne

Le début et la fin du cycle sont identiques. C’est le milieu qui change, et le milieu est exactement là où vit votre code.

Ce qui se passe	Rendu classique	Morph
`turbo:before-cache`	quand Turbo s’apprête à cacher le snapshot	idem
Snapshot mis en cache	selon la politique de la visite	idem
Le `<body>`	remplacé entièrement	comparé nœud à nœud par idiomorph
`disconnect()` / `connect()` Stimulus	sur tout	sur les nœuds ajoutés, supprimés ou déplacés ; même `moveBefore` produit les mutations que Stimulus interprète comme une déconnexion puis une reconnexion
`<script>` inline déjà présents	réexécutés sauf avec `data-turbo-eval="false"`	✕ jamais
`<script>` réellement nouveaux et éligibles à l’évaluation	exécutés	exécutés ; `data-turbo-eval="false"` les laisse inertes
`data-turbo-permanent`	transplanté par Bardo, `id` requis	nœud courant ignoré s’il porte déjà l’attribut, `id` non requis, Bardo n’est pas appelé
Scroll après un page refresh	préservé avec `scroll: :preserve`, sinon remis à zéro	idem
Focus et sélection de texte	perdus par défaut ; restaurés dans un élément permanent correspondant	conservés si le même nœud DOM reste en place ; après remplacement, restauration limitée aux `<input>` et `<textarea>` portant un `id`
`autofocus` lors d’un page refresh	honoré	✕ `MorphingPageRenderer.shouldAutofocus` vaut `false`
`turbo:render` puis `turbo:load`	émis	émis

Les deux premières lignes dépendent du chemin de visite, pas du mode de rendu. Après une soumission non-GET réussie, Turbo vide le cache puis démarre une visite avec shouldCacheSnapshot: false : pas de snapshot, donc pas de turbo:before-cache. Session#refresh passe aussi ce flag, avec une exception liée au LRU détaillée ci-dessous.

turbo:load se déclenche bien après un morph. Un refresh est une vraie visite. Ce qui ne rejoue pas, ce sont les <script> inline. C’est asserté par la suite de tests du dépôt lui-même (page_refresh_tests.js#L33-L42).

turbo:before-cache n’est pas une garantie du morphing. On lit, et j’ai écrit, que le morphing le supprime purement et simplement. Le moteur de rendu ne décide de rien. Tout dépend du chemin de visite et de sa politique de snapshot.

Sous le capot interne

Session#refresh force shouldCacheSnapshot: false (session.js#L108-L117). En l’absence d’un snapshot déjà caché pour l’URL courante, un <turbo-stream action="refresh"> n’émet donc pas turbo:before-cache. Mais BrowserAdapter#visitStarted() appelle d’abord loadCachedSnapshot() (browser_adapter.js#L21-L26). Si le LRU contient déjà un snapshot previewable pour cette URL et que le document courant est cacheable, ce chemin rappelle cacheSnapshot() sans vérifier le flag et émet l’événement (visit.js#L245-L263, page_view.js#L43-L50). Après une soumission réussie, Navigator passe shouldCacheSnapshot: formSubmission.isSafe et vide auparavant le cache pour une méthode non-GET (navigator.js#L71-L87) : un POST qui redirige sur la même URL peut donc morpher sans émettre l’événement. Une visite replace ordinaire ou un formulaire GET cacheable conserve au contraire le snapshot et l’émet.

Ne branchez donc pas un teardown nécessaire au DOM courant sur turbo:before-cache en supposant qu’il précède tous les morphs. Gardez cet événement pour nettoyer le snapshot quand il y en a un, et utilisez les événements de morph ou le cycle de vie du composant pour protéger le document courant.

Un script nouveau et éligible à l’évaluation peut s’exécuter sous morph. idiomorph matche l’ancien <script> avec le nouveau par nom de balise, puis synchronise leurs nœuds texte par oldNode.nodeValue = newNode.nodeValue. Modifier le nœud texte d’un script déjà exécuté ne le réexécute pas.

Un <script> issu de DOMParser ou d’un <template> est inerte et ne s’exécute pas par simple insertion. Turbo le remplace donc par un élément créé avec document.createElement("script") avant le rendu (util.js#L1-L15). Cette activation a aussi lieu sur le chemin morph, avant qu’idiomorph ne compare les arbres (page_renderer.js#L174-L190). Si le morph retrouve un script déjà présent, le nœud existant reste en place et ne rejoue pas. Si le script est réellement nouveau et ne porte pas data-turbo-eval="false", l’élément activé entre dans le DOM et s’exécute.

idiomorph décide par les identifiants

C’est le mécanisme central du morphing, et celui dont dépend tout le reste. Ce qui survit à un morph, ce qui se rejoue, ce qui casse dans Safari et pas ailleurs, tout part de là.

Le contenu et l'ordre visuel sont identiques dans les deux colonnes ; le nouveau HTML ne l'est pas. Ce qui change, c'est ce qui survit à l'opération.

Un id n’est considéré comme stable que si les trois conditions suivantes sont réunies : il existe dans les deux arbres, le nom de balise est identique, et il n’est dupliqué dans aucun des deux.

Cette troisième condition mérite d’être encadrée. Un seul id dupliqué dans l’une des deux racines morphées fait sortir cet id de l’ensemble persistant, dans les deux copies. Pour un page morph, ces racines sont les deux <body> ; pour un stream morph, la recherche reste limitée à la cible et au contenu entrant. Un doublon dans le <head> ou hors de la cible ne pollue donc pas ce morph. En revanche, un doublon accidentel dans la même racine peut dégrader à distance le matching d’un autre élément qui porte cet id.

Sans identifiants stables, le matching se fait par position. Ajouter une ligne en tête de liste réécrit le texte de toutes les lignes plutôt que d’insérer un nœud. Les objets DOM existants restent pourtant en place, et une transition CSS en cours continue si les attributs ou styles qui la déclenchent ne changent pas. Le bug utile à retenir : le state client peut rester attaché au mauvais record, ou être écrasé si idiomorph synchronise la propriété qui le porte.

À retenir

Donnez un id stable et unique à chaque élément de liste, ne le réutilisez jamais, ne changez jamais la balise associée. dom_id(record) respecte ces trois règles ; sans elles, le morphing d’une liste devient imprévisible.

Les déplacements de nœuds, et pourquoi Safari diffère

Voici le mécanisme qui explique les rapports de bug « ça marche chez moi mais pas chez lui », et qui n’est documenté nulle part.

Lorsqu’idiomorph réutilise ailleurs un nœud à id persistant, il le déplace sans le cloner. Selon l’ordre du morph, le déplacement se fait directement depuis l’arbre courant ou passe temporairement par la pantry, un <div> caché après <body>. Dans les deux cas, idiomorph utilise moveBefore() lorsqu’il est disponible, avec insertBefore() en fallback.

Le choix entre les deux change le comportement observable :

Avec moveBefore (Chromium 133 et plus, Firefox 144 et plus), le nœud reste connecté au niveau du DOM. Les <iframe> ne rechargent pas, l’état des transitions est conservé et les connectedCallback natifs ne rejouent pas. Stimulus observe malgré tout les mutations de déplacement et exécute disconnect() puis connect().
Avec insertBefore, le nœud est réellement déconnecté puis reconnecté. Les <iframe> rechargent, les transitions et animations CSS peuvent être interrompues ou relancées, les connectedCallback des custom elements rejouent, et Stimulus exécute aussi disconnect() puis connect(). La lecture d’un <video> ou d’un <audio> survit normalement au retrait et à la réinsertion ; ce n’est pas une différence entre les deux chemins.

Et voici la partie que j’ai vue mal comprise plus d’une fois. On présente volontiers moveBefore comme « largement disponible en 2026 ». Ça n’est vrai qu’en excluant Apple.

Sous le capot vérifié

D’après @mdn/browser-compat-data (relevé du 6 août 2026) : Chromium 133+, Firefox 144+, Opera 118, Samsung Internet 29. Safari, Safari iOS et l’iOS WebView sont tous les trois à version_added: false, le bug WebKit 281223 étant toujours ouvert.

Chrome et Firefox distribués aujourd’hui sur iPhone utilisent eux aussi WebKit, ils prennent donc ce fallback. Apple autorise toutefois des moteurs alternatifs dans l’Union européenne : assimiler durablement tout le trafic iOS à WebKit serait trop large. Safari, les WebViews et les navigateurs WebKit de votre trafic restent concernés, ainsi que les Mac sous Safari.

Donc oui, un bug de morphing peut être parfaitement reproductible sur iPhone et introuvable sur votre poste. Ce n’est pas nécessairement votre code. Et si votre produit est majoritairement consulté sur mobile, ce n’est pas un cas limite : cela peut concerner une part importante de vos utilisateurs, à mesurer dans vos propres statistiques.

La valeur des champs n’est pas protégée

idiomorph ne synchronise pas seulement les attributs, il écrit aussi les valeurs courantes des propriétés DOM des contrôles de formulaire. Le code est explicite :

if (!newElement.hasAttribute("value")) {
  if (!ignoreAttribute("value", oldElement, "remove", ctx)) {
    oldElement.value = ""           // ce que l'utilisateur avait tapé
    oldElement.removeAttribute("value")
  }
}

Le HTML serveur peut contenir un attribut value, les form builders Rails en émettent souvent un, ou ne pas en contenir. idiomorph efface alors la valeur courante dans le second cas, et la remplace par la valeur serveur dans le premier. Dans les deux cas, un refresh qui arrive pendant la frappe peut faire disparaître la saisie non enregistrée. Même traitement pour checked, disabled, <option selected> et le contenu des <textarea>.

Piège

Ce bug se rate facilement en développement dans un seul onglet, mais il n’a rien de spécifique à la production. Un page refresh déclenché pendant la frappe suffit ; un second onglet, un broadcast ou un Turbo.visit(location.href, { action: "replace" }) le reproduit localement. Si vous activez le morphing sur une application où l’on saisit des données, traitez la protection des champs comme un prérequis, pas comme une amélioration.

idiomorph possède une option ignoreActiveValue qui exclut document.activeElement de cette synchronisation. Les renderers intégrés de Turbo ne l’activent pas et n’offrent aucun réglage pour le faire. Turbo exporte toutefois morphElements et morphChildren, qui transmettent cette option à idiomorph ; un renderer custom peut donc l’utiliser.

Sans renderer custom, il reste à protéger le champ vous-même. Le levier le plus direct est data-turbo-permanent, qui fait sauter le morph sur l’élément ; les événements turbo:before-morph-element et turbo:before-morph-attribute permettent aussi des protections plus ciblées. Comme on ne veut pas geler le champ en permanence, on pose l’attribut au focus et on le retire à la sortie. Les fixtures de Turbo montrent ce pattern pour les inputs ; voici la variante étendue aux autres contrôles éditables cités ici :

addEventListener("focusin", ({ target }) => {
  const field = target instanceof HTMLInputElement ||
    target instanceof HTMLTextAreaElement ||
    target instanceof HTMLSelectElement
      ? target
      : target instanceof HTMLElement && target.isContentEditable
        ? target.closest("[contenteditable]")
        : null

  if (field && !field.hasAttribute("data-turbo-permanent")) {
    field.toggleAttribute("data-turbo-permanent", true)

    const unprotect = ({ relatedTarget }) => {
      if (relatedTarget instanceof Node && field.contains(relatedTarget)) return

      field.removeEventListener("focusout", unprotect)
      field.toggleAttribute("data-turbo-permanent", false)
    }

    field.addEventListener("focusout", unprotect)
  }
})

Tant que le même nœud DOM reste en place, il garde naturellement le focus. Si ce nœud est remplacé, idiomorph ne restaure explicitement le focus et la sélection que pour un <input> ou un <textarea> qui porte un id. Il n’offre aucune garantie équivalente pour un <select>, un contenteditable ou un champ sans id.

Lors d’un page morph, l’autofocus n’est pas honoré : MorphingPageRenderer déclare shouldAutofocus à false. Un frame morph suit un autre chemin ; MorphingFrameRenderer hérite de FrameRenderer, qui applique bien l’autofocus après le rendu.

La boîte à outils de protection

Du plus fin au plus brutal :

// 1. Protéger un attribut précis
document.addEventListener("turbo:before-morph-attribute", (event) => {
  const { attributeName } = event.detail            // + mutationType: "update" | "remove"
  if (attributeName === "open") event.preventDefault()
})

// 2. Protéger un sous-arbre entier
document.addEventListener("turbo:before-morph-element", (event) => {
  if (event.target.matches(".widget-tiers")) event.preventDefault()
})

// 3. Réinitialiser après coup (turbo:morph-element)
document.addEventListener("turbo:morph-element", ({ target }) => { /* … */ })

<%# 4. Le gel complet %>
<div id="map" data-turbo-permanent>…</div>

La documentation ne dit rien de ce qui suit.

data-turbo-permanent n’a pas la même sémantique selon le mode de rendu. En rendu classique, le sélecteur est [id][data-turbo-permanent] : l’id est obligatoire, et le nœud DOM existant est transplanté dans le nouveau corps par Bardo. Sous morph, c’est un autre code, avec d’autres règles.

Sous le capot interne

Sous morph, beforeNodeMorphed et beforeNodeAdded s’occupent de data-turbo-permanent, avec des critères différents.

Le guard « ne me touche pas » (beforeNodeMorphed) teste l’attribut du nœud courant : pas besoin d’id, le nœud est laissé tel quel s’il porte déjà data-turbo-permanent. Si seul le HTML entrant ajoute l’attribut, ce premier morph a lieu ; les suivants seront gelés. Le guard de beforeNodeAdded, lui, teste bien l’id, mais avec la polarité inverse : beforeNodeAdded = (node) => !(node.id && node.hasAttribute("data-turbo-permanent") && document.getElementById(node.id)) (morphing.js#L61-L63). Un élément permanent entrant qui porte un id déjà présent dans le document est donc refusé : c’est l’existant qui gagne. Sans id, il est inséré normalement.

Autre chose, qui explique bien des surprises. MorphingPageRenderer et MorphingFrameRenderer réduisent tous les deux Bardo à async preservingPermanentElements(callback) { return await callback() }. Sous morph, la machinerie de transplantation de Drive ne tourne pas du tout.

Sous morph, un nœud courant qui porte data-turbo-permanent gèle son sous-arbre complètement. Les mises à jour serveur légitimes à l’intérieur n’arriveront jamais. C’est l’outil de dernier recours, pas le réflexe.

Enfin, turbo:before-morph-element est aussi émis pour les nœuds sur le point d’être supprimés, et dans ce cas detail.newElement vaut undefined. Un listener qui écrit event.detail.newElement.matches(…) lèvera une TypeError un jour ou l’autre.

Les broadcasts

Les macros de broadcast tiennent en une ligne. Leurs erreurs, elles, n’apparaissent souvent qu’en production.

Quatre macros, et une asymétrie

class Card < ApplicationRecord
  broadcasts_refreshes_to :board   # 1 seul after_commit, tout part vers board
end

Macro	Création	Mise à jour	Suppression
`broadcasts_to :board`	`append` vers `board`	`replace` vers `board`	`remove` vers `board`
`broadcasts`	`append` vers `"cards"`	`replace` vers le flux GID du record	`remove` vers le flux GID
`broadcasts_refreshes`	`refresh` vers `"cards"`	`refresh` vers le flux GID	`refresh` vers le flux GID
`broadcasts_refreshes_to :board`	`refresh` vers `board`	`refresh` vers `board`	`refresh` vers `board`

Lisez la deuxième et la troisième ligne deux fois. broadcasts et broadcasts_refreshes envoient les créations vers le flux de la collection, mais les mises à jour et les suppressions vers le flux propre du record. Une page qui ne fait que turbo_stream_from "cards" verra apparaître les nouvelles cartes et ne verra jamais les modifications ni les suppressions.

Le code est intentionnel, mais turbo_stream_from Card ne corrige pas l’asymétrie : la classe donne le stream "Card", pas "cards". Pour qu’un index reçoive les trois opérations, utilisez une macro _to et abonnez la page au même stream. Avec les macros sans _to, il faudrait écouter le stream de collection pour les créations et celui de chaque record pour les mises à jour et suppressions.

À retenir

Deux macros gardent création, mise à jour et suppression sur un même flux : broadcasts_to :board pour diffuser append / replace / remove, et broadcasts_refreshes_to :board pour ne diffuser que refresh. Les variantes sans _to envoient la création à la collection et le reste au stream propre de chaque record. Un index abonné seulement à la collection voit donc les nouvelles lignes apparaître, puis plus rien bouger.

Autre asymétrie utile à connaître. Pour les trois premières macros, les suppressions sont synchrones alors que les créations et mises à jour passent par un job. C’est logique (une suppression n’a rien à rendre), mais ça veut dire que la suppression n’est pas soumise au debounce. broadcasts_refreshes_to échappe à ça justement parce qu’elle n’installe qu’un seul after_commit : tout y est asynchrone et passe par le debounce, y compris le destroy.

Le chemin complet d’un refresh

L’onglet qui écrit reçoit son propre broadcast, comme tous les autres. Tout le mécanisme d’identifiant de requête n’existe que pour lui permettre de l’ignorer.

Chaque fetch de Turbo génère un UUID, l’ajoute à un ensemble borné à 20 entrées, et l’envoie en X-Turbo-Request-Id. Côté Rails, un around_action le recopie dans Turbo.current_request_id. Le broadcast le réémet dans l’attribut request-id. À la réception, Session#refresh ignore le refresh si l’identifiant est dans son ensemble local.

La raison est bonne. L’onglet qui a écrit a déjà affiché le résultat de sa requête. Rejouer le refresh coûterait un aller-retour réseau et pourrait faire perdre le scroll ou le focus, selon la configuration du refresh et les nœuds conservés par le morph.

Cette protection disparaît, ou agit au mauvais moment, dans les cas suivants :

Hors requête, Turbo.current_request_id est nul : c’est un thread_mattr_accessor alimenté par un around_action. Tous les onglets rafraîchissent. C’est en général ce que vous voulez depuis un job.
Sans en-tête X-Turbo-Request-Id, par exemple depuis un autre client HTTP, le around_action n’a rien à recopier.
L’ensemble est borné à 20. Vingt nouvelles requêtes Turbo après celle qui a déclenché le broadcast suffisent à évincer son identifiant. Avec le prefetch au survol actif par défaut, ce n’est plus si théorique.
À l’inverse, turbo_stream.refresh rendu en réponse directe porte par défaut l’identifiant de la requête, donc l’onglet demandeur ignore l’action qu’il vient de recevoir. Il faut écrire turbo_stream.refresh(request_id: nil) si cette réponse doit réellement rafraîchir cet onglet.

La variante synchrone broadcast_refresh_to n’est pas une exception, elle passe elle aussi par turbo_stream_refresh_tag, dont le défaut est Turbo.current_request_id (action_helper.rb#L40-L46).

Le debounce, et ce qu’il coûte

broadcast_refresh_later_to passe par un Turbo::ThreadDebouncer mémorisé dans Thread.current, clé (nom de flux, request_id), qui programme un Concurrent::ScheduledTask 0,5 seconde dans le futur. Chaque nouvel appel portant la même clé annule le précédent. Mille records modifiés dans une requête et diffusant vers le même flux donnent donc un broadcast ; mille flux GID distincts restent mille broadcasts.

Côté client, Session#refresh ajoute un second debounce de 150 ms.

Le revers :

Piège

Un processus qui sort avant la fin du délai perd le broadcast. Un rails runner, une tâche rake ou un conteneur peut très bien l’envoyer s’il reste vivant plus de 0,5 s. S’il termine avant le déclenchement de la ScheduledTask, il n’y a ni erreur ni log. Pour un processus one-shot, la variante synchrone broadcast_refresh_to évite ce timing. Ajouter un sleep Turbo::Debouncer::DEFAULT_DELAY + 0.1 reste un workaround, pas un contrat documenté.

Ce bug traverse facilement la revue de code : le script de migration marche, les données sont bonnes, et personne ne remarque que les onglets ouverts n’ont pas bougé.

Dans les tests Rails qui chargent ActiveSupport::TestCase, il n’y a pas de debounce. L’initializer de turbo-rails remplace alors le debouncer par Turbo::ImmediateDebouncer. Pour N appels portant la même clé, vos assertions comptent N broadcasts là où la production n’en verra qu’un. Un test harness qui ne charge pas ActiveSupport::TestCase ne bénéficie pas automatiquement de ce remplacement.

`current_user` n’est pas disponible comme dans une requête

Tout broadcast qui doit rendre son propre HTML, synchrone ou asynchrone, passe par :

ApplicationController.render(formats: [format], **rendering)

broadcast_refresh_later_to, ainsi que les appels qui reçoivent déjà html: ou content:, n’ont rien à rendre et ne passent pas par ce renderer. Pour les autres, il s’agit d’un ActionController::Renderer avec un environnement Rack synthétique. Il n’y a ni session, ni cookies, ni clé Warden. Conséquences mécaniques :

Avec Devise standard, current_user lève Devise::MissingWarden. Le helper appelle warden, absent de l’environnement synthétique. Un partial qui contient if current_user.admin? fait donc échouer le rendu du broadcast ; il ne rend pas silencieusement une branche anonyme. Un helper applicatif personnalisé peut avoir un autre comportement, mais il ne faut pas en dépendre ici.
Current.* n’est pas transmis à un worker asynchrone. Un job réellement pris par la queue s’exécute dans un autre contexte, sans le state de la requête. perform_now et l’adapter :inline peuvent rester dans le même thread et donner l’impression inverse ; les variantes de broadcast synchrones rendent elles aussi dans le thread courant. Ne prenez pas ces chemins comme preuve qu’un worker verra Current.*.
ApplicationController est codé en dur, pas dépouillé de toute sa configuration. Le renderer conserve les view paths configurés et, avec le réglage Rails par défaut include_all_helpers, les helpers applicatifs. En revanche, aucun before_action ne tourne et aucune ivar de requête n’est préparée. Un helper_method qui dépend du state de l’instance du controller reste donc inutilisable.
Le résultat des helpers _url dépend de default_url_options et du default_env du renderer. Avec ce renderer Rails 8.0.2, l’absence de host configuré produit une URL synthétique sur example.org. Ne dépendez pas de ce fallback : configurez Rails.application.routes.default_url_options[:host] pour les broadcasts. Les helpers _path, eux, n’ont pas besoin de host (renderer.rb, v8.0.2).

Le pattern qui passe à l’échelle est le seul qui accepte que le HTML diffusé soit le même pour tous les destinataires : diffuser un partial neutre, et faire charger les parties personnalisées par un frame, que chaque navigateur ira chercher avec ses propres cookies.

<%# le partial diffusé, identique pour tous %>
<div id="<%= dom_id(card) %>">
  <%= card.title %>
  <%= turbo_frame_tag "#{dom_id(card)}_actions", src: card_actions_path(card), loading: :lazy %>
</div>

Les alternatives sont de diffuser un flux par utilisateur, ce qui est correct mais en O(utilisateurs), ou de passer explicitement tout ce dont vous avez besoin par locals: et traiter « ce partial est diffusable » comme une propriété stricte du partial.

C’est aussi une raison pratique de préférer broadcasts_refreshes. Un refresh ne rend rien côté serveur. Chaque navigateur refait sa propre requête, avec sa propre session, et le problème disparaît par construction.

Un flux signé n’est pas un flux autorisé

<%= turbo_stream_from "quotes" %>

Cette ligne produit un signed-stream-name identique pour tous les utilisateurs. La signature empêche la falsification, pas la lecture : le nom est un MessageVerifier, donc du base64 signé, pas du chiffré. Décoder le payload situé avant -- révèle ici la string JSON "quotes". Avec un record, cette string contient son to_gid_param, lui-même décodable en gid://app/Account/5. Aucun de ces décodages ne demande votre clé.

Et Turbo::StreamsChannel#subscribed accepte l’abonnement sans aucune vérification supplémentaire. Il vérifie que la signature est valide, point.

À retenir

Signer n’est pas autoriser. Un signed-stream-name prouve que le nom du flux vient bien de votre application ; il ne prouve rien sur la personne qui s’y abonne, et il n’expire pas par défaut. Porter le tenant dans le nom du flux cloisonne les diffusions accidentelles. Cela n’autorise pas l’abonné : si l’accès doit pouvoir être révoqué, le canal doit contrôler l’utilisateur courant au moment de l’abonnement.

Il faut donc porter le périmètre dans le nom du flux :

broadcasts_refreshes_to ->(quote) { [quote.company, :quotes] }

<%= turbo_stream_from current_company, :quotes %>

Ce cloisonnement ne remplace pas une autorisation. Pour une appartenance révocable, écrivez votre propre canal et faites le contrôle avant stream_from. Le scénario de réabonnement avec un ancien nom signé n’est exploitable que si la connexion Action Cable de cette personne est encore acceptée ; le contrôle du canal ferme cette porte.

Pièges de plomberie

En développement, l’adaptateur Action Cable par défaut est async, mono-processus. Un broadcast déclenché depuis bin/rails console n’atteindra jamais un navigateur connecté à un serveur lancé séparément. Passez sur redis dans config/cable.yml, ou utilisez <%= console %> pour déclencher dans le même processus.

Les jobs de turbo-rails héritent de ActiveJob::Base, pas de votre ApplicationJob. Les retry policies, callbacks et queue_as définis uniquement sur ApplicationJob ne s’appliquent donc pas. Les trois classes déclarent discard_on ActiveJob::DeserializationError, mais elles ne transportent pas les mêmes arguments. Avec ActionBroadcastJob et BroadcastJob, un record présent dans les rendering options puis supprimé avant le perform fait abandonner le job sans retry ; les helpers d’instance ajoutent justement self aux locals:. Le stream et la target sont déjà convertis en chaînes avant l’enqueue. BroadcastStreamJob, utilisé pour un refresh, ne reçoit que le nom du stream et le <turbo-stream> déjà rendu, tous deux sous forme de chaînes. Rails ne repropage pas une erreur de désérialisation traitée par discard_on, mais écrit un log au niveau error et émet discard.active_job.

Stimulus et les bibliothèques tierces

Le cycle de vie, précisément

Stimulus ne sait rien de Turbo. Il réagit à un MutationObserver, dans la microtask qui suit chaque modification.

Sur une visite classique qui conserve un snapshot, turbo:before-cache lance la capture, mais le clone n’est pas immédiat : PageView#cacheSnapshot attend le prochain event loop tick, et la visite n’attend pas cette Promise avant de poursuivre le rendu. L’échange de <body> et la microtask du MutationObserver peuvent donc faire tourner disconnect() avant le clone. Un cleanup synchrone dans disconnect() peut nettoyer aussi la copie différée ; l’ordre n’en fait toutefois pas un contrat. turbo:before-cache reste le hook public et déterministe pour préparer le snapshot.

Sous morph, il n’y a pas de disconnect/connect pour les éléments simplement modifiés en place. Stimulus exécute ces callbacks pour un ajout, une suppression ou un déplacement. Ce dernier peut être direct ou passer par la pantry, y compris avec moveBefore. Changer la valeur de data-controller les déclenche aussi. turbo:before-cache, lui, dépend du chemin de visite comme vu plus haut : absent après une soumission non-GET réussie ; absent pour Session#refresh, sauf si le LRU contient déjà un snapshot previewable de l’URL courante et que le document courant est cacheable ; présent pour une visite ordinaire qui conserve son snapshot.

Une fixture de test de Turbo 8.0.23 force la reconnexion ainsi :

addEventListener("turbo:morph-element", ({ target }) => {
  for (const { element, context } of application.controllers) {
    if (element === target) {
      context.disconnect()
      context.connect()
    }
  }
})

Ce n’est pas une API de reconnexion promise par Turbo : la fixture appelle directement le context de Stimulus et reste liée à cette version. À chaque turbo:morph-element, elle parcourt toute la collection application.controllers, mais elle ne reconnecte que les contrôleurs dont l’élément est exactement target. Sur une grande page, le coût vient donc du scan répété, pas d’une reconnexion générale.

Ce qui casse, et pourquoi

À retenir

Toute bibliothèque qui injecte du DOM absent du HTML serveur, ou qui écrit class ou style au runtime, peut entrer en conflit avec le morphing. La casse dépend de ce que le serveur renvoie et de la capacité de la bibliothèque à réconcilier ou reconstruire son state. Ce n’est pas une incompatibilité automatique, mais cette surface demande une protection ou un lifecycle explicite.

Bibliothèque	Ce qui casse	La cause	La parade
Chartkick	Le graphique disparaît, un « Loading… » reste	Chartkick écoute `turbo:before-render` et détruit tous les graphiques, y compris quand `renderMethod` vaut `morph`. Ce comportement n’est pas celui de Chart.js utilisé directement. Le `<script>` qui recréerait le graphique ne se réexécute pas	`Chartkick.config.autoDestroy = false`, puis redessiner sur `turbo:morph`
Alpine.js	Les éléments redeviennent invisibles, les `:class` sautent	Alpine retire `x-cloak` à l’init et écrit `class` et `style.display` à l’exécution. Le HTML serveur ne les connaît pas, le morph les rétablit	Annuler `turbo:before-morph-attribute` pour `x-cloak`, `class` et `style` sur les sous-arbres `[x-data]`
Tom Select, Select2, Choices	Le widget disparaît, la sélection revient en arrière	Le `<div>` injecté n’est pas dans le HTML serveur, donc supprimé. Le `<select>` d’origine survit, donc pas de reconnexion	Rendre côté serveur un wrapper stable qui contient le contrôle et le DOM injecté, puis poser `id` et `data-turbo-permanent` sur ce parent. Sinon, teardown avant son morph et réinitialisation après
Leaflet, Mapbox GL	Carte morte, tuiles grises, ou `Map container is already initialized`	Le DOM interne injecté par la bibliothèque est supprimé, tandis que le conteneur survit ; `disconnect()` ne tourne donc pas	Détruire avant le morph du conteneur, réinitialiser sur `turbo:morph-element`, puis appeler `invalidateSize()` avec Leaflet ou `resize()` avec Mapbox GL
`<dialog>` ouvert en `showModal()`	La page devient inutilisable	Le morph réécrit le contenu mais ne réinitialise pas le top layer du navigateur	Ticket ouvert et non résolu. Fermer le dialogue sur `turbo:before-render`, ou l’exclure du morph
`<details>`	Les panneaux s’ouvrent ou se ferment tout seuls chez tous les spectateurs	`open` est synchronisé comme un attribut ordinaire	Annuler `turbo:before-morph-attribute` pour `attributeName === "open"`
`<turbo-cable-stream-source>`	Des broadcasts sont perdus, ou l’UI croit le câble hors ligne	Un reparenting via le fallback `insertBefore` le désabonne ; un morph en place peut retirer l’attribut runtime `connected` sans reconnecter l’élément	`id` stable, hors des zones réordonnées, et protection de l’attribut `connected` ou `data-turbo-permanent`

Trix et Action Text sont corrigés depuis mars 2025, contrairement à ce qu’affirment encore beaucoup de billets. La technique employée donne un pattern utile pour un custom element sous morph : <trix-editor> pose un attribut connected à l’initialisation et le déclare dans observedAttributes. Le HTML serveur ne le contient pas, donc le morph le retire, attributeChangedCallback se déclenche, et l’élément se réinitialise tout seul.

C’est un custom element auto-réparant. Si vous écrivez le vôtre, faites ça.

Ce qui fuit si vous ne nettoyez pas

Avec Turbo, le même document et son contexte JavaScript peuvent rester actifs longtemps. Toute ressource possédée par une instance de controller doit avoir son teardown dans disconnect() : les setInterval, les addEventListener sur window ou document, les IntersectionObserver et ResizeObserver (qui maintiennent en vie le nœud observé et bloquent la collecte de tout le sous-arbre détaché), les abonnements Action Cable, les instances Chart.js. Une ressource réellement partagée ou singleton suit un autre lifecycle, souvent avec un comptage de références ; chaque disconnect() ne doit évidemment pas la détruire.

Le cas des contextes WebGL vaut d’être cité. Leur quota dépend du navigateur, du GPU et de l’implémentation. Si vous laissez fuiter des cartes Mapbox, le navigateur peut perdre un ou plusieurs contextes ou refuser d’en créer un nouveau ; les canvas concernés peuvent alors devenir blancs ou rester inutilisables jusqu’à leur réinitialisation.

Injecter un stream sans réponse HTTP

Turbo.renderStreamMessage() accepte une chaîne HTML contenant des <turbo-stream> et les applique comme s’ils étaient arrivés par le réseau. Les <script> à l’intérieur des <template> sont activés, les éléments permanents préservés, le focus restauré par id.

C’est ce qu’il faut pour un transport autre qu’Action Cable (WebSocket brut, SSE, postMessage depuis un service worker), un optimistic update construit côté client avant confirmation du serveur, ou un shell natif qui pousse du HTML dans la webview.

Turbo.renderStreamMessage(
  `<turbo-stream action="append" target="messages"><template>…</template></turbo-stream>`
)

Réseau et hors-ligne

Quand la requête échoue, il ne se passe rien

Turbo émet turbo:fetch-request-error, qui bubble jusqu’à document, y compris à travers les shadow roots, avec detail.request et detail.error. Un listener posé sur document l’attrape de façon fiable.

Ce qui arrive ensuite dépend du contexte, et la différence est brutale.

Pour un frame ou une soumission de formulaire, l’utilisateur ne voit rien. Pas de bandeau, pas de toast. console.error, et le frame reste sur son ancien contenu.

Pour une visite Drive, Turbo quitte la page. L’échec réseau est enregistré comme SystemStatusCode.networkFailure, l’adaptateur émet turbo:reload avec reason: "request_failed", puis fait une navigation classique. Hors ligne, cela veut dire la page d’erreur réseau du navigateur, avec tout le contexte JavaScript de l’application perdu. Vous perdez l’état client alors que le réseau vient déjà de tomber.

Sous le capot interne

Le nom reload induit en erreur, et j’ai mis du temps à comprendre ce qui se passait vraiment :
reload(reason) {
  dispatch("turbo:reload", { detail: reason })
  window.location.href = (this.redirectedToLocation || this.location)?.toString() || window.location.href
}
(browser_adapter.js#L130-L134) Ce n’est pas un location.reload(). C’est une navigation pleine page vers la destination de la visite, celle qui vient d’échouer. Sur un clic de lien hors ligne, vous n’atterrissez donc pas sur la page où vous étiez : vous atterrissez sur la page d’erreur réseau à l’adresse du lien, et l’état de la page précédente est perdu.

turbo:reload est en outre dispatché sans cancelable, donc l’écouter ne permet d’empêcher quoi que ce soit. Son detail est l’objet raison complet : event.detail.reason vaut "request_failed", et event.detail.context.statusCode porte le code interne.

D’où le seul point d’interception qui fonctionne, turbo:fetch-request-error, plus tôt dans la chaîne. Le preventDefault() n’y est pas cosmétique, il fait retourner false à #willDelegateErrorHandling, ce qui court-circuite requestErrored, donc recordResponse, donc l’adaptateur n’est jamais sollicité et la navigation n’a pas lieu. En contrepartie, FetchRequest#perform rethrow quand même l’erreur : attendez-vous à une unhandled promise rejection dans la console.

document.addEventListener("turbo:fetch-request-error", (event) => {
  event.preventDefault()   // empêche aussi le rechargement complet sur une visite Drive
  showOfflineBanner(event.detail.error)
})
window.addEventListener("offline", () => showOfflineBanner())
window.addEventListener("online",  () => hideOfflineBanner())

Attention à l’ordre des événements : turbo:before-fetch-response ne se déclenche que s’il y a une réponse. Une détection de perte réseau construite dessus ne se déclenchera jamais quand le réseau est réellement coupé.

Turbo et les service workers

Les navigations Turbo sont des appels window.fetch(). Turbo ne passe pas d’option mode, donc côté service worker la requête a mode === "cors" et, ce qui surprend davantage, destination === "", la valeur par défaut de tout ce qui sort de fetch().

Un service worker qui route sur request.mode === 'navigate' rate donc toutes les navigations Drive. Et le correctif qu’on lit partout, ajouter || request.destination === 'document', ne rattrape rien du tout, car ce destination n’existe que pour les navigations initiées par le navigateur lui-même. Il faut discriminer sur ce que Turbo, lui, envoie vraiment :

const isDocumentNavigation = ({ request }) => {
  const accept = request.headers.get('Accept') || ''

  return request.method === 'GET' && (
    request.mode === 'navigate' ||                                   // navigation navigateur
    (request.destination === '' &&                                   // fetch() de Turbo Drive
     !request.headers.has('Turbo-Frame') &&                           // pas une requête de frame
     !accept.includes('text/vnd.turbo-stream.html') &&                // pas un GET stream
     accept.includes('text/html'))
  )
}

registerRoute(isDocumentNavigation, new NetworkFirst())
registerRoute(
  ({ request }) => ['style', 'script', 'image', 'font'].includes(request.destination),
  new CacheFirst()
)

Les deux exclusions sont indispensables : Frames et Streams utilisent eux aussi fetch(), portent destination === "" et acceptent du HTML. Sans elles, une réponse partielle peut polluer le cache de la même URL utilisée ensuite par Drive. La seconde route, elle, fonctionne telle quelle : ces requêtes sont bien initiées par le navigateur et portent un destination renseigné.

Ce matcher suppose aussi que vos autres fetch() applicatifs en GET ne demandent pas de HTML sans en-tête distinctif. Si c’est votre cas, ces métadonnées HTTP ne suffisent pas à reconnaître Drive : marquez vos requêtes Drive d’un en-tête applicatif depuis turbo:before-fetch-request et faites porter le prédicat dessus.

Deux pannes de service worker reviennent souvent avec Turbo : un mauvais Content-Type et des asset fingerprints incohérents. Ce ne sont pas les deux seules possibles.

Servir une réponse au mauvais Content-Type. Sur une visite Drive, Turbo enregistre contentTypeMismatch, émet turbo:reload puis fait une navigation pleine page vers la destination. Dans un frame, une réponse non HTML laisse le frame inchangé après les événements de fetch. Ce n’est silencieux que dans ce second contexte côté interface.

Servir un HTML dont les asset fingerprints ne correspondent plus. Turbo compare les éléments data-turbo-track="reload" entre snapshots. En cas de divergence, il déclenche un rechargement complet du navigateur. Une boucle n’apparaît que si les réponses suivantes continuent d’alterner entre des HTML et des assets incompatibles ; une entrée de cache périmée ne suffit pas, à elle seule, à garantir la boucle.

Rails 8 ajoute ses propres contraintes :

Placez le service worker à une URL racine stable. Par défaut, son scope ne peut pas remonter au-dessus du répertoire de son URL. Le header HTTP Service-Worker-Allowed peut élargir ce scope, mais il ne règle pas l’URL instable d’un asset fingerprinté par Propshaft. Deux options simples : public/service-worker.js, ou la route que Rails 8 génère, qui est commentée par défaut dans config/routes.rb et qu’il faut donc décommenter : get "service-worker" => "rails/pwa#service_worker", as: :pwa_service_worker. Notez le controller rails/pwa et le chemin sans .js.
Les importmaps ne s’appliquent pas dans un service worker. Il n’y a pas de <script type="importmap"> là-bas. Utilisez importScripts() dans un classic worker, ou enregistrez un module worker avec { type: "module" } et des imports statiques résolus comme de vraies URL de modules, sans importmap.
Les URL d’assets fingerprintés changent avec leur contenu. Un precache manifest écrit à la main périme au premier déploiement qui touche un fichier. Préférez le runtime caching, par request.destination.

Un patch officiel est en cours (turbo#1427, une API Turbo.offline livrée dans un bundle séparé) mais il est ouvert, pas fusionné. N’écrivez pas d’architecture qui en dépende.

Action Cable ne rejoue rien

Ce risque de production reste peu documenté dans Hotwire.

Action Cable est du publish/subscribe sans persistance, sans accusé de réception, sans numéro de séquence et sans historique. Un message publié pendant qu’un consommateur est déconnecté est délivré à ceux qui sont abonnés à cet instant, puis jeté. Il n’y a rien dans le protocole capable de le rejouer.

Action Cable se reconnecte tout seul, et l’onglet reçoit de nouveau les messages suivants. Tout ce qui est passé pendant la coupure est définitivement perdu. La page reste périmée jusqu’à ce qu’une navigation, un catch-up refresh ou un payload ultérieur la resynchronise. Il n’y a ni replay automatique ni indication d’erreur.

Wifi qui bascule, ordinateur qui se réveille, tunnel, déploiement : ce n’est pas un cas limite, c’est le quotidien d’un utilisateur mobile.

La surface publique d’observation dans le DOM tient dans un attribut : <turbo-cable-stream-source> pose et retire connected. On peut instrumenter les callbacks de subscription ou le consumer Action Cable, mais au prix d’un couplage à leurs internals.

Sous le capot vérifié

L’élément dispatche bien un événement, mais pas celui qu’on voudrait : un MessageEvent("message") par payload reçu, qui est le canal par lequel StreamObserver le consomme (cable_stream_source_element.js#L30-L33). Ce qu’il ne dispatche pas, c’est le moindre événement de cycle de vie : subscriptionConnected et subscriptionDisconnected se contentent de poser et retirer l’attribut.

Pour rester sur l’interface publique du custom element, observez donc cet attribut avec un MutationObserver ou, pour un simple bandeau, avec du CSS : turbo-cable-stream-source:not([connected]) ~ .offline-banner { display: block }.

D’où la parade, qui est entièrement du code applicatif. connected est un attribut posé à l’exécution et absent du HTML serveur. Un morph en place peut donc le retirer sans reconnecter l’élément, donnant un faux état hors ligne. Protégez cet attribut, ou rendez la source permanente avec un id stable, avant de l’observer :

document.addEventListener("turbo:before-morph-attribute", (event) => {
  if (event.target.matches("turbo-cable-stream-source") &&
      event.detail.attributeName === "connected") {
    event.preventDefault()
  }
})

// contrôleur Stimulus posé sur <turbo-cable-stream-source>
connect() {
  this.observer = new MutationObserver(() => {
    const isConnected = this.element.hasAttribute("connected")
    if (isConnected && this.wasDisconnected) {
      Turbo.visit(location.href, { action: "replace" })
    }
    this.wasDisconnected = !isConnected
  })
  this.observer.observe(this.element, { attributeFilter: ["connected"] })
}

disconnect() { this.observer.disconnect() }

Traitez aussi visibilitychange (le réveil de la machine) et window.online.

Avec turbo_refreshes_with method: :morph, scroll: :preserve, ce rattrapage coûte un aller-retour et préserve le scroll. Le focus survit si son nœud reste en place ; idiomorph peut aussi le restaurer sur un <input> ou un <textarea> identifié. C’est ce qui rend le couple morphing + broadcasts praticable : le rattrapage devient assez bon marché pour qu’on l’écrive.

Dernière chose à savoir dans le même registre. Session#refresh abandonne aussi, sans retry, un refresh qui arrive pendant qu’une navigation est déjà en cours (!this.navigator.currentVisit). C’est un second chemin, plus étroit, vers la même péremption.

Checklist de debug

Cette checklist résout presque tous les bugs Turbo que j’ai rencontrés. Elle est volontairement mécanique : chaque étape élimine une classe de causes, et les trois premières prennent dix secondes.

1. La console, avant le réseau. Un console.error change complètement le diagnostic. Form responses must redirect → statut HTTP. unknown action ou target or targets attribute is missing → le <turbo-stream> est mal formé. Content missing → identifiant de frame. Console vide et rien à l’écran : cherchez d’abord un no-op silencieux, une target absente ou un événement annulé. Cela oriente le diagnostic, mais ne prouve pas que la réponse était vide.

2. La requête est-elle partie, et avec quels en-têtes. Dans l’onglet Réseau, vérifiez Accept, Turbo-Frame et X-Turbo-Request-Id. L’absence de text/vnd.turbo-stream.html dans Accept empêche la négociation habituelle du format, mais une extension .turbo_stream ou un params[:format] explicite peut encore le sélectionner. Regardez donc aussi l’URL et les params. Si la requête n’est pas partie du tout, cherchez un data-turbo="false" sur un ancêtre.

3. Le statut, et seulement à ce moment-là. 200 sans redirection sur un POST est le classique. Un Content-Type turbo-stream choisit le stream renderer avant que Turbo consulte les page/frame renderers, mais le statut alimente toujours turbo:submit-end.detail.success. Pour une navigation de frame lancée par link ou src, 2xx et 4xx/5xx HTML passent tous par loadResponse(). Pour une réponse HTML ordinaire à une frame form, le statut choisit la branche success ou failure. Il détermine aussi le frame qui reçoit la réponse et le vidage éventuel du cache Drive.

4. La cible existe-t-elle vraiment, à cet instant. Dans la console, document.getElementById("votre_id"). Vérifiez aussi qu’elle n’est pas dans un <template>, dans une <iframe>, ou dans un frame loading="lazy" pas encore chargé : trois endroits où Turbo ne regardera pas.

5. Combien y en a-t-il ? document.querySelectorAll("#votre_id").length. La réponse doit être 1. 2 explique à la fois les streams qui visent le mauvais élément et les morphs qui se comportent bizarrement à distance.

6. Quel renderer a tourné. document.addEventListener("turbo:before-render", e => console.log(e.detail.renderMethod)). MorphingPageRenderer exige une méthode effective morph et un page refresh au sens de PageView. Quand il existe une Visit, cela signifie action: "replace" et le même pathname que la dernière page rendue ; sans Visit, isPageRefresh() vaut directement true. Une soumission pleine page réussie crée une Visit, tandis qu’une réponse en échec prend le chemin de rendu direct. Un <%= yield :head %> manquant fait disparaître la meta morph, mais ce n’est qu’une des causes possibles.

7. Est-ce que ça vient d’un broadcast. Regardez si le HTML reçu est le même pour tout le monde. Avec Devise standard, un partial diffusé qui appelle current_user échoue faute de Warden ; un helper personnalisé peut produire un autre résultat, tout aussi dépendant d’un contexte absent. Rendez un HTML neutre ou passez des locals explicites.

8. Le même test dans Safari, ou sur un iPhone. Une différence limitée à ces navigateurs justifie de vérifier Element.prototype.moveBefore et le fallback insertBefore d’idiomorph. Ce n’est pas une preuve : le code applicatif, le CSS et d’autres écarts d’API restent des suspects. Réduisez le cas avant d’innocenter l’application.

9. Coupez le réseau, et regardez ce qui se passe. C’est le seul moyen de découvrir qu’un clic de lien hors ligne quitte votre application, et que personne n’écoute turbo:fetch-request-error.

Index par symptôme

Symptôme	Cause la plus probable
Le formulaire part, rien ne bouge, console : « Form responses must redirect »	`200` avec du HTML sur un POST. Répondre `422` sur échec, `303` sur succès
Le formulaire met à jour une zone inattendue	Il hérite du frame qui le contient, de son `target`, ou d’un `data-turbo-frame` sur le formulaire ou le bouton
Le frame se vide, « Content missing »	La réponse n’a pas de `<turbo-frame>` de même id. Souvent une redirection vers `/login`. Marquer la page cible avec `turbo_page_requires_reload`
Le stream arrive, visible dans le réseau, aucun effet	La cible n’existe pas dans le DOM. C’est un no-op totalement silencieux
Le stream n’arrive pas sur un lien GET	Ajouter `data-turbo-stream` : sinon l’en-tête `Accept` n’est pas envoyé
`first child element must be a <template> element`	Un `<turbo-stream>` construit à la main sans son `<template>`
Le `Content-Type` est mauvais	Un frame reste inchangé après les événements de fetch ; une visite Drive émet `turbo:reload` puis navigue en pleine page vers la destination
Le JS s’arrête de fonctionner après une navigation	Initialisation sur `DOMContentLoaded`, qui ne se déclenche qu’au premier chargement. Passer à `turbo:load` ou à Stimulus
Le JS s’arrête seulement depuis qu’on a activé le morphing	Les `<script>` inline ne se réexécutent pas. `turbo:before-cache` dépend en plus du chemin : absent après une soumission non-GET réussie ; absent sur `Session#refresh`, sauf si un snapshot previewable de l’URL courante existe déjà et que le document courant est cacheable
Le morphing « ne marche pas », la page se remplace	Sur un page refresh, la méthode effective n’est pas `morph`. Vérifier la meta émise par `turbo_refreshes_with`, donc `<%= yield :head %>`, ou l’attribut `method` du stream `refresh`
Le morphing ne se déclenche pas après un formulaire	Pour une réponse pleine page réussie transformée en Visit, il faut une méthode effective `morph`, `action: "replace"` et le même `pathname`. Sans action explicite, Turbo ne choisit `replace` que pour une redirection vers l’URL complète de départ ; sinon il choisit `advance`. Un 4xx pleine page passe directement par `renderPage`, un 5xx par `ErrorRenderer`, et une soumission de frame suit le renderer du frame : ces branches n’appliquent pas ce test de Visit
Rechargement complet du navigateur à chaque navigation	Divergence de signature `data-turbo-track="reload"`. Normal après un déploiement. Une boucle demande que les réponses successives restent incohérentes ; chercher un asset injecté dynamiquement ou un cache de service worker qui mélange les versions
Les listes s’animent n’importe comment sous morph	Pas d’`id` stable sur les éléments, ou un `id` dupliqué dans l’une des racines de ce morph, ou la balise a changé
Ça marche sur votre poste, ça casse sur iPhone, sous morph	Vérifier la présence de `Element.prototype.moveBefore`. Le fallback `insertBefore` peut déconnecter puis reconnecter les nœuds déplacés ; les navigateurs WebKit partagent souvent ce chemin, mais ce seul symptôme ne prouve ni la cause ni l’innocence du code applicatif
Le texte que l’utilisateur tape est effacé	`syncInputValue` écrit les valeurs courantes des propriétés DOM, et Turbo n’active pas `ignoreActiveValue`
Le bouton retour affiche un contenu périmé	Avec un snapshot de restauration utilisable, Turbo rend ce snapshot une seule fois et ne lance aucun fetch. Sans snapshot utilisable, il repart sur le réseau. `turbo-cache-control: no-cache` si le contenu est sensible
Le bouton retour affiche un widget en double	Le snapshot a gardé le DOM injecté. Le nettoyer dans `turbo:before-cache`, le hook déterministe prévu pour cela. Un `disconnect()` synchrone peut aussi précéder le clone différé, mais ne doit pas être votre seul contrat de cache
Les messages flash n’apparaissent pas sous morph	Un broadcast refresh ne porte aucun flash. Et si le flash a le même `id` et le même texte, le morph ne modifie rien du tout
Un broadcast met à jour la page du mauvais utilisateur	Nom de flux non cloisonné ou canal sans autorisation. Signer n’est pas autoriser
Un broadcast arrive deux fois chez l’auteur	`request_id` absent ou nul, broadcast hors requête, ou identifiant évincé après vingt nouvelles requêtes Turbo
Les mises à jour temps réel s’arrêtent, sans erreur	Le WebSocket est tombé. Action Cable ne rejoue rien. Rattraper sur l’attribut `connected`, après l’avoir protégé du morph
Rien ne se passe quand le réseau est coupé, dans un frame ou un formulaire	`turbo:fetch-request-error` est émis mais personne ne l’écoute
La page d’erreur du navigateur apparaît quand le réseau est coupé, sur un clic de lien	Une visite Drive en échec réseau navigue vers la destination, hors Turbo. `preventDefault()` sur `turbo:fetch-request-error` est le seul moyen de l’empêcher : `turbo:reload` n’est pas annulable
Après le 404 d’un formulaire, le frame affiche l’erreur mais `reload()` revient à l’ancien contenu	Une réponse de formulaire en échec ne remplace pas un `src` déjà présent. Une navigation lancée par un lien ou par `src`, elle, a fixé cette URL avant la requête : `reload()` rejoue alors l’URL en erreur
Après une erreur 500 sur un clic de lien, l’application devient instable	`ErrorRenderer` remplace tout le `<head>`, réactive les scripts sauf avec `data-turbo-eval="false"` et ne fait pas tourner Bardo : `data-turbo-permanent` n’est pas honoré
Le retour arrière est lent depuis qu’un formulaire de recherche existe	Un échec GET avec réponse HTML vide le cache Drive ; dans un frame, tout échec de formulaire le vide
Certaines modifications ne sont pas diffusées depuis un `rails runner`	Le processus est sorti avant la tâche de debounce programmée à 0,5 s. S’il reste vivant au-delà du délai, le broadcast part

Ce qui a changé récemment

Si vous relisez de la documentation ou des billets antérieurs à 2026, méfiez-vous de ces points, tous modifiés dans la version 8.0.21 de janvier 2026 :

data-turbo-cache="false" a été supprimé. C’est data-turbo-temporary.
Turbo.clearCache() a été supprimé. C’est Turbo.cache.clear().
data-turbo-frame="_parent" a été ajouté.
Les attributs method et scroll sur l’action de stream refresh ont été ajoutés : ils écrasent les balises meta, broadcast par broadcast.
before et after dédoublonnent désormais les frères, comme append et prepend le faisaient déjà pour les enfants.

Et quelques éléments présents dans le code mais absents de la référence officielle, tous à ranger sous l’étiquette vérifié : l’événement turbo:before-frame-morph, les options Turbo.config.forms.mode, Turbo.config.forms.submitter, Turbo.config.drive.enabled et Turbo.config.drive.unvisitableExtensions, la réassignation de event.detail.url sur turbo:before-fetch-request, et le fait que turbo:frame-render soit déclaré annulable alors que l’annuler ne produit aucun effet.

Les détails internes sont reliés au code ou aux tests des versions épinglées ; relisez ces sources à chaque montée de Turbo.

Gardez surtout la règle simple : Drive tant qu’une navigation suffit, Frame pour un fragment adressable, Stream quand le serveur doit orchestrer plusieurs cibles. Le cache, le morphing et les broadcasts ne changent pas ce périmètre ; ils changent le trajet ou le rendu.

Si votre application Hotwire accumule ces symptômes, c’est mon travail chez SXN Labs. Je pars d’un cas reproductible, corrige le contrat rompu et vérifie le résultat en production.

Six lots en parallèle, et la facture arrive à l'intégration

2026-08-05T09:00:00+02:00

Six lots fonctionnels, chacun testé et relu, ont produit dix défauts sérieux une fois réunis. Ils avaient été conçus comme indépendants alors qu’ils modifiaient les mêmes devis, sites d’intervention et contacts, appliquaient les mêmes règles métier et réécrivaient certains fichiers communs.

Le logiciel planifie des interventions, envoie des devis à signer et prévient les clients par SMS. Le parallélisme avait raccourci le développement de chaque lot tandis que le travail nécessaire pour obtenir un produit cohérent restait intact.

Le découpage séparait les tickets tout en laissant communes les surfaces qu'ils modifiaient.

Deux lots corrects, un parcours incohérent

Un lot ajoutait l’acceptation d’un devis en ligne : le système vérifiait le devis, confirmait la commande et produisait la facture. Un autre permettait au back-office de modifier le site d’intervention ou de supprimer la demande associée. Chaque comportement était cohérent et couvert par ses tests.

Ensemble, ils ouvraient une brèche entre la vérification et la confirmation. Le back-office pouvait modifier le site d’intervention pendant que le client signait. Le client validait alors la version courante du devis, tandis que le prestataire de signature conservait un contrat décrivant l’ancienne version.

Aucun test isolé ne couvrait cette séquence. Le défaut se trouvait dans leur jointure, autour d’un state partagé qui pouvait changer avant l’acte irréversible.

Les tickets masquaient un système partagé

Une règle métier dupliquée. Trois chemins devaient conserver le destinataire d’un devis, avec trois définitions : une empreinte complète du contact, son identifiant ou aucune vérification.
Un state relu trop tôt. Deux requêtes pouvaient charger le même brouillon et générer deux PDF, sans moyen fiable de déterminer ensuite lequel représentait l’offre acceptée.
Un artefact partagé. Deux branches réécrivaient le schéma de la base. Le merge avait supprimé une table nécessaire aux rendez-vous, malgré un code correct dans chaque branche.

Produire plus vite déplace le goulot

Lorsque chaque lot peut interagir avec tous les autres, le nombre maximal de paires à examiner suit la formule n × (n - 1) / 2 :

Lots parallèles	Calcul	Paires possibles
6	`6 × 5 / 2`	15
10	`10 × 9 / 2`	45

Ces 15 ou 45 paires ne correspondent pas à autant de conflits. Elles forment un plafond ; le coût réel dépend de la densité du graphe de dépendances et du coût de chaque jointure.

L’IA permet à un développeur de lancer plusieurs chantiers à faible coût. La génération, les tests locaux et la review se parallélisent bien. Réconcilier deux interprétations d’une règle métier reste un travail séquentiel qui exige de comprendre le produit entier.

Avant de lancer les lots en parallèle

Le chevauchement lecture/écriture impose une coordination, pas automatiquement une stack. La seconde PR part de la première seulement si elle dépend de son code ou de son schéma.

Cartographier les lectures et écritures. Pour chaque lot, noter les objets lus ou modifiés, les invariants et les artefacts partagés.
Classer les dépendances. Si un lot écrit ce qu’un autre lit ou écrit, ou s’ils partagent un invariant ou un artefact, leur intégration doit être planifiée ensemble.
Empiler les dépendances de code. Si une PR utilise le code ou le schéma de la précédente, la faire partir de cette branche pour qu’elle n’affiche que son diff. Fusionner la stack du bas vers le haut et restack ses descendantes après chaque changement. Une dépendance métier seule exige une coordination d’intégration et un test commun, pas forcément une stack.
Fermer les races. Lier la signature à une version immuable du devis et du site, puis comparer cette version dans la même transaction que la confirmation. Si elle diffère, invalider la signature et régénérer le contrat.
Tester après chaque merge. Régénérer les artefacts partagés, puis rejouer les parcours métier touchés. Une suite verte sur chaque PR ne couvre pas leurs jointures.
Planifier l’intégration. Nommer la personne qui intègre, fixer la cadence et réserver le temps nécessaire. La date annoncée doit inclure ce travail.

Le contraste ne se vérifie pas seulement dans la maquette

2026-07-30T09:00:00+02:00

Une charte graphique peut être magnifique sur le papier et produire des écrans qu’une partie de vos utilisateurs n’arrive pas à lire. Ça m’est arrivé récemment, sur une interface que je développe : des centaines de textes trop pâles sur leur fond, dont le libellé du bouton principal et la barre d’onglets, sur une trentaine d’écrans. Aucune revue de design ne l’avait vu.

Je ne parle ici que d’un morceau de l’accessibilité : le contraste des textes et des indicateurs. Il est visible, mesurable, et pourtant étonnamment facile à rater.

À gauche, l'écran validé en revue. À droite, le même écran dehors, celui que l'utilisateur a vraiment sous les yeux.

Ce que la maquette ne montre pas

Une revue regarde une intention, sur un bel écran, dans de bonnes conditions. La vraie vie, c’est aussi le même écran en plein soleil, sur un téléphone d’entrée de gamme, ou lu par quelqu’un de soixante ans. Un texte gris clair sur fond coloré peut sembler « stylé » dans le fichier de design et devenir invisible dehors.

Dans cette interface, beaucoup de textes sont posés sur un dégradé, une transparence ou un mélange de teintes. La couleur à juger est celle obtenue une fois les couches composées, dans chaque thème et chaque état, pas seulement celle inscrite dans le fichier. La maquette peut et doit éliminer une partie des erreurs. Elle ne peut pas, à elle seule, prouver que l’implémentation finale reste lisible partout.

La couleur écrite dans le fichier n'est qu'un aplat. Ce qui est peint, c'est un dégradé, et le texte blanc y descend jusqu'à 1,5:1 là où AA en demande 4,5.

Ce qu’un score vert ne prouve pas

Le réflexe suivant consiste à lancer Lighthouse, obtenir un joli score vert et cocher la case. Mais un score vert ne prouve pas que chaque texte est lisible. Il signifie que les contrôles automatisables n’ont pas détecté de problème. Les dégradés, les images de fond et certaines superpositions restent difficiles à analyser : ils demandent une vérification dédiée.

Le piège le plus instructif venait de notre propre contrôle. Pour juger un dégradé, il en calculait la couleur moyenne. Une plaque qui va du sombre au clair donnait donc une moyenne rassurante, une couleur peinte nulle part sur l’écran. Le test passait au vert sur une fiction.

Le même dégradé jugé de deux façons. Sur la moyenne, le contrôle passe au vert. Sur l'endroit le plus défavorable, il échoue.

Un contrôle qui affiche vert sur une couleur qui n’existe pas vend de la tranquillité sans rien garantir. Nous l’avons corrigé pour qu’il juge l’endroit le plus défavorable du dégradé, pas sa moyenne.

Pourquoi c’était un problème de produit

Les pires cas n’étaient pas des détails décoratifs. C’était le bouton sur lequel tout le monde clique, la barre de navigation, et le petit cadre qui indique où on se trouve quand on navigue au clavier. Les éléments que tout le monde touche, à peine visibles pour une partie des gens.

Un texte trop pâle, ce n’est pas « un peu moins joli ». C’est un utilisateur qui ne trouve pas le bouton, qui abandonne, qui appelle le support. Sur un produit grand public, la lisibilité est un chiffre de conversion avant d’être une case de conformité.

Ce que nous avons corrigé, et ce qui reste

Nous avons combiné les trois niveaux qui manquaient : la revue de design, le contrôle automatique et l’inspection de l’interface réellement rendue dans le navigateur. Aucun ne suffit seul. Ensemble, ils permettent de trouver les erreurs évidentes, les erreurs d’implémentation et les cas que l’automatisation ne sait pas trancher.

Le point qui compte pour un dirigeant, c’est qu’aucune couleur de marque n’a bougé. Ce qui a changé, c’est l’encre posée dessus. Chaque type de fond a désormais sa couleur de texte dédiée, décidée une fois dans le système de design plutôt que choisie à l’œil écran par écran. Nous sommes passés de centaines de cas insuffisants à une poignée.

Cette poignée est constituée de textes blancs sur le dégradé de marque, là où aucune couleur de texte unique ne respecte le seuil sur toute la surface. Les connaître ne les rend pas conformes. Ce sont des écarts résiduels qu’il reste à traiter en faisant évoluer la composition, par exemple avec un fond local ou un placement différent, sans nécessairement toucher à la palette.

Un garde-fou, pas un audit

Le garde-fou tient dans un petit test qui tourne en quelques secondes à chaque modification. Il ne remplace pas un audit d’accessibilité, et ne couvre même pas toute l’accessibilité. Il fait une chose plus étroite et très utile. Il empêche une nouvelle couleur, un composant refait ou un écran ajouté de repasser sous la barre sans que personne s’en aperçoive.

La bonne question n’est pas « quel est notre score ? »

L’accessibilité n’est pas une faveur rendue à une minorité. Elle rend le produit utilisable par des gens qui vieillissent, qui lisent au soleil ou qui ont simplement une vue moyenne : tout le monde, un jour ou l’autre.

Depuis juin 2025, l’European Accessibility Act impose aussi des exigences d’accessibilité à des catégories précises de produits et de services, notamment le commerce électronique, la banque, les transports et les communications électroniques. Mais la conformité n’est pas la meilleure raison de s’en occuper, et ce test de contraste ne suffit évidemment pas à l’établir.

Pour un dirigeant, les questions utiles sont plus simples : combien de nos utilisateurs arrivent réellement à lire nos écrans ? Qu’est-ce qui nous empêche de redevenir illisibles le mois prochain ? Si la réponse est « la vigilance de l’équipe », c’est qu’il n’y a pas de réponse.

Dans ce cas précis, un premier diagnostic et le garde-fou ont demandé une demi-journée. Si vous avez un produit grand public et que personne n’a jamais vérifié le contraste de l’interface réellement livrée, nous pouvons regarder cela ensemble.

Quand l'IA devient votre point de défaillance unique

2026-07-27T09:00:00+02:00

Récemment, mon tableau de bord de supervision est resté figé pendant trois jours. Les erreurs applicatives de mes projets y sont affichées en continu, agrégées toutes les heures. Pendant trois jours, la tuile a montré des chiffres parfaitement crédibles. Ils dataient de trois jours plus tôt.

Le service de monitoring, lui, n’avait jamais cessé de répondre. Les données étaient là, disponibles, à un appel d’API de distance. Ce qui était tombé, c’est le morceau que j’avais glissé au milieu du tuyau : une session d’IA.

Une panne silencieuse, la pire catégorie

Ce qui rend l’histoire désagréable, c’est que la panne ne ressemblait pas à une panne.

Un agent qui plante affiche une erreur, remonte une alerte, se voit. Ici, l’agent horaire échouait proprement, sans rien écrire, et la page continuait de servir le dernier état connu avec sa mise en forme habituelle. Rien ne clignotait. J’ai découvert le problème en cherchant autre chose.

La cause était banale. L’authentification de l’outil en ligne de commande qui portait la session avait expiré. Pas de quota dépassé, pas de modèle indisponible, pas de mauvaise réponse. Juste un jeton périmé sur un composant dont je n’avais jamais considéré qu’il faisait partie de ma chaîne de collecte.

Pourquoi l’IA était là au départ

Par facilité, et c’est le point intéressant.

L’accès au monitoring existait déjà sous forme d’outil branché à mon assistant. Écrire un prompt du type « récupère les erreurs non résolues, classe-les, écris la synthèse » prend dix minutes et fonctionne du premier coup. Écrire le client d’API équivalent, gérer la pagination, les champs, les cas limites, ça prend une demi-journée et ça ne produit aucune démo impressionnante.

Le choix était donc rationnel à l’instant où je l’ai fait. Il l’était beaucoup moins un mois plus tard, quand ce raccourci était devenu un maillon de production sur lequel reposait la seule vue que j’avais de la santé de mes applications.

C’est un schéma que je vois beaucoup en ce moment dans les entreprises qui « mettent de l’IA » dans leurs process. Le prototype est spectaculaire, la mise en production est indolore, et personne ne repasse derrière pour se demander ce qui se passe le jour où le composant le plus récent et le moins déterministe de la chaîne ne répond plus.

Le correctif, deux cents lignes ennuyeuses

Le remplacement fait environ deux cents lignes de Python. Il lit l’API REST du service de monitoring avec un jeton dédié, filtre les projets qui ne me concernent pas, applique une classification par mots-clés et écrit le résultat. Aucune IA sur le trajet.

Le modèle n’a pas disparu pour autant, il a changé de place. Le tri fin, la formulation d’un diagnostic, la décision de créer ou non une tâche : ça reste une couche au-dessus, qui peut échouer sans conséquence. Si elle ne tourne pas, je perds du commentaire. Avant, je perdais la donnée.

La différence tient en une phrase : la vérité affichée sur mon tableau de bord ne dépend plus de l’état d’authentification d’un assistant.

Ce n’était pas le premier avertissement

Quelques semaines plus tôt, l’agent qui surveille les autres agents s’était mis à m’envoyer des alertes de panne pour des services qui allaient très bien. La raison est qu’il calculait lui-même l’horodatage courant, et le modèle se trompait de journée dans certains créneaux horaires. Huit fausses alertes avant que je comprenne.

Le correctif a été de lui interdire de produire une date. Une date se demande au système d’exploitation, elle ne se déduit pas.

Là encore, la leçon n’est pas « l’IA est peu fiable ». Elle est plus précise. Un modèle de langage est non déterministe par construction, et c’est exactement ce qu’on lui demande quand on veut de la reformulation, du résumé ou de l’arbitrage. Le problème n’apparaît que si on lui confie en plus des tâches où le non déterminisme est un défaut : compter, dater, additionner, aller chercher une valeur qui existe déjà quelque part.

La règle que j’applique maintenant

Mon système personnel compte aujourd’hui quarante-huit agents actifs. Vingt-neuf d’entre eux ne contiennent aucune IA. Ce sont des scripts. Ils lisent une API, calculent, écrivent un fichier, envoient une notification. Ils tournent à l’heure, ils coûtent zéro, et leur mode de défaillance est lisible.

Les dix-neuf autres utilisent un modèle parce qu’ils font quelque chose qu’un script ne sait pas faire : lire une conversation client et en sortir une intention, rédiger un brouillon, hiérarchiser des signaux hétérogènes, proposer trois options et en recommander une.

La frontière que je trace est là. L’IA au-dessus du système, pour le jugement. Jamais dedans, sur le chemin d’acquisition ou de calcul de la donnée.

La question à poser avant d’en mettre partout

Pour un dirigeant qui évalue une automatisation avec de l’IA dedans, la question utile va plus loin que « est-ce que ça marche en démo ». Elle tient en deux temps.

Si le modèle est indisponible pendant trois jours, qu’est-ce qui s’arrête exactement ? Et est-ce que quelqu’un le voit, ou est-ce que l’écran continue d’afficher des chiffres qui ont l’air normaux ?

Si la réponse à la seconde partie est floue, le problème tient à la dépendance plutôt qu’à l’IA. On l’a ajoutée sans lui appliquer les exigences qu’on applique à toutes les autres : détection de panne, mode dégradé explicite, et une hypothèse claire sur ce qui se passe quand elle n’est pas là.

Une automatisation qui ne sait pas dire qu’elle est en panne n’est pas une automatisation, c’est un affichage.

Si vous avez un process où de l’IA s’est installée sans qu’on ait vraiment tracé cette frontière, on peut regarder ensemble ce qui mérite d’y rester et ce qui gagnerait à redevenir un script.

Facturation électronique 2026 : le vrai chantier n'est pas le format

2026-07-23T09:00:00+02:00

La réforme de la facturation électronique arrive, et la question que tout le monde se pose est la mauvaise. Ce n’est pas « quel format ? » ni « quelle plateforme ? ». C’est : est-ce que mon logiciel sait déjà produire une facture électronique propre, cas limites compris ?

Rappel en 30 secondes. Toutes les entreprises assujetties à la TVA en France sont concernées, même les TPE. La réception devient obligatoire dès septembre 2026 ; l’émission suit en septembre 2027 pour les TPE et PME, dès 2026 pour les grandes entreprises et les ETI. En face, une facture non conforme c’est un flux rejeté à l’entrée : retard de paiement, pénalité, risque direct sur la trésorerie.

Générer un Factur-X, techniquement, c’est quelques lignes. Le vrai travail est ailleurs : les avoirs qui doivent référencer la bonne facture, les validateurs SIREN, SIRET, TVA et IBAN, le rapprochement métier, le branchement à une plateforme agréée ou à Chorus Pro. C’est là que la plupart des chaînes existantes calent, parce que le papier laissait passer ce que le XML structuré refuse.

C’est pour ça que j’ai écrit einvoicing et einvoicing-connect, deux gems open source publiées sur RubyGems et déjà utilisées en production. Génération Factur-X PDF/A-3 conforme EN 16931, validateurs intégrés, client Chorus Pro et PPF prêt à brancher, sans SaaS tiers ni dépendance externe. Je les intègre dans un SI Rails existant en quelques jours.

Pour savoir où vous en êtes, j’ai monté une page dédiée avec un diagnostic de 30 minutes pendant lequel je regarde votre stack, votre volumétrie et votre plateforme cible, et vous repartez avec un plan d’intégration concret et un devis ferme.

Voir la page facturation électronique 2026

Et pour vérifier qu’un PDF est déjà conforme, un validateur Factur-X est en libre accès, analyse 100 % locale, sans upload.

Ma haute disponibilité Postgres n'en était pas une, autopsie d'une panne

2026-07-22T18:00:00+02:00

Hier soir, l’ensemble de mes services internes et les logiciels que j’héberge pour mes clients sont devenus injoignables pendant plusieurs heures. Une base Postgres saturée, une haute disponibilité qui n’a pas joué son rôle, et un incident Scaleway par-dessus. Voici l’autopsie, sans filtre, parce qu’une panne qu’on raconte honnêtement vaut mieux qu’une panne que l’on maquille.

Le déclencheur, ou plutôt les déclencheurs

À 22h15 (heure de Paris), Scaleway perd un nœud de son cluster de block storage en fr-par-1 (incident bsp2y5fysy9w). Côté infra, le résultat est immédiat : des machines virtuelles bloquées, et surtout des bases managées gelées sur un stockage devenu inaccessible.

Au même moment, de mon côté, j’avais lancé un batch de jobs d’enrichissement de contacts sur Argos, mon CRM. Ce genre de batch ouvre beaucoup de connexions Postgres, et vite. Est-ce lui qui a saturé le pool, ou la base souffrait-elle déjà du storage Scaleway ? Je n’ai pas de réponse nette, et c’est exactement le piège des incidents corrélés : deux causes plausibles qui tombent dans la même fenêtre, et un doute qui ne se lève qu’après coup. Ce que je sais, c’est que les deux se sont nourris l’un l’autre. Une base qui répond mal, des connexions qui s’accumulent au lieu de se libérer, un batch qui continue d’en réclamer. Le pool atteint sa limite de connexions, et à partir de là, plus aucune application ne peut en ouvrir une seule. Tout tombe en cascade.

Le vrai problème : une HA qui n’en était pas une

Ma base tournait en haute disponibilité, deux nœuds. Rassurant sur le papier. Sauf que les deux nœuds vivaient dans le même datacenter, fr-par-1. Quand l’étage block storage de fr-par-1 est tombé, mes deux répliques sont parties ensemble, à la même seconde. C’est la leçon que je retiens le plus : une redondance ne protège que contre ce qu’elle isole. La mienne couvrait la panne d’un process ou d’une machine, pas celle d’une zone entière. J’avais souscrit une assurance contre un risque, pas contre tous.

Pire, impossible de redémarrer la base. Le moteur Postgres managé restait accroché au stockage défaillant. Je pouvais tuer les connexions zombies et relancer mes applications autant que je voulais, le rétablissement final ne dépendait plus de moi : il était suspendu à la réparation de Scaleway. Se retrouver spectateur de sa propre panne, sans aucun levier, c’est le moment le plus désagréable de la soirée.

La sortie de crise

La situation s’est débloquée dans la nuit, en combinant trois choses. J’ai coupé les connexions restées ouvertes côté Postgres, j’ai redémarré les applications pour repartir sur des pools propres, et Scaleway a fini par réparer le nœud de storage. Ce dernier point était le facteur décisif. Sans lui, le reste ne servait à rien. Mes deux premières actions n’ont fait que préparer le terrain pour que tout reparte proprement une fois l’infra revenue.

Ce que j’en tire, et ce que j’ai déjà fait

Un bon incident, c’est celui qui vous fait enfin faire ce que vous repoussiez. J’ai attaqué trois chantiers dans la foulée.

PgBouncer devant Postgres, d’abord. Un pooler de connexions que je voulais poser depuis longtemps sans jamais m’y mettre. Il borne le nombre de connexions et empêche un batch d’affamer toutes les autres applications. C’est en place.

Un failover en lecture seule dans une autre zone, ensuite. Mes deux nœuds de HA dans le même datacenter, c’était le cœur du problème. J’ai ajouté une réplique lecture seule ailleurs, pour qu’une zone Scaleway qui tombe ne m’emporte plus tout d’un bloc.

De l’observabilité sur les connexions, enfin. Surveiller pg_stat_activity et le taux de remplissage du pool, pour voir la saturation grimper et déclencher une alerte avant qu’elle ne tue tout, au lieu de la découvrir quand le service est déjà par terre.

La leçon, en une phrase

Une dépendance d’infrastructure, aussi solide soit-elle sur le papier, reste un point de défaillance unique tant qu’on ne l’a pas explicitement isolée. Et une redondance qu’on n’a jamais testée contre le bon mode de panne n’est qu’une redondance de façade.

Si vous avez une infra dont vous répétez qu’elle est « en haute dispo » sans avoir vérifié contre quel type de panne exactement, on peut regarder ça ensemble, plutôt que de le découvrir un mardi soir.

Combien de cash on me doit, en tout, là, maintenant ?

2026-07-13T18:00:00+02:00

Toutes les données financières et tous les noms de clients de cet article sont fictifs. Les captures montrent de vrais écrans, avec un jeu de données inventé.

Quand on est seul aux commandes d’une boîte, il y a une question qui revient plus souvent que toutes les autres. Non pas “combien j’ai facturé le mois dernier”, pas “quel est mon chiffre d’affaires annuel”. La vraie question, celle qui décide de tout, c’est : combien de cash on me doit, en tout, et que je vais encaisser ?

Pas dans une fenêtre de 30 ou 90 jours. En tout. Tout ce qui est facturé et pas encore rentré, sans limite de temps, avec ce qui est en retard clairement signalé.

Et le problème, c’est que personne ne me répondait. Mon logiciel de compta me disait ce qui était facturé. Mon CRM ce qui était dans le pipe. Mon compte en banque ce qui était déjà là. Trois vérités partielles, dans trois outils différents, qu’il fallait recroiser à la main dans un tableur le dimanche soir. Autant dire jamais.

Alors j’ai recollé les morceaux à la source, dans Argos.

Argos, de CRM à cockpit de trésorerie

Argos, c’est le CRM que j’ai construit pour SXN Labs. À l’origine il gérait les contacts, les deals, les devis. Le dernier chantier a consisté à lui greffer une brique de suivi de trésorerie, avec une règle que je me suis fixée : afficher des faits, pas des prédictions. Je ne voulais pas d’un modèle qui devine mon avenir. Je voulais la vérité à l’instant T, celle que je peux vérifier ligne à ligne.

Le résultat, c’est un tableau de bord dont l’état par défaut est une phrase que j’adore lire : “Nothing needs your attention.” Quand quelque chose cloche, il le remonte. Quand tout va bien, il le dit, et il se tait. En tête d’écran, quelques chiffres, tous factuels, tous à jour, sans que j’aie rien à saisir.

Le tableau de bord Cash d'Argos, en un coup d'oeil (données fictives).

Sous ce calme apparent, il y a trois petits défis techniques que je trouve intéressants.

Tout le cash en attente, d’un coup

Le chiffre central, c’est le “à encaisser”. La somme de toutes les factures émises et pas encore payées. Pas de fenêtre glissante, pas d’horizon arbitraire. Le total, point.

Sauf qu’un montant brut ne suffit pas. Ce que je veux voir en un coup d’oeil, c’est le HT (ce qui m’appartient vraiment), la part de TVA (que je ne fais que garder pour l’État), et surtout ce qui est en retard. Un client qui doit 8 400 € depuis dix jours, ce n’est pas la même information qu’un client qui a jusqu’à la fin du mois pour me payer. Le premier appelle une relance, le second non.

Ce croisement HT / TTC / retard, Argos le calcule à partir des factures Pennylane. Et c’est là que le choix de Pennylane comme banque et logiciel de compta paie. Pas de rapprochement bancaire à faire, les paiements sont rapprochés nativement des factures, les transactions arrivent déjà catégorisées. Je consomme la donnée telle quelle, je ne reclassifie rien à la main.

Deux comptes, une seule trésorerie

Ma trésorerie vit à deux endroits. Pennylane pour la banque au quotidien. Spiko pour la trésorerie dormante, placée sur des fonds monétaires tokenisés qui rapportent un peu chaque jour.

La trésorerie totale, c’est donc la somme des deux poches. Comme elles sont physiquement distinctes, un compte en banque d’un côté, des parts de fonds de l’autre, il n’y a aucun risque de compter deux fois le même euro. Et si l’une des deux sources tombe, le système retombe proprement sur l’autre plutôt que d’afficher une trésorerie fantôme.

Petite anecdote pour ceux qui ont déjà intégré une API : Spiko renvoie un joli 403 Cloudflare si tu n’envoies pas un User-Agent de navigateur. Le classique “ton urllib est blacklisté par défaut”. Cinq minutes de perplexité, un header, et on passe à la suite.

Et tout le reste, au même endroit

Une fois le cash à encaisser et la trésorerie en place, j’ai ajouté les autres faits qui pèsent sur une petite boîte : les revenus récurrents mensuels, ce qui a été réellement encaissé ce mois-ci, et une estimation du dividende que je pourrais me verser, net après impôt. Toujours la même logique : des chiffres constatés, pas des promesses.

Et parce qu’Argos n’est pas qu’un outil financier, le même écran agrège aussi l’opérationnel : mes applications déployées sont-elles en bonne santé, combien de serveurs sont suivis, quels déploiements ont eu lieu aujourd’hui, ma boîte mail est-elle à jour, mes frais kilométriques sont-ils saisis. Finances, ops et admin, un seul coup d’oeil. Le tout couronné par ce fameux “rien ne requiert ton attention” quand la checklist est verte.

Le twist : moins d’interface, pas plus

Voici la partie contre-intuitive.

La tendance naturelle, quand on ajoute des données à un outil, c’est d’empiler les écrans, les graphiques, les filtres. J’ai fait l’inverse. J’ai réduit la surface de l’interface d’Argos au maximum, et je le pilote désormais presque exclusivement via MCP.

Pour ceux qui ne connaissent pas, MCP (Model Context Protocol) permet d’exposer les fonctions d’une application comme des outils utilisables par un assistant. Concrètement, Argos expose des outils du type list_deals, create_quote, get_metrics_summary, daily_briefing. Du coup, je ne clique quasiment plus. Je parle à mon CRM. “Résume-moi la trésorerie”, “quels devis sont signés mais pas encore facturés”, “crée un deal pour ce prospect”. La réponse arrive, ou l’action se fait, sans que j’ouvre une seule page.

Ce que j’ai compris en construisant ça, c’est que pour un outil que j’utilise seul, l’interface la plus efficace n’est pas une belle page web. C’est une bonne API, correctement décrite, qu’une IA peut manipuler à ma place. L’UI graphique devient l’exception, réservée aux moments où je veux vraiment voir quelque chose.

Un mot sur la confiance, parce que la question vient toujours : tout ce pipeline financier est en lecture seule. Aucune création de facture, aucun virement, aucun mouvement d’argent automatisé. Le système lit, agrège, affiche. Il ne touche jamais à l’argent. C’est un capteur, pas une main.

Le cash sous les yeux, sans le chercher

Restait un dernier détail, et c’est peut-être le plus agréable au quotidien.

Un tableau de bord, aussi juste soit-il, ne sert à rien s’il est enterré dans un onglet que j’ouvre une fois par semaine. Alors je l’ai sorti de l’écran. J’ai posé un petit afficheur e-ink, un TRMNL, sur l’étagère de mon bureau. Il fait tourner l’écran Cash d’Argos (à signer, à facturer, à encaisser, la trésorerie, les impayés, l’encaissé du mois) en rotation avec d’autres écrans du CRM et des écrans plus généralistes : la météo, une photo, et le reste.

Le TRMNL sur mon bureau : la trésorerie, ambiante (données fictives).

L’effet est étonnamment fort. L’information financière n’est plus quelque chose que je vais chercher : elle passe d’elle-même dans mon champ de vision plusieurs fois par jour, entre la météo et une photo, à côté du chapeau et des lunettes de soleil. Je lève les yeux, et régulièrement, je sais où j’en suis. Pas de notification, pas d’app à ouvrir. Juste un chiffre calme, mis à jour tout seul, en noir et blanc sur du papier électronique.

Ce que je retiens

En construisant ce truc pour moi, j’ai validé une conviction : les meilleurs outils qu’on peut fabriquer, ce sont souvent ceux qu’on utilise soi-même en premier, avec de vrais besoins et de vrais irritants. Le suivi de trésorerie d’Argos est né de ma question à moi, celle du cash qu’on me doit. Et cette exigence d’utilisateur, celle qui ne laisse rien passer, finit par infuser dans le produit que je propose à mes clients.

Trois idées à retenir : recoller les données à la source plutôt que dans un tableur, afficher des faits vérifiables plutôt que des prédictions, et accepter que la meilleure interface, c’est parfois celle qui n’existe pas.

La prochaine fois que vous vous demandez combien on vous doit vraiment, posez-vous une autre question : est-ce que votre outil vous répond en un coup d’oeil, ou est-ce que vous devez encore ouvrir un tableur le dimanche soir ?

Retirer Algolia d'un logiciel de santé, la dépendance qui ne se justifiait plus

2026-07-06T18:00:00+02:00

Sur ORIGAMI, le logiciel métier de santé que je développe pour SOS Médecins (voir le case study), la recherche de patients tournait sur Algolia. Un service de recherche hébergé, rapide, tolérant aux fautes de frappe. La semaine dernière, je l’ai débranché entièrement. Le bilan de la modification tient en deux chiffres : 33 lignes ajoutées, 331 supprimées. Et côté utilisateur, personne n’a rien remarqué. C’est exactement le résultat que je visais.

Pourquoi Algolia était là

Le réflexe est connu. On a besoin d’une « vraie » recherche, instantanée, qui pardonne les fautes de frappe, qui remonte le bon patient même quand on tape trois lettres de travers. On regarde Postgres, on se dit que ce sera compliqué, et on branche un service spécialisé. Algolia fait très bien ce travail. En quelques heures, la recherche est fluide et l’affaire semble réglée.

Sauf que « brancher Algolia » ne se résume jamais à une ligne. Dans le code, ça voulait dire une gem côté Ruby, un paquet npm côté front, un initializer à configurer, des clés d’API exposées au navigateur, un job qui réindexait les patients en parallèle de la base à chaque modification, et trois contrôleurs Stimulus qui parlaient directement au client Algolia. Une dépendance, ce n’est pas un bouton qu’on active : c’est une surface qu’on adopte, qu’on met à jour, qu’on surveille et qu’on facture tous les mois.

Le vrai besoin, une fois posé à plat

La question que je ne m’étais pas reposée depuis longtemps : de quelle recherche ai-je réellement besoin, ici ?

La réponse est modeste. On cherche des patients dans le périmètre d’une structure de soins. Le jeu de données se compte en centaines de milliers d’enregistrements, pas en dizaines de millions. Les champs sont simples : un nom, un prénom, quelques identifiants. Le besoin réel, c’est de retrouver « Dupont » quand on tape « dupon », et de le retrouver vite.

Pour ça, Postgres suffit largement, y compris à cette échelle. L’extension pg_trgm calcule une similarité par trigrammes : elle absorbe la faute de frappe et le préfixe incomplet sans qu’on écrive le moindre algorithme de distance à la main. Une table dédiée matérialise le document de recherche de chaque patient, un job l’alimente à la modification, et la recherche s’exécute dans la même base, dans la même transaction, sans aller-retour réseau vers un tiers. Ce backend interne existait déjà et tournait par défaut depuis quelques semaines. Algolia n’était plus qu’un second moteur qu’on trainait par prudence.

Le vrai argument : de la donnée de santé qui voyage

Le KISS est une bonne raison. Ce n’est pas la meilleure ici.

Envoyer des noms de patients vers un index de recherche hébergé à l’étranger, c’est faire sortir de la donnée de santé de son infrastructure. Ça engage l’hébergement des données de santé, le RGPD, le principe de minimisation. Même quand tout est contractuellement carré, c’est une surface de gouvernance de plus : un endroit supplémentaire où de la donnée sensible transite, un sous-traitant de plus à auditer, une clause de plus à défendre le jour où quelqu’un pose la question.

Retirer Algolia, ce n’est donc pas seulement supprimer une dépendance et une facture de 250 € par mois. C’est retirer une raison de s’inquiéter. La donnée patient ne quitte plus la base. Il n’y a plus d’index externe à sécuriser, plus de clés d’API à faire fuir depuis le front, plus de contrat de sous-traitance à surveiller pour une fonctionnalité qu’on savait déjà faire en interne.

Le vrai enjeu de la bascule : que personne ne sente rien

Basculer d’un moteur de recherche à un autre sur un logiciel utilisé en production, ça ne se fait pas d’un coup de commutateur global. Le critère était clair. Côté utilisateur, les temps de réponse de la recherche devaient rester rigoureusement identiques. Pas « à peu près aussi rapide », identique. Une recherche patient qui traîne d’un dixième de seconde de plus, sur un poste de régulation, ça se remarque tout de suite.

Pour valider ça sans risque, j’avais ajouté un booléen par utilisateur, internal_patient_search, qui activait le nouveau moteur pour quelques comptes seulement. Un mécanisme d’activation sélectif, pas un drapeau oublié : le temps de faire tourner les deux backends côte à côte, de comparer les temps de réponse en conditions réelles, et de confirmer que le passage à Postgres ne se sentait nulle part.

Une fois cette validation faite, le flag avait fait son travail. Je l’ai retiré en même temps qu’Algolia, dans la même passe : la colonne en base, la case dans les réglages, les paramètres autorisés du contrôleur, les libellés en deux langues et trois tests devenus sans objet. Un seul booléen touche déjà six endroits du code ; la discipline consiste moins à ne jamais en ajouter qu’à le démonter dès qu’il a fini de servir.

Ce que ce n’est pas

Aucune charge contre Algolia ici. C’est un excellent produit, et il y a des contextes où je le rebrancherais sans hésiter : un gros catalogue e-commerce, une recherche grand public en façade, une tolérance à la faute de frappe à l’échelle de millions de documents. Le sujet n’est pas l’outil.

Le sujet, c’est la question qu’on se pose avant de l’adopter. Non pas « quelle est la meilleure recherche ? », mais « de quelle recherche ai-je besoin, pour ce jeu de données, dans ce contexte ? ». Quand on prend le temps d’y répondre honnêtement, on évite souvent d’importer une dépendance, une facture récurrente, et, dans le cas de la santé, une donnée sensible qui n’avait aucune raison de voyager.

La simplicité est une décision

Absorber la complexité côté prestataire pour que le logiciel reste simple côté client, ça vaut aussi pour la complexité qu’on s’inflige à soi-même. Le meilleur code n’est pas celui qu’on écrit avec le plus d’élégance : c’est celui qu’on retire parce qu’on n’en a plus besoin, et qu’on n’aura plus jamais à maintenir. 331 lignes en moins, une dépendance de moins, une donnée de santé qui reste chez elle, et une interface strictement identique pour l’utilisateur, temps de réponse compris. C’est ça, un bon jour.

Si vous avez sous le capot une dépendance externe qui vous coûte tous les mois sans que vous sachiez vraiment ce qu’elle vous apporte, on peut regarder ensemble ce qui mérite d’y rester et ce qui peut rentrer à la maison.

L'IA n'a pas supprimé mon métier, elle a déplacé mon plafond

2026-06-22T11:00:00+02:00

On me demande régulièrement si l’IA va remplacer les développeurs. La question est posée à l’envers. Sur mes projets, l’IA n’a supprimé aucune compétence. Elle a déplacé une contrainte que je tenais pour acquise depuis dix ans : mon propre temps.

Le vrai plafond n’a jamais été le code

Quand on développe seul ou à deux un logiciel métier sérieux, ce qui plafonne la production, c’est le nombre d’heures qu’un humain tient dans une semaine sans casser la qualité. Un éditeur de petite taille passe sa vie à arbitrer : cette semaine je branche telle intégration, donc je ne touche pas au module de facturation ; ce trimestre je fais passer une certification, donc la refonte mobile attend.

Simon Willison le résume bien dans un billet récent : si l’IA n’a pas provoqué de vague de licenciements de développeurs, c’est que coder n’est qu’une petite partie du métier. Sur 160 entreprises ayant déclaré des licenciements à New York en 2025, « pas une seule n’a coché la case IA ». Décider quoi construire, spécifier, vérifier, assumer ce qu’on livre, comprendre le contexte métier, rien de tout ça ne s’automatise.

Je suis d’accord. Mais j’en tire une conclusion un peu différente de la sienne. Si le code n’est qu’une petite partie du job, alors accélérer le code ne change pas la nature du métier, ça change sa capacité. Et pour une petite structure, la capacité, c’est presque tout.

Ce que ça change concrètement

Ma façon de travailler a bougé sur le scoping, le chiffrage et la conduite de projet.

Le scoping. Avant, j’écartais d’instinct les fonctionnalités « correctes mais coûteuses » : le mode dégradé propre, le monitoring, les tests d’intégration sur un flux externe. Pas par paresse, par budget-temps. Aujourd’hui, le coût marginal de bien faire a baissé. Je branche le filet de sécurité parce que l’écrire ne me coûte plus une demi-journée.

Le chiffrage. Un forfait, c’est un pari sur le temps. Quand le plafond de production monte, le même périmètre se livre plus vite, ou un périmètre plus ambitieux tient dans la même enveloppe. Ça ne veut pas dire facturer moins ; ça veut dire livrer plus de valeur pour le prix, et passer plus vite à la commande suivante.

La conduite de projet. Plus d’allers-retours avec le client, et plus tôt. Maquetter une variante en un après-midi au lieu d’une semaine, c’est pouvoir dire « regarde, voilà à quoi ça ressemble » avant de figer une décision. La vélocité ne sert pas à produire plus de lignes ; elle sert à raccourcir la boucle entre une idée métier et un truc qu’on peut toucher.

Ce qu’elle ne change pas (et l’angoisse qui va avec)

Il existe une autre lecture, plus sombre, qui circule beaucoup chez les développeurs. Un billet qui a tourné récemment raconte la même histoire de l’intérieur : dix ans à bâtir une expertise pointue (finance, debugging, architecture) pour la voir devenir « promptable » en quelques semaines. L’angoisse n’est pas le chômage, c’est la commoditisation de la maîtrise.

Je comprends le vertige. Mais je crois qu’il confond deux choses : savoir faire, et savoir quoi faire et en répondre. L’IA rend le premier abondant. Le second (décider, spécifier, vérifier, porter la responsabilité de ce qui part en production sur un logiciel sensible) reste rare, et reste à moi.

Le métier ne disparaît pas. Il remonte d’un cran, vers moins de production et plus de jugement.

Pour élargir le sujet

Je vais élargir, en assumant que c’est un avis et pas une démonstration.

On parle beaucoup du problème démographique français : pyramide des âges qui s’inverse, départ des classes nombreuses, relève plus mince derrière. Le débat public se cristallise sur une seule variable, l’âge de départ. C’en est une parmi d’autres. Produire davantage par tête en est une autre, et l’outillage qui augmente la capacité d’un actif y participe directement.

Je ne prétends pas que l’IA règle la démographie, ce serait exactement le genre de raccourci marketing que je passe mon temps à critiquer. Mais quand un même actif peut tenir un volume de production qui en demandait deux hier, ça pèse dans l’équation. C’est moins clivant que de déplacer un curseur d’âge, et probablement plus durable. À condition que les gains aillent à la valeur produite, pas à l’empilement d’outils pour l’outil.

Conclusion

L’IA n’a pas remplacé mon métier. Elle a retiré la limite la plus bête qui pesait dessus : le fait qu’une journée fait vingt-quatre heures. Ce qui reste rare (décider, spécifier, vérifier, assumer) n’a pas bougé d’un pouce. C’est précisément là que se joue la valeur d’un éditeur, solo ou non.

Si vous pilotez une entreprise et que vous vous demandez où l’IA a un effet réel chez vous plutôt qu’un effet de manche, c’est exactement le genre de contexte qu’on peut regarder ensemble, et trancher ce qui mérite vraiment d’être automatisé.

Facture électronique 2026 : la partie que la plateforme ne fera pas pour vous

2026-06-08T15:30:00+02:00

Septembre 2026 est partout. À la radio, dans les mails de la DGFiP, dans les conversations avec les experts-comptables. La date est entrée dans le décor, et c’est plutôt une bonne chose : au moins, cette fois, personne ne découvrira la réforme la veille avec un air surpris et trois fichiers Excel ouverts.

Le problème n’est donc pas que personne ne parle de septembre 2026. Le problème est ce qu’on met derrière cette date. Beaucoup l’entendent encore comme « le début de la facture électronique », ou comme l’échéance des grandes entreprises qui devront émettre. Pour une TPE ou une PME, l’effet concret est plus immédiat : à partir du 1ᵉʳ septembre 2026, vos fournisseurs peuvent vous envoyer de vraies factures électroniques, et vous devez être capable de les recevoir.

Recevoir arrive avant émettre, et c’est précisément la partie qu’on ne contrôle pas. Mais la vraie question, derrière la date, n’est pas quel outil acheter : c’est qui va brancher tout ça sur votre logiciel. Et là, ni la plateforme ni le comptable ne tiennent le rôle.

Ce qui a changé dans le dispositif

Pendant deux ans, le schéma annoncé reposait sur le PPF (le Portail Public de Facturation) comme plateforme par laquelle pourraient transiter les factures. Le dispositif a été recentré : le PPF n’est plus la plateforme publique de transit promise aux entreprises, mais l’infrastructure d’annuaire et de remontée des données vers l’administration. Son rôle consiste à référencer qui reçoit quoi, via quelle plateforme, et à concentrer les informations fiscales utiles à la DGFiP.

Concrètement, ça veut dire trois choses :

Le transit des factures B2B passe désormais par des plateformes agréées (les ex-PDP), immatriculées par la DGFiP. Plus d’option publique simple où tout le monde irait déposer et récupérer ses factures.
Chorus Pro reste la plateforme de référence pour le B2G, la facturation vers le secteur public ne change pas de canal.
Les sanctions ont été renforcées : l’amende sur la facture passe de 15 à 50 € par facture, l’e-reporting de 250 à 500 € par transmission (avec plafonds annuels).

Dans la liste officielle au moment de publication, on trouve par exemple des acteurs connus comme Pennylane, Qonto, Sage, Cegid, Tiime, Indy, Yooz ou Esker. Ce n’est pas une liste de recommandations, plutôt un bon rappel que la réception ne passera pas par un formulaire public magique, mais par un choix d’intermédiaire.

Le calendrier opérationnel reste simple à retenir : réception obligatoire pour tous au 1ᵉʳ septembre 2026, émission pour les grandes entreprises et les ETI à la même date, émission pour les PME et micro-entreprises un an plus tard.

Pourquoi la réception est le piège

Quand on parle de septembre 2026, le réflexe naturel est de demander : « est-ce que je dois émettre ? ». Si vous êtes une PME ou une micro-entreprise, la réponse est souvent non, pas encore. Et c’est là que le malentendu commence.

Quand vous émettez, vous tenez le calendrier. Vous choisissez votre plateforme, vous migrez quand vous êtes prêt, vous testez sur vos propres flux.

Recevoir, c’est l’inverse : c’est votre fournisseur qui décide pour vous. À partir du 1ᵉʳ septembre 2026, dès qu’un de vos fournisseurs grand compte ou ETI bascule en émission électronique (et eux y sont obligés à cette date), vous devez être capable d’ingérer sa facture. Vous ne choisissez ni le moment, ni le format, ni la plateforme d’en face. Vous subissez.

Et « être capable de recevoir », ce n’est pas avoir une boîte mail. Au sens de la réforme, une facture électronique prend l’un de ces formats du socle :

un XML structuré pur (UBL ou CII),
ou un Factur-X : un PDF/A-3 lisible par un humain, avec le même XML CII embarqué à l’intérieur pour la machine.

La différence ne se voit pas à l’œil nu : les deux s’ouvrent dans un lecteur PDF. Si vous voulez savoir dans quelle catégorie tombe ce que produit votre logiciel aujourd’hui, déposez une de vos factures dans le pré-contrôle Factur-X, l’analyse tourne dans votre navigateur, le fichier ne part nulle part.

Recevoir proprement, c’est donc se connecter à une plateforme agréée, récupérer le flux, parser le XML, le valider, puis le rapprocher de vos bons de commande et de vos écritures. C’est un chantier d’intégration, pas un réglage de paramètre. Et c’est précisément le genre de travail qu’on sous-estime tant qu’on ne l’a pas fait.

Le format n’est pas le problème

J’ai écrit deux gems open source autour de ce sujet : einvoicing pour le cœur (génération et lecture de Factur-X, validation, profils CII) et einvoicing-connect pour le raccordement (Chorus Pro, plateformes agréées, e-reporting). À force de les faire tourner sur de vrais flux, une chose s’est imposée : le format est la partie facile.

Produire un Factur-X conforme, c’est mécanique. Un PDF/A-3, un XML CII attaché avec le bon nom de fichier et le bon profil, quelques règles de validation. Une bibliothèque fait ça très bien :

invoice = Einvoicing::Invoice.new(profile: :en16931)
invoice.add_line(description: "Prestation", quantity: 1, unit_price: 950_00)
facturx = invoice.to_facturx(pdf: rendered_pdf)   # PDF/A-3 + XML CII embarqué

Le vrai travail est ailleurs, dans le rapprochement métier. Une facture reçue, il faut la relier au bon fournisseur, au bon bon de commande, à la bonne TVA, gérer les avoirs, les factures partielles, les écarts de centimes, les identifiants qui ne matchent jamais du premier coup. Le XML vous donne des données propres ; il ne vous dit pas quoi en faire dans votre comptabilité. C’est là que part 90 % de l’effort, et c’est la partie qu’aucune plateforme ne fera à votre place.

Le rôle que personne ne tient

Regardez qui intervient vraiment sur le sujet. La plateforme agréée vous livre un flux propre jusqu’à votre porte. L’expert-comptable lit le résultat une fois qu’il est dans la compta. Entre les deux, il reste un espace que ni l’un ni l’autre ne couvre : faire en sorte que votre logiciel (votre app métier, votre ERP, le tableur autour duquel tout tourne) ingère cette facture, la rapproche et en fasse quelque chose d’utile. Cet espace, c’est de l’intégration. C’est le travail d’un dev.

Concrètement, ça tient en trois briques :

Le branchement. Connecter votre logiciel existant à l’API de la plateforme agréée pour que le flux entrant arrive dans votre système, pas dans un énième portail à consulter à la main. Personne d’autre ne connaît votre schéma de données.
Le rapprochement. Les fameux 90 % : relier chaque facture reçue au bon fournisseur, au bon bon de commande, à la bonne TVA, gérer avoirs et écarts, dans votre modèle métier. Aucune plateforme ne le fera, parce qu’aucune plateforme ne connaît votre activité.
Le cycle de vie. La réforme impose de remonter des statuts de facture (reçue, refusée, encaissée…). Ces transitions doivent vivre dans votre workflow réel, pas dans une interface à part que personne n’ira jamais mettre à jour.

C’est là que je me place, et c’est ce que je voulais clarifier ici : je ne vends pas de plateforme. Je fais parler votre logiciel existant la langue de la réforme (ingérer, rapprocher, déclarer), là où la plateforme s’arrête et où votre métier commence.

La bonne question à se poser maintenant

La réforme n’est pas « 2026 pour les gros, 2027 pour les petits », mais 2026 pour tout le monde côté réception, puis 2027 pour une partie des entreprises côté émission.

Donc la question utile va plus loin que « quand dois-je émettre ? » : « le 1ᵉʳ septembre 2026, suis-je capable de recevoir une facture électronique structurée et de l’intégrer sans la ressaisir à la main ? » Si la réponse est non, ce n’est pas un sujet de l’an prochain. C’est un sujet de cet été.

Choisir une plateforme agréée, brancher la réception, tester le parsing sur quelques vraies factures de vos fournisseurs : ça se fait tranquillement en quelques semaines si on s’y prend maintenant, et dans la douleur si on attend que le premier fournisseur bascule sans prévenir.

Préparer la réception sans subir

Un logiciel métier, un ERP bricolé autour d’Excel, une comptabilité qui tient encore parce que quelqu’un ressaisit tout à la main : la facture électronique va vite révéler les endroits où le système fonctionne surtout par patience humaine.

C’est le genre de sujet que je traite chez SXN Labs : cadrer le besoin réel, choisir le bon niveau d’automatisation, brancher la réception et faire en sorte que les factures arrivent au bon endroit sans ajouter une usine à gaz de plus. Si votre réception de factures électroniques risque de devenir un chantier pénible, écrivez-moi.

Hermès : automatiser mon quotidien sans confier les clés à une IA

2026-06-07T14:00:00+02:00

Hermès est mon assistant personnel. Le mien, pas le gros projet open source du même nom qui a fait parler de lui ensuite : j’avais déjà baptisé le dossier ~/Hermes avant qu’il sorte. Le nom était surtout évident pour un système qui transporte des messages, des signaux et des décisions, et le code n’a pas vocation à devenir un produit générique. C’est précisément parce qu’il est très personnel qu’il m’est utile.

Je l’ai construit parce qu’une partie de mon quotidien professionnel ressemble à celui de beaucoup d’indépendants et de petites équipes : des choses importantes sont éparpillées dans Gmail, GitHub, Sentry, Pennylane, Things (mon gestionnaire de tâches), des fichiers Markdown, des dashboards internes et quelques coins de cerveau qui auraient préféré servir à autre chose. Une CI qui tombe, une erreur Sentry qui revient, un devis à relancer, une facture à suivre, un projet presque fini qui risque de rester coincé : aucune de ces tâches n’est très compliquée seule. Leur accumulation, en revanche, finit par créer une charge mentale assez médiocre.

Le pitch ridicule serait de dire que j’ai créé un “operating system agentique personnel”. On pourrait même ajouter “augmenté par l’IA” pour être sûr de perdre tout le monde sauf deux consultants LinkedIn et un vendeur de formation prompt engineering. La réalité est plus simple : Hermès est un ensemble de petits agents locaux, lancés sur mon Mac, avec des fichiers d’état, des scripts Python, un dashboard privé, quelques intégrations métier, et surtout des règles assez strictes sur ce qu’ils ont le droit de faire.

Certains agents utilisent un LLM. Beaucoup n’en utilisent pas. C’est un détail important, parce que le bon usage de l’IA n’est pas de remplacer tous les if par une prière tarifée au million de tokens. Quand une tâche est déterministe, un script bête et fiable est souvent supérieur. Quand il faut résumer des signaux hétérogènes, proposer un arbitrage ou formuler trois options claires, un LLM peut être utile. La difficulté n’est pas d’ajouter de l’IA partout, mais de savoir où elle mérite vraiment d’entrer dans la boucle.

Un outil personnel, pas un framework générique

Je pense de plus en plus que l’IA devient réellement efficace quand elle est intégrée dans un outil très personnel, au sens strict : un outil fait pour une personne, avec ses réflexes, ses angles morts, ses priorités et sa manière de décider. Hermès prolonge ma façon de travailler plutôt qu’il ne se greffe dessus : mes sources d’information, mes seuils de risque, mes habitudes de décision, et les endroits précis où je veux reprendre la main.

C’est pour ça que je suis assez méfiant avec les frameworks d’agents génériques vendus comme des raccourcis. Ils peuvent être utiles pour prototyper, mais leur structure embarque déjà une vision du travail : comment la mémoire fonctionne, comment les tâches sont routées, ce qui compte comme une réussite, quand escalader, comment notifier, ce qu’on considère comme une action. Utiliser le framework d’un autre sans le remettre en question, c’est souvent adopter la logique d’un autre. Parfois elle colle à votre problème. Souvent elle colle surtout à la démo de celui qui l’a écrite.

On a déjà vu ce film avec les SPA React. Pendant des années, des sites vitrines, des back-offices minuscules et des formulaires assez banals ont absorbé la complexité de Facebook en pensant devenir Facebook. Ils ont surtout récupéré le coût mental, les bundles trop lourds, les états clients fragiles et les bugs d’hydratation, sans avoir le problème qui justifiait l’architecture. L’IA prend exactement le même chemin quand on commence par choisir une stack d’agents avant de comprendre le travail réel à automatiser.

Hermès est donc volontairement construit autour de mes contraintes. Mon inbox est ma todo-list. Things est l’endroit des vraies actions. Le dashboard porte les informations passives. Telegram sert aux arbitrages urgents. Les clients, les devis, les incidents et les projets ont déjà des sources de vérité. Le système n’a pas à inventer un monde parallèle ; il doit relier ce qui existe et me déranger seulement quand ça vaut le coût.

Ce que le système doit résoudre

Le besoin de départ n’était pas “avoir un agent”. Je n’avais pas besoin d’un chatbot de plus à qui il faut penser à parler, auquel il faut redonner le contexte, puis dont il faut vérifier la réponse. C’est parfois utile pour réfléchir ou produire un brouillon, mais ça ne retire pas vraiment la charge opérationnelle. Ça la déplace dans une fenêtre de chat, avec une interface plus polie et le même problème derrière.

Ce que je voulais, c’était savoir chaque matin ce qui mérite mon attention, éviter de découvrir trop tard une PR bloquée ou une erreur de production, suivre les devis sans transformer mon cerveau en CRM low-cost, garder le contexte client disponible avant un call, et surtout terminer les sujets proches de la fin au lieu d’ouvrir quinze fronts en parallèle. La plupart de ces besoins sont prosaïques. C’est justement pour ça qu’ils sont importants. Un outil utile commence souvent par retirer de la friction banale, pas par annoncer qu’il va réinventer le travail.

La frontière que j’ai posée dès le départ est simple : Hermès peut observer, classer, résumer, préparer, signaler et proposer. Il ne doit pas se prendre pour moi. Il ne publie pas un devis, n’envoie pas un mail client, ne prend pas une décision d’architecture, ne modifie pas un projet au-delà de correctifs triviaux, et ne crée pas de bruit pour prouver qu’il travaille. J’ai déjà assez de logiciels qui confondent activité et utilité.

Vue d’ensemble anonymisée : le dashboard garde les actions, les signaux et l’état des agents au même endroit, sans transformer chaque information en notification.

Une architecture volontairement ordinaire

Hermès tourne localement sur mon Mac. Un scheduler géré par launchd lit un fichier schedule.toml, regarde quels agents sont dus, applique des préconditions simples, puis lance les jobs. Les runs écrivent leurs logs, leur état, et une page HTML de dashboard. Les états partagés sont des fichiers JSON ou JSONL, les notes plus humaines sont en Markdown, et les tâches déterministes passent par des scripts Python.

Cette architecture n’impressionnera personne dans une conférence sur l’IA, et c’est très bien. Je préfère un système que je peux comprendre à 23 h, quand quelque chose ne tourne plus, à une plateforme magique où trois abstractions propriétaires masquent un cron, une queue et un prompt. Le jour où ça casse, je veux ouvrir un fichier, lire un log, comprendre quel agent a écrit quoi, et corriger. Le reste est souvent de la décoration vendue au prix du SaaS.

Le scheduler limite aussi la concurrence. Il ne lance pas vingt agents parce que vingt agents existent. Certains jobs tournent en Python pur, notamment quand la logique est stable et que l’appel LLM ne ferait qu’ajouter du coût et de l’aléatoire. D’autres passent par un modèle quand ils doivent agréger des signaux moins structurés. Ce mélange n’est pas très dogmatique, mais il a le mérite d’être honnête : l’IA est un composant, pas une religion d’architecture.

Des agents avec un métier précis

Chaque agent a un périmètre étroit. C’est probablement le choix le plus important du projet. Un agent “assistant général” finit vite par avaler tout le contexte disponible et agir avec une confiance inversement proportionnelle à sa compréhension réelle. Un agent qui lit une queue précise, produit un état précis et écrit un dashboard précis est beaucoup plus ennuyeux, mais il est aussi beaucoup plus exploitable.

Le morning briefing prépare la synthèse de début de journée : PRs à revoir, tâches échouées, activité de nuit, signaux Sentry, queue de travail. Inbox triage lit l’inbox Gmail parce que mon inbox est volontairement une todo-list ; il classe les threads, détecte ceux qui vieillissent, peut préparer des brouillons administratifs simples, mais il ne touche pas aux mails client ou prospect. Project focus choisit les trois projets à pousser dans la journée en favorisant ce qui est proche du fini, ce qui a reçu un signal client ou ce qui risque de se bloquer.

Dev agent est encore plus encadré. Il peut traiter quelques erreurs Sentry évidentes, des merges Dependabot sans risque, ou des corrections CI mécaniques. Il n’a pas le droit de faire du produit, de l’architecture, du refactoring ou des bugs applicatifs ambigus. Le moindre doute sort du scope. C’est frustrant pour une démo, mais très sain pour un outil qui touche à de vrais repos.

Les agents business suivent le même principe. Pennylane sync récupère les factures, transactions et soldes pour maintenir une vision de trésorerie, mais il reste en lecture seule. Estimates suit les devis et prépare des propositions, mais aucun envoi ou upload public ne part sans validation explicite. Client context keeper reconstruit des dossiers clients vivants à partir des devis, factures, conversations récentes, PRs et incidents, en préservant les notes manuelles. Rien de tout ça ne remplace le jugement humain. J’arrive devant la décision avec le bon contexte déjà rassemblé.

Project Focus ne cherche pas le projet le plus séduisant. Il pousse ce qui doit avancer : projets presque finis, signaux clients récents, blocages explicites.

L’attention comme contrainte produit

Le plus gros piège de l’automatisation, c’est le système qui marche assez pour produire du bruit. Une alerte inutile devient une interruption, une interruption répétée devient un réflexe d’ignorance, et un système ignoré finit par être pire qu’un système absent : il donne l’impression qu’une surveillance existe alors que plus personne ne l’écoute.

Hermès sépare donc les canaux. Le dashboard contient les informations passives, Things contient les actions que je dois réellement faire, Telegram sert aux urgences ou aux arbitrages courts, et les fichiers d’état gardent l’historique pour les prochains runs. Une facture attendue dans trois jours n’est pas forcément une action. Un client à relancer, oui. Une PR déjà mergée ne doit pas recréer un todo parce qu’un agent a relu un vieux JSON avec l’enthousiasme administratif d’un formulaire Cerfa sous amphétamines.

Il y a de la déduplication, des fenêtres anti-spam, des règles “un sujet = un todo”, et des cas où Hermès choisit explicitement de ne rien me pousser. C’est moins spectaculaire qu’une avalanche de notifications, mais c’est ce qui rend le système utilisable. L’attention est une ressource limitée ; un assistant qui la gaspille travaille contre moi, même si ses intentions sont statistiquement bienveillantes.

Les refus sont une fonctionnalité

La partie la plus importante d’Hermès n’est pas la liste de ce qu’il peut faire, mais celle de ce qu’il refuse. Pas d’envoi automatique de mail client. Pas de publication de devis sans validation explicite. Pas de modification de code au-delà d’un périmètre trivial. Pas de décision d’architecture. Pas de todo Things pour la cuisine interne. Pas de “je pense que…” quand le système peut poser une question claire avec trois options actionnables.

C’est là que l’approche produit compte vraiment. Quand on découvre les agents, le réflexe naturel est d’ajouter des capacités : répondre aux clients, publier les devis, merger les PRs, décider du prochain chantier, réorganiser le planning. Certaines de ces capacités peuvent être pertinentes un jour. Mais la bonne question n’est pas “est-ce possible techniquement ?”. La bonne question est “quelle erreur devient possible si je l’autorise ?”.

Un agent qui peut tout faire n’est pas nécessairement puissant. Il offre souvent une surface d’accident avec une bonne UX. Hermès est utile parce qu’il sait s’arrêter aux endroits où mon jugement reste nécessaire : arbitrer un besoin client, accepter un risque commercial, valider une proposition, décider qu’une demande contredit la raison d’être d’un logiciel. Ces décisions ne sont pas des détails gênants à automatiser ; ce sont précisément les endroits où se trouve la valeur.

Une mémoire inspectable

La mémoire d’Hermès tient dans des fichiers. JSON, JSONL, Markdown. C’est basique, versionnable, inspectable et réparable. Chaque agent lit ce dont il a besoin et écrit dans des zones précises : queue de dev, mémoire des PRs, tâches échouées, signaux projet, réponses aux questions, dossiers clients.

Je n’ai rien contre la recherche sémantique ; Hermès en utilise quand elle apporte quelque chose. Mais la mémoire opérationnelle d’un système de travail doit rester lisible. Un agent qui justifie une décision par “j’ai trouvé ça dans ma mémoire” sans qu’on puisse inspecter la source n’est pas intelligent. Il est pénible à auditer, ce qui est une manière très moderne d’être dangereux.

Le dashboard joue le même rôle. Il ne sert pas à faire joli, même si j’ai fini par lui donner une forme correcte parce que je suis faible devant une interface propre. Il permet surtout de vérifier qu’un agent a tourné, ce qu’il a vu, ce qu’il a fait, et parfois ce qu’il a refusé de faire. Les dates sont absolues, pas relatives, parce qu’un “il y a deux heures” devient vite faux dans une page mise en cache ou une capture. Les timestamps viennent du système, pas de l’imagination du modèle. Un agent qui écrit une date future n’est pas visionnaire, il est juste cassé.

Ce que ça montre vraiment

Hermès est un side project, mais pas un caprice technique. J’y traite mon activité comme un produit interne. Le besoin n’était pas d’utiliser de l’IA ; le besoin était de réduire les oublis, prioriser le travail réellement utile, garder une vision financière exploitable, éviter les tâches administratives répétitives, rendre le contexte client disponible au bon moment et préserver les décisions humaines là où elles ont de la valeur.

Cette logique ressemble beaucoup à celle que j’applique chez mes clients. Avant de développer, il faut comprendre le travail réel : qui fait quoi, avec quelles informations, dans quel ordre, avec quels risques, et quelles décisions ne doivent surtout pas être automatisées. Ensuite seulement on choisit l’outil. Parfois il faut un logiciel sur mesure complet. Parfois il faut automatiser trois étapes pénibles. Parfois il faut surtout arrêter de demander à Excel de jouer l’ERP, le CRM, le planning, le reporting et la conscience collective de l’entreprise. Excel est très fort, mais il a lui aussi droit à une retraite digne.

Je ne vais pas publier Hermès tel quel. Il contient ma vie professionnelle, mes clients, mes finances, mes emails et assez de chemins internes pour faire tousser n’importe quel RSSI normalement constitué. Les principes, eux, sont réutilisables : partir d’une friction récurrente, distinguer information, action et décision, donner un périmètre étroit à chaque automatisation, garder l’état inspectable, mettre l’humain dans la boucle aux bons endroits, et utiliser un LLM pour l’ambiguïté plutôt que pour remplacer un script fiable.

Si ce genre de situation vous parle

Hermès est personnel, mais le problème est très courant : informations dispersées, processus manuels, relances oubliées, décisions prises sans vue d’ensemble, outils SaaS trop génériques, Excel qui tient encore debout par patriotisme local. Dans ces situations, la bonne question n’est pas “comment mettre de l’IA dans l’entreprise ?”, mais plutôt : quelles tâches reviennent tout le temps, quelles décisions demandent vraiment un humain, quelles informations arrivent trop tard, et quels outils existants peuvent être reliés au lieu d’être remplacés.

C’est le genre de travail que je fais chez SXN Labs : comprendre le métier, trouver les vraies frictions, construire le logiciel ou les automatisations qui couvrent le besoin, puis laisser derrière un système simple à utiliser, observable et maintenable. Pas une démonstration magique. Un outil qui sert, avec suffisamment de limites pour rester fréquentable.

Brancher INSi avec TLS strict et continuité métier

2026-06-04T18:00:00+02:00

Un mardi matin, sur un logiciel métier de santé en production dont j’assure le développement et la maintenance, tous les appels au téléservice INSi de la CNAM se sont mis à échouer côté serveur. Plus aucune vérification d’identité patient ne passait.

Côté utilisateur, le logiciel faisait ce qu’il devait faire : il n’affichait pas une stacktrace, il indiquait que la vérification INS n’avait pas abouti. Le patient était là, l’acte pouvait continuer, mais l’identité restait non vérifiée.

L’erreur sous-jacente, remontée par Sentry, tenait en une ligne :

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0
  certificate verify failed (self-signed certificate in certificate chain)

Le diagnostic a pris vingt minutes. La correction propre, deux heures. Mais le sujet n’était pas de reprendre l’UX ou le comportement métier. L’intégration INSi tournait en production avec une vérification TLS stricte et un comportement correct en cas d’échec ; l’incident a surtout rendu visible un sujet d’exploitation qu’il fallait expliciter : la confiance IGC-Santé.

Il fallait remettre le téléservice en marche, sans baisser la sécurité, et conserver cette propriété importante : une panne externe ne devait pas bloquer le travail clinique.

Il existe une mauvaise réponse à ce problème, recopiée partout sur les forums, qu’il faut absolument éviter quand on transporte de l’identité patient. Elle “corrige” TLS à peu près comme couper le voyant moteur corrige une panne.

Le besoin réel

Le besoin métier n’était pas “réussir un handshake TLS”. C’était beaucoup plus simple :

Vérifier l’identité INS d’un patient quand le téléservice répond.
Permettre au soignant de continuer son acte quand le téléservice ne répond pas.
Marquer clairement la donnée comme provisoire tant qu’elle n’a pas été vérifiée.
Savoir avant la panne suivante qu’un certificat va expirer.

La partie TLS n’était qu’un morceau du problème. Important, mais pas suffisant. Une intégration critique a aussi besoin d’une réponse explicite pour les jours où la dépendance externe ne répond pas.

Ce que fait INSi

INSi est le téléservice de la CNAM qui permet à un logiciel métier d’aller chercher ou vérifier l’Identifiant National de Santé d’un patient à partir de ses traits civils : nom, prénom, date et lieu de naissance. C’est une brique centrale pour produire, échanger ou archiver des données de santé avec la bonne identité patient.

L’endpoint vit sur services-ps-tlsm.ameli.fr. C’est du SOAP, authentifié par certificat client délivré via le Portail de Confiance ANS. Côté serveur, la chaîne TLS remonte à la racine IGC-Santé, l’autorité de certification de l’État pour l’e-santé française.

Cette racine n’est dans aucun magasin de confiance système par défaut. Ni Debian, ni Ubuntu, ni macOS, ni le bundle Mozilla embarqué dans la plupart des libs HTTP. C’est une PKI gouvernementale spécialisée, séparée du Web PKI grand public. Si vous ne l’ajoutez pas explicitement, OpenSSL ne la devinera pas par communion administrative.

La fausse bonne idée

Si vous tapez “OpenSSL self-signed certificate in certificate chain Ruby” dans un moteur de recherche, vous tomberez sur dix réponses StackOverflow qui disent la même chose :

# NE FAITES PAS ÇA SUR UN FLUX D'IDENTITÉ PATIENT
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

Sur un script perso qui scrape un site avec un certificat auto-signé, chacun négocie avec sa conscience. Sur un flux qui transporte le numéro de sécu, le nom et la date de naissance d’un patient vers un service authentifié par certificat client ? Surtout pas.

Désactiver verify_mode, c’est :

Accepter n’importe quel certificat en face, y compris un attaquant en MitM sur le réseau.
Trouer la seule garantie cryptographique que la machine en face est bien celle de la CNAM.
Inscrire dans le code, durablement, une régression de sécurité que personne ne reverra jamais.

Et pour rien, puisque la vraie réponse demande peu de temps, elle est documentable, et elle laisse la sécurité en place. Détail appréciable quand on parle d’identité patient.

La correction propre

L’ANS publie publiquement la chaîne IGC-Santé sur son site (autorités racine + intermédiaires, format PEM). Le bon réflexe :

Télécharger la chaîne officielle depuis le portail ANS.
Vérifier les empreintes : SHA-256 du certificat récupéré comparé à celui présenté par l’endpoint live, et à celui publié par l’ANS. Trois sources, un seul hash. Si l’un des trois diffère, on s’arrête.
L’embarquer dans le projet, sous version, distinct des certificats clients (qui eux restent en credentials chiffrés).
Pointer OpenSSL dessus au moment d’instancier le client SOAP.

Côté Rails, ça donne, en simplifiant, ceci dans le service Ameli::Insi :

class Ameli::Insi
  def http_client
    Savon.client(
      wsdl: wsdl_path,
      ssl_cert_file: client_cert_path,
      ssl_cert_key_file: client_key_path,
      ssl_ca_cert_file: igc_sante_bundle_path, # <- la chaîne publique embarquée
      ssl_verify_mode: :peer                   # <- on garde la vérif stricte
    )
  end

  private

  def igc_sante_bundle_path
    Rails.root.join("lib", "certs", "igc_sante.pem").to_s
  end
end

Pour valider de bout en bout avant même de redéployer, openssl fait le boulot :

openssl s_client \
  -connect services-ps-tlsm.ameli.fr:443 \
  -CAfile lib/certs/igc_sante.pem \
  -servername services-ps-tlsm.ameli.fr \
  -showcerts < /dev/null 2>&1 | grep "Verify return code"

Sortie attendue : Verify return code: 0 (ok). À partir de là, le client Ruby remarche, en VERIFY_PEER, sans aucune dégradation de sécurité.

Le comportement utile

Une fois la cause racine corrigée, il restait un point intéressant à expliciter : pourquoi l’incident n’avait pas bloqué le soignant ?

Parce que le logiciel ne traitait pas l’échec INSi comme une exception à jeter à l’écran, mais comme un état métier. Quand INSi répond, l’identité patient est vérifiée. Quand le téléservice ne répond pas, l’erreur technique reste dans Sentry et l’interface indique au soignant que la vérification INS n’a pas pu être effectuée.

La frontière applicative ressemble à ça, en simplifiant :

def fetch_by_traits(patient)
  response = http_client.call(:fetch_by_traits, message: payload_for(patient))
  Ameli::Insi::Identity.from_soap(response)
rescue HTTPI::Error, Savon::Error => e
  Sentry.capture_exception(e, extra: { patient_id: patient.id })
  raise Ameli::Insi::TeleserviceUnavailable
end

Le contrôleur appelant rescue TeleserviceUnavailable et conserve une identité provisoire (les traits civils saisis par le soignant, taggés “non-vérifiés INS”), avec un bandeau qui explique qu’INSi est indisponible et qu’il faudra re-vérifier plus tard. Le soignant continue son acte, le patient n’est pas bloqué, et la donnée sera consolidée au prochain appel réussi.

C’était déjà le comportement utile. Pas spectaculaire, pas très vendeur en démo, mais c’est lui qui compte en production : une dépendance externe qui tombe ne doit pas arrêter la chaîne de soins. Elle doit être traduite en mode dégradé explicite.

Le travail invisible

Cet incident a aussi rappelé un point d’exploitation facile à sous-estimer. Les certificats clients INSi, MSSanté ou Pro Santé Connect sont renouvelés à la main sur le Portail de Confiance ANS, puis stockés dans des credentials chiffrés. L’application peut fonctionner parfaitement pendant des mois, jusqu’au jour où une échéance arrive en silence.

Le jour où l’un d’eux expire, on retrouve exactement la même panne, avec un sentiment de déjà-vu et une envie raisonnable d’insulter un calendrier.

Donc dans la foulée, j’ai ajouté un job quotidien qui parcourt l’inventaire des certificats embarqués : chaînes publiques et certificats clients. Il remonte à Sentry tout certificat à moins de 30 jours d’expiration, puis passe en erreur à 7 jours ou si le certificat est déjà expiré.

J’ai aussi ajouté un runbook de renouvellement versionné dans le repo (lib/certs/README.md), avec la procédure PFC pas à pas. Personne ne le verra tant que ça marche. Le jour où ça menace de casser, ce sera un avertissement exploitable, pas une panne surprise.

Mini-cartographie de la PKI e-santé française

Pour qui découvre l’écosystème, les briques se ressemblent et c’est facile de s’y perdre :

INS : l’identifiant national de santé du patient (NIR ou NIA + traits). C’est la donnée.
INSi : le téléservice CNAM qui permet de récupérer / vérifier un INS. C’est l’API.
MSSanté : la messagerie sécurisée entre professionnels et avec le patient. PKI séparée, certificats émis par les opérateurs MSSanté.
Pro Santé Connect : le SSO d’État pour les professionnels de santé (carte CPS dématérialisée, OIDC).
IGC-Santé : la racine PKI commune qui signe l’essentiel de tout ça côté serveur ANS.

Chaque brique est documentée, chaque chaîne est publique et vérifiable. Le piège, c’est de traiter ça comme un détail technique gênant alors que c’est une partie du produit : identité, sécurité, continuité de service, procédures d’exploitation.

Ce que je retiens

Quand une intégration TLS casse en production, la bonne réponse n’est presque jamais “désactiver la vérification”. C’est : trouver le maillon de confiance manquant, le rendre explicite, le versionner, et l’auditer dans le temps. Le réflexe VERIFY_NONE économise dix minutes sur le moment et laisse une dette de sécurité qui vieillira tranquillement dans le code.

L’autre point, plus produit, c’est qu’une intégration critique doit avoir un mode dégradé. Un téléservice externe en panne, c’est normal sur dix ans d’exploitation. Ici, cette décision existait déjà côté utilisateur : la vérification INS échouait, le soignant était informé, et le soin pouvait continuer.

Le vrai travail a donc été de couvrir la boucle complète : comprendre le besoin clinique, rendre la chaîne de confiance explicite, préserver la sécurité, s’appuyer sur le fallback métier existant, puis surveiller les certificats pour éviter de rejouer la même scène trois mois plus tard avec un autre certificat.

Si ce genre de situation vous parle

Les intégrations e-santé françaises (INSi, MSSanté, Pro Santé Connect, DMP), c’est un mélange de PKI, de certificats, de WSDL et de procédures ANS qui demandent plus de patience que de génie. Ça se fait. Ça marche. Mais il faut cadrer le besoin métier autant que le branchement technique.

C’est le genre de sujet que je traite chez SXN Labs : comprendre ce qui doit vraiment continuer à fonctionner, simplifier le périmètre, brancher proprement, puis laisser derrière un système exploitable. Si vous avez un téléservice santé coincé, écrivez-moi.

Piloter mon spa Intex sans son app

2026-05-31T18:00:00+02:00

J’ai un spa gonflable Intex PureSpa Baltik dans le jardin. Il fonctionne très bien. L’application iOS qui va avec, en revanche, est un drame : il faut un compte cloud Tuya, l’auth lâche tous les trois jours, la moitié des commandes mettent 10 secondes à arriver, et l’interface ressemble à un POC oublié en 2018. Pour un objet qui passe sa vie sur mon Wi-Fi à 3 mètres de mon Mac, l’aller-retour par un serveur en Chine me paraissait inutilement absurde.

Donc j’ai jeté l’app et j’ai écrit la mienne. Un week-end de reverse engineering, puis quelques soirs pour empiler les features que l’app officielle n’aura jamais. Voici ce que ça donne.

Le reverse engineering en 30 minutes

J’ai eu une chance énorme : mathieu-mp/aio-intex-spa avait déjà fait le boulot ingrat. Le module Wi-Fi du spa écoute en TCP sur le port 8990, le protocole est binaire avec un checksum simple (modulo 0xFF, pas 0x100, c’est le piège classique), et les commandes fonctionnelles (power, chauffe, filtration, bulles) sont des toggles : on lit l’état courant et on n’envoie que si l’état désiré diffère. C’est idempotent par construction.

J’ai validé byte-for-byte contre mon vrai spa avec un probe.py autonome (stdlib only, zéro dépendance), puis empaqueté ça dans une couche protocol.py pure qui se teste hors ligne.

Toute l’architecture découle de ces invariants :

Une seule connexion TCP. Le firmware n’accepte qu’un client à la fois sur 8990. Tout passe par un unique IntexSpaClient avec un lock asyncio, possédé par un unique Supervisor.
Le polling sert de keepalive. Le firmware ferme la socket si rien ne parle pendant trop longtemps. Donc on poll toutes les 10 s et ça nourrit aussi l’UI en SSE.
Stale-but-useful. Si le spa devient injoignable, on garde la dernière lecture connue et on affiche un bandeau « hors ligne ». Le prochain poll récupère tout.

Ce que l’app officielle ne fera jamais

Une vraie web UI

FastAPI + HTMX + Chart.js (vendorisé, pas de CDN, l’app vit sur le LAN, elle doit marcher si Internet tombe). Une page mobile-first, un graphique 7 jours de la température, des contrôles instantanés. Le tout servi en un seul processus uvicorn sur mon Mac qui tourne H24.

Un scheduler météo-aware

L’app Intex propose un timer rudimentaire qui n’est même pas exposé via le protocole LAN, donc j’ai écrit le mien. Trois primitives : consigne par tranche horaire, fenêtres de filtration, et surtout « prêt à 18 h » qui calcule le moment de démarrer la chauffe.

La nouveauté intéressante est que le taux de chauffe n’est pas constant. Un spa perd de la chaleur proportionnellement à (eau − air extérieur). Donc je tire la météo locale depuis Open-Meteo (gratuit, sans clé API), j’apprends le coefficient de pertes thermiques sur l’historique des phases de chauffe et de refroidissement, et le scheduler décale automatiquement le démarrage plus tôt quand il fait froid. Si la nuit s’annonce à 4 °C, on commence à chauffer 90 min avant ; si c’est 18 °C, 30 min suffisent.

Une caméra avec détection de housse (expérimentale)

Le spa est à moitié visible dans le champ d’une caméra IP du jardin. J’ai branché ffmpeg pour grabber une frame toutes les 10 s, l’écrire atomiquement (tmp + replace), reconstruire un timelapse mp4 quotidien à la volée, et (pour le fun) détecter si la housse est en place via une ROI calibrable et une heuristique luma + écart-type. C’est partiel et capricieux la nuit, donc ce n’est pas branché sur le scheduler en v1. Mais la plomberie est là pour le jour où.

Un service launchd qui survit aux silent failures

C’est la partie qui m’a pris le plus de temps et que personne ne raconte. Sur cette machine, CPython 3.14 tuait silencieusement le service au bout de ~30 s sous launchd. Pas de traceback, pas de log, juste un process qui meurt. Le coupable est un segfault dans uvloop / httptools / pydantic-core en cas de boucle longue. Retour à 3.12, problème évaporé. Et puis tous les paramètres plist qu’on apprend à la dure : ThrottleInterval=15 pour éviter les boucles de respawn qui saturent launchd, ProcessType=Adaptive (pas Background, sinon le jetsam nous tue en premier sous pression mémoire), ExitTimeOut=20 pour laisser le temps de fermer la TCP proprement, et surtout pas de --workers 1 sur uvicorn (ce flag bascule en mode multiprocess et wedge sous launchd ; le défaut single-process fait exactement ce qu’on veut).

Stack

Python 3.12 + FastAPI + HTMX + Chart.js + ffmpeg + Open-Meteo + launchd + ngrok pour l’accès distant. Pas de base de données. Tout l’état tient dans une poignée de fichiers JSON et JSONL sous state/. 135 tests offline qui tournent en 3 secondes sans toucher au vrai spa (un fake_spa.py rejoue le protocole).

Le pattern réutilisable

Cette boîte noire ressemble à toutes les autres : un device IoT bas de gamme qui exige un compte cloud pour faire le boulot le plus trivial. Le pattern marche aussi pour les ampoules Tuya, les volets Somfy, et probablement la moitié des trucs dans votre maison :

Trouver le port TCP ouvert sur le LAN (un nmap suffit souvent).
Capturer quelques échanges avec Wireshark depuis l’app officielle.
Identifier le checksum et le framing (la doc du protocole est rarement publique mais rarement compliquée).
Réécrire un client minimal, valider byte-for-byte, ajouter ce que le vendeur n’a jamais voulu construire.
Bloquer la sortie WAN du device au routeur, fin du phone-home.

Le code est public, maintenant découpé en deux dépôts : github.com/sxnlabs/onsen-server pour le service FastAPI et le protocole du spa, et github.com/sxnlabs/onsen-app pour l’application. Licences permissives. Si vous avez un PureSpa Baltik, vous pouvez littéralement forker le serveur et l’installer. Et si vous avez un autre device avec le même pattern, lisez intex_spa/protocol.py côté serveur, c’est un bon template pour démarrer le vôtre.

Si ce genre de situation vous parle

Cette histoire de boîte noire, je la croise régulièrement côté pro : une machine industrielle avec une API non documentée, un capteur derrière une app cloud qui ralentit tout le monde, une intégration domotique B2B qu’un fournisseur refuse de faire. C’est exactement ce que je débloque chez SXN Labs. Si vous avez un device coincé qui devrait juste parler à votre SI, écrivez-moi.

SXN Labs

Ce que l'IA n'a pas rendu plus rapide

Ce qui est allé plus vite

Décider

Spécifier

Vérifier

Sécuriser

Répondre de la production

Ce que ça change quand on commande un logiciel

Le popover qui clignote au survol, ce petit bug qui trahit tout le reste

Pourquoi la bulle clignote

Interpréter une intention plutôt que des événements

Deux détails qui font la différence

Ce que je retiens

Un carnet manuscrit hors-ligne dans le navigateur, sans app native

La mise à jour qui efface les notes hors ligne

Le stylet qui écrit « trop épais »

Le trait qui ne colle pas à la pointe

Ce que j’en retiens

Si ce sujet vous parle

Connecter un logiciel Rails à l'ordonnance numérique via Ordoclic

Un logiciel métier qui doit prescrire

Deux chemins, deux surfaces réglementaires

Ce qu’Ordoclic prend en charge

Ce qui reste à l’éditeur

Quand le partenaire est indisponible

Le branchement côté Rails

La certification CNDA, portée par l’éditeur

Le pattern, pour d’autres éditeurs métier

Si vous avez ça dans votre boîte

Le code était juste, le package livré ne l'était pas

Chez moi, ça marche

Trois écarts entre le repo et le package

Les contrôles ajoutés

Au-delà de Ruby

La TVA n'est pas un taux, c'est un régime

Sept régimes, pas un taux

Le champ que le papier ne demandait pas

Trois centimes d’écart, et la facture est refusée

Les taux qui existent quand même

Pourquoi ça devient un problème d’entreprise

La question à poser à son éditeur

Ce que j’en retiens

Quand le code décrit une fonction qui n'existe pas

Une fonction présente uniquement dans le dépôt

Prouver que le code est inaccessible

Supprimer le code, conserver le besoin

Ce que l’audit doit conclure

Turbo n’a pas trois outils, il a trois scopes

Versions et niveau de garantie

Le modèle en une page

Quelle primitive choisir ?

Turbo Drive

Ce qui est intercepté, et ce qui ne l’est pas

Le cycle de vie

Le cache, en chiffres

Turbo.config

Prefetch et preload

Turbo Frames

Tout tient dans un identifiant

Le layout, et le piège du layout statique

Les attributs qui comptent

Turbo Streams

Frames ou Streams ? Ce qui les sépare vraiment

Le trajet complet, du controller à la vue

Huit actions, et morph n’en est pas une

target et targets ne sont pas la même chose

Le silence quand la cible n’existe pas

Ajouter vos propres actions

Le statut HTTP, et pourquoi 422

4xx et 5xx : deux chemins de rendu, pas un

Le morphing

Ce qui déclenche réellement un morph

Ce que le morphing change, ligne à ligne

idiomorph décide par les identifiants

Les déplacements de nœuds, et pourquoi Safari diffère

La valeur des champs n’est pas protégée

La boîte à outils de protection

Les broadcasts

Quatre macros, et une asymétrie

Huit actions, et `morph` n’en est pas une

`target` et `targets` ne sont pas la même chose

`current_user` n’est pas disponible comme dans une requête