Vidocq Documentation

Vidocq Runtime adopte le vocabulaire d’extensions popularisé par Quarkus, mais l’implémente sur un socle 100 % JDK (CDI Lite via Vauban + Class-File API standard, JEP 484). Cette page définit les termes utilisés dans le reste de la documentation.

Extension

Une extension est un module Maven qui contribue au runtime via la SPI vidocq-runtime-spi. Elle se présente comme :

  • un fragment de bytecode et de configuration injecté dans la séquence de boot ;

  • une ou plusieurs classes annotées @BuildStep qui s’exécutent à la compilation ;

  • éventuellement un ou plusieurs @Recorder qui produisent du bytecode rejoué au démarrage.

Une extension est statique : elle ne charge rien dynamiquement à l’exécution. Tout ce qu’elle apporte est résolu à mvn package.

Build step

Une build step est une méthode annotée @BuildStep dans une extension. Elle :

  • consomme zéro, un ou plusieurs BuildItem en paramètres ;

  • produit un ou plusieurs BuildItem en valeur de retour ou via BuildProducer<T> ;

  • s’exécute à la compilation, dans un graphe topologique calculé par vidocq-runtime-core.

Le moteur d’orchestration garantit qu’une build step ne tourne qu’après la production de ses entrées et avant la consommation de ses sorties. Les paires producteur/consommateur définissent les arêtes du graphe.

BuildItem

Un BuildItem est l’unité d’échange entre build steps. Trois familles :

  • SimpleBuildItem — un seul producer autorisé (ex. JaxRsApplicationBuildItem) ;

  • MultiBuildItem — N producers possibles (ex. BeanBuildItem, ResourceBuildItem) ;

  • SymbolicBuildItem — marqueur de phase sans payload (ex. ApplicationStartBuildItem).

Recorder

Un recorder est une classe annotée @Recorder dont les invocations sont enregistrées plutôt qu’exécutées. À la compilation, chaque appel de méthode sur un recorder est sérialisé sous forme de bytecode invokevirtual dans une classe générée par Class-File API. Au démarrage, ce bytecode est rejoué — sans réflexion, sans proxy.

Les recorders distinguent deux phases :

  • @Record(STATIC_INIT) — exécuté tôt, dans le bloc statique de la classe générée ;

  • @Record(RUNTIME_INIT) — exécuté au démarrage, après la lecture de la configuration externe.

Lifecycle phase

La séquence de boot Vidocq Runtime comporte cinq phases ordonnancées :

  1. Config — résolution des sources MicroProfile Config, surcharge externe.

  2. Extensions init — chaque extension reçoit ExtensionContext et publie ses BuildItem runtime.

  3. CDI start — Vauban démarre le BeanManager (les beans ont déjà été indexés au build).

  4. Transport bind — Chappe ouvre les listeners HTTP/1.1, H2, H3 selon la config.

  5. Routes register — Cassini et Foy enregistrent ressources REST et servlets ; Mansart ouvre le pool JDBC.

Différences notables avec Quarkus

Aspect Quarkus Vidocq Runtime

CDI runtime

ArC (custom)

Vauban (CDI 4.1 Lite, TCK 774/774)

Génération bytecode

Gizmo (ASM)

Class-File API JDK (JEP 484)

Transport HTTP

Vert.x

Chappe sur virtual threads

JSON

Jackson

Champollion (JSON-B 3.0)

Persistence

Hibernate ORM/Reactive

Mansart (Jakarta Data 1.0 + JDBC)

JDK minimum

17

25 (LTS)

JPMS natif

Non

Oui — module-info.java partout

Composition des six briques

Vidocq Runtime n’invente aucun runtime ; il compose les six briques fondatrices. Une extension vidocq-runtime-cassini-rest-extension enregistre par exemple un build step qui :

  • consomme CdiBeanIndexBuildItem produit par vidocq-runtime-vauban-extension ;

  • déclenche la génération du routage statique de Cassini ;

  • produit HttpRouteBuildItem consommé par vidocq-runtime-chappe-webserver-extension.

C’est cette grammaire de BuildItem qui rend l’écosystème homogène alors que chaque brique reste autonome dans son propre repo.

Pour aller plus loin