Kafka Listener Harmonization

English

Finalization of a shared Kafka listener pattern for Kotlin services.

Completed work

• Created a reusable Kafka consumer template focused on explicit routing and small integration points.
• Standardized message selection with the topic, required headers, and an optional Kafka key.
• Unified typed JSON decoding through Jackson before dispatching messages to suspendable handlers.
• Removed raw-message fallback paths so malformed or unsupported messages are handled deliberately instead of silently branching through alternate flows.
• Added a clear non-retryable failure category for terminal processing errors while keeping unexpected failures retryable.
• Migrated an existing listener to the registration-based model and verified the template and integration test suites.

Current state

The consumer template now exposes a compact API: each operation registers its topic, header filters, optional key filter, payload type, and suspendable handler. This keeps routing decisions visible at the boundary and leaves business logic inside the operation implementation.

Next steps

• Apply the same listener template progressively to other Kafka consumers.
• Keep failure classification explicit as new operations are added.
• Add deployment-level observability or dead-letter handling only where runtime behavior proves it is needed.

This worklog entry was summarized with AI assistance.

Français

Finalisation d’un modèle partagé de listener Kafka pour des services Kotlin.

Travaux réalisés

• Création d’un template Kafka réutilisable centré sur un routage explicite et des points d’intégration réduits.
• Standardisation de la sélection des messages avec le topic, les headers requis et une clé Kafka optionnelle.
• Unification du décodage JSON typé avec Jackson avant la distribution vers des handlers suspendables.
• Suppression des chemins de traitement brut afin que les messages invalides ou non supportés soient traités explicitement.
• Ajout d’une catégorie claire d’échec non rejouable pour les erreurs terminales, tout en conservant les erreurs inattendues comme rejouables.
• Migration d’un listener existant vers le modèle par enregistrement, avec vérification des suites de tests du template et de l’intégration.

État actuel

Le template expose maintenant une API compacte : chaque opération enregistre son topic, ses filtres de headers, son filtre de clé optionnel, son type de payload et son handler suspendable. Les décisions de routage restent visibles à la frontière, tandis que la logique métier reste dans l’implémentation de l’opération.

Prochaines étapes

• Appliquer progressivement le même template aux autres consommateurs Kafka.
• Conserver une classification explicite des échecs lors de l’ajout de nouvelles opérations.
• Ajouter de l’observabilité ou une gestion dead-letter côté déploiement uniquement si le comportement réel le justifie.

Cette entrée de journal a été résumée avec l’aide de l’IA.