Vidocq Documentation
Version

This page lists every artefact published by Cyrano, the Java modules they export, the MicroProfile Rest Client 4.0 annotations supported, and the full set of MicroProfile Config keys recognised.

Maven artefacts

Artefact Recommended scope Role

io.vidocq.cyrano:cyrano-mp-rest-client-api:0.3.0

compile (transitive via cyrano-api)

Explicit Java Modules repackage of microprofile-rest-client-api 4.0 — neutralises the upstream automatic module.

io.vidocq.cyrano:cyrano-api:0.3.0

compile

Controlled re-export of the spec + stable public SPI (io.vidocq.cyrano.spi, io.vidocq.cyrano.spi.gen).

io.vidocq.cyrano:cyrano-processor:0.3.0

annotation processor path (or provided)

APT processor CyranoClientProcessor — generates <Interface>$$CyranoClient sources (proxy + literal descriptor + ServiceLoader-able Factory) at compile time for every @RegisterRestClient interface. The primary proxy path.

io.vidocq.cyrano:cyrano-core:0.3.0

runtime

Implementation: CyranoRestClientBuilder, ClientProxyRegistry resolution chain, CyranoInterfaceScanner + CyranoProxyGenerator (Class-File API, runtime fallback), CyranoInvocationHandler, CyranoHttpTransport.

io.vidocq.cyrano:cyrano-cdi-vauban:0.3.0

runtime (optional)

Vauban BCE CyranoRestClientCdiExtension — @RegisterRestClient discovery, synthetic @RestClient-qualified bean, MP Config resolution.

io.vidocq.cyrano:cyrano-tck:0.3.0

test (in-reactor, tck Maven profile)

Official MicroProfile Rest Client 4.0 TCK runner — invoked through run-official-tck-mp-rest-client-4.0.sh.
cyrano-tck is in-reactor, gated behind the tck Maven profile (TCK harmonisation, vidocq-runtime-tck-* pattern): a plain mvn install neither downloads nor runs anything TCK-related. The historical out-of-reactor constraint (ShrinkWrap Maven Resolver 3.3 vs Model 4.1.0 POMs) disappeared with the Maven 3.9.16 / Model 4.0.0 migration. See TCK.

Exported Java modules

Module Exported packages

io.vidocq.cyrano.mp.rest.client.api

org.eclipse.microprofile.rest.client, org.eclipse.microprofile.rest.client.annotation, org.eclipse.microprofile.rest.client.ext, org.eclipse.microprofile.rest.client.inject, org.eclipse.microprofile.rest.client.spi

io.vidocq.cyrano.api

io.vidocq.cyrano.spi and io.vidocq.cyrano.spi.gen (the SPI consumed by APT-generated client code).

io.vidocq.cyrano.processor

No exported package — consumed exclusively through provides javax.annotation.processing.Processor with CyranoClientProcessor (javac ServiceLoader).

io.vidocq.cyrano.core

io.vidocq.cyrano.runtime only (io.vidocq.cyrano.internal stays unexported). Also: provides RestClientBuilderResolver with CyranoRestClientBuilderResolver, uses io.vidocq.cyrano.runtime.ProviderInstantiator, uses io.vidocq.cyrano.spi.gen.ClientProxyFactory (module-layer resolution of generated factories).

io.vidocq.cyrano.cdi.vauban

io.vidocq.cyrano.cdi.internal. Three provides: BuildCompatibleExtension with CyranoRestClientCdiExtension, io.vidocq.cyrano.runtime.ProviderInstantiator with CyranoCdiProviderInstantiator (CDI-aware provider instantiation), and io.vidocq.vauban.api.VaubanComponentProvider with the APT-generated _VaubanComponents (no opens …​ to io.vidocq.vauban.core needed).

Supported annotations

Annotation Spec / Level

@org.eclipse.microprofile.rest.client.inject.RegisterRestClient

MP Rest Client §6.1 — registers the interface with CDI.

@org.eclipse.microprofile.rest.client.inject.RestClient

MP Rest Client §6.2 — injection qualifier.

@org.eclipse.microprofile.rest.client.annotation.RegisterProvider

MP Rest Client §5 — declares a provider.

@org.eclipse.microprofile.rest.client.annotation.RegisterProviders

Repeating container of @RegisterProvider.

@org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam

MP Rest Client §4 — static or dynamic header (default method).

@org.eclipse.microprofile.rest.client.annotation.RegisterClientHeaders

MP Rest Client §4 — ClientHeadersFactory (propagation from inbound request).

@org.eclipse.microprofile.rest.client.annotation.ClientHeaderParams

Repeating container of @ClientHeaderParam.

@jakarta.ws.rs.Path, @GET, @POST, @PUT, @DELETE, @PATCH, @HEAD, @OPTIONS

JAX-RS — HTTP method + path template. Custom verbs meta-annotated with @jakarta.ws.rs.HttpMethod are honoured too.

@PathParam, @QueryParam, @HeaderParam, @CookieParam, @MatrixParam, @FormParam, @DefaultValue, @BeanParam

JAX-RS — parameters.

@Consumes, @Produces

JAX-RS — content negotiation (request side / response side).

Supported return types

Type Semantics

Primitives and their wrappers

Conversion from the text body or JSON-B types.

