Spring Modulith + Namastack Outbox — externaliser des événements par un vrai outbox

1📖 Glossaire — le vocabulaire de base

• Externalisation — republication d'un événement Spring interne vers un broker externe (Kafka, AMQP, SNS).
• @Externalized — annotation Modulith qui marque un événement à externaliser. Sa valeur porte la cible et une clé de routage : topic::clé.
• Event Publication Registry (EPR) — table event_publication de Modulith. Une ligne par listener transactionnel, écrite dans la transaction métier.
• Mode outbox — valeur de spring.modulith.events.externalization.mode qui délègue la livraison à un outbox externe (Namastack ou JobRunr).
• Outbox record — ligne de la table outbox_record de Namastack : payload sérialisé, clé, statut, compteur d'échecs, prochaine tentative.
• Clé (record key) — valeur métier qui fixe l'ordre de traitement et la partition. Deux records de même clé sont livrés dans leur ordre de création.
• Partition Namastack — un des 256 slots fixes obtenus par hachage de la clé. À ne pas confondre avec une partition Kafka.
• Handler — composant qui livre un record. Avec Modulith, il est fourni : c'est le publieur Kafka de Modulith.
• Fallback handler — handler appelé quand tous les retries sont épuisés. Sert de dead letter applicative.

2Ce que fait déjà Modulith, et ce qui manque

Le point de départ est la note spring-modulith-monolithe-modulaire-avec-spring-boot (section 8). Le problème de fond, le dual write, est traité dans pattern-outbox-publication-fiable-de-messages-depuis-une-transaction-db.

Rappel du mécanisme natif. Quand un événement est publié, Modulith repère les listeners transactionnels concernés. Il écrit une ligne par listener dans event_publication, dans la transaction métier. L'externalisation vers Kafka est elle-même un de ces listeners.

Avant exécution : une ligne par listener, écrite avec la transaction métier. Source : doc Spring Modulith.

Après exécution : chaque listener marque sa ligne comme complétée. Une ligne non complétée est rejouable. Source : doc Spring Modulith.

Depuis la 2.0, chaque ligne porte un statut :

stateDiagram-v2
    [*] --> PUBLISHED : INSERT dans la transaction métier
    PUBLISHED --> PROCESSING : le listener démarre
    PROCESSING --> COMPLETED : listener OK
    PROCESSING --> FAILED : listener KO ou périmé
    FAILED --> RESUBMITTED : resubmit()
    RESUBMITTED --> PROCESSING
    COMPLETED --> [*]

Ce mécanisme protège contre la perte. Il ne protège pas contre le désordre ni contre les doublons entre instances. La doc elle-même le dit : le mode natif est pragmatique mais il manque des fonctions attendues d'un vrai outbox.

3Ce que Namastack Outbox apporte

Namastack Outbox est une librairie Spring Boot open source (Apache 2.0), écrite en Kotlin, utilisable en Java. Elle implémente l'outbox transactionnel sans composant d'infrastructure supplémentaire. Tout tourne dans l'application, avec la base de données comme seul point de coordination.

Écriture atomique de l'entité et du record, puis livraison asynchrone par le scheduler. Source : namastack.io.

Les garanties, telles que la doc les formule :

• Atomicité. Le record est écrit dans la même transaction que la donnée métier. Pas de record sans commit, pas de commit sans record.
• At-least-once. Un record peut être livré deux fois après un crash. Les consommateurs doivent être idempotents.
• Ordre par clé. Les records de même clé sont traités dans l'ordre de création. Les clés différentes sont traitées en parallèle.
• Scaling horizontal. 256 partitions fixes, calculées par MurmurHash3 sur la clé. Les partitions sont réparties entre les instances actives. Pas de verrou distribué.
• Retry. Politiques fixe, linéaire, exponentielle, avec jitter et filtres d'exceptions. Fallback handler après épuisement.
• Observabilité. Observations Micrometer, gauges d'état, propagation de trace à travers la frontière asynchrone.

