Vidocq 0.4.0-RC1 Is Out: Servlet 6.1, Pages, MicroProfile 7.2 and a Better Development Loop

Foy, the Servlet implementation of the family, was a standalone brick in 0.3.0. In 0.4.0 it is a Vidocq extension, vidocq-runtime-foy-servlet-extension, and a Servlet application is an ordinary Vidocq application: your servlets, filters, listeners, web.xml and ServletContainerInitializer`s are served on the HTTP server the runtime already starts, with Vauban providing the CDI beans behind them. CDI works the way you expect: the request context is active for every request, filters and listeners are beans, and a `@SessionScoped bean lives with the HTTP session.

The measure that matters is the official Jakarta Servlet 6.1 TCK:

The seven skipped tests are server push, which Chappe does not implement. When we started Foy, it passed 920 of those 1714. The road from there is the 34 Servlet fixes of the last section: sessions, dispatching, async, upgrade, error pages, security. One limit is stated plainly in the documentation: the session scope is Vauban-only in Foy for now.

Peano implements Jakarta Expression Language 6.0, and passes the official TCK, 361 tests out of 361, on Temurin 25. It is the engine behind #{…​} in pages, and it is a dependency of Ibarra rather than something you configure.

Ibarra implements Jakarta Pages 4.0, what you may still call JSP. The official TCK passes 682 of 682. The design choice is the one of the rest of the family: no work at startup that a build can do. vidocq:generate compiles your pages with Ibarra into the application module, and a page that does not compile fails the build instead of failing the first request that asks for it. The runtime extension, vidocq-runtime-ibarra-pages-extension, serves them through the Servlet extension, and an application made of pages only can be deployed. In a project: vidocq extension add ibarra-pages. The Bistro example shows pages next to servlets.

Both ship named Java modules, like every brick, and both are documented on the 0.4.0-RC1 line.

The runtime now targets MicroProfile 7.2, and the three specifications that changed are implemented:

One precision, because it matters for the word "compatible". The MicroProfile 7.2 finals are still under ballot at the Eclipse Foundation. We ran the TCKs of the release candidates, which are byte-identical to the finals, and they are green. We will run them again on the finals the day they are on Maven Central, and not before we say "MicroProfile 7.2 compatible".

A brick should not need Vauban to be correct, and Vauban should not be the only thing proving it. Each brick now has an <brick>-it-other-containers module that runs its jars, unchanged, under Weld SE on a plain class path and, for the MicroProfile bricks and Champollion, as a WAR on Open Liberty, with the server’s own implementation of that specification turned off. Cassini and Foy, which an application server replaces with its own Jakarta REST and Servlet, are proven on Weld SE only.

That found real bugs, and they are fixed: normal-scoped beans could not load outside Vauban, because the build wove a constructor taking a vauban-api type that was provided (Knock, Heisenberg, Cervantes, Humboldt); Heisenberg keyed metric names and configuration overrides by Weld’s subclass; Humboldt’s span finalizer turned every exception, a 404 included, into a 500. A brick now depends on APIs, and its Vidocq extension brings the implementations. The page of each brick proven on Open Liberty says which server features to keep off, in a WARNING block its Open Liberty module tests.

A Vaadin application runs on Vidocq, in dev mode with vidocq:dev, packaged with vidocq:package, and in a jlink image. The story of how we got there, and of what we asked from Vaadin, is in its own post; what changed in the runtime is that every fix it required is now generic:

The last fix came the night before the release. After mvn clean, vidocq:dev answered 404 on a Vaadin application and vidocq:run answered 500, because nothing had built the project. vidocq:dev now builds a project nobody built, and says so. We found it by checking the release candidate against a real Vaadin application, which is why the check exists.

A runtime can boot in 120 milliseconds and still lose a new user in the first ten minutes. That is not spent in the runtime. It is spent in the pom, in module-info.java, in a warning nobody explains, in a command that works one way and its Maven twin another. 0.4.0 is the release where we went after those ten minutes.

This is how. First we made the CLI and the Maven plugin one tool. Then we audited the result with the eyes of someone who has never seen Vidocq, found eleven bugs we did not like, and changed what an application has to carry. At the end, the session you get with 0.4.0-RC1, command by command.

