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 mandatory sans route, par un basic.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 mandatory signifie « 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.

Publiée veut dire routée : un ack, et aucun basic.return avant lui Table outbox PostgreSQL Relais service order RabbitMQ app.events lit un lot FOR UPDATE SKIP LOCKED basic.publish , mandatory order.return.requested.v1 Un binding correspond : au moins une queue l'accepte basic.ack published_at = now() Aucun binding : confirmé, puis écarté par le broker basic.return 312 NO_ROUTE basic.ack attempts + 1, next_attempt_at la ligne reste à publier COMMIT du lot Sans mandatory , aucun basic.return : l'ack seul ferait marquer publiée une ligne perdue.

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 mandatory sur 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 LOCKED dans la lecture du relais.
  • pcntl dans l'image, init: true et 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_name différent de la clé de routage.

Sources