Comment les instances se partagent le travail

flowchart LR
    subgraph DB["Base de données"]
        R["outbox_record<br/>key, payload, status,<br/>failure_count, next_retry_at"]
        I["outbox_instance<br/>heartbeat toutes les 5s"]
        P["outbox_partition<br/>256 slots → instance"]
    end
    A["Instance A<br/>partitions 0-127"] -->|heartbeat| I
    B["Instance B<br/>partitions 128-255"] -->|heartbeat| I
    I -->|rebalance toutes les 10s| P
    P -->|"hash(key) % 256"| R
    A -->|poll ses partitions| R
    B -->|poll ses partitions| R

Trois tables. outbox_record porte les événements. outbox_instance enregistre les instances vivantes par heartbeat. outbox_partition affecte chaque slot à une instance. Une instance qui ne bat plus depuis stale-instance-timeout (30 s par défaut) est retirée. Ses partitions sont redistribuées au prochain rebalance.

Le cycle interne, étape par étape

Le diagramme ci-dessus donne la structure. Voici la mécanique dans l'ordre où elle se déroule.

1. Insertion. Dans la transaction métier, la lib insère une ligne dans outbox_record. La ligne porte la clé (par exemple order-123), le payload, le type, le statut NEW, la date de création, et une colonne partition. Cette colonne est calculée à l'insertion : MurmurHash3(clé) mod 256. Le nombre de partitions est fixe. Il ne dépend pas du nombre de pods.

2. Registre des instances. Au démarrage, chaque pod s'enregistre dans outbox_instance avec un identifiant et un heartbeat. Le heartbeat est renouvelé toutes les 5 s (heartbeat-interval). Une instance silencieuse depuis 30 s (stale-instance-timeout) est considérée morte.

3. Attribution des partitions. Toutes les 10 s (rebalance-interval), chaque instance relit outbox_instance, trie les instances vivantes, et calcule de façon déterministe qui possède quoi : 256 partitions réparties à parts égales entre les N instances vivantes. Le résultat est écrit dans outbox_partition (partition vers instance). Il n'y a pas de coordinateur. Chaque instance arrive au même calcul parce qu'elle voit la même liste.

4. Poll. À chaque cycle (2 s en mode fixed, variable en mode adaptive), une instance ne lit que ses partitions : records en NEW ou FAILED, dont next_retry_at est passé, triés par date de création. Aucun SELECT FOR UPDATE SKIP LOCKED n'est nécessaire. Deux instances ne regardent jamais les mêmes partitions, donc il n'y a pas de contention.

5. Traitement. Un seul executor par instance. Le cycle se termine avant que le suivant démarre. Les records sont groupés par clé et traités dans l'ordre au sein d'une clé (batch-size clés par cycle). Succès : le record passe en COMPLETED, ou est supprimé si delete-completed-records=true. Exception : le record passe en FAILED, failure_count augmente, next_retry_at est calculé par la politique de retry, la dernière erreur est persistée. Avec stop-on-first-failure=true (défaut), les records suivants de la même clé attendent. Retries épuisés : le fallback handler prend la main, sinon le record reste en FAILED.

6. Rebalancing. Un pod tombe : après 30 s sans heartbeat il sort de la liste. Au check suivant, ses partitions sont réattribuées aux survivants. Un pod arrive : il s'enregistre, les autres recalculent, chacun lâche une partie de ses partitions. À l'arrêt propre, graceful-shutdown-timeout laisse le temps de finir le cycle en cours avant de se désinscrire.

Deux conséquences de cette mécanique :

• Entre la mort réelle d'un pod et sa détection, ou pendant un handoff, un record peut être traité deux fois. C'est le at-least-once de la section 8.
• Une clé bloquée par un record en échec ne bloque que sa partition. Les autres clés de la même instance continuent.

4Mise en place en trois étapes

L'exemple : un module order publie OrderCompleted vers le topic Kafka orders.completed, avec l'identifiant de commande comme clé.