The runtime boots in about 120 milliseconds; a loop that tells you nothing about what it started wastes them. 0.4.0 makes the application describe itself.

Every boot says what it is. Version, commit and build time (Vidocq 0.4.0-RC1 (…)), the Java version, the launch mode (dev, test or prod, with the signal it was read from) and the debugger address, then a startup report just before Started in: the listeners with the address they really bound (so port=0 prints the real port), the REST routes, the Servlet context, the migrations. A terminal gets the banner, a container or CI gets one log line, and the console logs are one aligned line per record unless you configured logging yourself.

Every jar built on vidocq-parent carries META-INF/vidocq/build-info/<artifactId>.properties, so a stack trace that mixes two builds can be told apart at a glance.

The dev console. Under mvn vidocq:dev (or vidocq dev), Vidocq dev console: http://127.0.0.1:8888/ opens a read-only page on a loopback listener of its own. Each extension contributes a live panel, and the console adds its own:

The actions are behind an origin check and a token generated at each boot, and the five minutes of history behind every chart live on the server, so a hidden tab loses nothing. The console is a development tool and stays one: it is added by vidocq:dev itself, so there is nothing to declare, and the -dev panel modules are never packaged.

A dev MCP server for coding agents. In a dev launch the console is also an MCP server, at POST /mcp on its own listener, with the console’s panels as read-only tools. A coding agent can ask the running application which beans exist, which configuration it read, what the last log lines say or whether a health check is down, instead of guessing from the source. It is read-only on purpose.

Continuous testing. vidocq:dev runs the application’s tests after every reload, or alone after a test-only change without reloading, and the new vidocq:test goal (vidocq test) does the same without the application. With @VidocqTest from the previous section, a test of the real application is a few lines.

Dev services. PostgreSQL and Keycloak start in containers (Testcontainers 2) named vidocq-dev-<application>-…, so you can find them. They are visible in the console, aware of vidocq.properties (a PostgreSQL container starts only for an application that is on PostgreSQL, never in place of your H2 URL), and available to vidocq:run and to tests, not only to vidocq:dev. Each key an application gets from a dev service is marked -Dvidocq.dev.provided.<key>=<provider>, so nothing arrives by magic.

Smaller things that cost us time before. vidocq:run runs the application once, in a JVM forked as the production launcher does. vidocq:dev passes -Dvidocq.* on to the application. The debugger listens on this machine only, where it used to listen on every interface. Every main shape Java 25 accepts starts the application. A boot that fails stops what it had already started. Schema migrations find their scripts where the application runs, in the module layer.

The panels above are not special. Each one is a dev extension, written against two small interfaces that an extension of yours can use as well. An extension already says, once per boot, what it found: that is its section of the startup report. A panel adds what it is doing: values sampled about once a second, the charts to draw, and optionally actions.

There are two shapes. The all-in-one one is the shortest: your extension class is also the panel.

That is the whole panel: contribute for the boot facts, charts and sample for the live half. It depends on vidocq-runtime-devconsole-spi, an API jar of five small types, and nothing else of the console.

The catch is in the word all-in-one: whatever implements DevConsolePanel ships in every binary that has the extension, whether or not anyone ever runs vidocq:dev. So the extensions of the runtime itself, Cassini’s REST mounts, Knock’s health, Dirac’s metrics, Mansart’s pools, the schema migrations, the MCP server, use the split shape:

The -dev module is a small Java module next to the extension, with the same parent and version, the artifact id suffixed -dev and the module name suffixed .dev. vidocq:dev alone puts it on the module path of the application it starts. Nothing else ever depends on it, and nothing that gets packaged contains it: a jlink image or a -dist archive of your application never carries a panel, and the brick it describes does not even know that the console exists. The Health panel of Knock, below, is one of these.

A few rules keep a panel harmless, and the console documents them as a contract: sample reads memory only, never blocks, never creates a bean, and never puts a secret in a value. An action, the kind of button the migration panel offers, goes through the origin check and the per-boot token described above. And since the dev MCP server shows the console’s panels to coding agents as read-only tools, a panel that keeps its values honest and free of secrets is also one an agent can safely read.

