Logger.info("panier = #{inspect(panier)}")

Trois défauts, qu’on ne voit pas tant qu’on n’a pas essayé autre chose. Il casse le pipe — il faut sortir la valeur du flux pour l’observer. Il perd la provenance — au sixième log, plus personne ne sait lequel a produit quoi. Et il faut le retirer à la main, ce qu’on oublie une fois sur trois.

Elixir livre une petite échelle d’outils qui règlent ces défauts un par un. On monte d’un barreau quand le précédent ne suffit plus. Toutes les sorties ci-dessous ont été produites sur Elixir 1.19.5 / OTP 28.

Barreau 0 : le shell, comme terrain d’essai

Avant de déboguer quoi que ce soit, il faut un endroit où essayer. C’est iex, et il ne demande aucun projet :

$ iex
Interactive Elixir (1.19.5) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)>

Quatre aides suffisent à s’y sentir chez soi.

h ouvre la documentation sans quitter le shell — h Enum.reduce affiche la doc de la fonction, h Enum celle du module. i interroge une valeur :

iex> i :atome
Term
  :atome
Data type
  Atom
Reference modules
  Atom
Implemented protocols
  IEx.Info, Inspect, JSON.Encoder, List.Chars, String.Chars

v(n) rattrape un résultat qu’on a laissé filer. On a calculé quelque chose de long, on n’a pas pensé à l’affecter : v(3) renvoie le résultat de la troisième expression, et v() celui de la dernière.

La touche tabulation complète les noms de modules et de fonctions. Enum. suivi de tabulation liste tout ce que le module expose ; c’est la façon la plus rapide de découvrir la bibliothèque standard.

Un cas qui bloque tous les débutants : on tape une expression, on oublie un end, et le shell reste coincé à attendre la suite. La sortie de secours est #iex:break :

iex> if true do
...>   :oui
...> #iex:break
** (TokenMissingError) token missing on iex:1:
error: incomplete expression

L’erreur n’est pas un échec : c’est le shell qui abandonne l’expression inachevée et rend la main.

Dans un projet : iex -S mix

Le même shell, mais avec le projet chargé — toutes ses fonctions et toutes ses dépendances accessibles. C’est la façon normale de travailler sur du code Elixir, et pas seulement pour déboguer.

Le compagnon indispensable est recompile() : après avoir modifié un fichier dans l’éditeur, il recompile sans quitter la session, donc sans perdre l’état qu’on a monté à la main. Il répond :ok s’il a travaillé, :noop s’il n’y avait rien à faire.

Et open ouvre le source dans l’éditeur : open Enum.map saute directement à la définition, y compris dans la bibliothèque standard. Il s’appuie sur la variable d’environnement ELIXIR_EDITOR, et retombe sur EDITOR si elle n’est pas définie :

export ELIXIR_EDITOR="zed"

Barreau 1 : IO.inspect et son label:

Premier vrai outil de débogage, et le seul que beaucoup connaissent. Son intérêt tient en une phrase : il renvoie la valeur qu’il reçoit, donc il se glisse dans un pipe sans le casser.

lignes
|> Enum.filter(&(&1.quantite > 0))
|> IO.inspect(label: "après filtre")
|> Enum.map(&(&1.prix * &1.quantite))
|> Enum.sum()

Le label: répond à la question qui vient toujours au sixième affichage : lequel a produit ça ?

après filtre: [%{prix: 30, quantite: 2}, %{prix: 45, quantite: 1}]

Deux options qui évitent des heures perdues

limit: — au-delà d’une centaine d’éléments, l’affichage est tronqué par des points de suspension. Mesuré sur 1.19.5 : la limite par défaut est de 100, une liste de 101 éléments est coupée. On débogue alors une ellipse.

IO.inspect(grande_liste, label: "complet", limit: :infinity)

structs: false — pour voir ce qu’il y a vraiment dans une structure, sans la mise en forme du protocole Inspect :

struct: %Panier{
  client: "Alice",
  lignes: [...]
}

brut: %{
  __struct__: Panier,
  client: "Alice",
  lignes: [...]
}

Sur un %Ecto.Changeset{}, dont l’affichage par défaut cache une bonne partie du contenu, la différence est décisive.

Barreau 2 : dbg, qui montre le chemin et pas seulement l’arrivée

IO.inspect montre une valeur. dbg montre toutes les étapes qui y ont mené, avec le fichier, la ligne et la fonction. Il est disponible partout, sans import ni require.

def total(%Panier{lignes: lignes}) do
  lignes
  |> Enum.filter(&(&1.quantite > 0))
  |> Enum.map(&(&1.prix * &1.quantite))
  |> dbg()
  |> Enum.sum()
end

[lib/panier.ex:8: Panier.total/1]
lignes #=> [%{prix: 30, quantite: 2}, %{prix: 50, quantite: 0}, %{prix: 45, quantite: 1}]
|> Enum.filter(&(&1.quantite > 0)) #=> [%{prix: 30, quantite: 2}, %{prix: 45, quantite: 1}]
|> Enum.map(&(&1.prix * &1.quantite)) #=> ~c"<-"

Deux choses à noter tout de suite.

dbg n’affiche que les étapes jusqu’à lui. Le Enum.sum() placé après n’apparaît pas — ce n’est pas un bug, c’est une macro qui ne voit que le pipe qu’on lui a passé. Pour voir la fin, on déplace le dbg à la fin.

Et cette sortie contient un piège. Regardez la dernière ligne : ~c"<-". C’est la liste [60, 45]. Les entiers 60 et 45 sont les codes des caractères < et -, et comme tous les éléments sont imprimables, Elixir suppose une charlist. L’option :charlists vaut :infer par défaut. On n’est pas obligé de subir :

|> dbg(charlists: :as_lists)

|> Enum.map(&(&1.prix * &1.quantite)) #=> [60, 45]

dbg/2 accepte les mêmes options que inspect/2. C’est le genre de détail qui fait perdre une demi-heure à chercher d’où sort une chaîne bizarre, alors que la valeur était correcte depuis le début.

dbg comprend if et case

C’est sa fonctionnalité la plus sous-estimée. Sur une condition, il montre l’argument, la branche prise, et le résultat :

def remise(total) do
  dbg(if total > 100, do: total * 0.9, else: total)
end

[lib/panier.ex:13: Panier.remise/1]
If condition:
total > 100 #=> true

If expression:
if total > 100 do
  total * 0.9
else
  total
end #=> 94.5

Sur un case, il indique quelle clause a matché :

Case argument:
statut #=> :paye

