Vidocq Documentation

Référence technique consolidée. Cette page sert de point d’ancrage pour les liens externes (issues, RFC, autres sites Antora).

Artefacts Maven

Artefact Rôle

io.vidocq.foy:foy-api:0.1.0-SNAPSHOT

Interfaces SPI publiques : SessionStore, SecurityProvider, AuthenticatedUser. Zéro dépendance hors jakarta.servlet-api.

io.vidocq.foy:foy-core:0.1.0-SNAPSHOT

Moteur Servlet 6.1 — dispatcher, filter chain, sessions, error pages, listeners, sécurité, parser web.xml, multipart.

io.vidocq.foy:foy-chappe:0.1.0-SNAPSHOT

Pont HTTP vers Chappe (FoyChappeBoot, ChappeServletBridge).

io.vidocq.foy:foy-cdi-vauban:0.1.0-SNAPSHOT

Pont CDI vers Vauban (FoyVaubanBootstrap).

io.vidocq.foy:foy-tck

Harness Arquillian pour le TCK officiel — POM modelVersion 4.0.0 standalone, hors reactor (voir État TCK).

Modules JPMS et exports

module io.vidocq.foy.api {
    requires transitive jakarta.servlet;
    requires static jakarta.annotation;

    exports io.vidocq.foy.spi.session;    // SessionStore
    exports io.vidocq.foy.spi.security;   // SecurityProvider, AuthenticatedUser
}
module io.vidocq.foy.core {
    requires transitive io.vidocq.foy.api;
    requires transitive jakarta.servlet;
    requires static jakarta.cdi;
    requires static jakarta.annotation;
    requires java.xml;
    requires static java.net.http;
    requires io.vidocq.chappe.api;        // couplage M1 — sera SPI en M2

    exports io.vidocq.foy.internal.async;
    exports io.vidocq.foy.internal.boot;
    exports io.vidocq.foy.internal.bridge;
    exports io.vidocq.foy.internal.container;
    exports io.vidocq.foy.internal.dispatcher;
    exports io.vidocq.foy.internal.error;
    exports io.vidocq.foy.internal.http;
    exports io.vidocq.foy.internal.listener;
    exports io.vidocq.foy.internal.security;
    exports io.vidocq.foy.internal.session;
    exports io.vidocq.foy.internal.webxml;
}
module io.vidocq.foy.chappe {
    requires transitive io.vidocq.foy.api;
    requires io.vidocq.foy.core;
    requires io.vidocq.chappe.api;
    requires jakarta.servlet;
    requires jakarta.cdi;

    exports io.vidocq.foy.chappe;         // FoyChappeBoot
}
module io.vidocq.foy.cdi.vauban {
    requires transitive io.vidocq.foy.api;
    requires jakarta.cdi;
    requires io.vidocq.vauban.core;

    exports io.vidocq.foy.cdi.vauban;     // FoyVaubanBootstrap
}

Les packages io.vidocq.foy.internal.* sont exportés pour permettre des intégrations avancées (custom dispatcher, observabilité). Ils ne sont pas stables au sens semver — voir Migration pour les variations entre jalons.

API publique : FoyChappeBoot

Méthode Description

FoyChappeBoot.builder()

Retourne un Builder neuf.

Builder.beanManager(BeanManager bm)

Obligatoire. BeanManager Vauban depuis lequel les beans @WebServlet / @WebFilter / @WebListener seront résolus.

Builder.contextPath(String path)

Préfixe d’URL servi par ce container. Défaut : "/".

Builder.sessionTimeoutSeconds(int seconds)

Timeout de session en secondes. Défaut : 1800 (30 min).

Builder.build()

Retourne Optional<Mounted>. Vide si aucun bean Servlet/Filter/Listener n’a été découvert.

Mounted.handler()

Le io.vidocq.chappe.api.Handler à monter sur un ChappeMountPoint.

Mounted.mountPrefix()

Préfixe de mount à utiliser ("" si contextPath == "/").

Mounted.servletContext()

Le VidocqServletContext du container — utile pour l’observabilité.

Mounted.fireContextInitialized()

Déclenche les ServletContextListener.contextInitialized (à appeler après mount).

Mounted.fireContextDestroyed()

Déclenche les ServletContextListener.contextDestroyed (à appeler avant unmount).

SPI publique (foy-api)

Type Rôle

io.vidocq.foy.spi.session.SessionStore

Backend de stockage de sessions. Default : InMemorySessionStore. Implémenter pour Redis, Hazelcast, JDBC, etc.

io.vidocq.foy.spi.security.SecurityProvider

Authentification applicative. Default : AnonymousSecurityProvider (dev) ou BasicAuthenticator. Implémenter pour OIDC, LDAP, JWT.

io.vidocq.foy.spi.security.AuthenticatedUser

Représentation immutable d’un utilisateur authentifié (login, rôles, attributs).

Configuration web.xml

Foy lit le WEB-INF/web.xml standard Servlet 6.1 :

  • <servlet> / <servlet-mapping>

  • <filter> / <filter-mapping>

  • <listener>

  • <session-config> (timeout, cookie config)

  • <security-constraint>, <login-config>, <security-role>

  • <error-page>

  • <welcome-file-list>

  • <context-param> exposés via ServletContext.getInitParameter

  • <multipart-config> au niveau <servlet>

Les fragments META-INF/web-fragment.xml sont mergés selon metadata-complete standard.

Comparaison API Servlet 6.1

Domaine Statut Foy Notes

Core (Servlet, HttpServlet, Filter)

✅

Couverture quasi complète au TCK officiel.

RequestDispatcher (forward / include)

✅

Cross-context (getContext) non implémenté — voir TCK.

Async (AsyncContext)

⚠️

Cas standards OK ; setTimeout + dispatch tardif : encore quelques erreurs TCK.

Multipart (@MultipartConfig)

✅

Streaming sur le body Chappe.

Sessions

✅

InMemorySessionStore ; SPI SessionStore pour distribution.

Security (Basic)

✅

BasicAuthenticator + <security-constraint>.

Security (Form, Digest, Jakarta Auth)

❌

// TODO@user: planifié.

WebSocket (Servlet 6.1 upgrade)

❌

// TODO@user: planifié.

JSP

❌

Non supporté, non planifié.

Compatibilité

  • Java 25 (LTS)

  • Maven 3.9.16

  • Jakarta Servlet 6.1

  • JPMS strict, virtual threads (un VT par requête)

  • AOT-friendly (pas de réflexion, pas de proxy dynamique)

Bugs et benchmarks

  • lien:https://codeberg.org/Vidocq/foy/src/branch/main/BUG.md[BUG.md] — bugs reproductibles, hypothèses, statut.

  • lien:https://codeberg.org/Vidocq/foy/src/branch/main/BENCH.md[BENCH.md] — chiffres JMH/wrk, deltas vs run précédent.