Étape 1 : les dépendances

Le BOM Modulith aligne la version de Namastack. Modulith 2.1.1 embarque Namastack 1.8.1. On ne déclare pas la version de Namastack soi-même, sauf pour personnaliser (section 6).

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.modulith</groupId>
      <artifactId>spring-modulith-bom</artifactId>
      <version>2.1.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- registry Modulith persisté (JPA ou JDBC) -->
  <dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-starter-jpa</artifactId>
  </dependency>
  <!-- transport : publieur Kafka de Modulith -->
  <dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-events-kafka</artifactId>
  </dependency>
  <!-- ✓ intégration outbox : tire namastack-outbox-core + starter JDBC -->
  <dependency>
    <groupId>org.springframework.modulith</groupId>
    <artifactId>spring-modulith-starter-namastack</artifactId>
  </dependency>
</dependencies>

Le starter spring-modulith-starter-namastack ne fonctionne qu'avec une base relationnelle. Pas de MongoDB dans ce mode.

Étape 2 : activer le mode outbox

spring:
  modulith:
    events:
      externalization:
        mode: outbox        # ✓ délègue @Externalized à Namastack
  kafka:
    bootstrap-servers: localhost:9092

C'est la seule ligne obligatoire. Le multicaster d'événements de Namastack est désactivé par le starter. C'est celui de Modulith qui intercepte les événements et les route vers l'outbox.

Étape 3 : le code (inchangé)

// shop/order/OrderCompleted.java
@Externalized("orders.completed::#{#this.orderId()}")  // topic :: clé
public record OrderCompleted(UUID orderId, BigDecimal total) {}

@Service
class OrderManagement {

  private final OrderRepository orders;
  private final ApplicationEventPublisher events;

  @Transactional
  public void complete(UUID orderId) {
    var order = orders.findById(orderId).orElseThrow();
    order.markCompleted();
    events.publishEvent(new OrderCompleted(order.getId(), order.total()));  // ✓ record écrit dans cette transaction
  }
}

Rien ne référence Namastack. Le handler Kafka est fourni par Modulith. Le topic et la clé viennent de @Externalized. Le mapping et les headers restent configurables par EventExternalizationConfiguration, comme en mode natif.

5Le flux de bout en bout

sequenceDiagram
    participant S as OrderManagement
    participant M as Modulith (multicaster)
    participant DB as PostgreSQL
    participant SCH as Scheduler Namastack
    participant K as Kafka

    S->>S: order.markCompleted()
    S->>M: publishEvent(OrderCompleted)
    M->>M: événement @Externalized ? oui
    M->>DB: INSERT outbox_record (key = orderId, status = NEW)
    Note over S,DB: même transaction que la commande
    S->>DB: COMMIT
    loop toutes les 2 s (fixed) sur ses partitions
        SCH->>DB: SELECT records NEW, ordonnés par clé et date
        SCH->>K: send(topic = orders.completed, key = orderId, payload)
        alt envoi OK
            SCH->>DB: UPDATE status = COMPLETED (ou DELETE)
        else envoi KO
            SCH->>DB: UPDATE failure_count + 1, next_retry_at = backoff
            Note over SCH,DB: les records suivants de la même clé attendent
        end
    end

Points à lire sur le diagramme :

• L'écriture du record se fait dans la transaction de complete(). Un rollback annule les deux.
• La livraison est asynchrone et découplée de la requête. Le délai minimal est l'intervalle de polling.
• La clé issue de @Externalized sert à la fois de clé Kafka et de clé d'ordre dans l'outbox. Une commande garde donc son ordre de bout en bout.
• Avec stop-on-first-failure=true (défaut), un échec bloque les records suivants de la même clé. Les autres clés continuent.

6Configuration utile

Polling et traitement

