Vidocq Documentation

Cyrano is at 0.1.0-SNAPSHOT. A real application migration is premature until TCK coverage clears M5 (see TCK status). This page documents the model correspondences and known pitfalls in preparation for the transition.

Cyrano implements MicroProfile Rest Client 4.0 strictly. Migration means aligning annotations with the spec and giving up the proprietary extensions of existing implementations.

From SmallRye Rest Client

SmallRye is the implementation used by Quarkus and WildFly. Its spec fidelity is high; porting is conceptually direct.

SmallRye Cyrano Note

@RegisterRestClient

@RegisterRestClient

Identical (MP spec).

@RestClient (qualifier)

@RestClient (qualifier)

Identical.

RestClientBuilder.newBuilder()

RestClientBuilder.newBuilder()

Identical. Resolved via ServiceLoader.

io.vertx or Apache HttpClient transport

java.net.http.HttpClient (JDK)

No Vert.x configuration. Vert.x connection-pool settings have no equivalent — the pool is internal to HttpClient.

@io.smallrye.faulttolerance.api.RateLimit

No equivalent in Cyrano

Use Heisenberg (MP Fault Tolerance) alongside.

OpenTelemetry propagation via SmallRye OTel

Via Humboldt server-side + W3C propagator

To be documented.

Quarkus-style application.properties (quarkus.rest-client.users-api.url=…​)

users-api/mp-rest/url=…​ (standard MP Config keys)

Namespace switch. Official MP Config keys are preserved.

@ClientHeaderParam + default method

Same

Identical.

Dev mode (hot reload)

Standard Maven cycle

No dev-mode equivalent for now.

From RESTEasy MicroProfile Rest Client

RESTEasy exposes the same MP Rest Client API plus a proprietary extension layer.

RESTEasy Cyrano Note

@RegisterRestClient + @Path

@RegisterRestClient + @Path

Identical.

org.apache.http.client.HttpClient (Apache HC 4.x or 5.x)

java.net.http.HttpClient (JDK)

Zero external dependency. No Apache HC config to port — JDK HttpClient is configured through standard MP Config keys.

@org.jboss.resteasy.annotations.providers.multipart.PartType

Not supported

Multipart is not covered by MP Rest Client 4.0.

ResteasyWebTarget (fluent API)

Standard RestClientBuilder

The JAX-RS Client fluent API is not the MP Rest Client operating mode (typed interface only).

@ClientHeaderParam

Same

Identical.

org.jboss.resteasy.client.jaxrs.ResteasyClient

RestClientBuilder.newBuilder().build(iface)

The Cyrano client is an interface proxy, not a WebTarget.

@Provider filters

ClientRequestFilter / ClientResponseFilter filters via @RegisterProvider

Standard JAX-RS — identical declarations.

Logging via RestClientListener

@RegisterProvider(LoggingFilter.class) + custom filter

No global listener API — Cyrano follows the spec strictly.

From Jakarta REST Client (no MicroProfile)

The jakarta.ws.rs.client.Client + WebTarget mode is fluent and imperative; Cyrano is declarative via interface. Porting requires more effort.

Jakarta REST Client Cyrano Note

ClientBuilder.newClient().target(uri).path(…​).request().get(…​)

@RegisterRestClient interface + @Inject @RestClient

Required refactor — extract each HTTP call into an annotated interface method.

Instance per call

One proxy per client, shared

Bonus: no connection leak, shared HttpClient.

Invocation.Builder.async()

Method returning CompletionStage<T>

Same semantics, more natural signature.

Imperative configuration

Annotations + MP Config

More declarative, more testable.

To preserve jakarta.ws.rs.client.Client usage in edge cases (e.g. fully dynamic URL), it remains legal to instantiate a standard JAX-RS Client alongside Cyrano — the two coexist.

Known pitfalls

  • module-info.java — remember to add requires io.vidocq.cyrano.mp.rest.client.api; and opens com.example.dto to jakarta.json.bind; for the DTOs. This is the number-one source of InaccessibleObjectException.

  • Spec repackage — do not import microprofile-rest-client-api directly (automatic module → jlink-incompatible). Always go through cyrano-mp-rest-client-api.

  • MP Config is required for <configKey>/mp-rest/url — without Ravel (or another impl), only @RegisterRestClient(baseUri=…​) works.

  • Async + CDI context — @RequestScoped propagation in a CompletionStage is not yet complete (see TCK §AsyncMethodTest). Prefer synchronous calls on a virtual thread until M4-6 ships.

Going further

  • Getting started — first typed client in under 50 lines.

  • Concepts — MP Rest Client vocabulary.

  • TCK — current conformance status.