Aller au contenu

Recevoir les e-mails en développement

Vous êtes développeur·se sur Kirexo et vous attendez un e-mail (réinitialisation de mot de passe, par exemple) qui n'apparaît jamais dans Mailpit. Ce guide explique pourquoi et comment le faire arriver.

Prérequis

  • Le proxy hôte est démarré (castor proxy:up) et la stack Docker aussi (castor docker:up).
  • Vous savez ouvrir l'UI Mailpit : https://mailpit.main.localhost pour le dépôt principal, ou https://mailpit.<worktree>.localhost depuis un worktree.

Pourquoi l'e-mail n'arrive pas tout de suite

En développement, le Mailer de Kirexo est asynchrone. L'e-mail n'est pas envoyé pendant la requête HTTP : un message Symfony\Component\Mailer\Messenger\SendEmailMessage est dispatché sur le bus Messenger, routé vers le transport async qui pointe sur RabbitMQ (config/packages/messenger.yaml).

# config/packages/messenger.yaml
routing:
    Symfony\Component\Mailer\Messenger\SendEmailMessage: async

Le transport async utilise le DSN AMQP de MESSENGER_TRANSPORT_DSN (.env), soit amqp://guest:guest@rabbitmq:5672/%2f/messages.

Conséquence : tant qu'aucun worker ne consomme la file, le message reste en attente dans RabbitMQ et aucun e-mail n'atteint Mailpit. En développement, un worker Messenger tourne en permanence dans le conteneur php, sous le supervisor (transports plugin_web et async) : dans le cas nominal, vous n'avez donc rien à lancer. Si l'e-mail n'arrive pas, c'est que ce worker est mort ou que RabbitMQ ne répond pas — voir Diagnostiquer.

En test, c'est synchrone

En environnement de test, messenger.yaml (bloc when@test) force async: 'sync://' : l'e-mail part immédiatement, sans worker. C'est pour ça que les tests n'ont jamais à drainer de file. Le comportement asynchrone décrit ici ne concerne que le dev. (En test, MAILER_DSN=null://null : rien n'est réellement émis.)

Le worker qui traite ces e-mails

Il n'y a rien à démarrer : le programme messenger du supervisor consomme plugin_web et async en continu, avec la verbosité -vv. Son journal est le meilleur endroit pour vérifier qu'un e-mail est bien parti :

tail -f var/log/supervisor/messenger.log

Deux lignes suffisent à conclure : Received message Symfony\Component\Mailer\Messenger\SendEmailMessage (le worker a bien dépilé le message) puis Message … handled by … (le handler est allé au bout). Leur absence signifie que le message n'a jamais été consommé.

Le worker se recycle tout seul au bout d'une heure (--time-limit=3600) ou de 192 Mio (--memory-limit=192M) : la boucle de supervision le relance aussitôt. Détail dans Supervision des process long-running.

Ne lancez pas un second worker

castor messenger:consume refuse de démarrer tant que le worker supervisé tourne : deux consommateurs sur les mêmes transports enverraient chaque e-mail deux fois. La forme castor console "messenger:consume async", elle, ne contrôle rien — à réserver aux cas où le worker supervisé est explicitement arrêté.

Diagnostiquer

Le worker tourne-t-il ?

# Depuis le conteneur php
castor doctor

Les lignes « Supervisor messenger actif » et « Transports Messenger joignables (plugin_web, async) » distinguent les deux causes possibles : worker mort (réparable depuis le conteneur) ou RabbitMQ injoignable (action hôte). Pour relancer le worker : Relancer FrankenPHP ou le worker Messenger.

Combien de messages attendent ?

castor console "messenger:stats async"

Un Count supérieur à 0 sur la ligne async signifie que des e-mails (ou d'autres messages) sont en attente : le worker ne les a pas encore consommés — ou ne les consomme plus.

L'envoi a-t-il échoué ?

Après trois tentatives infructueuses (retry_strategy), le message part au transport failed :

castor console "messenger:failed:show"
castor console "messenger:failed:retry <id>"

Côté Symfony Profiler

Comme rien n'est envoyé pendant la requête HTTP, l'envoi n'apparaît pas dans l'onglet Mailer du profiler. Il apparaît dans l'onglet Messenger, sous la forme d'un message SendEmailMessage dispatché sur le transport async. Si vous cherchez la preuve qu'un e-mail a bien été « parti » côté application, c'est là qu'il faut regarder, pas dans Mailer.

Gotcha : le worker garde les templates Twig en mémoire

Un worker messenger:consume est un process long : il charge le kernel une fois et conserve les templates Twig d'e-mail compilés en mémoire. Si vous modifiez un template d'e-mail (par exemple templates/email/base.html.twig ou templates/reset_password/email.html.twig) pendant qu'un worker tourne, le worker continue de rendre l'ancienne version compilée.

Un cache:clear ne suffit pas : le process a déjà chargé l'ancienne classe compilée en mémoire. Il faut recycler le worker :

castor supervisor:worker-restart

La cible demande au worker de s'arrêter après son message en cours, puis attend que le supervisor en ait relancé un neuf (le PID du process change — c'est la preuve du recyclage). FrankenPHP n'est jamais touché. C'est l'équivalent, côté Messenger, du rechargement du worker FrankenPHP après modification d'une route.

SMTP de développement (Mailpit)

En dev, MAILER_DSN=smtp://mailer-int:1025 (.env) pointe sur le service mailer, qui est Mailpit (compose.override.yaml). Mailpit capture tous les e-mails sortants sans jamais les délivrer réellement :

  • UI web : https://mailpit.main.localhost pour le dépôt principal, servie par le proxy hôte. Depuis un worktree, https://mailpit.<worktree>.localhost sert la même boîte : le conteneur est unique, seul le nom d'hôte change. L'ancienne URL canonique https://mailpit.localhost a été retirée — un seul label sous .localhost la condamnait à un certificat invalide, et elle faisait doublon avec l'adresse du dépôt principal, qui ne se détruit jamais.
  • SMTP : mailer-int:1025, joignable depuis les conteneurs de la stack uniquement. Aucun port n'est publié sur l'hôte.

Une fois le worker passé sur la file, l'e-mail s'affiche dans cette boîte.

mailer-int, jamais le nom de service nu mailer

Le conteneur Mailpit est attaché à deux réseaux (celui de la stack et celui du proxy hôte), et Docker répond à une résolution de nom par toutes les adresses partagées : le nom nu mailer rendrait deux enregistrements A, et un envoi SMTP sur deux partirait vers le réseau du proxy — où il est jeté. Symptôme : des e-mails perdus par intermittence, sans trace. mailer-int est l'alias déclaré sur le seul réseau applicatif. Raisonnement complet : Un service sur deux réseaux rend deux adresses.

Voir aussi