Pattern Outbox — publication fiable de messages depuis une transaction DB

1📖 Glossaire — le vocabulaire de base

• Dual write — écrire dans deux systèmes externes différents (typiquement DB + broker) sans transaction commune. C'est le problème que l'outbox résout.
• Atomicité — propriété d'une opération qui réussit complètement ou échoue complètement, sans état intermédiaire visible. Une transaction DB classique est atomique, un save() + send() ne l'est pas.
• At-least-once delivery — chaque message est délivré au moins une fois, possiblement plusieurs fois en cas de retry. C'est la garantie naturelle de l'outbox.
• Exactly-once delivery — chaque message est délivré exactement une fois. Très difficile en distribué, demande coopération producteur ↔ broker ↔ consommateur. Kafka le permet via les transactions Kafka, mais l'outbox seul ne le garantit pas.
• At-most-once delivery — chaque message est délivré zéro ou une fois. Sous-entend qu'on peut perdre des messages. C'est ce qu'on a en save() + send() naïf en cas de crash.
• Idempotence — propriété d'une opération qu'on peut appliquer plusieurs fois sans changer le résultat. INSERT ... ON CONFLICT DO NOTHING est idempotent, INSERT simple ne l'est pas. C'est le prérequis non négociable côté consumer quand on est en at-least-once.
• CDC (Change Data Capture) — technique qui consiste à capturer les changements appliqués à une DB en lisant son journal interne, sans interroger les tables. Utilisé par Debezium.
• WAL (Write-Ahead Log) — journal de transactions de Postgres. Toute modification est d'abord écrite ici avant d'aller dans les tables. Debezium lit ce journal pour faire du CDC.
• Poller — un job applicatif qui interroge périodiquement une table SQL (SELECT WHERE …) pour trouver du travail à faire. Approche classique de l'outbox sans CDC.
• SMT (Single Message Transform) — dans l'écosystème Kafka Connect, une transformation appliquée à chaque message entre la source et le sink. L'Outbox Event Router de Debezium est une SMT.
• Aggregate (DDD) — un cluster d'entités qu'on modifie en bloc dans une transaction (ex: Order + ses OrderLine). En outbox pattern, on émet typiquement un event par aggregate modifié.

2Le dual write problem

Le scénario typique. Un service e-commerce reçoit une commande. Il doit (a) la persister en DB, (b) publier un event OrderPlaced sur Kafka pour que les services Inventory, Billing, Shipping puissent réagir.

@Service
public class OrderService {
    @Transactional
    public void placeOrder(Order order) {
        orderRepository.save(order);              // (a) commit DB
        kafkaTemplate.send("orders", new OrderPlaced(order.getId())); // (b) publish broker
    }
}

Ça paraît correct. Ça ne l'est pas.

Les 4 façons dont ça casse

sequenceDiagram
    participant App as Service
    participant DB as DB
    participant K as Kafka

    App->>DB: save(order)
    DB-->>App: ✓ commit
    Note over App: 💥 JVM crash ici
    App--xK: send(OrderPlaced) jamais envoyé
    Note over DB,K: État incohérent :<br/>order en DB, aucun event publié

Cas 1 — Crash JVM entre commit DB et send Kafka. Le save() a commit, l'event n'a jamais été publié. La commande existe, personne en aval ne le sait.

Cas 2 — Kafka indisponible au moment du send. kafkaTemplate.send() throw une KafkaException. Si on est dans un @Transactional, la transaction Spring rollback → la commande est effacée.

Cas 3 — Send réussit côté client mais Kafka crashe avant fsync sur disque. send() retourne sans erreur, mais le broker tombe avant que le message ne soit durablement écrit.

Cas 4 — Timeout réseau. send() part, le broker l'a peut-être reçu mais la réponse n'arrive pas à temps. L'app croit que c'est échoué, retry → doublon publié.

Matrice : que se passe-t-il si X tombe ?

Quel que soit l'ordre choisi, il existe un cas où la cohérence est cassée.

3Les solutions naïves et pourquoi elles échouent

🚫 Naïveté 1 — Try/catch + retry en mémoire

Si la JVM crashe pendant les retries (kill -9, OOM, redéploiement Kubernetes), l'event est perdu et tu n'as aucune trace qu'il devait être publié.

