Veredium

Veredium is a web client implementation — named after the Roman veredus, the post-horse of the cursus publicus: the mount that carries the envoy to the foreign party and back. Its sibling Legatium records what the envoy's call came to; Veredium is the ride itself.

Quickstart

A host declares the client module of the stack it calls with - veredium-restclient for the blocking client, veredium-webclient for the reactive one, both for a host that runs the two side by side (ADR-0003). Each brings veredium-core along. The badge shows the current release on Maven Central — use that version where the snippet says ...:

<dependency>
    <groupId>eu.inqudium</groupId>
    <artifactId>veredium-restclient</artifactId>
    <version>...</version>
</dependency>

About the name

Veredium derives from veredus, the post-horse of the cursus publicus, the Roman state courier service: the fast horse a rider took from one station (mutatio) to the next, changed there for a fresh one, and rode on. A web client is exactly that: not the message and not the envoy, but the mount that carries them to the other side — and the one that has to be sound for the journey to end well.

The form follows the naming of chemical elements, like its siblings Limesium (the watched frontier, where the inbound crossings are recorded), Legatium (the envoy, whose outbound calls are recorded) and Tabellarium (the letter-carrier, who ships the log events). All are published under the eu.inqudium group, the fictional periodic table of Inqudium.

Module	Role	Root package
veredium-core	the stack-neutral core both clients share: mesh timeout ladder, breaker verdicts, Resilience4j wiring	eu.inqudium.veredium.core
veredium-restclient	the blocking client: Spring RestClient over a selectable HTTP engine (default Apache HttpClient 5; ADR-0004), mesh timeout ladder, Resilience4j	eu.inqudium.veredium.restclient
veredium-webclient	the reactive client: Spring WebClient over a selectable HTTP engine (default Reactor Netty; ADR-0004), mesh timeout ladder, Resilience4j	eu.inqudium.veredium.webclient

veredium-examples shows a host using veredium: one Spring Boot application per calling style of the two clients (blocking, asynchronous, reactive), one that runs both clients in one context, and one that bounds a native Apache HttpClient 4 call with the core's BlockingResilienceDecorator, each run by the build's tests. It is never published, and neither are the other two build-only modules, veredium-test-support and veredium-coverage.

Documentation

• Core guide — veredium-core: what both clients share, and the mesh timeout ladder.
• Blocking client guide — veredium-restclient: the hand-off, the ladder, the bulkheads, metrics, what differs from the reactive sibling.
• Reactive client guide — veredium-webclient: configuration, metrics, logging.
• Test evidence — the generated inventory of the test suite: every test sentence plus its rationale.
• Coverage report — the cross-module JaCoCo report of the run that built the site (a class counts as covered when any module's tests run it).
• API reference — generated with Dokka.
• Architecture decision records — the decisions, numbered and never renumbered.

Compatibility

Each Veredium release is built and tested against one Spring Boot line, one Kotlin line and one Java target; the table is the history of those lines, newest first. The Java column is the bytecode target the artifacts run on - the build itself needs JDK 24+.

Veredium	Spring Boot	Kotlin	Java
1.0.0	4.1.x	2.4.x	21

Build

mvn verify

Maven multi-module build (group eu.inqudium), Java 21, Kotlin, Spring Boot parent.

Reproducible builds

The same source and version produce the same bytes on any machine: the root POM sets project.build.outputTimestamp (bumped in every release commit), so the jar and source archivers write that instant as every zip entry's timestamp, sort the entries and normalize their permissions, and the manifests carry no build user, build JDK or Maven version (Build-Jdk-Spec is omitted on purpose - CI builds on JDK 25, a maintainer on whatever 24+ is installed). The javadoc jar is rendered by Dokka but packaged by the jar plugin, because Dokka's own javadocJar goal writes the build time and JDK into the archive. Consequently the jars the Release workflow attaches to the GitHub release (built on the tag by GitHub Actions, attested with SLSA provenance) and the jars deployed to Maven Central from a local checkout of the same tag are byte-identical. To check a build, run mvn -DskipTests package twice, or once on the tag, and compare sha256sum veredium-core/target/veredium-core-<version>.jar with the release asset.

Contributing

Contributions are welcome — please read CONTRIBUTING.md first. The Code of Conduct applies to all project spaces, and security issues should be reported privately as described in SECURITY.md.

License

Licensed under the Apache License, Version 2.0.