namastack:
  outbox:
    polling:
      trigger: adaptive          # fixed | adaptive
      batch-size: 50             # clés par cycle (défaut 10)
      adaptive:
        min-interval: 500ms      # accélère quand il y a du travail
        max-interval: 5s         # ralentit quand la table est vide
    processing:
      stop-on-first-failure: true
      delete-completed-records: true     # ✓ la table ne grossit pas
      executor-core-pool-size: 4
      executor-max-pool-size: 8
    instance:
      heartbeat-interval: 5s
      stale-instance-timeout: 30s
      rebalance-interval: 10s

delete-completed-records=false par défaut. Comme pour le registry Modulith, la valeur par défaut garde tout. Sur un service à fort trafic, activer la suppression ou prévoir une purge.

Retry

namastack:
  outbox:
    retry:
      policy: exponential        # fixed | linear | exponential
      max-retries: 5
      exponential:
        initial-delay: 2s
        max-delay: 1m
        multiplier: 2.0
      jitter: 500ms              # évite les retries synchronisés entre instances
      exclude-exceptions:
        - org.apache.kafka.common.errors.SerializationException   # ⚠️ inutile de réessayer un payload invalide

Pour une politique en code, on déclare un bean OutboxRetryPolicy. Cela demande io.namastack:namastack-outbox-api en dépendance directe, via le BOM Namastack :

<dependency>
  <groupId>io.namastack</groupId>
  <artifactId>namastack-outbox-api</artifactId>   <!-- version alignée par le BOM Modulith -->
</dependency>

@Configuration
class OutboxConfig {

  @Bean
  OutboxRetryPolicy outboxRetryPolicy(OutboxRetryPolicy.Builder builder) {  // ✓ builder préconfiguré depuis le yaml
    return builder
        .retryOn(TimeoutException.class, org.apache.kafka.common.errors.RetriableException.class)
        .noRetryOn(SerializationException.class)
        .build();
  }
}

Ordre de résolution : politique du handler (interface OutboxRetryAware ou @OutboxRetryable), puis bean global, puis propriétés yaml.

Fallback : la dead letter applicative

Quand max-retries est atteint, le record passe en FAILED. Un @OutboxFallbackHandler peut le prendre en charge : log structuré, écriture dans une table de quarantaine, alerte. Sans fallback, le record reste en base avec le statut FAILED. Il est visible dans les métriques (section 7) mais rien ne se passe.

Schéma et migrations

Namastack crée ses trois tables au démarrage si namastack.outbox.jdbc.schema-initialization.enabled=true (défaut). En production, désactiver et gérer le DDL par Flyway. Les noms et le schéma sont configurables :

namastack:
  outbox:
    jdbc:
      schema-initialization:
        enabled: false             # ✓ Flyway gère le DDL
      schema-name: messaging
      table-prefix: ""
      table-names:
        record: outbox_record
        instance: outbox_instance
        partition: outbox_partition

Modulith crée aussi sa table event_publication de son côté. Deux jeux de tables cohabitent : le registry Modulith pour les listeners internes, l'outbox Namastack pour la sortie vers le broker. Le DDL de référence est dans le repo GitHub de Namastack (module namastack-outbox-jdbc) et dans l'appendice de la doc Modulith.

Tests

# application-test.yml
namastack:
  outbox:
    enabled: false                 # ✓ pas de scheduler ni de heartbeat dans un slice test

Namastack active @EnableScheduling par auto-configuration. Désactiver l'outbox désactive aussi cette activation. Pour tester le flux complet, garder l'outbox actif et utiliser l'API Scenario de Modulith avec un Kafka Testcontainers.

7Observabilité

Ajouter io.namastack:namastack-outbox-observability. Les anciens modules -metrics et -tracing sont dépréciés. Le module s'auto-configure dès qu'un ObservationRegistry Micrometer existe.

Trois alertes suffisent pour démarrer :

1. outbox.records{status=failed} > 0 pendant 5 minutes.
2. outbox.records{status=new} qui monte sans redescendre : la livraison ne suit pas, ou le broker est injoignable.
3. outbox.cluster.partitions.unassigned > 0 pendant plus d'un rebalance : une instance est morte et personne n'a repris ses partitions.