Case expression (clause #1 matched):
case statut do
  :paye -> "ok"
  :attente -> "patiente"
end #=> "ok"

« Quelle clause a matché » est précisément la question qu’on se pose devant un case qui tombe dans la mauvaise branche. Aucun Logger.info ne répond à ça sans qu’on l’écrive à la main dans chaque clause.

Barreau 3 : le même dbg, en point d’arrêt

Voici l’idée qui change la façon de travailler : on ne modifie pas le code pour déboguer plus fort, on change le lanceur.

iex --dbg pry -S mix

Les dbg() déjà présents dans le code deviennent des points d’arrêt interactifs. Le code est identique ; seule la commande de démarrage a changé.

Le mur qu’on rencontre au premier essai

Sur un projet déjà compilé, la commande échoue :

** (Mix) the application :elixir has a different value set for key :dbg_callback
during runtime compared to compile time. Since this application environment entry
was marked as compile time, this difference can lead to different behavior than expected:

  * Compile time value was set to: {Macro, :dbg, []}
  * Runtime value was set to: {IEx.Pry, :dbg, []}

C’est le mécanisme de validation de Application.compile_env qui parle : le comportement de dbg est figé à la compilation, et il ne peut pas être changé au lancement d’un code déjà compilé. Le message propose lui-même un --no-validate-compile-env — sur 1.19.5, mix run répond --no-validate-compile-env : Unknown option. Ce n’est donc pas la solution.

Le remède est celui que le message donne en deuxième : recompiler.

mix clean && iex --dbg pry -S mix

Une fois arrêté

iex(1)> Panier.remise(200)
Break reached: Panier.remise/1 (lib/panier.ex:13)

   12:   def remise(total) do
   13:     dbg(if total > 100, do: total * 0.9, else: total)
   14:   end

iex(2)> binding()
[total: 200]

binding() donne toutes les variables locales, whereami réaffiche le contexte autour de la ligne, et continue relance l’exécution. Entre les deux, on est dans un vrai shell : on peut appeler n’importe quelle fonction avec les valeurs réelles sous la main.

Quand le dbg est atteint par un autre processus

Dans une requête Phoenix, le dbg n’est pas exécuté par le shell mais par le processus de la requête. IEx demande alors l’autorisation avant de vous confier la main :

Request to pry #PID<0.153.0> at Panier.remise/1 (lib/panier.ex:13)

   12:   def remise(total) do
   13:     dbg(if total > 100, do: total * 0.9, else: total)
   14:   end

Allow? [Yn]

Répondre n laisse le processus continuer normalement — le dbg reprend son affichage habituel. C’est important : un point d’arrêt oublié dans un chemin très fréquenté ne fige pas l’application, il pose une question.

Barreau 4 : break!, sans toucher au code

Les trois barreaux précédents supposent qu’on peut éditer le fichier. Parfois non — le code est dans une dépendance, ou dans la bibliothèque standard. break! pose un point d’arrêt sur une fonction déjà compilée :

iex> break! Panier.remise/1
1

iex> breaks
 ID   Module.function/arity   Pending stops
---- ----------------------- ---------------
 1    Panier.remise/1         1

Et ça marche jusque dans Enum :

iex> break! Enum.map/2
1

iex> Enum.map([1, 2], & &1)
Break reached: Enum.map/2 (/home/runner/work/elixir/elixir/lib/elixir/lib/enum.ex:1688)

iex> binding()
[enumerable: [1, 2], fun: #Function<42.113135111/1 in :erl_eval.expr/6>]

Notez le chemin : /home/runner/work/elixir/elixir/..., celui de la machine qui a construit Elixir. Le fichier n’existe pas chez vous, donc aucun extrait de code n’est affiché — mais l’arrêt a bien lieu et binding() répond. remove_breaks nettoie tout.

Le confort : .iex.exs

Un fichier .iex.exs à la racine du projet est exécuté à chaque ouverture du shell. C’est l’endroit où mettre les alias et les import qu’on retape dix fois par jour :

import Ecto.Query
alias MonApp.{Repo, Comptes, Facturation}

IEx.configure(inspect: [charlists: :as_lists, limit: :infinity])

La dernière ligne referme les deux pièges vus plus haut, pour toute la session : plus de ~c"<-" surprise, plus de listes tronquées.

La frontière avec Logger

Tout ce qui précède sert la boucle de développement. Logger sert autre chose : ce qu’on veut relire demain, en production, filtré par niveau et routé vers un backend.

La différence est vérifiable en trois lignes. Avec Logger.configure(level: :error), un Logger.info disparaît — et le dbg de la ligne suivante s’affiche quand même :

[essai.exs:4: (file)]
:coucou #=> :coucou

dbg ne passe pas par Logger. Il ne connaît ni les niveaux, ni les métadonnées, ni les backends, et il n’a donc rien à faire dans un release. C’est un outil de mise au point, pas de journalisation.

Le partage est simple :

• dbg et IO.inspect : je cherche quelque chose maintenant, et je les retire avant de committer.
• Logger : je veux savoir demain ce qui s’est passé cette nuit.

À retenir

• iex seul est un terrain d’essai sans projet : h, i, v(n), tabulation, et #iex:break pour se dépêtrer d’une expression inachevée.
• iex -S mix charge le projet ; recompile() évite de relancer la session, open saute au source.
• IO.inspect renvoie sa valeur, donc ne casse pas un pipe. label: pour s’y retrouver, limit: :infinity et structs: false quand l’affichage ment par omission.
• dbg montre chaque étape d’un pipe, et pour un if ou un case, quelle branche a été prise. Il accepte les options d’inspect — dont charlists: :as_lists, sans quoi [60, 45] s’affiche ~c"<-".
• iex --dbg pry -S mix transforme ces mêmes dbg en points d’arrêt, sans toucher au code. Il faut recompiler (mix clean) : la valeur est figée à la compilation.
• break! s’arrête dans du code qu’on ne peut pas éditer, dépendances et bibliothèque standard comprises.
• Logger n’est pas un outil de débogage. Un dbg traverse un filtre de niveau qui bloquerait un Logger.info — ce sont deux mécanismes séparés, pour deux besoins séparés.

Quand malgré tout ça une erreur reste illisible, la suite se trouve dans Lire une stacktrace Elixir sans paniquer. Et sur la raison pour laquelle dbg ne peut pas changer de comportement au lancement, Structurer un projet Elixir détaille Application.compile_env.

Ces deux structures ne remplacent pas la liste chaînée. Elles sont faites avec.

Le problème : une file d’attente

Vous voulez une file d’attente : on ajoute d’un côté, on retire de l’autre. Avec une liste, un des deux gestes est forcément coûteux.

Retirer en tête est gratuit. Ajouter en queue recopie toute la liste :

def enfiler(file, x), do: file ++ [x]     # O(n)
def defiler([h | t]), do: {h, t}          # O(1)

Sur cinquante mille allers-retours, ça se voit :

50 000 enfilements puis 50 000 défilements
  liste native (++)   5 194 ms

L’astuce : deux listes au lieu d’une

La solution est ancienne et tient en une idée. Gardez deux listes : celle de l’avant dans le bon sens, celle de l’arrière à l’envers. Enfiler, c’est empiler en tête de l’arrière. Défiler, c’est prendre la tête de l’avant. Et quand l’avant est vide, on retourne l’arrière d’un coup.

# Surtout pas `defmodule File` : ça remplacerait le module de la
# bibliothèque standard, et File.read/1 cesserait d'exister pour le reste
# de la session — avec un simple avertissement qu'on survole.
defmodule FileAttente do
  def new, do: {[], []}

  # Empiler en tête : gratuit.
  def enfiler({avant, arriere}, x), do: {avant, [x | arriere]}

  def defiler({[], []}), do: :vide
  # L'avant est vide : on retourne l'arrière, une fois.
  def defiler({[], arriere}), do: defiler({Enum.reverse(arriere), []})
  def defiler({[h | t], arriere}), do: {h, {t, arriere}}
end

Le Enum.reverse est en O(n), mais il n’arrive qu’une fois par élément inséré : chaque élément est retourné exactement une fois dans sa vie. Réparti sur toutes les opérations, le coût par opération est constant — c’est ce qu’on appelle une complexité amortie.

Le résultat :

  liste native (++)      5 194 ms
  deux listes (maison)       2 ms

Dix lignes, et un facteur 2 600.

:queue, la même chose en mieux testé

Inutile d’écrire ce module : Erlang le fournit depuis toujours, et il fait exactement ça.

file = :queue.new()
file = :queue.in(:a, file)
file = :queue.in(:b, file)

{{:value, premier}, file} = :queue.out(file)
premier   #=> :a

  deux listes (maison)   2 ms
  :queue (OTP)           3 ms

Ma version maison n’est pas plus rapide — elle est juste moins éprouvée. :queue gère aussi les deux bouts : in_r/2 et out_r/1 insèrent et retirent à l’envers, ce qui en fait une file doublement terminée.

Un piège à connaître

:queue.len/1 est en O(n). La documentation l’annonce, et c’est contre-intuitif pour une structure aussi soignée :

100 appels à :queue.len sur une file de 100 000 : 15 ms
100 appels à :queue.is_empty                    :  0 ms

La raison est un choix délibéré : ne pas maintenir de compteur évite de reconstruire la structure à chaque insertion. Conséquence pratique — :queue.len(q) == 0 est une faute, il faut :queue.is_empty(q).

Le module propose par ailleurs trois API, dont une dite « Okasaki » aux noms inversés (cons, snoc, head, tail) que la documentation elle-même qualifie de « by many regarded as strange and avoidable ». Restez sur in, out, peek.

Le zipper : se déplacer dans une structure immuable

Second retour du forum, et il répond à un besoin différent : parcourir une structure en la modifiant au passage, avec la possibilité de revenir en arrière.

Avec une liste, modifier l’élément courant coûte cher, et il n’y a aucun moyen de reculer :

parcourir 50 000 éléments en modifiant chacun
  List.replace_at à chaque pas   20 879 ms

Un zipper applique la même idée que la file : retourner la liste, cette fois autour d’un point de focus. À gauche, ce qu’on a déjà parcouru, stocké à l’envers. À droite, ce qui reste.

defmodule Zipper do
  def depuis(liste), do: {[], liste}

  def droite({gauche, [x | droite]}), do: {[x | gauche], droite}
  def gauche({[x | gauche], droite}), do: {gauche, [x | droite]}

  def lire({_, [x | _]}), do: x
  def remplacer({gauche, [_ | droite]}, v), do: {gauche, [v | droite]}

  def vers_liste({gauche, droite}), do: Enum.reverse(gauche) ++ droite
end

Six lignes utiles. Chaque déplacement fait passer un élément d’une pile à l’autre : temps constant. La modification locale est un simple remplacement de tête : temps constant aussi.

  List.replace_at à chaque pas   20 879 ms
  zipper                              2 ms

Facteur 10 000. Et surtout, une capacité que la liste n’a pas du tout :

z = Zipper.depuis([:a, :b, :c, :d])
z = z |> Zipper.droite() |> Zipper.droite()
Zipper.lire(z)                        #=> :c
z = Zipper.gauche(z)
Zipper.lire(z)                        #=> :b
Zipper.vers_liste(Zipper.remplacer(z, :B))
#=> [:a, :B, :c, :d]

On recule. Dans une liste chaînée, c’est impossible : les cellules ne pointent que vers l’avant.

Là où ça devient vraiment utile

Le zipper prend tout son sens sur un arbre, où l’on garde en plus le chemin parcouru depuis la racine. C’est ce qui permet de descendre dans une structure, de modifier une feuille, et de remonter — sans reconstruire l’arbre entier à chaque étape.

En Elixir, l’implémentation de référence est Sourceror.Zipper, qui travaille sur l’arbre syntaxique. C’est ce qui fait tourner les outils de réécriture automatique de code — et sa documentation est un bon endroit pour comprendre le concept sur un cas réel.

Fred Hebert a écrit l’article de référence sur le sujet en 2010, en Erlang. Il reste la meilleure explication du mécanisme.

Ce que ces deux structures ont en commun

Ni l’une ni l’autre n’abandonne la liste chaînée. Elles en utilisent deux.

C’est le même geste dans les deux cas : placer le coût du bon côté. Une liste est gratuite en tête et chère en queue ; alors on en met deux dos à dos, et les deux extrémités deviennent gratuites. On paie un retournement, mais une seule fois par élément.

Cette idée éclaire aussi la limite. Une liste ne devient pas magiquement indexable : :queue ne sait pas plus accéder au 5 000ᵉ élément qu’une liste, et un zipper doit s’y rendre pas à pas. Pour l’accès par index, il faut une structure d’une autre forme — un vecteur, c’est-à-dire un arbre.

Comment choisir

La question n’est jamais « quelle est la meilleure structure ». C’est « de quel côté vais-je payer ».

Ces deux pistes viennent d’un fil de l’Elixir Forum, en réponse à l’article sur les vecteurs. Merci à dimitarvp, qui a signalé :queue et l’article de Fred Hebert sur les zippers, et à sodapopcan, qui a pointé l’implémentation de Sourceror. Publier sert exactement à ça : je suis reparti avec deux structures que je ne connaissais pas.

Toutes les mesures ont été prises sur Elixir 1.19.5 et Erlang/OTP 28. Les nombres varient d’une machine à l’autre ; les ordres de grandeur, non.

En Elixir, on écrit async: true et ça marche. Il vaut la peine de comprendre pourquoi — parce que les raisons qui le rendent possible dessinent aussi précisément l’endroit où il cesse de vous protéger.

Pourquoi la concurrence est envisageable

Deux tests qui tournent ensemble ne se marchent dessus que s’ils partagent quelque chose de modifiable. En Elixir, il n’y a presque rien à partager : pas de variable globale, pas d’objet mutable, pas de singleton. Chaque test vit dans son processus, avec son propre tas.

Reste exactement une ressource commune, et elle est de taille : la base de données.

C’est là qu’intervient la sandbox.

Ce que fait vraiment la sandbox

Le principe est plus simple qu’il n’en a l’air. Chaque test emprunte une connexion, et la sandbox l’enveloppe dans une transaction. À la fin du test, la transaction est annulée.

# config/test.exs
config :mon_app, MonApp.Repo, pool: Ecto.Adapters.SQL.Sandbox

# test/support/data_case.ex
setup tags do
  pid = Ecto.Adapters.SQL.Sandbox.start_owner!(MonApp.Repo, shared: not tags[:async])
  on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
  :ok
end

Deux tests concurrents travaillent donc sur deux connexions différentes, chacune dans sa transaction non validée. Aucun ne voit ce que l’autre écrit, et personne ne nettoie quoi que ce soit : le ROLLBACK s’en charge.

C’est élégant, et c’est aussi la source des trois pièges qui suivent.

Piège 1 — les autres processus n’ont pas la connexion

En mode :manual, un processus qui n’a pas emprunté de connexion n’a pas accès à la base. Or votre code en démarre : une tâche, un GenServer, un travailleur Oban.

Il faut leur en donner explicitement le droit :

parent = self()

tache =
  Task.async(fn ->
    # En PREMIÈRE ligne de la tâche : autoriser depuis l'extérieur créerait
    # une course, Task.async démarrant l'exécution immédiatement.
    Ecto.Adapters.SQL.Sandbox.allow(MonApp.Repo, parent, self())
    MonApp.Comptes.compter()
  end)

Task.await(tache)

L’ordre compte. Écrire Sandbox.allow(...) après le Task.async semble naturel et fonctionne la plupart du temps — jusqu’au jour où la tâche atteint la requête avant que l’autorisation soit posée. On obtient alors un test rouge par intermittence, le pire genre.

Sans ce allow/3, la tâche échoue sur une erreur de propriété — un message déroutant la première fois, qui n’a rien à voir avec votre requête.

L’autre solution est le mode :shared, où tous les processus se partagent la connexion du test. Il est plus commode, et la documentation en donne le prix sans détour :

The downside is that tests can no longer run concurrently in shared mode.

D’où le shared: not tags[:async] du setup ci-dessus : les tests synchrones prennent le confort, les tests concurrents gardent l’isolation.

Piège 2 — tout se passe dans une transaction jamais validée

Celui-là est le plus coûteux, parce qu’il produit un test vert sur du code faux.

Dans la sandbox, votre test et le code testé vivent dans la même transaction ouverte. Rien n’est jamais validé. Or plusieurs comportements de PostgreSQL ne se manifestent qu’au COMMIT — et vos tests ne l’atteignent jamais.

Le cas typique : du code qui écrit en base puis diffuse une notification, laquelle déclenche ailleurs une relecture de la donnée.

Repo.transaction(fn ->
  {:ok, commande} = Repo.insert(changeset)
  # Diffusé AVANT le COMMIT : c'est le bug.
  Phoenix.PubSub.broadcast(MonApp.PubSub, "commandes", {:creee, commande.id})
end)

En production, l’abonné reçoit le message, relit la commande depuis une autre connexion, et ne la trouve pas : elle n’est pas encore validée.

En test, il n’y a plus de frontière à franchir. Si la relecture a lieu dans le processus de test — le cas le plus courant — elle se fait dans la transaction ouverte, et trouve une commande que personne n’a encore validée. La relecture réussit, et le test passe.

Une précision qui découle du piège précédent : en mode :shared, tous les processus partagent cette connexion, donc le problème est masqué même quand l’abonné est ailleurs. En async: true, un abonné dans un autre processus obtiendrait plutôt une erreur de propriété — le test échouerait bruyamment, ce qui est préférable mais pour la mauvaise raison.

Dans le cas courant, le test ne peut pas voir ce bug, parce que la sandbox supprime précisément la frontière qui le révèle. Un test vert n’est pas une preuve que le code est bon ; c’est une preuve qu’il se comporte bien dans les conditions du test.

La parade est de diffuser après le commit — et pas dans une étape de Multi, car il n’y en a aucune qui s’exécute hors transaction : Multi.run/3 compris, tout se déroule à l’intérieur de celle qu’ouvre Repo.transaction/2.

resultat =
  Multi.new()
  |> Multi.insert(:commande, changeset)
  |> Repo.transaction()

# Ici seulement : la transaction est validée, la donnée est visible de tous.
with {:ok, %{commande: commande}} <- resultat do
  Phoenix.PubSub.broadcast(MonApp.PubSub, "commandes", {:creee, commande.id})
  {:ok, commande}
end

Et il faut savoir que la vérification, elle, devra être faite autrement que par un test unitaire.

Piège 3 — Mox en mode global interdit la concurrence

Mox fonctionne par défaut en mode privé : les attentes posées dans un test ne valent que pour son processus, et il faut un allow/3 pour les partager. C’est ce qui le rend compatible avec async: true.

Le mode global rend les attentes visibles de tous les processus. Plus commode quand le code sous test démarre des processus qu’on ne contrôle pas — et la documentation est catégorique :

An ExUnit case where tests use Mox in global mode cannot be async: true.

C’est la même mécanique que pour la sandbox : dès qu’on partage un état entre processus, on renonce à la concurrence. Le confort se paie en temps de suite.

Un outil sous-utilisé : start_supervised/1

Quand un test démarre un processus, la question est toujours : qui l’arrête ? Un start_link dans un test laisse un processus derrière lui, qui polluera le test suivant.

start_supervised/1 le place sous le superviseur du test, avec une garantie que la documentation énonce ainsi :

The advantage of starting a process under the test supervisor is that it is guaranteed to exit before the next test starts.

test "le cache répond" do
  pid = start_supervised!({MonApp.Cache, nom: :test})
  assert MonApp.Cache.recuperer(pid, :cle) == nil
end

Aucun nettoyage à écrire. Et les processus sont arrêtés dans l’ordre inverse de leur démarrage, ce qui évite qu’un enfant survive à ce dont il dépend.

Ce que vos tests ne prouvent pas

Deux limites à garder en tête, en plus des trois pièges.

Un test qui passe dans la sandbox ne dit rien du comportement transactionnel réel. C’est le piège 2, et il mérite d’être répété : ce que vous validez, c’est le code dans des conditions où la frontière entre connexions n’existe pas.

Un test LiveView ne passe pas par un navigateur. Dans leur forme fondée sur la vue, render_click et render_change envoient l’événement directement au processus. Ils prouvent que votre handle_event fonctionne, pas qu’un utilisateur peut le déclencher — c’est le sujet d’un précédent article.

En résumé

async: true fonctionne en Elixir parce qu’il n’y a presque rien à partager entre processus, et parce que la sandbox transforme la seule ressource commune — la base — en une ressource privée par test.

Les trois limites découlent toutes du même mécanisme. Un processus tiers n’a pas la connexion, sauf autorisation explicite. Le mode partagé et Mox global rendent la commodité contre la concurrence. Et surtout, la transaction jamais validée efface une frontière qui existe en production.

Cette dernière est la seule qui produise un test vert sur du code faux. C’est celle qu’il faut connaître par cœur.

Et presque toujours, elle est comprise de travers — comme une permission de ne pas gérer les erreurs. C’est l’inverse.

Ce que la formule dit vraiment

Elle ne dit pas « ne gérez pas les erreurs ». Elle dit : séparez le code qui travaille du code qui décide quoi faire quand ça rate.

Dans la plupart des langages, les deux sont entrelacés. Chaque fonction attrape ce qu’elle peut, remet une valeur par défaut, journalise, continue tant bien que mal — et vous vous retrouvez avec un objet à moitié initialisé qui traverse trois couches avant de causer un problème ailleurs, quinze minutes plus tard.

Elixir propose autre chose : quand un processus rencontre une situation qu’il ne sait pas décrire, il meurt. Un autre processus, dont c’est le seul métier, le remplace par un neuf dans un état connu.

Le pari est là : il est plus simple de raisonner sur un état frais que sur un état abîmé.

La démonstration

Un compteur supervisé, qu’on incrémente puis qu’on tue :

{:ok, sup} = Supervisor.start_link([{Compteur, name: :c}], strategy: :one_for_one)

GenServer.cast(:c, :incr)
GenServer.cast(:c, :incr)
GenServer.call(:c, :valeur)
#=> 2

pid_avant = Process.whereis(:c)
Process.exit(pid_avant, :kill)
Process.sleep(50)

Process.whereis(:c) != pid_avant   #=> true  — c'est un autre processus
GenServer.call(:c, :valeur)        #=> 0     — l'état est reparti de zéro

Le superviseur a fait exactement son travail : il a remplacé un processus mort par un processus vivant, dans l’état que init/1 définit.

Et les deux incréments sont perdus. C’est le point que les explications enthousiastes passent sous silence, et c’est pourtant le cœur du sujet.

Ce que ça coûte

Trois choses, toutes vérifiables.

L’état disparaît

C’est ce que la démonstration ci-dessus montre. « Let it crash » ne fonctionne que si l’état perdu peut être reconstruit — relu en base, redemandé à un service, recalculé.

Un GenServer qui détient la seule copie d’une donnée importante n’est pas un candidat au redémarrage joyeux : c’est un problème de conception qu’on découvrira le jour du crash. La règle pratique : ce qui doit survivre à un crash ne vit pas dans l’état d’un processus.

Le crash emporte celui qui attendait

Un GenServer.call/2 est synchrone. Si le serveur meurt en traitant la demande, l’appelant ne reçoit pas une erreur qu’il pourrait examiner tranquillement : il reçoit un exit, et meurt à son tour s’il ne l’attrape pas.

defmodule Compteur do
  use GenServer
  def start_link(opts), do: GenServer.start_link(__MODULE__, 0, opts)
  def init(n), do: {:ok, n}
  def handle_call(:boum, _from, _n), do: raise("panne métier")
end

{:ok, pid} = GenServer.start(Compteur, 0)

try do
  GenServer.call(pid, :boum)
catch
  # La raison d'un exit provoqué par une exception est un tuple imbriqué :
  # {{exception, pile}, {GenServer, :call, arguments}}. Filtrer sur
  # {raison, _} attraperait la paire {exception, pile}, pas l'exception.
  :exit, {{raison, _pile}, _} -> IO.inspect(raison)
  #=> %RuntimeError{message: "panne métier"}
end

Le serveur, lui, est redémarré par son superviseur. Mais la requête en cours est perdue, et le processus appelant — souvent un LiveView ou un contrôleur — tombe avec elle. Un crash n’est jamais confiné au seul processus fautif : il se propage à qui l’attendait.

Trop de crashs tuent l’arbre

Un superviseur n’est pas un ressusciteur infatigable. Il compte les redémarrages, et abandonne :

{:ok, sup} = Supervisor.start_link([{Compteur, name: :c3}],
  strategy: :one_for_one, max_restarts: 2, max_seconds: 5)

# Indispensable pour rejouer ceci dans IEx : start_link lie le superviseur à
# vous. Quand il renonce, il sort en :shutdown et emporte la session avec lui.
Process.unlink(sup)

for i <- 1..3 do
  if Process.alive?(sup) do
    Process.exit(Process.whereis(:c3), :kill)
    Process.sleep(60)
  end
  IO.puts("crash #{i} : superviseur vivant ? #{Process.alive?(sup)}")
end

crash 1 : superviseur vivant ? true
crash 2 : superviseur vivant ? true
crash 3 : superviseur vivant ? false

Au-delà de max_restarts redémarrages en max_seconds secondes, le superviseur se termine lui-même — et son propre superviseur applique alors la même logique, un cran plus haut. Une erreur qui se reproduit systématiquement ne tourne donc pas en boucle : elle remonte l’arbre et finit par arrêter l’application.

C’est délibéré et c’est sain. Un service qui redémarre en boucle sans jamais fonctionner est pire qu’un service arrêté : il consomme, il ment aux sondes de santé, et personne ne le remarque. Les valeurs par défaut sont de 3 redémarrages en 5 secondes.

Ce qui n’est PAS un crash

Voilà la distinction qui manque à toutes les explications rapides, et elle est décisive.

Une erreur attendue n’est pas un crash. Un utilisateur introuvable, un formulaire invalide, une adresse mal formée, un service externe qui répond 503 : ce sont des issues prévues de votre code. Elles se représentent par des valeurs.

# Attendu : ça fait partie du fonctionnement normal.
case Comptes.recuperer(id) do
  {:ok, utilisateur} -> afficher(utilisateur)
  {:error, :introuvable} -> rediriger_vers_inscription()
end

# Inattendu : cet identifiant DOIT exister à ce stade, sinon c'est un bug.
utilisateur = Comptes.recuperer!(id)

La convention Elixir rend la frontière visible : recuperer/1 renvoie un tuple parce que l’échec est un cas normal ; recuperer!/1 lève parce que l’échec signifierait que le programme se trompe sur lui-même.

« Let it crash » ne concerne que la seconde catégorie. Écrire un try/rescue autour d’un formulaire invalide n’est pas du Elixir idiomatique — c’est simplement du code qui confond une erreur et un bug.

Et terminate/2 ?

On y pense vite : puisqu’un processus meurt, autant nettoyer derrière lui. Mais terminate/2 n’est pas la porte de sortie qu’on imagine. Mesuré :

exception dans un callback   → terminate/2 appelé
GenServer.stop/1             → terminate/2 appelé
Process.exit(pid, :kill)     → terminate/2 PAS appelé

Un :kill est brutal par définition, et c’est exactement ce qui arrive quand la machine s’arrête sèchement, quand la mémoire manque, ou quand un superviseur perd patience. Ce qui doit absolument être fait ne peut pas dépendre de terminate/2.

Si vous avez besoin d’une garantie, elle doit vivre ailleurs : une transaction en base, un travail persistant dans une file, un Process.monitor chez quelqu’un qui survivra.

Ce que ça change à l’écriture

En pratique, cette philosophie se traduit par trois habitudes.

On écrit le chemin heureux. Pas de vérification défensive à chaque étape pour des états qui ne devraient pas exister. Si l’invariant est faux, le pattern matching échoue et le processus meurt — ce qui est le comportement correct.

On dessine l’arbre de supervision comme on dessine un schéma de base. Qui redémarre qui, dans quel ordre, avec quelle stratégie. C’est une décision d’architecture, pas une formalité de démarrage.

On range l’état durable hors des processus. Base de données, ETS, service externe. L’état d’un GenServer est un cache de travail, pas une mémoire.

En résumé

« Let it crash » n’autorise pas à ignorer les erreurs. Elle sépare deux responsabilités qui étaient mélangées : faire le travail, et décider quoi faire quand il échoue.

Le prix est réel — l’état est perdu, l’appelant tombe avec, et une panne répétée arrête l’application. Ces trois coûts sont voulus : ils vous forcent à concevoir un système où un processus peut mourir sans que ce soit un drame.

Et le jour où ça arrive en production à trois heures du matin, un processus mort et remplacé vaut infiniment mieux qu’un processus vivant dans un état que personne ne sait décrire.

Les trois comportements décrits ici — perte d’état, propagation à l’appelant, arrêt du superviseur — ont été exécutés sur Elixir 1.19.5 et Erlang/OTP 28 avant publication. Le notebook du parcours permet de les rejouer.

C’est là qu’interviennent les hooks. Ils sont simples à écrire et faciles à mal écrire, parce qu’ils posent une question qu’on n’a pas l’habitude de se poser : qui possède ce morceau de DOM ?

D’abord : avez-vous vraiment besoin d’un hook ?

Beaucoup de choses pour lesquelles on écrit un hook n’en demandent pas. Le module Phoenix.LiveView.JS déclenche des commandes côté client sans aller au serveur ni écrire une ligne de JavaScript :

<button phx-click={JS.toggle(to: "#menu")}>Menu</button>
<div phx-click={JS.hide(to: "#alerte") |> JS.push("marquer_lu")}>…</div>

Afficher, masquer, basculer une classe ou un attribut, poser le focus, animer une transition, naviguer : tout cela existe déjà. En revanche JS ne sait pas tout — il n’a par exemple aucune commande de défilement, qu’il faut obtenir par JS.dispatch et un écouteur.

Un hook se justifie quand il faut intégrer du code qui n’est pas le vôtre — une librairie JavaScript — ou réagir à un événement du navigateur que LiveView n’expose pas.

Le hook minimal

Trois pièces. Un objet JavaScript :

const RightClickHook = {
  mounted() {
    this.el.addEventListener("contextmenu", (event) => {
      event.preventDefault()
      this.pushEvent("right-click", {
        x: event.clientX,
        y: event.clientY,
        element_id: this.el.id
      })
    })
  }
}

export default RightClickHook

Son enregistrement au démarrage du socket :

import RightClickHook from "./hooks/right-hook"

const liveSocket = new LiveSocket("/live", Socket, {
  params: {_csrf_token: csrfToken},
  hooks: {RightClickHook}
})

Et l’attribut côté gabarit :

<div id="zone" phx-hook="RightClickHook">Clic droit ici</div>

L’id n’est pas facultatif, et LiveView le vérifie à deux endroits.

D’abord à la compilation. HEEx refuse de compiler un gabarit où phx-hook — ou phx-update — apparaît sans id littéral :

attribute "phx-hook" requires the "id" attribute to be set

C’est le cas le plus fréquent, et le plus confortable : mix compile échoue, vous corrigez, vous n’avez jamais lancé le navigateur.

Le second garde-fou est côté client, pour ce que le compilateur ne peut pas voir — un id={@quelque_chose} qui vaut nil à l’exécution, ou un identifiant arrivant par des attributs dynamiques :

no DOM ID for hook "RightClickHook". Hooks require a unique ID on each element.

Celui-là ne sort que dans la console du navigateur. Si votre hook ne démarre pas sans raison apparente, c’est le premier endroit à regarder.

La raison de fond est la même dans les deux cas : LiveView doit pouvoir retrouver l’élément d’un rendu à l’autre pour savoir s’il s’agit du même. Sans identifiant, il ne le peut pas.

Les six moments de la vie d’un hook

La documentation en définit six, et chacun répond à un besoin précis.

mounted() — l’élément est dans le DOM et le LiveView a fini de monter. C’est là qu’on instancie sa librairie, qu’on pose ses écouteurs, qu’on démarre ce qu’on a à démarrer. Neuf hooks sur dix n’utilisent que celui-là.

beforeUpdate() — l’élément est sur le point d’être mis à jour. Vous recevez toEl, une copie détachée portant la mise à jour à venir, tandis que this.el est encore l’élément inchangé. C’est le moment de sauvegarder ce que la mise à jour va détruire : une position de défilement, une sélection de texte. Tout ce que vous faites ici doit être synchrone — l’opération ne peut être ni différée ni annulée.

updated() — le serveur vient de mettre l’élément à jour. On y resynchronise sa librairie avec le nouveau contenu, et on y restaure ce que beforeUpdate avait mis de côté.

destroyed() — l’élément a quitté la page, retiré par une mise à jour du parent ou par la disparition du parent. C’est votre seule occasion de faire le ménage, et on y reviendra.

disconnected() et reconnected() — le LiveView parent a perdu, puis retrouvé, sa connexion au serveur. De quoi griser une interface pendant une coupure et la réactiver au retour.

Un hook n’a pas besoin de les déclarer tous. Mais les lister vides, avec un commentaire expliquant à quoi chacun sert, est un excellent réflexe quand on débute — on se souvient qu’ils existent le jour où on en a besoin.

Les deux sens de la conversation

Du navigateur vers le serveur

this.pushEvent("right-click", payload)          // vers le LiveView
this.pushEventTo(this.el, "reposition", params) // vers le propriétaire de l'élément

La différence est décisive et se paie cher quand on se trompe. pushEvent vise le LiveView. pushEventTo vise, selon la documentation, « the LiveComponent or LiveView owning the targeted element(s) ».

Dans un LiveComponent, il faut pushEventTo. Sinon l’événement arrive chez le parent, qui n’a évidemment pas de handler pour lui, et vous cherchez longtemps un bug dans le composant alors que l’erreur nomme le parent. Le conteneur doit également porter phx-target={@myself} pour que les événements déclaratifs suivent le même chemin.

En cas de doute, pushEventTo(this.el, …) fonctionne dans les deux situations : il vise le propriétaire réel de l’élément, LiveView ou composant.

Du serveur vers le navigateur

C’est la moitié qu’on oublie souvent. Le serveur pousse avec push_event/3 :

def handle_event("exporter", _params, socket) do
  {:noreply, push_event(socket, "telecharger", %{url: url})}
end

Et le hook écoute :

mounted() {
  this.handleEvent("telecharger", ({url}) => window.open(url))
}

À défaut de hook, ces événements sont aussi diffusés sur window, préfixés de phx: — window.addEventListener("phx:telecharger", …). Pratique pour du code global, mais un hook reste préférable dès que l’événement concerne un élément précis.

La vraie question : qui possède ce DOM ?

Tout le reste découle de là. Deux cas concrets, opposés.

Cas 1 — le serveur reste maître : le tri par glisser-déposer

mounted() {
  new Sortable(this.el, {
    animation: 150,
    onEnd: e => {
      const params = { old: e.oldIndex, new: e.newIndex, ...e.item.dataset }
      this.pushEventTo(this.el, "reposition", params)
    }
  })
}

<div id="sort-items" phx-hook="SortableHook">
  <div :for={item <- @columns} data-id={item.id}>…</div>
</div>

Le data-id sur chaque enfant mérite qu’on s’y arrête : c’est lui que ...e.item.dataset fait remonter dans la charge utile. Sans lui, le serveur ne reçoit que deux positions, old et new — ce qui suffit tant que la liste est complète et non filtrée, et casse dès qu’elle est paginée, filtrée ou servie par un stream, où l’indice affiché ne correspond plus à l’indice réel. Faites toujours voyager une identité, pas seulement une position.

Remarquez ce qui n’est pas là : aucun phx-update="ignore". C’est délibéré. Sortable réordonne le DOM tout de suite, pour que le geste paraisse instantané ; puis le serveur reçoit reposition, met à jour ses données, et re-rend la liste dans le bon ordre. Le DOM affiché redevient celui que le serveur décide.

Le hook ne fait ici que traduire un geste en événement. L’ordre des éléments appartient au serveur — et c’est ce qui rend le montage robuste : le jour où vous enregistrez cet ordre en base, un rechargement de page le restitue sans toucher au hook.

Précisons pour être honnête : le dépôt d’exemple garde ses colonnes dans l’état du socket, pas en base. Rechargez sa page de démonstration et l’ordre initial revient. La propriété décrite ici tient à l’architecture — le serveur décide — pas à cette démonstration en particulier.

Cas 2 — la librairie reste maîtresse : un éditeur de texte riche

Un éditeur comme ProseMirror ou TipTap construit et gère son propre arbre DOM, avec la position du curseur, la sélection, l’historique d’annulation. Si LiveView le re-rend, tout est perdu au milieu d’une phrase.

Il faut donc lui céder le terrain :

<div id="editeur" phx-hook="EditorHook" phx-update="ignore"></div>

Et là, un piège que la documentation énonce en une incise facile à manquer :

Updates from the server to the element’s content and attributes are ignored, except for data attributes.

Les attributs data-* continuent donc d’être mis à jour — et pire, ceux que le serveur n’envoie pas sont retirés. Un hook qui range son état dans un data-* sur son élément racine le verra disparaître au rendu suivant.

La règle : l’état du hook vit à l’intérieur du sous-arbre ignoré, jamais sur sa racine. Dans un éditeur, il vit naturellement dans le nœud DOM de l’éditeur lui-même.

Comment trancher

Posez-vous une seule question : après un rechargement complet de la page, qu’est-ce qui doit survivre ?

Ce qui doit survivre appartient au serveur — il le stocke, il le re-rend, et le hook se contente de lui signaler les gestes. Ce qui est éphémère appartient à la librairie — on lui donne phx-update="ignore" et on ne s’en mêle plus.

Faire le ménage

Un hook qui pose un écouteur sur this.el n’a rien à nettoyer : l’élément disparaît, l’écouteur avec lui. Mais dès qu’il touche à autre chose, la fuite est réelle :

mounted() {
  this.onResize = () => this.recalculer()
  window.addEventListener("resize", this.onResize)
  this.timer = setInterval(() => this.rafraichir(), 5000)
},

destroyed() {
  window.removeEventListener("resize", this.onResize)
  clearInterval(this.timer)
}

Sans ce destroyed(), chaque navigation ajoute un écouteur et un minuteur de plus. La page ralentit progressivement, sans qu’aucune erreur n’apparaisse jamais. Écouteurs sur window ou document, minuteurs, IntersectionObserver, MutationObserver, connexions WebSocket ouvertes à la main : tout cela se libère dans destroyed().

Ce que les tests ne diront pas

Un point à garder en tête, développé dans l’article précédent : render_click, render_change et leurs voisins, dans leur forme fondée sur la vue, envoient l’événement directement au LiveView sans navigateur.

Ils prouvent que votre handle_event fait ce qu’il faut. Ils ne prouvent rien de votre hook — qui n’a même pas été chargé. Pour tester ce qu’un hook fait réellement, il faut un vrai navigateur : Wallaby pilote un Chrome.

En résumé

Un hook est un traducteur posté à la frontière. Il convertit des gestes du navigateur en événements pour le serveur, et des décisions du serveur en actions dans le navigateur.

Écrivez-en le moins possible : Phoenix.LiveView.JS couvre déjà beaucoup. Quand il en faut un, décidez d’abord qui possède le DOM concerné, nettoyez dans destroyed() tout ce que vous avez posé ailleurs que sur votre élément, et souvenez-vous que dans un LiveComponent, pushEventTo est la seule forme correcte.

Deux exemples complets et exécutables : le tri par glisser-déposer et le menu au clic droit.

Les pires sont ceux dont l’information se perd en route. Tantôt le serveur n’a rien vu passer et les journaux sont vides ; tantôt il lève bien une erreur, mais elle désigne le mauvais coupable. Et dans un cas, les tests restent au vert.

Voici trois de ces pannes, avec pour chacune l’endroit exact où l’information se perd.

1. Un phx-change hors d’un formulaire

Vous ajoutez un champ de recherche qui filtre une liste au fil de la frappe :

<input type="text" name="q" phx-change="filtrer" />

Vous tapez. Rien. Aucune erreur côté serveur, aucune ligne dans les journaux, handle_event("filtrer", …) n’est jamais appelé.

La cause est côté navigateur, dans une exception que personne ne regarde. Le code de LiveView est explicite — assets/js/phoenix_live_view/view.ts :

pushInput(inputEl, targetCtx, forceCid, phxEvent, opts, callback?) {
  if (!inputEl.form) {
    throw new Error("form events require the input to be inside a form");
  }

phx-change est un événement de formulaire. Sans <form> parent, LiveView refuse de pousser quoi que ce soit et lève dans la console. Le serveur, lui, n’apprendra jamais qu’on a essayé.

Le réflexe est d’entourer d’un <form>. Il est juste, mais incomplet — et l’incomplétude est elle-même une panne silencieuse.

<!-- Corrige le premier problème, en crée un second. -->
<form phx-change="filtrer">
  <input type="text" name="q" />
</form>

Un formulaire qui porte phx-change sans phx-submit est traité par LiveView comme un formulaire externe. Toujours dans live_socket.ts :

if (!externalFormSubmitted && phxChange && !phxSubmit) {
  externalFormSubmitted = true;
  e.preventDefault();
  this.withinOwners(e.target, (view) => {
    view.disableForm(e.target as HTMLFormElement, phxChange);
    // safari needs next tick
    window.requestAnimationFrame(() => {
      if (DOM.isUnloadableFormSubmit(e)) {
        this.unload();
      }
      (e.target as HTMLFormElement).submit();
    });
  });
}

form.submit() : un envoi de formulaire pour de vrai, avec rechargement complet de la page et perte de l’état du LiveView. Or un formulaire à un seul champ déclenche sa soumission implicite dès qu’on appuie sur Entrée — un geste que fait naturellement quelqu’un qui vient de taper une recherche.

La version qui tient debout déclare les deux événements :

<form phx-change="filtrer" phx-submit="filtrer">
  <input type="text" name="q" />
</form>

Entrée déclenche alors handle_event("filtrer", …) comme la frappe, et la page reste en place.

Et le test reste vert

Voilà le vrai piège. Vous écrivez le test qui va bien :

assert render_change(view, :filtrer, %{"q" => "elixir"}) =~ "résultat"

Il passe. Il passera toujours, formulaire ou pas — parce qu’il ne regarde pas le HTML. Dans live_view_test.ex, cette forme de render_change/3 se réduit à :

def render_change(view, event, value) do
  render_event(view, :change, event, value)
end

L’événement part directement au LiveView. Le balisage rendu n’est jamais consulté, donc l’absence de formulaire lui est invisible. Votre test valide un comportement que l’utilisateur n’obtiendra jamais.

La forme fondée sur un élément — element(view, "#recherche") |> render_change(%{…}) — est plus honnête, puisqu’elle exige au moins que l’élément existe dans le rendu. Mais rien ne remplace un test navigateur pour ce qui dépend du navigateur.

2. Un hook dans un LiveComponent

Votre hook JavaScript pousse un événement, et le LiveView plante avec un no function clause matching in MonAppWeb.ParentLive.handle_event/3 — alors que le handler existe, sous vos yeux, dans le composant.

Il existe deux fonctions, et elles ne visent pas la même chose. La documentation les distingue nettement : pushEvent pousse vers le LiveView, tandis que pushEventTo pousse « to the LiveComponent or LiveView owning the targeted element(s) ».

Un hook posé dans un LiveComponent qui appelle pushEvent envoie donc son événement au parent, qui n’a effectivement aucun handler pour lui.

// Dans un LiveComponent : l'événement part chez le parent.
this.pushEvent("ouvrir", {id: 1})

// Ce qu'il faut : viser le composant propriétaire de l'élément.
this.pushEventTo(this.el, "ouvrir", {id: 1})

Et côté gabarit, le conteneur doit porter phx-target={@myself} pour que les événements déclaratifs suivent le même chemin.

Le message d’erreur ne ment pas, et il est même précis : il nomme le module où il a cherché. Ce qu’il ne peut pas dire, c’est qui aurait dû recevoir l’événement. Vous lisez le nom du parent et vous allez inspecter le parent, alors que le problème est dans l’enfant.

3. phx-update="ignore" ne protège pas ce qu’on croit

On pose phx-update="ignore" sur un conteneur pour que LiveView n’écrase pas ce qu’une librairie JavaScript y a construit — un éditeur de texte riche, une carte, un composant de tri.

Puis l’état que le hook conservait disparaît au rendu suivant. La documentation explique pourquoi, à condition de lire la fin de la phrase :

Updates from the server to the element’s content and attributes are ignored, except for data attributes.

Cette exception est tout le problème. Un hook range volontiers son état dans un data-* sur son élément racine — et les attributs data-* sont précisément ceux que LiveView continue de mettre à jour. La fonction DOM.mergeAttrs va même plus loin : elle retire de l’élément les data-* que le serveur n’envoie pas. L’état posé par le hook n’est pas seulement écrasé, il est effacé.

La règle qui en découle : l’état maintenu par le hook doit vivre à l’intérieur du sous-arbre ignoré, pas sur sa racine. Dans un éditeur ProseMirror, par exemple, il vit naturellement dans le nœud DOM de l’éditeur lui-même, à l’abri.

Ce que ces trois pannes ont en commun

Elles se ressemblent, et pas par hasard : l’information existe, mais elle reste dans la couche qui l’a produite.

Le navigateur sait que le phx-change est mal placé — il a levé une exception. Le serveur ne le saura jamais, puisque rien ne lui a été envoyé. Le parent sait qu’il n’a pas de handler — mais pas que le vrai destinataire était son enfant. Le rendu sait qu’il a mis à jour un data-* — il ignore que le hook y rangeait quelque chose.

LiveView efface presque entièrement la frontière client/serveur, et c’est sa qualité principale. Ces trois cas sont le prix de cette réussite : quand quelque chose se perd à la frontière, il n’y a plus personne pour le dire.

Trois réflexes

Ouvrez la console du navigateur. C’est la première chose à faire devant une interaction qui ne produit rien côté serveur. Le message y est peut-être depuis le début.

Méfiez-vous d’un test vert sur un comportement qui dépend du DOM. Dans leur forme render_change(view, :evenement, params), ces fonctions pilotent le LiveView directement, sans jamais regarder le rendu : elles prouvent que votre handle_event fonctionne, pas qu’un utilisateur peut le déclencher.

Préférez systématiquement la forme fondée sur un élément — element(view, "#recherche") |> render_change(%{…}) — qui résout le sélecteur dans le HTML produit et exige donc que l’élément et sa liaison existent vraiment. Et pour ce qui dépend du navigateur lui-même, il faut un vrai navigateur : Wallaby pilote un Chrome.

Quand un événement se perd, demandez-vous qui l’écoute. Dans un LiveComponent, la réponse par défaut est « le parent », et ce n’est presque jamais ce que vous vouliez.

La question est excellente. La réponse est qu’on ne recopie rien.

Ce que « nouvelle liste » veut vraiment dire

Prenons une liste de dix mille éléments et ajoutons-lui une tête. La machine virtuelle sait mesurer ce que ça coûte : :erts_debug.flat_size/1 compte une valeur comme si rien n’était partagé, :erts_debug.size/1 en tenant compte du partage. Mesurons les deux listes ensemble :

grande = Enum.to_list(1..10_000)
avec_tete = [0 | grande]
paire = {grande, avec_tete}

:erts_debug.flat_size(paire)   #=> 40_005 mots
:erts_debug.size(paire)        #=> 20_005 mots

Deux listes de dix mille éléments occupent l’espace d’une seule. L’écart de cinq mots mérite d’être décomposé, parce qu’il est instructif : trois viennent du tuple que j’ai construit pour la mesure, et deux seulement sont la cellule nouvelle. Ajouter une tête à une liste de dix mille éléments coûte deux mots — une valeur et un pointeur.

La seconde liste n’a pas recopié la première : elle pointe dessus.

C’est le partage structurel. Une liste chaînée est une suite de cellules, chacune contenant une valeur et un pointeur vers la suivante. [0 | grande] fabrique une unique cellule nouvelle, dont le pointeur vise la première cellule de grande. Rien d’autre n’est touché.

Et c’est l’immutabilité qui rend ce partage possible. Dans un langage où grande pourrait changer, partager sa structure serait dangereux : modifier l’une modifierait l’autre. Puisque rien ne peut changer, tout peut être partagé sans risque. L’immutabilité n’est pas le prix à payer pour la sûreté — c’est ce qui autorise l’optimisation.

Ce que ça donne à l’échelle

Cent mille ajouts en tête, en conservant chaque résultat pour empêcher le ramasse-miettes de tricher :

{temps, listes} = :timer.tc(fn ->
  Enum.map(1..100_000, fn i -> [i | grande] end)
end)

temps                              : 8 ms
taille réelle des 100 000 listes   :           420 000 mots
si chacune était une copie complète : 2 000 400 000 mots

Un facteur 4 762. Sur une machine 64 bits où un mot fait 8 octets, c’est 3,4 Mo au lieu de 16 Go. Voilà pourquoi [element | accumulateur] est le geste idiomatique en Elixir : il est réellement gratuit.

Le revers : ++ en boucle

L’ajout en fin ne peut rien partager. Pour que la dernière cellule pointe vers un nouvel élément, il faut la reconstruire — donc reconstruire toutes celles qui y mènent. Et comme l’accumulateur grandit à chaque tour, le coût de chaque tour grandit avec lui.

C’est ce qui rend l’effet visible dès qu’on change d’échelle :

Enum.reduce(1..1_000, [], fn i, acc -> acc ++ [i] end)   # 1 ms
Enum.reduce(1..10_000, [], fn i, acc -> acc ++ [i] end)  # 273 ms

Dix fois plus d’éléments, deux cent soixante-treize fois plus de temps. C’est la signature d’un algorithme quadratique, et c’est le piège classique de l’accumulateur construit avec ++.

Le remède tient en deux gestes : empiler en tête, puis Enum.reverse/1 une seule fois à la fin. L’inversion est linéaire, l’ensemble reste linéaire.

Le partage n’est pas magique

Modifier un élément au milieu oblige à reconstruire tout ce qui précède — la partie qui suit, elle, reste partagée. Le coût est donc proportionnel à la distance depuis la tête, et ça se mesure :

À la position 9 999, on est à 40 003 mots : plus rien n’est partagé, la liste entière a été reconstruite. La progression est parfaitement régulière — le partage porte sur la queue, jamais sur la tête.

Le partage ne rend pas le parcours rapide

Voilà la distinction qu’il ne faut pas manquer, parce qu’elle sépare deux questions qu’on confond volontiers.

Le partage porte sur la mémoire. Il n’a aucun effet sur le temps d’accès. Enum.at(liste, 9_999) doit suivre neuf mille neuf cent quatre-vingt-dix-neuf pointeurs, que la liste soit partagée avec dix autres ou avec aucune. Aucune structure partagée ne raccourcit une chaîne.

On pourrait croire qu’un vecteur — comme ceux d’Aja, dont j’ai parlé ici — s’en sort mieux parce qu’il partagerait davantage. Ce n’est pas ça du tout. Mesuré, il partage exactement de la même façon :

vec = Aja.Vector.new(1..10_000)
vec2 = Aja.Vector.append(vec, :nouveau)

:erts_debug.flat_size({vec, vec2})  #=> 22_779 mots
:erts_debug.size({vec, vec2})       #=> 11_454 mots

Même mécanisme, même économie de moitié. Ce qui sépare les deux structures n’est donc pas le partage : c’est leur forme. Une liste est une chaîne qu’il faut parcourir ; un vecteur est un arbre large et plat qu’on indexe. Et ça se voit :

100 000 accès à l'index 9 999
  liste   : 1 619 ms
  vecteur :     6 ms

Un facteur 256, sur des structures qui partagent aussi bien l’une que l’autre.

D’où la conclusion, qui n’a rien de contradictoire avec tout ce qui précède : l’immutabilité ne vous coûte presque rien, mais elle ne vous dispense pas de choisir la bonne structure de données. Le partage rend une modification bon marché ; il ne rend pas une chaîne indexable.

« Mais la BEAM sait optimiser, non ? »

On lit parfois que le parcours n’est pas toujours linéaire, et c’est vrai — à condition de voir d’où vient l’optimisation. Elle ne vient jamais d’une ruse sur les listes chaînées : elle vient de ce que la chose parcourue n’est pas une liste.

Comparons la même fonction Enum appliquée à une liste et à un intervalle, sur cent mille itérations :

Enum.at(liste, 9_999)                 1 619 ms
Enum.at(1..10_000, 9_999)                10 ms      160x

Enum.slice(liste, 9_990..9_999)       2 159 ms
Enum.slice(1..10_000, 9_990..9_999)       9 ms      235x

Enum.count(liste)                     1 050 ms
Enum.count(1..10_000)                     3 ms      269x

Deux ordres de grandeur d’écart, sur les trois paires. Pourtant c’est le même appel, et 1..10_000 a bien dix mille éléments.

L’explication tient au protocole Enumerable. Les deux structures implémentent la fonction slice/1 — une implémentation de protocole doit définir tous ses callbacks — mais elles n’y répondent pas la même chose :

Enumerable.Range.slice(1..10_000)  #=> {:ok, 10000, #Function<...>}
Enumerable.List.slice([1, 2, 3])   #=> {:error, Enumerable.List}

L’intervalle répond « oui, je sais me découper, voici comment » ; la liste répond « non, débrouille-toi en me parcourant ». C’est cette réponse, et non l’existence de la fonction, qui décide du coût.

Un intervalle n’est pas une collection en mémoire : c’est un début, une fin et un pas. Enum.at(1..10_000, 9_999) calcule le résultat, il ne va pas le chercher. La liste, elle, n’a pas ce luxe — il faut suivre la chaîne.

Deux autres points valent d’être posés clairement :

Le JIT ne change pas la complexité. Depuis OTP 24, la BEAM compile à la volée vers du code machine, et tout va plus vite — mais un parcours linéaire reste linéaire. Le JIT améliore le facteur constant, pas l’exposant.

Certaines opérations sur les listes sont bel et bien en temps constant — hd/1 par exemple, mesuré à 0 ms sur cent mille appels. Mais ce sont celles qui touchent à la tête. Dès qu’on vise la fin, on repaie le parcours : List.last/1 coûte 1 927 ms sur les mêmes cent mille itérations.

La règle qui résume tout : sur une liste chaînée, ce qui est près de la tête est gratuit, ce qui est loin se paie — et aucune optimisation de la machine virtuelle ne rend une chaîne indexable.

Quand rien ne peut être partagé

Enum.map/2 produit une liste dont chaque élément diffère. Il n’y a rien à partager, et la mesure le confirme :

doubles = Enum.map(grande, &(&1 * 2))
:erts_debug.size({grande, doubles})       #=> 40_003 mots
:erts_debug.flat_size({grande, doubles})  #=> 40_003 mots

Les deux chiffres sont identiques : aucun partage. C’est normal et ce n’est pas un défaut — simplement, le partage récompense les transformations qui laissent la majorité des données intactes, pas celles qui touchent à tout.

Les maps, elles, sont des arbres : ajouter une clé à une map de dix mille entrées ne recopie que le chemin menant à la feuille. Encore faut-il le mesurer correctement — comparer deux flat_size séparés ne prouverait rien, puisqu’une copie intégrale donnerait exactement le même chiffre. Il faut mesurer les deux maps ensemble :

m = Map.new(1..10_000, &{&1, &1})
m2 = Map.put(m, :nouveau, 1)

:erts_debug.flat_size({m, m2})  #=> 75_638 mots
:erts_debug.size({m, m2})       #=> 37_875 mots

En retranchant la map d’origine et le tuple de mesure, le Map.put coûte 58 mots — soit 0,15 % de la map. Pas dix mille.

Là où l’immutabilité coûte vraiment

Il y a un endroit où la copie a bien lieu, et il vaut mieux le connaître : entre processus.

Chaque processus de la BEAM possède son propre tas. Un message envoyé d’un processus à un autre est donc copié, précisément parce qu’il ne peut rien partager avec l’extérieur.

envoi d'une liste de 10 000 éléments à un autre processus : 76 µs

C’est peu, mais ce n’est plus zéro — et ça devient significatif si vous faites transiter de grosses structures entre processus dans une boucle chaude. C’est le vrai coût de l’isolation, et c’est ce qui rend possible le ramasse-miettes par processus, sans pause globale.

Une exception notable : les binaires de plus de 64 octets vivent hors du tas et sont comptés par référence. Ils ne sont donc pas recopiés à l’envoi.

:erts_debug.flat_size(:crypto.strong_rand_bytes(60))        #=> 10 mots
:erts_debug.flat_size(:crypto.strong_rand_bytes(1_000_000)) #=> 8 mots

Un mégaoctet occupe moins de place sur le tas que soixante octets. Le petit binaire y est stocké en entier ; le grand n’y laisse qu’une référence. C’est pour ça qu’on peut passer de gros contenus entre processus sans y penser — et pourquoi découper une grosse binaire en petits morceaux peut, paradoxalement, consommer davantage.

Ce qu’il faut en retenir

Empilez en tête, inversez à la fin. C’est gratuit dans un sens, quadratique dans l’autre.

Ne craignez pas de « copier » une structure pour la modifier. Map.put, %{struct | champ: valeur}, List.replace_at près de la tête : rien de tout cela ne duplique vos données.

Méfiez-vous de la distance à la tête, pas de la modification elle-même. Si vous accédez par index sur une grande collection, le problème n’est pas l’immutabilité — c’est la liste chaînée.

Surveillez ce qui traverse les frontières de processus. C’est le seul endroit où le runtime copie même quand rien n’a changé — ailleurs, comme avec Enum.map/2, on paie une copie parce qu’on a effectivement produit des données nouvelles. C’est aussi le cas d’ETS, qui copie à l’écriture comme à la lecture.

L’immutabilité en Elixir n’est pas un compromis qu’on accepte en échange de la sûreté. C’est ce qui permet à la machine virtuelle de ne presque jamais copier — et de vous laisser raisonner sur vos données en sachant que personne ne les changera sous vos pieds.

Refaites ces mesures vous-même. Toutes celles de cet article vivent dans un notebook exécutable : ouvrez-le dans votre Livebook et relancez-les. C’est la seule réponse honnête au fait que ces nombres dépendent de la machine.

Les mesures publiées ici ont été prises sur Elixir 1.19.5 avec Erlang/OTP 28, sur une machine 64 bits où un mot fait 8 octets. Les nombres varient d’une machine à l’autre ; les ordres de grandeur, non.

C’est déroutant quand on vient de Ruby ou de Python, où le chemin d’un fichier détermine ce qu’on peut importer. En Elixir, le compilateur ne fait aucun lien entre un nom de module et un nom de fichier. Il compile tout ce qu’il trouve dans lib/ et enregistre les modules par leur nom.

Alors pourquoi tout le monde suit-il la convention ? Et y a-t-il un endroit où Elixir vérifie vraiment quelque chose ? Oui — un seul, et il ne se contente pas d’avertir : il refuse de démarrer.

Ce que mix new crée réellement

Sept fichiers — huit avec --sup, qui ajoute l’arbre de supervision :

mix.exs                       le projet, ses dépendances, son application
lib/mon_app.ex                le module racine
lib/mon_app/application.ex    l'arbre de supervision (avec --sup)
test/mon_app_test.exs
test/test_helper.exs
.formatter.exs
.gitignore
README.md

Pas de config/. Pas de priv/. Ils apparaissent quand on en a besoin — et c’est déjà une indication : ce ne sont pas des dossiers obligatoires, ce sont des conventions que l’outillage sait exploiter.

Le nom du fichier ne sert pas au compilateur

Il sert à tout le reste.

À vous, dans six mois. La règle « MonApp.Comptes.Utilisateur vit dans lib/mon_app/comptes/utilisateur.ex » transforme un nom de module aperçu dans une stacktrace en un chemin de fichier, sans réfléchir ni chercher.

À votre éditeur — en partie seulement. Soyons précis, parce que c’est là qu’on raconte facilement n’importe quoi : « aller à la définition » ne dépend pas de la convention. Elixir enregistre le vrai chemin du fichier source dans le module compilé, et les serveurs de langage le lisent :

# Le module vit dans lib/zzz.ex, contre toute convention.
MonApp.Comptes.__info__(:compile)[:source]
#=> ~c"/chemin/du/projet/lib/zzz.ex"

Ce qui dépend bel et bien de la convention, c’est tout ce qui part du nom : ouvrir un fichier en tapant son nom de module dans le sélecteur, basculer entre un module et son test, deviner un chemin depuis une stacktrace sans rien ouvrir.

Aux tests. mix test cherche test/**/*_test.exs. Là, c’est une vraie contrainte : un fichier de test mal nommé n’est simplement jamais exécuté, sans le moindre avertissement. C’est le premier endroit où une convention ignorée devient un bug silencieux.

Aux relectures. Un fichier de mille lignes contenant quatre modules passe la compilation. Il ne passe pas une revue.

La convention n’est donc pas arbitraire : elle est ce qui permet à tout le monde — humains et outils — de deviner où sont les choses.

Une porte d’entrée par domaine

La seconde convention, moins visible, est celle qui rend un projet lisible à mesure qu’il grossit.

Un domaine fonctionnel expose un module public, et cache le reste :

lib/mon_app/comptes.ex              l'API publique : inscrire, authentifier…
lib/mon_app/comptes/utilisateur.ex  un détail d'implémentation
lib/mon_app/comptes/jeton.ex        un autre

Rien n’empêche techniquement d’appeler MonApp.Comptes.Jeton.creer/1 depuis un contrôleur. C’est bien le problème : rien ne l’empêche, donc quelqu’un le fera, et la frontière disparaîtra sans qu’aucun outil ne s’en aperçoive.

Le marqueur conventionnel est @moduledoc false sur les modules internes. Il ne verrouille rien — il ne fait que les retirer de la documentation générée. C’est une convention entre humains, comme le souligne cette phrase qu’on lit souvent : en Elixir, la frontière publique est un accord, pas une barrière.

Si vous voulez une vraie barrière, il existe des outils d’analyse qui la font respecter. Mais l’accord suffit dans la plupart des projets, à condition d’être explicite.

priv/, le dossier qui suit le code

priv/ contient ce qui doit voyager avec l’application sans être du code : migrations, fichiers de traduction, certificats, gabarits, ressources statiques.

Sa particularité est d’exister aussi dans la release, à un chemin différent. On ne le devine donc pas :

# Faux : ce chemin n'existe plus une fois la release assemblée.
File.read!("priv/donnees.csv")

# Juste : Elixir résout le chemin réel, en développement comme en production.
:mon_app
|> Application.app_dir("priv/donnees.csv")
|> File.read!()

C’est une erreur classique, et elle a le mauvais goût de ne se manifester qu’au déploiement.

La configuration, seul endroit où Elixir vous rattrape

Voilà la partie qui justifie cet article, et la seule où une convention ignorée provoque une erreur explicite.

Un projet Elixir a deux familles de fichiers de configuration, qui ne sont pas évaluées au même moment :

config/config.exs — et les dev.exs, test.exs, prod.exs qu’il importe — est lu à la compilation, sur la machine qui construit. Ses valeurs sont figées dans l’artefact produit.

config/runtime.exs est lu à chaque démarrage, sur la machine qui exécute.

La documentation officielle est explicite sur le piège :

The :secret_key key under :my_app will be computed on the host machine, whenever the release is built.

…à propos de cette configuration :

import Config
config :my_app, :secret_key, System.fetch_env!("MY_APP_SECRET_KEY")

Autrement dit : votre secret de production est celui qui existait sur la machine de compilation. Au mieux la construction échoue parce que la variable n’y est pas ; au pire elle réussit avec la mauvaise valeur, et vous déployez.

Toute valeur qui dépend de l’environnement va dans runtime.exs. Ce fichier obéit à trois règles que la documentation formule en majuscules : il doit commencer par import Config, il ne doit pas utiliser import_config, et il ne doit pas toucher à Mix — lequel n’existe pas dans une release.

Le contrôle qui refuse de démarrer

Certaines valeurs doivent légitimement être lues à la compilation, quand elles déterminent le code produit. Elixir fournit pour ça Application.compile_env/2 — une macro, et non une fonction, ce qui n’est pas un détail : c’est ce qui lui permet d’enregistrer la valeur vue à la compilation.

Ce que vous y gagnez, c’est un garde-fou. J’ai monté le cas — projet compilé avec une valeur, release assemblée, puis runtime.exs en imposant une autre — et voici ce qui se passe au démarrage (message abrégé, il propose ensuite trois façons de corriger) :

ERROR! the application :demo_cfg has a different value set for key :mode
during runtime compared to compile time. Since this application environment
entry was marked as compile time, this difference can lead to different
behavior than expected:

  * Compile time value was set to: :dev
  * Runtime value was set to: :prod

[…]

Runtime terminating during boot ({<<"aborting boot">>,...})

La release ne démarre pas. C’est exactement ce qu’on veut : mieux vaut un déploiement qui échoue franchement qu’une application qui tourne avec la configuration de développement.

Notez au passage un comportement rassurant en développement : si vous modifiez config.exs, mix recompile les modules concernés tout seul. Le problème ne se pose donc qu’entre une compilation et une exécution séparées — c’est-à-dire dans une release, précisément là où on ne le verrait pas.

En résumé

Presque toutes les conventions d’un projet Elixir sont des accords entre humains : le compilateur ne relie pas les fichiers aux modules, ne protège pas les frontières de vos domaines, ne vous empêche pas de tout mettre dans un seul fichier. On les suit parce que l’outillage et les relecteurs s’appuient dessus, et parce qu’un projet qui ressemble aux autres se reprend sans effort.

Deux endroits font exception, et ce sont ceux à connaître par cœur : mix test ignore silencieusement un fichier mal nommé, et une valeur marquée comme lue à la compilation fait échouer le démarrage si elle change. La seconde est brutale — et c’est une bonne nouvelle.

Cet article doit son sujet au billet de João Paulo Abreu cité ci-dessous, qui couvre le même terrain en anglais, avec une progression pédagogique différente. Le texte, les exemples et l’angle sont les miens.

L’article précédent montrait comment transformer un script jetable en outil. Celui-ci s’attaque à la suite : brancher cet outil non plus sur une API publique, mais sur votre application, en train de tourner.

Pourquoi c’est possible

Rien de magique : la BEAM est distribuée depuis toujours. Un nœud Erlang peut en joindre un autre et exécuter du code dedans, à condition de connaître son nom et de partager son secret — le cookie.

C’est le mécanisme derrière iex --remsh, derrière les commandes d’une release, derrière Observer. Livebook s’en sert, avec une interface au-dessus.

Deux mécanismes distincts, qu’on confond souvent alors qu’ils n’ont ni la même puissance ni les mêmes risques.

Préparer l’application

Dans les deux cas, l’application doit avoir un nom de nœud et un cookie. En développement, c’est la ligne que donne la documentation de Livebook :

iex --name phoenix-app@127.0.0.1 --cookie secret -S mix phx.server

Pour une release, ces valeurs viennent des variables RELEASE_NODE et RELEASE_COOKIE. Sur un hébergeur, la marche à suivre dépend de la plateforme — Fly.io documente la sienne.

Mécanisme 1 — la cellule « Remote execution »

Le plus prudent, et curieusement le moins connu.

Vous ajoutez une cellule intelligente « Remote execution » via le bouton « + Smart cell ». Elle vous demande le nom du nœud, le cookie, et le code à exécuter là-bas.

Ce qui compte : votre runtime reste le vôtre. Le notebook tourne dans son propre nœud, avec ses propres dépendances installées par Mix.install. Seul le code de cette cellule part sur le nœud distant, et son résultat revient.

Vous pouvez donc récupérer des données de production, puis les analyser localement avec des librairies que l’application n’a pas — les tracer avec VegaLite, les charger dans un DataFrame Explorer — sans rien installer sur le système en fonctionnement.

Mécanisme 2 — le runtime « Attached node »

L’autre approche déplace le curseur entièrement.

Dans la barre latérale, l’icône « Runtime » — ou le raccourci s puis r — permet de choisir « Attached node » et d’y saisir le nom et le cookie. À partir de là, le notebook entier s’exécute dans le nœud de l’application. Vos cellules appellent directement les fonctions de votre code, comme si vous étiez dedans. Parce que vous y êtes.

La documentation officielle assortit ce mode d’un avertissement qui mérite d’être cité tel quel :

Once connected, be careful: any code that you execute in the notebook now runs within the connected application.

Et d’une limite technique nette :

your notebook cannot invoke Mix.install, it only has access to what’s already loaded in the external node

Ce n’est pas une lacune, c’est une conséquence : on ne recompile pas des dépendances dans un système en production. La documentation le dit d’ailleurs sans détour — « nor would that be a good idea on a running system ».

Comment choisir. Le mode attaché quand vous avez besoin d’appeler le code de l’application directement, en développement ou sur un environnement de recette. La cellule « Remote execution » quand vous touchez à la production, parce qu’elle vous force à décider explicitement ce qui part là-bas.

Ce qu’on va vraiment y chercher

L’intérêt n’est pas de remplacer iex, c’est de garder une trace.

L’état d’un processus. :sys.get_state(MonApp.Cache) vous rend l’état interne d’un GenServer. Dans un notebook, la commande reste écrite, commentée, réexécutable — et le collègue à qui vous envoyez le fichier voit ce que vous avez regardé.

Une requête sur la vraie base. En mode attaché, Repo est déjà chargé : Repo.aggregate(Commande, :count) fonctionne. Combiné à un Kino.DataTable, on obtient une exploration lisible plutôt qu’un IO.inspect déroulant.

La forme du système. Supervisor.count_children/1, Registry.count/1, Process.list() |> length(), :erlang.memory(). Ces chiffres, pris à intervalle régulier dans un Kino.Frame, donnent un tableau de bord improvisé en quelques lignes — sans déployer quoi que ce soit.

Un correctif de données ponctuel. Le cas où l’on migre trois lignes à la main. Écrit dans un notebook, il est relu avant d’être exécuté, et il reste ensuite comme trace de ce qui a été fait.

Les précautions, qui ne sont pas facultatives

Ce mécanisme donne un accès complet à un système en fonctionnement. Il mérite le même sérieux qu’un accès SSH root.

Le cookie est un secret. Qui connaît le nom du nœud et le cookie exécute ce qu’il veut sur votre machine. Un cookie par environnement, jamais dans un dépôt, jamais dans une cellule de notebook — Livebook a des secrets prévus pour ça.

La distribution Erlang n’est pas chiffrée par défaut. En clair sur le réseau, cookie compris. Ne l’exposez jamais sur l’internet public : passez par un tunnel SSH, un réseau privé, ou activez TLS sur la distribution.

Tout ce que vous exécutez tourne pour de bon. Une boucle infinie occupe un ordonnanceur de production. Un Enum.map sur une table entière la charge en mémoire. Un System.halt() arrête l’application. Il n’y a ni bac à sable ni confirmation.

Lire avant d’écrire. Les commandes qui observent — :sys.get_state, un Repo.all borné, :erlang.memory — sont sans danger. Celles qui modifient méritent d’être relues à froid, et de préférence par quelqu’un d’autre.

Le notebook garde ce que vous avez tapé. C’est sa qualité, et c’est aussi un risque : un fichier contenant des données de production ne se laisse pas traîner. Nettoyez les sorties avant de le partager.

Ce que ça change

Le vrai gain n’est pas technique — iex distant faisait déjà l’essentiel. Il est dans la trace.

Une session de débogage devient un document : les commandes, leurs résultats, et vos commentaires entre les deux. Il se relit le lendemain, se transmet à un collègue, se range à côté du code. La prochaine fois que le même symptôme apparaît, vous rouvrez le fichier au lieu de tout refaire.

C’est le même déplacement que dans l’article précédent — du script jetable vers quelque chose qui se garde — appliqué cette fois à ce qui tourne pour de vrai.

Cet article n’est pas livré en notebook exécutable, contrairement au précédent : il n’aurait de sens que branché à votre propre application. Les commandes ci-dessus se recopient dans un notebook vierge une fois la connexion établie.

Un notebook Livebook change exactement ça : le même script devient quelque chose qui se garde, s’envoie, et s’utilise sans lire une ligne de code.

Ce que Mix.install change vraiment

Un notebook commence par ses dépendances :

Mix.install([
  {:kino, "~> 0.19"},
  {:req, "~> 0.5"}
])

Ce n’est pas un détail de confort. C’est ce qui rend le fichier autonome : pas de mix.exs, pas de projet, pas de « il faut d’abord cloner le dépôt ». Vous envoyez un fichier, la personne l’ouvre, ça tourne.

Une nuance sur laquelle il vaut mieux ne pas se tromper : ~> 0.5 ne fige pas la version 0.5. La contrainte signifie « au moins 0.5.0 et moins de 1.0.0 », donc une installation faite aujourd’hui ramènera la dernière 0.x publiée — 0.7.4 pour req au moment où j’écris. Si la reproductibilité compte vraiment, écrivez la version exacte : {:req, "== 0.7.4"}. Le notebook est autonome, pas figé dans le temps.

Un notebook .livemd est par ailleurs du Markdown ordinaire. Il se lit sur GitHub, se versionne, se relit dans une revue de code. C’est une différence de fond avec les notebooks au format JSON, dont le diff est illisible.

Étape 1 — Rendre la sortie lisible

Interrogeons l’API publique de Hex, qui a le bon goût de ne demander aucune authentification.

paquets = Req.get!("https://hex.pm/api/packages", params: [search: "liveview"]).body
length(paquets)
#=> 100

Cent paquets. Un IO.inspect produirait un mur illisible. Kino.DataTable en fait un tableau trié et triable :

paquets
|> Enum.map(fn p ->
  %{
    nom: p["name"],
    version: p["latest_version"],
    telechargements: get_in(p, ["downloads", "all"]) || 0,
    description: p["meta"]["description"]
  }
end)
|> Enum.sort_by(& &1.telechargements, :desc)
|> Enum.take(20)
|> Kino.DataTable.new(name: "Paquets Hex")

Kino.DataTable.new/2 accepte n’importe quelle donnée tabulaire — une liste de maps convient. L’option :keys fixe les colonnes et leur ordre si l’ordre par défaut ne vous va pas.

Déjà à ce stade, ce n’est plus le même objet : quelqu’un peut trier par téléchargements sans savoir ce qu’est une map.

Étape 2 — Rendre l’outil interactif

Un tableau figé sur "liveview" reste un script. Ce qui en fait un outil, c’est le formulaire.

D’abord, isolons la recherche dans un module — le notebook exécutera cette cellule une fois pour toutes :

defmodule OutilHex do
  def chercher(terme) do
    "https://hex.pm/api/packages"
    |> Req.get!(params: [search: terme])
    |> Map.fetch!(:body)
    |> Enum.map(fn p ->
      %{
        nom: p["name"],
        version: p["latest_version"],
        telechargements: get_in(p, ["downloads", "all"]) || 0,
        description: p["meta"]["description"]
      }
    end)
    |> Enum.sort_by(& &1.telechargements, :desc)
    |> Enum.take(20)
  end
end

Trois pièces suffisent ensuite. Kino.Control.form/2 construit le formulaire ; Kino.Frame réserve une zone d’affichage ; Kino.listen/2 réagit aux soumissions.

formulaire = Kino.Control.form([terme: Kino.Input.text("Rechercher")], submit: "Chercher")
zone = Kino.Frame.new()

Kino.listen(formulaire, fn %{data: %{terme: terme}} ->
  case OutilHex.chercher(terme) do
    [] -> Kino.Frame.render(zone, Kino.Markdown.new("Aucun paquet pour **#{terme}**."))
    lignes -> Kino.Frame.render(zone, Kino.DataTable.new(lignes, name: "Résultats"))
  end
end)

Kino.Layout.grid([formulaire, zone], boxed: true)

Deux choses méritent d’être soulignées.

Une option d’émission est obligatoire. La documentation est explicite : « Either :submit or :report_changes must be specified ». Avec :submit, le formulaire n’émet qu’à la validation, et l’option donne son libellé au bouton. Avec :report_changes, il émet à chaque frappe, sous la forme %{type: :change} — pratique pour un filtre qui se met à jour en direct, coûteux si chaque événement déclenche un appel réseau comme ici.

L’événement reçu est une map de la forme %{data: %{…}, origin: …, type: :submit}. Le origin identifie le client : si deux personnes ouvrent le même notebook, vous savez laquelle a soumis. Le pattern matching sur %{data: %{terme: terme}} suffit tant qu’on n’en a pas besoin.

Et surtout : aucune cellule n’est réexécutée. Kino.listen démarre un processus qui redessine la zone. C’est du BEAM ordinaire, et c’est pour ça que ça semble instantané.

Ce que ça ne remplace pas

Il faut être clair sur les limites, sinon la déception arrive au mauvais moment.

Ce n’est pas une application. L’état vit dans un processus attaché au notebook. Vous le fermez, tout disparaît. Il n’y a ni persistance ni redémarrage automatique.

Ce n’est pas un tableau de bord partagé. Chaque personne qui ouvre le notebook exécute le sien, avec ses propres processus. Livebook sait déployer un notebook comme une application multi-utilisateur, mais c’est un autre mécanisme — et un autre article.

Ce n’est pas un endroit pour des secrets en clair. Un notebook se partage justement trop facilement. Livebook a des secrets prévus pour ça ; une clé d’API collée dans une cellule finira dans un dépôt.

Ce que c’est, en revanche : un outil personnel qu’on envoie par courriel, qu’on range à côté du code qu’il interroge, et qu’on relance dans six mois sans se demander quelles versions étaient installées.

Le seuil intéressant

Tout ce qui précède interroge une API publique, ce qui est commode pour un exemple mais reste anecdotique.

Le vrai basculement, c’est quand le même formulaire ne parle plus à une API distante mais à une application Elixir en cours d’exécution — inspecter l’état d’un GenServer, lancer une requête Ecto sur la base de production, lire des métriques en direct. Livebook sait s’attacher à un nœud existant, et c’est là qu’il cesse d’être un outil de démonstration.

C’est le sujet du prochain article.

Ce notebook est exécutable. Il vit dans le dépôt à côté de cet article : ouvrez-le dans votre Livebook et modifiez-le. Tout le code ci-dessus y a été exécuté avant publication.