Vidocq Documentation

Cette page montre comment ajouter Knock à un projet, écrire un premier HealthCheck, le faire découvrir par CDI et servir les endpoints MicroProfile Health. Aucune réflexion ne s’exécute au démarrage : la découverte passe par une Build Compatible Extension de Vauban et le runtime ne s’appuie que sur du câblage généré.

Prérequis

  • Java 25 — Temurin recommandé (java=25-tem dans .sdkmanrc). Module path activé.

  • Maven 3.9.16 — épinglé via .sdkmanrc à la racine du dépôt.

  • JPMS strict : un module-info.java par module Maven.

Coordonnées Maven

Choisissez les modules correspondant à votre niveau d’intégration. Pour une application CDI + Jakarta REST, l’API et les deux modules d’intégration suffisent :

<properties>
    <knock.version>0.2.0-SNAPSHOT</knock.version>
</properties>

<dependencies>
    <!-- API MicroProfile Health + SPI Knock -->
    <dependency>
        <groupId>io.vidocq.knock</groupId>
        <artifactId>knock-api</artifactId>
        <version>${knock.version}</version>
    </dependency>
    <!-- Cœur autonome : registre, agrégation, sérialisation JSON-P -->
    <dependency>
        <groupId>io.vidocq.knock</groupId>
        <artifactId>knock-core</artifactId>
        <version>${knock.version}</version>
        <scope>runtime</scope>
    </dependency>
    <!-- Découverte CDI des beans @Liveness/@Readiness/@Startup (Vauban) -->
    <dependency>
        <groupId>io.vidocq.knock</groupId>
        <artifactId>knock-cdi-vauban</artifactId>
        <version>${knock.version}</version>
        <scope>runtime</scope>
    </dependency>
    <!-- Endpoints Jakarta REST /health* (déployés sur Cassini) -->
    <dependency>
        <groupId>io.vidocq.knock</groupId>
        <artifactId>knock-jaxrs</artifactId>
        <version>${knock.version}</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

knock-jaxrs est le nom de l’artefact (il ne dépend que de l’API jakarta.ws.rs). Cassini est le runtime JAX-RS qui héberge la ressource au déploiement — Knock n’importe aucun paquet interne de Cassini.

Premier contrôle

Un contrôle de santé est un bean CDI implémentant HealthCheck, portant exactement un qualificateur de sonde :

package io.example;

import jakarta.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Liveness;

@Liveness
@ApplicationScoped
public class DatabaseCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("database")
                .up()
                .withData("responseTime", "8ms")
                .build();
    }
}

Un contrôle doit porter exactement l’un de @Liveness, @Readiness ou @Startup. Un bean implémentant HealthCheck sans qualificateur de sonde est rejeté par l’extension CDI au déploiement (MicroProfile Health §4.2).

module-info.java minimal

module io.example {
    requires microprofile.health.api;
    requires jakarta.cdi;
    requires jakarta.inject;
    exports io.example;
}

L’extension knock-cdi-vauban découvre les beans io.example via le graphe de modules — ni opens ni balayage du classpath ne sont nécessaires.

Interroger les endpoints

Une fois déployés sur Cassini, les quatre endpoints répondent immédiatement :

curl -i http://localhost:8080/health
{
  "status": "UP",
  "checks": [
    {
      "name": "database",
      "status": "UP",
      "data": { "responseTime": "8ms" }
    }
  ]
}

Un agrégat DOWN bascule le statut HTTP à 503 tout en conservant la même forme JSON.

Autonome (sans CDI)

knock-core est du Java SE pur. Vous pouvez le piloter sans conteneur via la façade KnockHealthService :

import io.vidocq.knock.spi.HealthCheckRegistry;
import io.vidocq.knock.spi.ProbeType;
import io.vidocq.knock.internal.KnockHealthCheckRegistry;
import io.vidocq.knock.runtime.KnockHealthService;
import io.vidocq.knock.runtime.HealthReport;

HealthCheckRegistry registry = new KnockHealthCheckRegistry();
registry.register(new DatabaseCheck());

KnockHealthService service = new KnockHealthService(registry);
HealthReport report = service.report(ProbeType.ALL);

System.out.println(report.httpStatus());   // 200 ou 503
System.out.println(report.json());         // charge utile sérialisée

Compiler et exécuter

sdk env
./mvnw -ntp install -DskipTests
./mvnw test

Étape suivante

  • Schémas d’utilisation — qualificateurs de sonde, données de réponse, agrégation, gestion des erreurs.

  • Concepts — contrôle de santé, type de sonde, registre, instantané, contrat JSON.