Le tracing traverse la frontière asynchrone. À l'écriture du record, le module sérialise le contexte de trace (traceparent) dans la colonne context. À la livraison, il ouvre un span enfant sous la trace d'origine. La requête HTTP qui a créé la commande et l'envoi Kafka apparaissent dans la même trace. Le même mécanisme (OutboxContextProvider) propage aussi un tenant ou un correlation id.

Modulith ajoute de son côté /actuator/modulith et les compteurs module.events.published. Les deux jeux de métriques se complètent : Modulith dit combien d'événements ont été publiés, Namastack dit combien ont été livrés.

8Pièges de production

Autres points à connaître :

• Deux tables, deux purges. event_publication (Modulith) et outbox_record (Namastack) grossissent chacune de leur côté. Régler completion-mode côté Modulith et delete-completed-records côté Namastack.
• Versions alignées par le BOM Modulith. Déclarer un BOM Namastack plus récent que celui attendu par Modulith est possible, mais c'est une combinaison non testée par Modulith. Suivre la version tirée par le BOM, sauf besoin précis.
• stop-on-first-failure bloque une clé, pas le monde. Une commande dont un événement est en échec voit tous ses événements suivants attendre. Si les événements d'une même clé sont indépendants, passer à false.
• Le payload est du JSON Jackson. Pas d'Avro ni de Schema Registry par défaut. Pour un contrat externe typé, produire un payload dédié via EventExternalizationConfiguration.mapping(...) et versionner ce contrat. Les bases Spring Kafka sont dans kafka-spring-core.
• Relationnel uniquement. Le starter Modulith pour Namastack ne couvre pas MongoDB, même si Namastack seul le fait.

9Face aux alternatives

Quand le choisir

Modulith + Namastack :

• plusieurs réplicas de l'application
• l'ordre par agrégat compte pour les consommateurs
• pas d'équipe plateforme pour opérer Kafka Connect
• on veut rester dans le périmètre de l'application Spring Boot

Externalisation native :

• une seule instance, ou l'ordre n'a pas d'importance
• prototype, ou volume faible
• on accepte de gérer le rejeu avec FailedEventPublications

JobRunr :

• JobRunr est déjà en place pour d'autres tâches et l'on veut un seul mécanisme de jobs
• l'ordre n'est pas une contrainte

CDC :

• volume élevé, où le polling coûte trop cher à la base
• la latence de livraison doit être minimale
• une plateforme Kafka Connect existe déjà et l'équipe sait l'opérer

Sources

• Spring Modulith Integration — guide officiel Namastack : pourquoi l'intégration, tableau EPR vs outbox, migration en trois étapes, précédence du multicaster
• Working with Application Events — doc Modulith 2.1.1 : registry, cycle de vie, externalisation native, sections Namastack et JobRunr, images du registry
• Namastack Outbox Configuration Reference — toutes les propriétés namastack.outbox.*, activation automatique du scheduling
• Core Features — ordre par clé, stop-on-first-failure, partitionnement 256 slots et coordination d'instances
• Reliability Guarantees — at-least-once, fenêtre de doublons pendant le rebalancing, pas d'ordre global
• Retry Mechanisms — politiques, filtres d'exceptions, OutboxRetryPolicy et builder, ordre de résolution
• Observability — métriques, gauges, schéma de tags, propagation de trace
• Outbox Pattern: The Hard Parts — article du mainteneur sur le hachage consistant, l'attribution des partitions et le rebalancing
• namastack/namastack-outbox — code source, DDL par SGBD, exemple namastack-outbox-example-modulith
• Spring Modulith 2.1 GA released — annonce du mode outbox et des contributions Namastack / JobRunr
• Never Lose an Event Again — article du mainteneur, prise en main et vue d'ensemble
• spring-modulith-example-outbox — exemple officiel côté Spring