Both shapes, the tests that go with them and a checklist are in Writing a dev console panel. If you maintain an extension with a state worth watching, a cache, a pool, a queue, a client, the panel is a few dozen lines, and vidocq:dev shows it from then on.

The TCKs are the part of this release we trust most, because we do not write them. Official suites, run on Temurin 25; the runtime figures are run against the assembled runtime, each test deployed the way an application would be.

That is 1888 MicroProfile tests on the assembled runtime, and 1707 for Servlet next to them. Two honest footnotes. The Telemetry and OpenAPI runs use the release candidates of the 7.2 TCKs, for the ballot reason given above. And Jakarta Persistence and Messaging are not in this release candidate.

Until this month, quality at Vidocq meant tests and TCKs. On 21 October we added the other half. SonarQube runs on our own infrastructure, at https://sonar.vidocq.dev, behind the same single sign-on as the forge, with JaCoCo coverage. A shared action of our CI runs the analysis on the pull requests of each brick and posts one comment on it. It runs in report mode: it never blocks a merge. A merge still means reading the comment, and we learned that on the second day, when a pull request with a new finding went in and turned Chappe’s gate red on main.

The first thing it did was to measure honestly. Chappe showed 14.7% coverage, which was false: its tests live in other modules and JaCoCo read each module alone. With one aggregate report, the figure was 82.7%. Then we cleaned, brick by brick, starting with the ones we know best:

The rest of the family is the backlog, and here it is as it stands this morning, not rounded:

Seventeen analysed projects, about 212,000 lines of Java, and about 10,700 tests counted by Sonar. Two sentences on what the table says. The runtime itself has 85 open bugs and a gate that fails on main: that is the next campaign, ahead of any new feature work, and the coverage of Cassini and Mansart (about 43%) is the first thing to raise. And the vulnerability column is the one we have read least; it is a list to triage, not a verdict, and a share of it will turn out to be false positives we will mark as such, with a comment, in Sonar.

Sonar and JaCoCo are the only analysis tools in place. Error Prone, NullAway, a secret and vulnerability scanner for dependencies, an architecture test and an API-compatibility check are planned, in report mode first, and each brick’s gate becomes blocking when we have reviewed that brick, at 0.4.0.

Most of it is additions. These need an action, or a look:

0.4.0-RC1 is the latest release on Maven Central, so the installer picks it up:

The project it writes is on vidocq-runtime-parent 0.4.0-RC1, and builds with nothing but Maven Central. We checked it the way you would meet it: a fresh Maven repository that can reach Central only, then vidocq build jlink (5 seconds, a 40 MB image) and the image’s own launcher, which reports Started in 120 to 126 ms on three runs.

To upgrade an existing application, bump the parent (or the BOM) to 0.4.0-RC1 and run vidocq doctor: it reads your project and says what to change, and --fix makes the changes it can.

The getting-started guide, the full what’s new and the TCK page are on the 0.4.0-RC1 line of the documentation. If something does not work, tell us on CodeFloe: a release candidate is the moment when a report costs us the least.

0.4.0 is planned for the end of November: the MicroProfile 7.2 finals once they are on Maven Central, the TCKs run again on them, the static analysis gates reviewed brick by brick, and Jakarta Persistence through Noether if it is ready. The registry behind vidocq extension list --available is the catalog shipped with your CLI; a live catalog belongs with the web project initializer we want at start.vidocq.dev (vidocq#17). And we will keep doing the empty-directory audit before every release, because the bugs it finds are the ones we no longer see.

Every bug we reproduce goes into the BUG.md of its repository, with a symptom, a minimal reproduction and a status. Since 0.3.0 the files of eight repositories record at least 169 closed entries: Vidocq 46, Vauban 56, Foy 34, Grimm 16, Humboldt 8, Cyrano 7, Ravel 1 and Knock 1. The other bricks track theirs in the same place; their count is not in this number. Here they are by brick, grouped by what they had in common, with the id of the entry in brackets; read the BUG.md of the repository for the symptom, the reproduction and the test that now covers it.