Le problème
Le service order de notre boutique en ligne
écrit ses événements dans une table outbox, dans la
transaction de la commande. Un relais lit cette table,
publie sur l'exchange app.events, attend la
confirmation du broker et marque la ligne publiée :
c'est
le pattern Outbox.
Reste le trajet entre « la ligne est dans l'outbox » et « le message est dans la bonne queue ». Les pannes y sont silencieuses : aucune exception, aucun message en échec.
Une version ajoute order.return.requested.v1,
une demande de retour : seul shipping la
consomme, pour faire enlever le colis. Le joker
order.order.*.v1 de
shipping.events ne la couvre pas, et
order est déployé avant son binding. Chaque
demande est publiée, confirmée par RabbitMQ, puis
écartée : aucune queue ne la retient.
Le relais marque ces lignes publiées.
shipping ne reçoit jamais ces demandes, et les
retours ne sont jamais enlevés. D'autres pannes guettent le
même trajet :
- deux relais actifs pendant un déploiement ;
- un relais arrêté au milieu d'un lot ;
- un binding retiré de la topologie voulue, toujours actif sur le broker ;
- un message qui, sous une clé autorisée, se dit autre chose ;
- un utilisateur RabbitMQ resté sur un mot de passe par défaut.
Les options
Toutes supposent les publisher confirms. Elles diffèrent sur un point : que sait le relais d'un message sans route ?
Les publisher confirms seuls
- Ce qu'ils règlent : un ack signifie que le broker a pris le message en charge. Un message persistant est alors écrit sur disque (queue durable) ou accepté par une majorité de réplicas (quorum queue).
- Ce qu'ils coûtent : RabbitMQ confirme aussi un message qu'aucune queue ne reçoit, dès qu'il constate l'absence de route. Pour le relais, « pris en charge » et « écarté » donnent le même ack.
Une alternate exchange
- Ce qu'elle règle : les messages sans route partent vers une exchange de secours, dont la queue les garde. Rien n'est perdu côté broker.
- Ce qu'elle coûte : le relais marque quand même la ligne publiée. Il faut surveiller la queue de secours, puis renvoyer ses messages une fois le binding créé.
Le drapeau mandatory
-
Ce qu'il règle : RabbitMQ renvoie au
publieur un message
mandatorysans route, par unbasic.return(code 312,NO_ROUTE) émis avant l'ack. Le relais sait, ligne par ligne, ce qui n'est arrivé nulle part. -
Ce qu'il coûte : le client doit
traiter ce retour, ce que le transport AMQP de Messenger
ne fait pas. Et
mandatorysignifie « au moins une queue » : un abonné manquant parmi plusieurs passe inaperçu.
Les deux ne se cumulent pas : un message déposé dans
l'alternate exchange compte comme routé, et
mandatory ne le renvoie plus.
Notre recommandation
Le relais publie avec mandatory et les
publisher confirms. Il ne marque une ligne publiée
qu'après un ack sans basic.return, et la
topologie se déploie avant les producteurs.
Trois réponses, trois gestes
-
Un ack seul : au moins une queue a
accepté le message. Le relais renseigne
published_at. -
Un
basic.return, puis l'ack : aucune queue. La ligne reste à publier, avec un nouvel essai plus tard. Le relais passe à la ligne suivante : le défaut tient à une clé de routage, pas au broker. - Un nack, un délai dépassé ou une connexion perdue : le broker est en cause. Le relais arrête le lot et ouvre un nouveau canal au lot suivant.
Un nack n'empêche pas toujours la livraison. Une queue
pleine réglée en reject-publish refuse le
message, mais les autres queues gardent leur copie. Le
nouvel essai crée des doublons, que le
consommateur idempotent
écarte.
Ce que les clients PHP font du retour
Le transport AMQP de Messenger accepte le drapeau (new AmqpStamp($routingKey, \AMQP_MANDATORY)), mais ne pose aucun callback de retour, en Symfony 7.4
comme en 8.1. Sans callback, ext-amqp émet un avis
E_NOTICE et cesse d'attendre.
En production, Symfony journalise cet avis sans lever
d'exception (php_errors.throw vaut par défaut
%kernel.debug%). send() rend la
main, et le relais marque la ligne publiée. php-amqplib,
lui, ignore le retour sans
set_return_listener().
Notre relais parle donc directement à ext-amqp, avec
setReturnCallback(). Les consommateurs restent
sur Messenger.
La topologie avant les producteurs
L'ordre de déploiement devient une règle : la topologie
(exchanges, queues, bindings, utilisateurs, permissions),
puis les consommateurs, puis les producteurs. Qu'elle vienne
de messenger:setup-transports ou de définitions
importées par le broker, elle précède le premier message.
Avec mandatory, une erreur d'ordre sur un
nouvel événement coûte un délai, pas une perte : les
lignes attendent le binding. Pour un nouvel abonné à un
événement déjà consommé, mandatory ne voit
rien. L'ordre reste la seule protection, et un rejeu depuis
l'outbox répare un oubli.
Un événement que personne n'écoute reste lui aussi à publier. C'est voulu : dans un monorepo, le contrat, l'abonnement et le handler arrivent ensemble, et un événement sans abonné signale un oubli.
Les compromis assumés
Un client AMQP de plus. Le relais sort de Messenger : connexion, canal et callbacks sont à notre charge, à tester contre un vrai RabbitMQ.
L'ordre entre clés. Une ligne retournée est
sautée, les suivantes partent. Tant que
order.return.requested.v1 attend son binding,
les événements publiés après lui le devancent : une
copie d'état vérifie une version avant d'écrire.
Des essais sans effet. Une ligne sans
abonné est republiée après 30 secondes, puis à un intervalle
qui double, jusqu'à 15 minutes. Une alerte sur
last_error = 'NO_ROUTE' nomme chaque clé
concernée.
Pas d'alternate exchange sur
app.events.
Notre topologie
la suggérait, mais elle rendrait
mandatory muet. Un message publié hors du
relais n'a donc pas de filet.
Le signal qui doit faire réexaminer ce choix : des retours fréquents, ou le besoin de savoir que chaque abonné attendu a reçu l'événement. Il faut alors comparer les bindings à un catalogue des abonnements.
Mise en œuvre
Les exemples visent PHP 8.4, Symfony 7.4 ou 8.1, ext-amqp
2.2, RabbitMQ 4.3 et PostgreSQL 18. La table
outbox et la tâche Scheduler qui lance le
relais sont celles de
l'article sur le pattern Outbox.
1. Suivre les échecs dans l'outbox
// src/Entity/OutboxMessage.php (service order, extrait)
#[ORM\Column(length: 255, nullable: true)]
private ?string $lastError = null;
// Pas de nouvel essai avant cette date ; NULL pour une ligne neuve.
#[ORM\Column(type: Types::DATETIMETZ_IMMUTABLE, nullable: true)]
private ?\DateTimeImmutable $nextAttemptAt = null;
public function recordFailure(string $error, ?\DateTimeImmutable $nextAttemptAt = null): void
{
++$this->attempts;
$this->lastError = mb_substr($error, 0, 255);
$this->nextAttemptAt = $nextAttemptAt;
}
2. Publier en mandatory avec ext-amqp
// src/Outbox/ConfirmedPublisher.php (service order)
namespace App\Outbox;
use App\Entity\OutboxMessage;
use AppContracts\Routing;
final class ConfirmedPublisher
{
private ?\AMQPExchange $exchange = null;
private int $sequence = 0;
/** @var array<string, string> message_id => motif du retour */
private array $returned = [];
public function __construct(
// host, vhost, login, password : lus dans l'environnement (RABBITMQ_*).
private readonly array $credentials,
private readonly float $confirmTimeout = 5.0,
) {
}
/** true : routé vers au moins une queue. Lève \AMQPException sur nack ou délai. */
public function publish(OutboxMessage $message): bool
{
$this->exchange ??= $this->open();
$channel = $this->exchange->getChannel();
$id = $message->getEnvelope()['event_id'];
$sequence = ++$this->sequence;
$channel->setConfirmCallback(
// false arrête l'attente : notre ack est arrivé, seul ou groupé.
static fn (int $tag, bool $multiple): bool => $tag < $sequence,
static fn (int $tag, bool $multiple, bool $requeue): bool => $tag < $sequence
?: throw new \AMQPException('Nack du broker.'),
);
$this->exchange->publish(
json_encode($message->getEnvelope(), \JSON_THROW_ON_ERROR),
$message->getRoutingKey(),
\AMQP_MANDATORY,
[
'message_id' => $id,
'content_type' => 'application/json',
'delivery_mode' => \AMQP_DELIVERY_MODE_PERSISTENT,
],
);
$channel->waitForConfirm($this->confirmTimeout);
if (isset($this->returned[$id])) {
unset($this->returned[$id]);
return false;
}
return true;
}
public function close(): void
{
$this->exchange?->getConnection()->disconnect();
$this->exchange = null;
}
private function open(): \AMQPExchange
{
$connection = new \AMQPConnection($this->credentials);
$connection->connect();
$channel = new \AMQPChannel($connection);
$channel->confirmSelect();
$this->sequence = 0;
$channel->setReturnCallback(
function (int $code, string $text, string $exchange, string $routingKey, \AMQPBasicProperties $properties, string $body): bool {
// 312 NO_ROUTE : aucun binding ne correspond à la clé de routage.
$this->returned[(string) $properties->getMessageId()] = $code.' '.$text;
return true; // continuer : l'ack de ce message suit le retour.
},
);
$exchange = new \AMQPExchange($channel);
// Aucun declareExchange() : la topologie appartient au broker.
$exchange->setName(Routing::EXCHANGE);
return $exchange;
}
}
3. Le relais : publier, puis marquer ou reporter
// src/Outbox/OutboxRelay.php (service order), extrait de relay()
// La lecture du lot gagne une condition, avant ORDER BY ... FOR UPDATE SKIP LOCKED :
// AND (o.next_attempt_at IS NULL OR o.next_attempt_at <= now())
$count = 0;
foreach ($messages as $message) {
try {
$routed = $this->publisher->publish($message);
} catch (\AMQPException $e) {
// Le broker est en cause : arrêt du lot, nouveau canal au lot suivant.
$this->publisher->close();
$message->recordFailure($e->getMessage());
break;
}
++$count;
if (!$routed) {
// Confirmé mais écarté : la ligne reste à publier, avec un délai croissant.
$delay = min(30 * 2 ** $message->getAttempts(), 900);
$message->recordFailure('NO_ROUTE', new \DateTimeImmutable("+{$delay} seconds"));
continue;
}
$message->setPublishedAt(new \DateTimeImmutable());
}
// $count compte les lignes publiées ou retournées ; wrapInTransaction() commite le lot.
return $count;
Pendant un déploiement, SKIP LOCKED laisse deux
relais se chevaucher : chacun saute les lignes que
l'autre a verrouillées.
Un arrêt entre l'ack et le commit annule le marquage : le lot suivant republie la ligne, un doublon et jamais une perte.
4. Arrêter le relais proprement
Le relais tourne dans
messenger:consume scheduler_default. Avec
l'extension pcntl, le worker traite SIGTERM après la tâche
en cours ; sans elle, SIGTERM tue PHP au milieu du lot.
En PID 1 dans un conteneur, un processus ignore les signaux
qu'il ne traite pas lui-même. Docker envoie alors SIGKILL au
bout de 10 secondes par défaut.
init: true place un init en PID 1, qui transmet
le signal.
# services/order/compose.yml (relais, extrait)
services:
outbox-relay:
# Image du service order, construite avec pcntl.
command: ['php', 'bin/console', 'messenger:consume', 'scheduler_default', '--time-limit=3600']
init: true
# Au-delà, SIGKILL : le lot en cours est annulé, puis republié.
stop_grace_period: 30s
environment:
RABBITMQ_HOST: rabbitmq
RABBITMQ_VHOST: app
RABBITMQ_USER: order
# Sans valeur, Compose refuse de démarrer : pas de mot de passe par défaut.
RABBITMQ_PASSWORD: ${RABBITMQ_ORDER_PASSWORD:?missing}
5. Un utilisateur par service, sans mot de passe par défaut
Chaque service a son utilisateur RabbitMQ, avec des droits limités à ses queues. Une permission de topic borne en plus ses publications à son préfixe :
rabbitmqctl set_topic_permissions -p app order app.events '^order\.' '.*'
Le piège est un provisionnement qui retombe sur un mot de
passe par défaut quand une variable manque. Or un compose
qui énumère ses variables dans
environment: n'en transmet aucune autre au
conteneur. Nous préférons l'échec, par
${VAR:?error}.
6. Vérifier la topologie réelle
Ni messenger:setup-transports ni l'import de
définitions ne suppriment un binding. Un binding retiré de
la référence continue donc de livrer, par exemple une
v1 que plus personne ne lit. Nous comparons à
chaque déploiement du broker :
# tools/check-bindings.sh
rabbitmqctl export_definitions /tmp/live.json
query='.bindings[] | select(.source == "app.events") | "\(.destination) \(.routing_key)"'
diff <(jq -r "$query" deploy/rabbitmq/definitions.json | sort) <(jq -r "$query" /tmp/live.json | sort)
Une ligne présente seulement sur le broker se supprime à la main :
rabbitmqadmin --vhost app bindings delete --source app.events \
--destination-type queue --destination shipping.events --routing-key 'order.order.*.v1'
7. Une garde chez le consommateur
La permission de topic contrôle la clé de routage, pas le
message. order peut publier sous
order.order.placed.v1 un corps dont
event_name désigne un autre message, que
stock traiterait comme le sien. La garde refuse
donc, sans retry, un message d'un autre service dont l'event_name
diffère de la clé.
// src/Messenger/RoutingKeyGuardMiddleware.php (service stock)
namespace App\Messenger;
use Symfony\Component\Messenger\Bridge\Amqp\Transport\AmqpReceivedStamp;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Exception\UnrecoverableMessageHandlingException;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
use Symfony\Component\Messenger\Middleware\StackInterface;
final class RoutingKeyGuardMiddleware implements MiddlewareInterface
{
// Le trafic propre au service, retries compris (clé « stock.events »).
private const OWN_PREFIX = 'stock.';
public function handle(Envelope $envelope, StackInterface $stack): Envelope
{
$routingKey = $envelope->last(AmqpReceivedStamp::class)?->getAmqpEnvelope()->getRoutingKey();
if (null !== $routingKey && !str_starts_with($routingKey, self::OWN_PREFIX)) {
$eventName = $envelope->last(EventMetadataStamp::class)?->eventName;
if ($eventName !== $routingKey) {
throw new UnrecoverableMessageHandlingException(sprintf(
'Message refusé : clé de routage "%s", événement "%s".',
$routingKey,
$eventName ?? 'absent',
));
}
}
return $stack->next()->handle($envelope, $stack);
}
}
Elle lit EventMetadataStamp, posé par
le sérialiseur de nos contrats, et se place avant doctrine_transaction. Le
message refusé part dans le failure transport. Les droits
d'écriture comptent autant : qui écrit sur l'exchange
par défaut (amq.default) atteint toute queue
par son nom, sans contrôle de topic.
Les queues de délai de Messenger y renvoient les retries, ce
qui exige ce droit. L'option
delay[arguments] (x-dead-letter-exchange: app.events) les renvoie plutôt par app.events, avec un
binding de chaque queue sur son propre nom.
8. Compter les échecs au bon endroit
La DLQ d'une quorum queue reçoit une copie à chaque retry de
Messenger, pas seulement l'échec final (notre note sur les dead letter queues). Les échecs définitifs se comptent avec
messenger:failed:show.
Checklist
-
Des publisher confirms et le drapeau
mandatorysur chaque publication du relais. -
Une ligne marquée publiée seulement après un ack sans
basic.return. - Un callback de retour sur le canal, testé contre un vrai RabbitMQ.
-
Les lignes retournées reportées sans bloquer les autres,
et une alerte sur
NO_ROUTE. - La topologie déployée avant les consommateurs, et ceux-ci avant les producteurs.
-
FOR UPDATE SKIP LOCKEDdans la lecture du relais. -
pcntl dans l'image,
init: trueet un délai d'arrêt adapté. - Un utilisateur par service, une permission de topic sur son préfixe, aucun mot de passe par défaut.
- Les bindings réels comparés aux bindings voulus à chaque déploiement du broker.
-
Une garde qui refuse sans retry un
event_namedifférent de la clé de routage.
Sources
-
RabbitMQ,
Publisher Confirms : messages sans route,
basic.returnavantbasic.ack, persistance et quorum queues. -
RabbitMQ,
messages sans route,
Alternate Exchanges
et
reject-publish. -
AMQP 0-9-1,
référence du protocole :
mandatory,basic.return, code 312no-route. -
RabbitMQ,
Access Control
(permissions de topic,
amq.default), rabbitmqctl et Dead Letter Exchanges. - RabbitMQ, Definitions, rabbitmqadmin et liste rabbitmq-users, import additif (équipe RabbitMQ, 27 octobre 2023).
- ext-amqp 2.2.0 (2 janvier 2026), AMQPChannel et basic.return sans callback ; php-amqplib, AMQPChannel.
-
Symfony,
Messenger
(transport AMQP, pcntl),
code du transport AMQP
et
php_errors.throw. -
PostgreSQL,
clause de verrouillage :
SKIP LOCKED. -
Docker,
docker run
(PID 1), Compose
services
(
init,stop_grace_period) et interpolation. - Lychen, pull requests 253 et 236 : une mise en œuvre open source du relais avec confirmations, de la garde et des mots de passe par service, dans un monorepo moon.