String

Raw decoded body (charset = Content-Type).

POJO / record

JSON-B deserialisation through Champollion.

Optional<T>

Present if status < 400 and body non-empty; Optional.empty() otherwise.

List<T>, Set<T>, Map<K,V>

JSON-B deserialisation.

jakarta.ws.rs.core.Response

Access to status, headers and raw body.

CompletionStage<T>

Async through HttpClient.sendAsync, completed on virtual thread.

void

The response is consumed and discarded.

MicroProfile Config keys

All keys follow the <key>/mp-rest/<attribute> pattern, where <key> is either the declared configKey (@RegisterRestClient(configKey = "x")) or the interface’s FQN (when no configKey is set).

Key Effect

<key>/mp-rest/url

Base URL (host + base path). Medium priority.

<key>/mp-rest/uri

Full base URI. High priority (wins over url).

<key>/mp-rest/scope

CDI scope of the synthesised bean (jakarta.enterprise.context.Dependent by default, spec §6.3; a scope annotation on the interface or this key overrides it).

<key>/mp-rest/providers

Comma-separated list of provider FQNs.

<key>/mp-rest/connectTimeout

Connect timeout in milliseconds.

<key>/mp-rest/readTimeout

Read timeout in milliseconds.

<key>/mp-rest/followRedirects

true to follow redirections (3xx).

<key>/mp-rest/queryParamStyle

MULTI_PAIRS, COMMA_SEPARATED or ARRAY_PAIRS (serialisation style for multivalued @QueryParam).

<key>/mp-rest/trustStore

Truststore location — classpath: or URL (e.g. classpath:/truststore.jks).

<key>/mp-rest/trustStoreType

Truststore type (default JKS).

<key>/mp-rest/trustStorePassword

Truststore password.

<key>/mp-rest/keyStore

Client keystore location — classpath: or URL.

<key>/mp-rest/keyStoreType

Keystore type (default JKS).

<key>/mp-rest/keyStorePassword

Keystore password.

<key>/mp-rest/hostnameVerifier

FQN of a javax.net.ssl.HostnameVerifier implementation.

Each key resolves against the interface FQN first, then the configKey. The global (non-per-client) property microprofile.rest.client.disable.default.mapper (spec §8.1) is also read from MP Config; an explicit builder property wins.

HTTP proxying is configured programmatically through RestClientBuilder.proxyAddress(host, port) — no proxy* MP Config key is read.

Resolution priority for the base URL (strongest to weakest): mp-rest/uri > mp-rest/url > @RegisterRestClient(baseUri=…​). Other attributes have a single priority (MP Config wins over the builder’s defaults).

Public SPI

Two stable SPI packages are exported by cyrano-api, plus one runtime SPI in cyrano-core:

Type Role

io.vidocq.cyrano.spi.Cyrano

Implementation metadata constants (IMPLEMENTATION_NAME, SPEC_VERSION, IMPLEMENTATION_VERSION) for TCK tests and runtime integration.

io.vidocq.cyrano.spi.gen.ClientProxyFactory

The contract implemented by every APT-generated $$CyranoClient$Factory — clientInterface(), descriptor(), newProxy(ClientInvoker). Resolved by ClientProxyRegistry through the module layer (provides …​ with …​) or META-INF/services.

io.vidocq.cyrano.spi.gen.ClientInvoker

The invocation contract a generated proxy delegates to; implemented by CyranoInvocationHandler in cyrano-core.

io.vidocq.cyrano.spi.gen.ClientDescriptor (+ ClientMethodDescriptor, ClientParamDescriptor, DynamicHeaderDescriptor)

Literal, reflection-free description of the client interface embedded in the generated code; converted back to internal RequestSpec`s by `DescriptorConverter.

io.vidocq.cyrano.runtime.ProviderInstantiator

Provider instantiation SPI (uses in cyrano-core): lets adapters supply managed instances for filters/mappers — cyrano-cdi-vauban provides the CDI-aware CyranoCdiProviderInstantiator.

io.vidocq.cyrano.runtime.CyranoRestClientBuilderResolver

The spec’s RestClientBuilderResolver, published via provides and META-INF/services.

There is no transport-substitution SPI: the transport is java.net.http.HttpClient, and the extension points around a request are the standard JAX-RS/MP providers (ClientRequestFilter, ClientResponseFilter, MessageBodyReader/Writer, ResponseExceptionMapper, ParamConverterProvider, ClientHeadersFactory).

Runtime prerequisites

  • JDK 25+ — for the Class-File API and virtual threads.

  • Java Modules: one module-info.java per application Maven module consuming Cyrano.

  • A JSON-B implementation: Champollion (declared separately, runtime scope).

  • Optional — an MP Config implementation (Ravel) for <key>/mp-rest/*.

Utility scripts

Script Effect

./mvnw -ntp install -DskipTests

Build the reactor (no TCK).

./mvnw test

Unit tests (cyrano-api, cyrano-core, cyrano-cdi-vauban).

./run-official-tck-mp-rest-client-4.0.sh

Smoke mode (fast).

./run-official-tck-mp-rest-client-4.0.sh all

Full official TCK suite.

./run-official-tck-mp-rest-client-4.0.sh -Dtest=ConfigKeyTest

Targeted TCK test.