🚫 Naïveté 2 — Inverser l'ordre (publish avant save)

Si le save() échoue après un send() réussi, tu as publié un event sur une commande qui n'existe pas en DB. Inventory décrémente le stock, Shipping prépare l'expédition, mais la commande → 404.

🚫 Naïveté 3 — Two-Phase Commit (XA)

Kafka ne supporte pas XA. Les transactions Kafka couvrent uniquement Kafka ↔ Kafka. Coordinator failure possible. Complexité opérationnelle (Atomikos, Narayana).

4Le pattern outbox — principe

L'idée centrale. Au lieu de faire save() + send(), on fait save() + insert dans table outbox, dans la même transaction DB. Un acteur séparé (poller, CDC) lira la table outbox plus tard et publiera vers Kafka.

sequenceDiagram
    participant App as Service
    participant DB as DB<br/>(orders + outbox)
    participant Pub as Publisher<br/>(poller / CDC)
    participant K as Kafka

    App->>DB: BEGIN TX
    App->>DB: INSERT INTO orders
    App->>DB: INSERT INTO outbox (event)
    App->>DB: COMMIT (atomique)
    Note over App: ✓ Réponse client OK
    
    rect rgb(200, 230, 200)
    Pub->>DB: SELECT FROM outbox WHERE not published
    DB-->>Pub: events à publier
    Pub->>K: send(event)
    K-->>Pub: ack
    Pub->>DB: UPDATE outbox SET published_at = NOW()
    end

Schéma typique de la table outbox

CREATE TABLE outbox (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    aggregate_type  VARCHAR(255) NOT NULL,
    aggregate_id    VARCHAR(255) NOT NULL,
    event_type      VARCHAR(255) NOT NULL,
    payload         JSONB        NOT NULL,
    created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    published_at    TIMESTAMPTZ
);

CREATE INDEX idx_outbox_unpublished
    ON outbox (created_at)
    WHERE published_at IS NULL;  -- index partiel

5Le rôle critique de l'idempotence côté consumer

Entre "Kafka a accepté le message" et "j'ai marqué la ligne outbox comme publiée", le publisher peut crasher. Au redémarrage, il retrouve l'event comme "non publié" et le republie. Doublon garanti.

@KafkaListener(topics = "orders")
public void onOrderPlaced(OrderPlacedEvent event) {
    if (processedEventsRepository.existsById(event.getEventId())) {
        return; // déjà traité, on ignore
    }
    // … traitement métier …
    processedEventsRepository.save(new ProcessedEvent(event.getEventId()));
}

6Implémentation 1 — Poller maison

@Component
@RequiredArgsConstructor
public class OutboxPoller {
    private final JdbcTemplate jdbc;
    private final KafkaTemplate<String, String> kafka;

    @Scheduled(fixedDelay = 500)
    @Transactional
    public void publishPending() {
        List<OutboxEvent> events = jdbc.query("""
            SELECT id, aggregate_type, aggregate_id, event_type, payload
            FROM outbox
            WHERE published_at IS NULL
            ORDER BY created_at
            LIMIT 100
            FOR UPDATE SKIP LOCKED
            """, outboxRowMapper);
        
        for (OutboxEvent e : events) {
            String topic = e.aggregateType().toLowerCase() + ".events";
            kafka.send(topic, e.aggregateId(), e.payload()).get();
            
            jdbc.update(
                "UPDATE outbox SET published_at = NOW() WHERE id = ?",
                e.id()
            );
        }
    }
}

FOR UPDATE SKIP LOCKED — en multi-pods, chaque instance traite un sous-ensemble disjoint sans coordination explicite.

7Comparaison des implémentations

Sources

• microservices.io — Pattern: Transactional outbox (Chris Richardson)
• Debezium — Outbox Event Router SMT documentation
• Debezium Blog — Reliable Microservices Data Exchange With the Outbox Pattern
• Spring Modulith — Externalization of events
• kafka-core-model — at-least-once, idempotence consumer, delivery semantics
• kafka-connect-2-debezium-cdc — WAL, logical decoding, replication slot utilisés par l'implémentation CDC
• spring-boot-transactional-propagation-isolation-appels-entre-beans — @Transactional ne couvre que la DB, pas le broker