Heisenberg · Vidocq

Heisenberg est l’implémentation MicroProfile Fault Tolerance 4.1 de l’écosystème Vidocq. Elle applique les politiques @Retry, @Timeout, @CircuitBreaker, @Bulkhead, @Fallback et @Asynchronous aux beans CDI au travers d’un unique intercepteur, branchée sur Vauban pour le container et sur Ravel pour la configuration. Objectif : conformance 100 % au TCK MicroProfile Fault Tolerance 4.1 (actuellement 463/463), zéro dépendance externe au-delà des specs, JPMS strict, prête pour jlink.

Origine du nom

Werner Heisenberg (1901-1976), physicien allemand. Formula en 1927 le principe d’incertitude, pierre angulaire de la mécanique quantique : la position et la quantité de mouvement d’une particule ne peuvent pas être mesurées simultanément avec une précision arbitraire — Δp · Δx ≥ ℏ/2. Prix Nobel de physique 1932 « pour la création de la mécanique quantique ». Voir la fiche Wikipédia.

Heisenberg a posé que l’incertitude est intrinsèque, pas un défaut de l’instrument. Le runtime Heisenberg encapsule l’incertitude inhérente aux appels réseau et aux services distants — latence variable, échecs transitoires, surcharge — et y répond avec des politiques formellement composables, ordonnées comme des opérateurs non-commutatifs.

Heisenberg, le physicien Heisenberg, le runtime

Heisenberg, le physicien	Heisenberg, le runtime
Principe d’incertitude	L’appel réseau est intrinsèquement incertain — la réussite n’est pas déterminée.
Matrices observables non-commutatives	Politiques non-commutatives : `@Retry ∘ @Timeout ≠ @Timeout ∘ @Retry`.
Mécanique matricielle (Göttingen, 1925)	Composition formelle des aspects — chaîne d’intercepteurs ordonnée par la spec §2.5.
Inégalité `Δp · Δx ≥ ℏ/2`	Borne intrinsèque latence × débit (Little’s Law) — un `@Bulkhead` la rend explicite.
Effondrement du paquet d’ondes	`@CircuitBreaker` qui s’ouvre — l’état devient discret (OPEN), les appels suivants sont court-circuités.
États propres et observables compatibles	Politiques compatibles, composables dans un ordre canonique unique.

Principe d’incertitude

L’appel réseau est intrinsèquement incertain — la réussite n’est pas déterminée.

Matrices observables non-commutatives

Politiques non-commutatives : @Retry ∘ @Timeout ≠ @Timeout ∘ @Retry.

Mécanique matricielle (Göttingen, 1925)

Composition formelle des aspects — chaîne d’intercepteurs ordonnée par la spec §2.5.

Inégalité Δp · Δx ≥ ℏ/2

Borne intrinsèque latence × débit (Little’s Law) — un @Bulkhead la rend explicite.

Effondrement du paquet d’ondes

@CircuitBreaker qui s’ouvre — l’état devient discret (OPEN), les appels suivants sont court-circuités.

États propres et observables compatibles

Politiques compatibles, composables dans un ordre canonique unique.

En un coup d’œil

Spec implémentée

MicroProfile Fault Tolerance 4.1

Dépôt

https://codeberg.org/Vidocq/heisenberg

Java

25 (LTS)

Modules JPMS

io.vidocq.heisenberg.api, io.vidocq.heisenberg.core, io.vidocq.heisenberg.cdi.vauban

Packages publics

io.vidocq.heisenberg.api. (SPI stable), io.vidocq.heisenberg.cdi. (intégration CDI)

Dépendances runtime

microprofile-fault-tolerance-api 4.1, jakarta.enterprise.cdi-api 4.1 (provided), jakarta.interceptor-api 2.2 (provided), ravel-mp-config-api (MicroProfile Config 3.1), opentelemetry-api 1.39 (requires static)

Prête pour jlink

✅ — chaque sous-module a son module-info.java, pas de fallback Automatic-Module-Name côté production.

TCK MP FT 4.1

✅ 463 / 463 — voir état détaillé

Trois traits identitaires

Zéro librairie tierce d’implémentation — seules les API Jakarta EE et MicroProfile spécifiées sont compilées. Pas de SmallRye Fault Tolerance, pas de Hystrix, pas de Resilience4j. Les automates (retry, circuit breaker, bulkhead) sont écrits à la main dans heisenberg-core.
Virtual threads natifs pour @Asynchronous et @Timeout — Thread.ofVirtual() + join(Duration) bornent chaque tentative ; aucun pool de threads plateforme n’est créé. Pas de synchronized, pas de ThreadLocal — ReentrantLock, Semaphore, LongAdder, ConcurrentHashMap et ScopedValue sont préférés.
Config Ravel + BCE Vauban — toutes les clés fault-tolerance/… sont résolues via Ravel (MicroProfile Config 3.1) ; l’intercepteur unique est enregistré par une Build Compatible Extension Vauban, qui scanne et indexe les annotations au démarrage.

Positionnement dans l’écosystème

L’ordre d’enveloppement de la chaîne suit la spec MP FT 4.1 §2.5 — @Fallback est l’enveloppe la plus externe, la méthode cible est au coeur. Cassini et tout client HTTP applicatif bénéficient ainsi de la tolérance aux pannes sans modification de code. Humboldt (OpenTelemetry) et l’implémentation MP Metrics Dirac peuvent récolter les métriques §9 et §10 ; le script run-tck-no-observability.sh les coupe pour valider que la tolérance fonctionne sans aucune dépendance d’observabilité au classpath.

Ressources rapides

Démarrage rapide — première méthode protégée, première chaîne @Retry + @CircuitBreaker + @Fallback.
Concepts — annotations, ordre de composition, états du circuit breaker.
Cas d’usage — clients REST robustes, @Asynchronous, FallbackHandler, surcharges MP Config.
Référence — artefacts, modules JPMS, annotations, clés fault-tolerance/*.
Fonctionnement interne — moteurs purs, StateRegistry, virtual threads.
TCK — exécution, statut, mode no-observability.
Migration — depuis SmallRye Fault Tolerance ou Resilience4j.

Bugs et benchmarks consolidés : BUG.md, BENCH.md.

Suivant : Démarrage rapide.