Quarkus REST Client still defaults to a 15 second connect timeout and a 30 second read timeout. I would not call that resilience. Your request can sit there burning somebody else’s budget until the failure finally shows up in the wrong place. Turn on request-response logging with no masking and the bearer token you needed for debugging is now in the log stream. Add retries on the wrong call and one flaky dependency can turn into duplicate work.

This tutorial builds a small service with explicit per-client timeouts, one bounded retry on a safe read path, masked outbound logs, useful downstream error translation, and tests that cover the bad days as well as the happy path.

What we build

We will build carrier-bridge, a Quarkus service that exposes GET /tracking/{trackingId} and calls a downstream carrier status API through a declarative REST client. By the end you will have:

• a declarative REST client using rest-client-jackson

• explicit connect-timeout and read-timeout on that client

• one bounded retry for a transient 503 on an idempotent read

• request-response logging with redacted auth headers

• client-side and server-side error mapping into clean JSON

• WireMock Dev Service tests through the Quarkus WireMock extension for slow, flaky, and permanently broken downstream responses

The retry example is a read operation on purpose. Automatic retry is only safe when the call is safe to repeat. If you retry writes, charges, or submit flows, you need idempotency keys or another guardrail. That rule comes from HTTP semantics, not from Quarkus magic.

What you need

You need Java 21, the Quarkus CLI, and basic familiarity with declarative REST clients. The walkthrough takes about two ☕️☕️.

• Java 21

• Quarkus CLI (quarkus create app)

• Basic Quarkus REST Client knowledge

Build the base

This article uses Quarkus 3.36.1 and Java 21. Create the project:

quarkus create app org.acme:carrier-bridge \
  --extension='rest-jackson,rest-client-jackson,smallrye-fault-tolerance,smallrye-openapi' \
  --java=21 \
  --no-code

Extensions:

• rest-jackson for the inbound API

• rest-client-jackson for the declarative outbound client

• smallrye-fault-tolerance for retry policy

• smallrye-openapi so the service still looks like something a team would ship

Add the Quarkus WireMock extension. It starts WireMock as a Dev Service in dev and test mode, so you do not manage server lifecycle yourself:

./mvnw quarkus:add-extension -Dextensions="io.quarkiverse.wiremock:quarkus-wiremock"

And yes. I am using the mvn command here instead the CLI. I keep mixing both, depending on which command I remember first. So please bear with me. Both integrations are great and I do not want anybody to feel like they have to use the Quarkus CLI.

The command adds quarkus-wiremock to the build. Pin the Quarkiverse version and add the test helper module in pom.xml:

<properties>
    <quarkus-wiremock.version>1.6.3</quarkus-wiremock.version>
</properties>

<dependencies>
    <dependency>
        <groupId>io.quarkiverse.wiremock</groupId>
        <artifactId>quarkus-wiremock</artifactId>
        <version>${quarkus-wiremock.version}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.wiremock</groupId>
        <artifactId>quarkus-wiremock-test</artifactId>
        <version>${quarkus-wiremock.version}</version>
    </dependency>
</dependencies>

quarkus-wiremock-test brings in @ConnectWireMock, which injects a WireMock client into your tests. The extension publishes quarkus.wiremock.devservices.port so the REST client URL can point at the running stub without hard-coding a port.

Make it work

Let’s follow one boring happy path first, then widen it. Start with the payload types and failure exceptions, then the client, service, and resource.

Payload and error types

The downstream carrier returns a full tracking document. Our public API returns a trimmed response. Failures become typed exceptions with a stable downstreamStatus field for the caller.

Create src/main/java/org/acme/carrier/bridge/CarrierTrackingPayload.java:

package org.acme.carrier.bridge;

import java.time.Instant;

record CarrierTrackingPayload(String trackingId, String carrier, String status, Instant lastUpdated) {
}

Create src/main/java/org/acme/carrier/bridge/TrackingResponse.java:

package org.acme.carrier.bridge;

import java.time.Instant;

public record TrackingResponse(String trackingId, String carrier, String status, Instant lastUpdated) {
}

Create src/main/java/org/acme/carrier/bridge/ApiError.java:

package org.acme.carrier.bridge;

public record ApiError(String code, String message, Integer downstreamStatus) {
}

Create src/main/java/org/acme/carrier/bridge/CarrierFailures.java:

package org.acme.carrier.bridge;

abstract class CarrierFailure extends RuntimeException {

    private final Integer downstreamStatus;

    CarrierFailure(String message, Integer downstreamStatus) {
        super(message);
        this.downstreamStatus = downstreamStatus;
    }

    CarrierFailure(String message, Integer downstreamStatus, Throwable cause) {
        super(message, cause);
        this.downstreamStatus = downstreamStatus;
    }

    Integer downstreamStatus() {
        return downstreamStatus;
    }
}

final class TrackingNotFoundException extends CarrierFailure {

    TrackingNotFoundException(String trackingId) {
        super("Carrier API could not find tracking ID '%s'.".formatted(trackingId), 404);
    }
}

final class CarrierUnavailableException extends CarrierFailure {

    CarrierUnavailableException() {
        super("Carrier API is temporarily unavailable.", 503);
    }
}

final class CarrierTimeoutException extends CarrierFailure {

    CarrierTimeoutException(Throwable cause) {
        super("Carrier API did not respond before the outbound read timeout.", null, cause);
    }
}

final class CarrierInvocationException extends CarrierFailure {

    CarrierInvocationException(Throwable cause) {
        super("Carrier API call failed before a usable response was returned.", null, cause);
    }
}

Each exception maps to one caller-facing HTTP status later. A timeout is not the same shape as a missing tracking ID, and neither should look like a generic transport failure.

Outbound auth filter

Real carrier APIs expect credentials on every call. A ClientRequestFilter is the right place to attach them so the rest of the code stays focused on business logic.

Create src/main/java/org/acme/carrier/bridge/CarrierAuthFilter.java:

package org.acme.carrier.bridge;

import io.quarkus.arc.Unremovable;
import jakarta.ws.rs.client.ClientRequestContext;
import jakarta.ws.rs.client.ClientRequestFilter;
import jakarta.ws.rs.core.HttpHeaders;

@Unremovable
public class CarrierAuthFilter implements ClientRequestFilter {

    static final String DEMO_BEARER_TOKEN = "carrier-demo-bearer-token";
    static final String DEMO_API_KEY = "carrier-demo-api-key";

    @Override
    public void filter(ClientRequestContext requestContext) {
        requestContext.getHeaders().putSingle(HttpHeaders.AUTHORIZATION, "Bearer " + DEMO_BEARER_TOKEN);
        requestContext.getHeaders().putSingle("X-Carrier-Key", DEMO_API_KEY);
    }
}

@Unremovable keeps Arc from dropping the filter when nothing else injects it directly. In production these values come from configuration or a secrets store, not constants. The test suite uses the constants to prove redaction works.

Declarative REST client

The client interface is the outbound contract. Register it with configKey = "carrier-api" so timeouts, URL, and logging stay in one configuration namespace.

Create src/main/java/org/acme/carrier/bridge/CarrierStatusClient.java:

package org.acme.carrier.bridge;

import java.net.URI;

import io.quarkus.rest.client.reactive.ClientExceptionMapper;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.core.Response;
import org.eclipse.microprofile.rest.client.annotation.RegisterProvider;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

@Path("/carrier-api")
@RegisterRestClient(configKey = "carrier-api")
@RegisterProvider(CarrierAuthFilter.class)
public interface CarrierStatusClient {

    @GET
    @Path("/tracking/{trackingId}")
    CarrierTrackingPayload getTracking(@PathParam("trackingId") String trackingId);

    @ClientExceptionMapper
    static RuntimeException toException(Response response, URI uri) {
        return switch (response.getStatus()) {
            case 404 -> new TrackingNotFoundException(uri.getPath().substring(uri.getPath().lastIndexOf('/') + 1));
            case 503 -> new CarrierUnavailableException();
            default -> null;
        };
    }
}

@ClientExceptionMapper runs before the response body is unmarshalled into CarrierTrackingPayload. That is why a 404 with an error JSON body does not explode into a Jackson mapping exception. Returning null leaves other status codes to the default client error handling.

@RegisterProvider(CarrierAuthFilter.class) wires the auth filter without touching the interface method signatures.

Service with retry and timeout handling

Retries belong on the service method, not on the client interface. That keeps the retry policy tied to one business operation and one failure type.

Create src/main/java/org/acme/carrier/bridge/TrackingService.java:

package org.acme.carrier.bridge;

import java.net.SocketTimeoutException;
import java.util.concurrent.TimeoutException;

import org.eclipse.microprofile.faulttolerance.Retry;
import org.eclipse.microprofile.rest.client.inject.RestClient;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.ProcessingException;

@ApplicationScoped
class TrackingService {

    private final CarrierStatusClient carrierStatusClient;

    TrackingService(@RestClient CarrierStatusClient carrierStatusClient) {
        this.carrierStatusClient = carrierStatusClient;
    }

    @Retry(retryOn = CarrierUnavailableException.class)
    TrackingResponse fetchTracking(String trackingId) {
        try {
            CarrierTrackingPayload payload = carrierStatusClient.getTracking(trackingId);
            return new TrackingResponse(
                    payload.trackingId(),
                    payload.carrier(),
                    payload.status(),
                    payload.lastUpdated());
        } catch (ProcessingException e) {
            if (hasTimeoutCause(e)) {
                throw new CarrierTimeoutException(e);
            }
            throw new CarrierInvocationException(e);
        }
    }

    private boolean hasTimeoutCause(Throwable throwable) {
        Throwable current = throwable;
        while (current != null) {
            if ((current instanceof SocketTimeoutException) || (current instanceof TimeoutException)) {
                return true;
            }
            String simpleName = current.getClass().getSimpleName();
            if (simpleName.contains("Timeout")) {
                return true;
            }
            current = current.getCause();
        }
        return false;
    }
}

@Retry(retryOn = CarrierUnavailableException.class) retries only transient carrier outages. A 404 does not retry. A read timeout does not retry either, because CarrierTimeoutException is outside retryOn. That is the behavior you want: one safe retry for a blip, not a second slow wait on an already late call.

ProcessingException wraps transport-level failures from the REST client. The hasTimeoutCause walk is ugly but practical. Vert.x timeout types do not always surface as SocketTimeoutException at the top of the stack.

Inbound resource and API error mapping

The resource stays thin. Exception mapping turns typed failures into stable JSON for callers.

Create src/main/java/org/acme/carrier/bridge/TrackingResource.java:

package org.acme.carrier.bridge;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import org.jboss.resteasy.reactive.RestResponse;
import org.jboss.resteasy.reactive.server.ServerExceptionMapper;

@Path("/tracking")
@Produces(MediaType.APPLICATION_JSON)
public class TrackingResource {

    private final TrackingService trackingService;

    TrackingResource(TrackingService trackingService) {
        this.trackingService = trackingService;
    }

    @GET
    @Path("/{trackingId}")
    public RestResponse<TrackingResponse> tracking(@PathParam("trackingId") String trackingId) {
        return RestResponse.ok(trackingService.fetchTracking(trackingId));
    }

    @ServerExceptionMapper
    RestResponse<ApiError> mapTrackingNotFound(TrackingNotFoundException exception) {
        return RestResponse.status(
                Response.Status.NOT_FOUND,
                new ApiError("tracking_not_found", exception.getMessage(), exception.downstreamStatus()));
    }

    @ServerExceptionMapper
    RestResponse<ApiError> mapCarrierUnavailable(CarrierUnavailableException exception) {
        return RestResponse.status(
                Response.Status.SERVICE_UNAVAILABLE,
                new ApiError("carrier_unavailable", exception.getMessage(), exception.downstreamStatus()));
    }

    @ServerExceptionMapper
    RestResponse<ApiError> mapCarrierTimeout(CarrierTimeoutException exception) {
        return RestResponse.status(
                Response.Status.GATEWAY_TIMEOUT,
                new ApiError("carrier_timeout", exception.getMessage(), exception.downstreamStatus()));
    }

    @ServerExceptionMapper
    RestResponse<ApiError> mapCarrierInvocation(CarrierInvocationException exception) {
        return RestResponse.status(
                Response.Status.BAD_GATEWAY,
                new ApiError("carrier_invocation_failed", exception.getMessage(), exception.downstreamStatus()));
    }
}

Each mapper picks a deliberate HTTP status. 504 for timeout, 503 for downstream outage, 404 for unknown tracking ID, 502 for everything else that failed before a usable response arrived. Callers and monitors can tell these apart without reading stack traces.

Configure it

Add src/main/resources/application.properties:

carrier.api.url=http://localhost:8089

quarkus.rest-client."carrier-api".url=${carrier.api.url}
quarkus.rest-client."carrier-api".connect-timeout=100
quarkus.rest-client."carrier-api".read-timeout=200

quarkus.rest-client.logging.scope=request-response
quarkus.rest-client.logging.body-limit=120
quarkus.rest-client.logging.masked-headers=Authorization,Cookie,X-Carrier-Key

quarkus.log.category."org.jboss.resteasy.reactive.client.logging".min-level=DEBUG
quarkus.log.category."org.jboss.resteasy.reactive.client.logging".level=DEBUG

quarkus.fault-tolerance."org.acme.carrier.bridge.TrackingService/fetchTracking".retry.max-retries=1
quarkus.fault-tolerance."org.acme.carrier.bridge.TrackingService/fetchTracking".retry.delay=50
quarkus.fault-tolerance."org.acme.carrier.bridge.TrackingService/fetchTracking".retry.delay-unit=millis
quarkus.fault-tolerance."org.acme.carrier.bridge.TrackingService/fetchTracking".retry.jitter=25
quarkus.fault-tolerance."org.acme.carrier.bridge.TrackingService/fetchTracking".retry.jitter-unit=millis

carrier.api.url - Base URL for the downstream carrier. In tests, the %test. profile override below points this at the WireMock Dev Service port.

connect-timeout=100 and read-timeout=200 - One attempt gets about 300 ms before the client gives up. Without these, Quarkus falls back to 15 s connect and 30 s read. That is a long time to block a caller-facing thread.

logging.scope=request-response - Logs outbound requests and responses. Useful for debugging, dangerous without header masking.

logging.body-limit=120 - Truncates logged response bodies. Downstream JSON may still appear in logs at this limit. We are not logging full payloads to callers; this setting only caps what operations sees in log lines.

logging.masked-headers - Replaces matching header values with <hidden>. Setting this property replaces the default list. If you want Authorization and Cookie masked, keep them in your explicit list alongside any custom headers like X-Carrier-Key.

REST client log category at DEBUG - Request-response logging does not show up in tests unless this category is enabled. The redaction test depends on it.

Fault tolerance properties - One retry, 50 ms base delay, 25 ms jitter. Worst case for a permanent 503 is two outbound attempts plus roughly 75 ms of backoff, still inside a sub-second caller budget.

Point the REST client at the WireMock Dev Service during tests. Create src/test/resources/application.properties:

%test.carrier.api.url=http://localhost:${quarkus.wiremock.devservices.port}

The ${quarkus.wiremock.devservices.port} expression is published by the Quarkus WireMock extension when the Dev Service starts. Main application.properties keeps carrier.api.url=http://localhost:8089 for manual dev runs against a real or standalone stub.

Make it survive

Retry only where repetition is safe

The @Retry on fetchTracking is scoped to CarrierUnavailableException. That is a read and a transient outage shape. Do not copy this pattern onto charge, create, or submit endpoints without idempotency keys. One duplicate tracking lookup is annoying. One duplicate charge is a incident.

Keep the retry budget small

max-retries=1 means one extra attempt after the first failure, not an open-ended loop. Under load, generous retry policies turn one slow dependency into a traffic multiplier. If you need more than one retry, you probably need a circuit breaker or async recovery path instead of another blind repeat.

Separate failure shapes for callers and operators

A timeout (504), a downstream outage (503), a missing ID (404), and a broken transport call (502) should not collapse into one generic error. The mappers above give callers that separation. Quarkus REST Client also exposes http.clients metrics for declarative clients when Micrometer is on the classpath. That is worth wiring in production, but metrics deserve their own article once the failure mapping is correct.

Response body logging can still leak operational detail even when headers are masked. Treat log access with the same care as credential storage. Do not forward raw downstream error JSON to your public API; the ApiError record is the contract.

Prove it

Stub helper

The Quarkus WireMock extension injects a WireMock client when the test class carries @ConnectWireMock. Keep the stub recipes in a small helper so the test class stays readable.

Create src/test/java/org/acme/carrier/bridge/CarrierStubs.java:

package org.acme.carrier.bridge;

import static com.github.tomakehurst.wiremock.client.WireMock.aResponse;
import static com.github.tomakehurst.wiremock.client.WireMock.get;
import static com.github.tomakehurst.wiremock.client.WireMock.getRequestedFor;
import static com.github.tomakehurst.wiremock.client.WireMock.okJson;
import static com.github.tomakehurst.wiremock.client.WireMock.urlEqualTo;

import com.github.tomakehurst.wiremock.client.WireMock;
import com.github.tomakehurst.wiremock.stubbing.Scenario;

final class CarrierStubs {

    private CarrierStubs() {
    }

    static void reset(WireMock wireMock) {
        wireMock.resetMappings();
        wireMock.resetRequests();
        wireMock.resetScenarios();
    }

    static void stubSuccess(WireMock wireMock, String trackingId) {
        wireMock.register(get(urlEqualTo(path(trackingId)))
                .willReturn(okJson(successBody(trackingId, "IN_TRANSIT", "2026-06-05T12:30:00Z"))));
    }

    static void stubSlow(WireMock wireMock, String trackingId) {
        wireMock.register(get(urlEqualTo(path(trackingId)))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withFixedDelay(450)
                        .withBody(successBody(trackingId, "IN_TRANSIT", "2026-06-05T12:30:00Z"))));
    }

    static void stubUnavailableThenSuccess(WireMock wireMock, String trackingId) {
        String scenarioName = "carrier-retry-" + trackingId;
        wireMock.register(get(urlEqualTo(path(trackingId)))
                .inScenario(scenarioName)
                .whenScenarioStateIs(Scenario.STARTED)
                .willReturn(aResponse()
                        .withStatus(503)
                        .withHeader("Content-Type", "application/json")
                        .withBody(errorBody("carrier unavailable")))
                .willSetStateTo("recovered"));

        wireMock.register(get(urlEqualTo(path(trackingId)))
                .inScenario(scenarioName)
                .whenScenarioStateIs("recovered")
                .willReturn(okJson(successBody(trackingId, "DELIVERED", "2026-06-05T12:31:00Z"))));
    }

    static void stubUnavailable(WireMock wireMock, String trackingId) {
        wireMock.register(get(urlEqualTo(path(trackingId)))
                .willReturn(aResponse()
                        .withStatus(503)
                        .withHeader("Content-Type", "application/json")
                        .withBody(errorBody("carrier unavailable"))));
    }

    static void stubNotFound(WireMock wireMock, String trackingId) {
        wireMock.register(get(urlEqualTo(path(trackingId)))
                .willReturn(aResponse()
                        .withStatus(404)
                        .withHeader("Content-Type", "application/json")
                        .withBody(errorBody("unknown tracking"))));
    }

    static int requestCount(WireMock wireMock, String trackingId) {
        return wireMock.findAll(getRequestedFor(urlEqualTo(path(trackingId)))).size();
    }

    private static String path(String trackingId) {
        return "/carrier-api/tracking/" + trackingId;
    }

    private static String successBody(String trackingId, String status, String lastUpdated) {
        return """
                {
                  "trackingId": "%s",
                  "carrier": "Parcel Rocket",
                  "status": "%s",
                  "lastUpdated": "%s"
                }
                """.formatted(trackingId, status, lastUpdated);
    }

    private static String errorBody(String message) {
        return """
                {
                  "error": "%s"
                }
                """.formatted(message);
    }
}

stubSlow uses a 450 ms fixed delay against a 200 ms read timeout, so the timeout test fails for the right reason. stubUnavailableThenSuccess uses WireMock scenarios to return 503 once, then 200 on the second call.

Log capture helper

Create src/test/java/org/acme/carrier/bridge/InMemoryLogHandler.java:

package org.acme.carrier.bridge;

import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.logging.Handler;
import java.util.logging.LogRecord;

final class InMemoryLogHandler extends Handler {

    private final List<String> messages = new CopyOnWriteArrayList<>();

    @Override
    public void publish(LogRecord record) {
        if (record != null) {
            messages.add(record.getMessage());
        }
    }

    @Override
    public void flush() {
        // nothing to flush
    }

    @Override
    public void close() {
        messages.clear();
    }

    void clear() {
        messages.clear();
    }

    String joinedMessages() {
        return String.join("\n", messages);
    }
}

Failure tests

Create src/test/java/org/acme/carrier/bridge/TrackingResourceTest.java:

package org.acme.carrier.bridge;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.nullValue;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.logging.Level;
import java.util.logging.Logger;

import com.github.tomakehurst.wiremock.client.WireMock;

import io.quarkiverse.wiremock.devservice.ConnectWireMock;
import io.quarkus.test.common.http.TestHTTPEndpoint;
import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

@QuarkusTest
@ConnectWireMock
@TestHTTPEndpoint(TrackingResource.class)
class TrackingResourceTest {

    private static final String REST_CLIENT_LOG_CATEGORY = "org.jboss.resteasy.reactive.client.logging";

    private static Logger restClientLogger;
    private static InMemoryLogHandler logHandler;

    WireMock wiremock;

    @BeforeAll
    static void installLogHandler() {
        restClientLogger = Logger.getLogger(REST_CLIENT_LOG_CATEGORY);
        logHandler = new InMemoryLogHandler();
        restClientLogger.addHandler(logHandler);
        restClientLogger.setLevel(Level.FINE);
    }

    @AfterAll
    static void removeLogHandler() {
        if (restClientLogger != null && logHandler != null) {
            restClientLogger.removeHandler(logHandler);
        }
    }

    @BeforeEach
    void resetState() {
        CarrierStubs.reset(wiremock);
        logHandler.clear();
    }

    @Test
    void returnsTrackingStatus() {
        CarrierStubs.stubSuccess(wiremock, "TRACK-123");

        given()
                .when().get("/TRACK-123")
                .then()
                .statusCode(200)
                .body("trackingId", equalTo("TRACK-123"))
                .body("carrier", equalTo("Parcel Rocket"))
                .body("status", equalTo("IN_TRANSIT"))
                .body("lastUpdated", equalTo("2026-06-05T12:30:00Z"));
    }

    @Test
    void returnsGatewayTimeoutWhenCarrierIsSlow() {
        CarrierStubs.stubSlow(wiremock, "TRACK-SLOW");

        given()
                .when().get("/TRACK-SLOW")
                .then()
                .statusCode(504)
                .body("code", equalTo("carrier_timeout"))
                .body("message", equalTo("Carrier API did not respond before the outbound read timeout."))
                .body("downstreamStatus", nullValue());
    }

    @Test
    void retriesOnceAndSucceedsAfterTransientFailure() {
        CarrierStubs.stubUnavailableThenSuccess(wiremock, "TRACK-RETRY");

        given()
                .when().get("/TRACK-RETRY")
                .then()
                .statusCode(200)
                .body("trackingId", equalTo("TRACK-RETRY"))
                .body("status", equalTo("DELIVERED"));

        assertEquals(2, CarrierStubs.requestCount(wiremock, "TRACK-RETRY"));
    }

    @Test
    void returnsServiceUnavailableAfterPermanentCarrierFailure() {
        CarrierStubs.stubUnavailable(wiremock, "TRACK-DOWN");

        given()
                .when().get("/TRACK-DOWN")
                .then()
                .statusCode(503)
                .body("code", equalTo("carrier_unavailable"))
                .body("message", equalTo("Carrier API is temporarily unavailable."))
                .body("downstreamStatus", equalTo(503));

        assertEquals(2, CarrierStubs.requestCount(wiremock, "TRACK-DOWN"));
    }

    @Test
    void returnsNotFoundWhenCarrierDoesNotKnowTrackingId() {
        CarrierStubs.stubNotFound(wiremock, "TRACK-MISSING");

        given()
                .when().get("/TRACK-MISSING")
                .then()
                .statusCode(404)
                .body("code", equalTo("tracking_not_found"))
                .body("message", equalTo("Carrier API could not find tracking ID 'TRACK-MISSING'."))
                .body("downstreamStatus", equalTo(404));

        assertEquals(1, CarrierStubs.requestCount(wiremock, "TRACK-MISSING"));
    }

    @Test
    void masksSensitiveHeadersInRestClientLogs() {
        CarrierStubs.stubSuccess(wiremock, "TRACK-LOGS");

        given()
                .when().get("/TRACK-LOGS")
                .then()
                .statusCode(200);

        String logs = logHandler.joinedMessages();
        assertFalse(logs.contains(CarrierAuthFilter.DEMO_BEARER_TOKEN));
        assertFalse(logs.contains(CarrierAuthFilter.DEMO_API_KEY));
        assertTrue(logs.contains("Authorization"));
        assertTrue(logs.contains("X-Carrier-Key"));
        assertTrue(logs.contains("<hidden>"));
    }
}

Before you run the retry test, predict how many calls WireMock should see for TRACK-RETRY. The answer is two: first call gets 503, retry gets 200. For TRACK-DOWN it is also two, then the API returns 503 to the caller. For TRACK-MISSING it is one, because 404 is not in retryOn.

Run the suite:

./mvnw test

All six tests should pass. The slow-downstream test proves the read timeout surfaces as 504. The permanent failure test proves retries stop after one extra attempt. The redaction test proves fake secrets never appear in captured log lines.

Conclusion

We built an outbound HTTP path that fails on purpose instead of by accident. Explicit timeouts stop slow dependencies from eating the caller’s budget, one bounded retry handles a transient 503 on a safe read, masked headers keep credentials out of logs, and separate error codes give callers something useful when the carrier misbehaves.

The complete code is on my GitHub for you to check out.

Subscribe now

If you want the full talk, the recording is here and you can find the slides here. This article is the shorter version I would hand to a team before they let an agent loose in a real repository.

The exciting part of AI coding is obvious. You ask for a REST endpoint, a refactor, a migration sketch, or a first-pass UI, and the blank page disappears. That part is real. I use these tools too. They save time, remove some boring work, and make it easier to try things quickly.

The problem starts when people confuse easier code generation with easier software engineering.

Real systems are full of hidden contracts. Authorization rules, deployment assumptions, stale docs, weird integration edges, and business logic nobody wrote down but everybody now depends on. A model can infer some of that from nearby code. It cannot infer all of it just because the prompt sounded confident.

That is still the main lesson for me after the last 18 months. AI can draft a lot of syntax. It does not automatically understand the software around it.

Prompting is not the hard part

I keep seeing teams treat AI coding as a prompting problem. Write better prompts. Add more detail. Find the right magic spell. That helps a bit, but it is not the part I trust.

The bigger lever is context.

If the agent does not know your architecture constraints, your business boundary, your non-negotiable tests, or the parts of the repository it should not touch, it will make something up. That is not a moral failure. That is how the system works. Statistical tools fill gaps with likely-looking answers.

So I would spend less time chasing clever wording and more time building context the model can actually use.

That means repository rules. It means ADRs. It means decision logs. It means tests that define behavior clearly enough that the agent has something better than vibes. It also means being selective. Dumping a pile of stale internal docs into the context window is not context engineering. It is just a different way to confuse the model.

The real question is not “how much context can I fit?” It is “which context changes the quality of the decision?”

Big tasks still fail for familiar reasons

AI has not rescued us from decomposition.

If a change is too messy to explain in two or three clear sentences, it is probably too messy to hand to an agent as one job. The tool may still produce a lot of output. That is not the same as producing a controlled result.

This is one place where the AI discourse sometimes sounds weirdly ahistorical. We already know big-bang rewrites fail. We already know broad “clean this whole area up while you are there” work spreads risk faster than teams can review it. Why would an agent be the magical exception?

The pattern that keeps holding up is still the old one:

• Smaller tasks

• Tight boundaries

• Fast verification

• Easy rollback

• Explicit ownership

That is less glamorous than “fully autonomous development,” but it is much closer to how production teams stay sane.

I also think local git matters more than people admit. When an agent goes off the rails, the difference between a useful experiment and an annoying afternoon is often whether you can inspect the diff quickly, throw it away, and try again with a narrower request.

The useful tooling exposes systems, not just text

One reason I care about MCP and similar tool surfaces is that they shift the interaction away from pure guessing.

A model is much more useful when it can inspect runtime state, read the logs that matter, query the system you are actually changing, or reach structured docs instead of paraphrasing what it half-remembers. That does not make the model magical. It just gives it better ground to stand on.

For me, that is the real promise of this layer. Not “the model can use tools” as a demo trick. The better promise is that the model can stop pretending text alone is enough to understand a live system.

The same rule still applies, though: more tools are not automatically better. Tool sprawl creates its own tax. A giant tool catalog, a huge context payload, and 10 overlapping ways to do the same thing can make the session worse, not better. Good AI workflows need a shaped surface just as much as they need a capable model.

The bill comes back during review

This is the part I think teams still underestimate.

AI output is fast to produce and often expensive to verify. That cost does not show up in the demo. It shows up when a senior engineer has to read a clean-looking diff and decide whether the system still deserves trust.

That review load is real work. You are checking hidden assumptions, edge cases, failure paths, auth behavior, operational risk, naming drift, and whether the tests prove anything useful or just mirror the implementation. If the change touches infrastructure, security, or business rules, the cognitive bill gets even higher.

This is why I do not trust raw productivity claims that stop at code generation speed. A fast draft plus a slow, exhausting review loop is not automatically a win. Sometimes it is. Sometimes it is just a different queue.

The failure mode is subtle because tired reviewers still look productive from the outside. Files changed. The pull request is large. CI passed. Everybody feels movement. But fatigue is not the same as confidence, and momentum is not the same as understanding.

If I had to keep one professional rule from all of this, it would be simple: if you do not understand an AI-generated change well enough to explain its failure mode, do not merge it.

Java is in a stronger position than the hype suggests

A lot of AI coding conversation still defaults to Python because the AI ecosystem grew up around Python-first tooling. That does not mean Python teams are automatically in a better engineering position.

Java has a very practical advantage here. The code is explicit. Types are visible. Contracts are clearer. Framework conventions are stronger. Build and runtime boundaries are easier to follow than in many loosely structured stacks. That kind of shape helps humans review faster, and it helps models stay closer to the rails.

I do not mean Java makes AI safe. It does not. I mean Java gives both the model and the reviewer more structure to work with, which is one reason I think enterprise Java teams are better positioned for this transition than the public AI narrative suggests.

If anything, Java teams should lean into that advantage on purpose. Strong tests, typed config, explicit boundaries, and boring conventions are not old habits the AI era made irrelevant. They are what make the AI era survivable.

What I would actually tell a team

If I had to compress the whole keynote into one short working agreement, it would look like this:

1. Give the model better context, not just longer prompts.

2. Keep tasks small enough that verification stays cheap.

3. Use tools that expose real system state when the task depends on real system state.

4. Treat review load as part of the cost, not as free cleanup after the model is done.

5. Keep a human owner attached to every production change.

That is not a revolutionary message. It is mostly software engineering refusing to disappear just because the draft got cheaper.

AI is changing how we build. I do not think that part is controversial anymore. The part people still keep relearning is that faster code generation does not remove the expensive parts of software. Intent is still expensive. Architecture is still expensive. Verification is still expensive. Ownership is still expensive.

That is why the sentence on the slide still holds up.

Code is cheap. Software isn’t.

Subscribe now

I was curious about what Signals replaces. Y’all probably ask the same question right away: why not CDI events?

If the answer were “CDI events, but async,” this would be a short article and not a very interesting feature. CDI already gives us multicast events and async observers. Signals matter because they pull three in-process messaging patterns into one API:

• publish() for multicast notification

• send() for unicast work dispatch

• request() for typed request-reply

That is the gap. CDI events are still great for observer-style fan-out. Reactive Messaging is still the right tool when a broker, connectors, or backpressure are part of the problem. Vert.x EventBus can cover the same ground too, but with string addresses and a lower-level model. Signals sit in the middle: in-process, type-safe, async by default, and explicit about whether you are broadcasting, dispatching work, or asking another component for an answer.

Signals ship as a new experimental extension in Quarkus 3.36.0.

What we build

We build NebulaTrack, a small cloud cost monitor in a command-mode Quarkus app (no REST). It detects cost anomalies, fans out alerts, dispatches remediation work to one worker, and asks a pricing component for estimates.

When you finish, you have:

• three signal patterns wired with @Receives receivers

• qualifier lanes (@Default, @Critical, @Any)

• metadata on emissions

• programmatic receiver registration

• @QuarkusTest proof for every behavior

Signals are not an HTTP feature. A command-mode app keeps that obvious.

Prerequisites

You need a current JDK, Maven or the Quarkus CLI, and about one ☕️.

• JDK 25 (this project targets Java 25)

• Maven 3.9+ or the Quarkus CLI

• Familiarity with CDI injection

You can grab the full source code from my repository if you don’t want to follow along.

Project setup

Create the application without codestarts so we stay out of the web stack:

quarkus create app dev.quarkex:nebulatrack-signals \
  --extension='quarkus-signals' \
  --java=25 \
  --no-code

Under src/main/java, create the package dev.quarkex.nebulatrack and the subpackages used below (model, qualifier, service, support).

Add two test dependencies for AssertJ and Awaitility:

<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <version>3.27.3</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.awaitility</groupId>
  <artifactId>awaitility</artifactId>
  <scope>test</scope>
</dependency>

The only production extension we need is quarkus-signals. You do not need Vert.x on the classpath for blocking receivers. Vert.x only enters the story when you move into non-blocking execution or Uni-based receivers.

Experimental: treat API and semantics as subject to change until the extension graduates.

Verify

From the project root:

./mvnw test

An empty or placeholder test should compile and pass before we add behavior.

Domain records

Create src/main/java/dev/quarkex/nebulatrack/model/Severity.java:

package dev.quarkex.nebulatrack.model;

public enum Severity {
    NORMAL,
    CRITICAL
}

Create CostAnomaly.java, RemediationRequest.java, EstimateRequest.java, and CostEstimate.java:

package dev.quarkex.nebulatrack.model;

public record CostAnomaly(String region, double hourlyDelta, Severity severity) {
}

package dev.quarkex.nebulatrack.model;

public record RemediationRequest(String region, String action) {
}

package dev.quarkex.nebulatrack.model;

public record EstimateRequest(String service, int units) {
}

package dev.quarkex.nebulatrack.model;

import java.math.BigDecimal;

public record CostEstimate(String service, int units, BigDecimal monthlyCost) {
}

For the “no matching receiver” test later, add UnmatchedEstimateRequest.java with no receivers:

package dev.quarkex.nebulatrack.model;

/**
 * Signal type with no registered receivers — used to prove {@code request()} returns {@code null}.
 */
public record UnmatchedEstimateRequest(String service, int units) {
}

Test ledger

Receivers run asynchronously, so tests need a place they can poll without guessing about timing. This bean is plain on purpose. Each receiver just records what happened:

package dev.quarkex.nebulatrack.support;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.atomic.AtomicInteger;

import jakarta.enterprise.context.ApplicationScoped;

import dev.quarkex.nebulatrack.model.CostAnomaly;

@ApplicationScoped
public class InMemoryLedger {

    private final CopyOnWriteArrayList<CostAnomaly> anomalyEvents = new CopyOnWriteArrayList<>();
    private final AtomicInteger alertCount = new AtomicInteger();
    private final AtomicInteger auditCount = new AtomicInteger();
    private final AtomicInteger dashboardCount = new AtomicInteger();
    private final AtomicInteger workerACount = new AtomicInteger();
    private final AtomicInteger workerBCount = new AtomicInteger();
    private final AtomicInteger defaultLaneCount = new AtomicInteger();
    private final AtomicInteger criticalLaneCount = new AtomicInteger();
    private final AtomicInteger catchAllCount = new AtomicInteger();
    private final AtomicInteger pluginCount = new AtomicInteger();
    private final CopyOnWriteArrayList<Map<String, Object>> metadataSnapshots = new CopyOnWriteArrayList<>();
    private final CopyOnWriteArrayList<UUID> requestScopeIds = new CopyOnWriteArrayList<>();

    public void recordAnomaly(CostAnomaly anomaly) {
        anomalyEvents.add(anomaly);
    }

    public void recordAlert() {
        alertCount.incrementAndGet();
    }

    public void recordAudit() {
        auditCount.incrementAndGet();
    }

    public void recordDashboardRefresh() {
        dashboardCount.incrementAndGet();
    }

    public void recordWorkerA() {
        workerACount.incrementAndGet();
    }

    public void recordWorkerB() {
        workerBCount.incrementAndGet();
    }

    public void recordDefaultLane() {
        defaultLaneCount.incrementAndGet();
    }

    public void recordCriticalLane() {
        criticalLaneCount.incrementAndGet();
    }

    public void recordCatchAll() {
        catchAllCount.incrementAndGet();
    }

    public void recordPlugin() {
        pluginCount.incrementAndGet();
    }

    public void recordMetadata(Map<String, Object> metadata) {
        metadataSnapshots.add(Map.copyOf(metadata));
    }

    public void recordRequestScopeId(UUID id) {
        requestScopeIds.add(id);
    }

    public List<CostAnomaly> anomalyEvents() {
        return Collections.unmodifiableList(new ArrayList<>(anomalyEvents));
    }

    public int alertCount() {
        return alertCount.get();
    }

    public int auditCount() {
        return auditCount.get();
    }

    public int dashboardCount() {
        return dashboardCount.get();
    }

    public int workerACount() {
        return workerACount.get();
    }

    public int workerBCount() {
        return workerBCount.get();
    }

    public int defaultLaneCount() {
        return defaultLaneCount.get();
    }

    public int criticalLaneCount() {
        return criticalLaneCount.get();
    }

    public int catchAllCount() {
        return catchAllCount.get();
    }

    public int pluginCount() {
        return pluginCount.get();
    }

    public List<Map<String, Object>> metadataSnapshots() {
        return Collections.unmodifiableList(new ArrayList<>(metadataSnapshots));
    }

    public List<UUID> requestScopeIds() {
        return Collections.unmodifiableList(new ArrayList<>(requestScopeIds));
    }

    public void reset() {
        anomalyEvents.clear();
        alertCount.set(0);
        auditCount.set(0);
        dashboardCount.set(0);
        workerACount.set(0);
        workerBCount.set(0);
        defaultLaneCount.set(0);
        criticalLaneCount.set(0);
        catchAllCount.set(0);
        pluginCount.set(0);
        metadataSnapshots.clear();
        requestScopeIds.clear();
    }
}

Pattern 1: Publish for multicast

CostMonitor emits an anomaly on the default lane:

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.model.Severity;
import io.quarkus.signals.Signal;

@ApplicationScoped
public class CostMonitor {

    private final Signal<CostAnomaly> anomalySignal;

    @Inject
    public CostMonitor(Signal<CostAnomaly> anomalySignal) {
        this.anomalySignal = anomalySignal;
    }

    public void detect() {
        anomalySignal.publish(new CostAnomaly("us-east-1", 340.0, Severity.NORMAL));
    }
}

Add three receivers. AlertService and DashboardRefresher take the signal directly; AuditTrail already uses SignalContext, which pays off again when we attach metadata later:

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class AlertService {

    private final InMemoryLedger ledger;

    @Inject
    public AlertService(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void onAnomaly(@Receives CostAnomaly anomaly) {
        ledger.recordAlert();
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;
import io.quarkus.signals.SignalContext;

@ApplicationScoped
public class AuditTrail {

    private final InMemoryLedger ledger;

    @Inject
    public AuditTrail(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void onAnomaly(@Receives SignalContext<dev.quarkex.nebulatrack.model.CostAnomaly> ctx) {
        ledger.recordAudit();
        ledger.recordMetadata(ctx.metadata());
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class DashboardRefresher {

    private final InMemoryLedger ledger;

    @Inject
    public DashboardRefresher(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void onAnomaly(@Receives CostAnomaly anomaly) {
        ledger.recordDashboardRefresh();
    }
}

publish() delivers to every matching receiver, asynchronously. Each receiver gets its own CDI request context. That is a bigger shift than “observer on another thread.”

Verify

Add src/test/java/dev/quarkex/nebulatrack/NebulaTrackSignalsTest.java with @QuarkusTest, inject CostMonitor and InMemoryLedger, and implement publishNotifiesAllReceivers():

@Test
void publishNotifiesAllReceivers() {
    costMonitor.detect();

    await().atMost(10, TimeUnit.SECONDS).untilAsserted(() -> {
        assertThat(ledger.alertCount()).isGreaterThanOrEqualTo(1);
        assertThat(ledger.auditCount()).isGreaterThanOrEqualTo(1);
        assertThat(ledger.dashboardCount()).isGreaterThanOrEqualTo(1);
    });
}

Before you run the test, predict the shape of the result. If publish() behaved like queue dispatch, only one counter would move. Here all three should move.

Run ./mvnw test -Dtest=NebulaTrackSignalsTest#publishNotifiesAllReceivers. All three counters should move.

Qualifier primer: @Default is not catch-all

Before more patterns, one CDI trap: a receiver with no qualifier is @Default, not “any signal of this type.”

void onAnomaly(@Receives CostAnomaly anomaly) {
    // default lane only
}

For every lane, use @Any:

void onAnyAnomaly(@Receives @Any CostAnomaly anomaly) {
    // all qualifier lanes
}

That difference matters enough to model directly:

package dev.quarkex.nebulatrack.qualifier;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import jakarta.enterprise.util.AnnotationLiteral;
import jakarta.inject.Qualifier;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Qualifier
@Retention(RUNTIME)
@Target({ FIELD, METHOD, PARAMETER, TYPE })
public @interface Critical {

    final class Literal extends AnnotationLiteral<Critical> implements Critical {
        public static final Literal INSTANCE = new Literal();
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class DefaultLaneReceiver {

    private final InMemoryLedger ledger;

    @Inject
    public DefaultLaneReceiver(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void general(@Receives CostAnomaly anomaly) {
        ledger.recordDefaultLane();
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.qualifier.Critical;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class CriticalLaneReceiver {

    private final InMemoryLedger ledger;

    @Inject
    public CriticalLaneReceiver(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void critical(@Receives @Critical CostAnomaly anomaly) {
        ledger.recordCriticalLane();
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Any;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class CatchAllAnomalyReceiver {

    private final InMemoryLedger ledger;

    @Inject
    public CatchAllAnomalyReceiver(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void catchAll(@Receives @Any CostAnomaly anomaly) {
        ledger.recordCatchAll();
    }
}

Emit critical anomalies from an emitter that injects both Signal<CostAnomaly> (default lane) and @Any Signal<CostAnomaly> (for select(Critical.Literal.INSTANCE)):

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Any;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.model.Severity;
import dev.quarkex.nebulatrack.qualifier.Critical;
import io.quarkus.signals.Signal;

@ApplicationScoped
public class CriticalAnomalyEmitter {

    private final Signal<CostAnomaly> defaultAnomalySignal;
    private final Signal<CostAnomaly> anyAnomalySignal;

    @Inject
    public CriticalAnomalyEmitter(
            Signal<CostAnomaly> defaultAnomalySignal,
            @Any Signal<CostAnomaly> anyAnomalySignal) {
        this.defaultAnomalySignal = defaultAnomalySignal;
        this.anyAnomalySignal = anyAnomalySignal;
    }

    public void publishCritical() {
        anyAnomalySignal.select(Critical.Literal.INSTANCE)
                .publish(new CostAnomaly("eu-west-1", 900.0, Severity.CRITICAL));
    }

    public void publishDefault() {
        defaultAnomalySignal.publish(new CostAnomaly("us-west-2", 120.0, Severity.NORMAL));
    }
}

Publishing only on the @Any bean does not hit @Default receivers. That is the behavior we test next.

Verify

Before you run defaultReceiverIgnoresCriticalLane(), decide which counter should stay flat. If the answer is not defaultLaneCount, the CDI mental model is still in the driver’s seat.

defaultReceiverIgnoresCriticalLane() publishes only on the critical lane and asserts the default-lane counter stays at zero while the critical counter moves.

Pattern 2: Send for unicast work

Sometimes you want one worker, not fan-out. RemediationDispatcher uses send():

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.RemediationRequest;
import io.quarkus.signals.Signal;

@ApplicationScoped
public class RemediationDispatcher {

    private final Signal<RemediationRequest> remediationSignal;

    @Inject
    public RemediationDispatcher(Signal<RemediationRequest> remediationSignal) {
        this.remediationSignal = remediationSignal;
    }

    public void dispatch(String region, String action) {
        remediationSignal.send(new RemediationRequest(region, action));
    }
}

The workers are deliberately boring:

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.RemediationRequest;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class RemediationWorkerA {

    private final InMemoryLedger ledger;

    @Inject
    public RemediationWorkerA(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void handle(@Receives RemediationRequest request) {
        ledger.recordWorkerA();
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.RemediationRequest;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class RemediationWorkerB {

    private final InMemoryLedger ledger;

    @Inject
    public RemediationWorkerB(InMemoryLedger ledger) {
        this.ledger = ledger;
    }

    void handle(@Receives RemediationRequest request) {
        ledger.recordWorkerB();
    }
}

send() picks one receiver in round-robin order. This is the first pattern CDI events do not model cleanly.

Receivers default to blocking execution when they return a plain value. That keeps the “no Vert.x required” story honest for this walkthrough.

Verify

Before you run sendRoundRobinsBetweenWorkers(), predict the split. Six sends should not wake both workers six times. It should land close to 3/3.

sendRoundRobinsBetweenWorkers() sends six remediations and asserts worker A and B counts differ by at most one.

Pattern 3: Request for typed replies

BudgetService asks PricingEngine for a CostEstimate:

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostEstimate;
import dev.quarkex.nebulatrack.model.EstimateRequest;
import io.quarkus.signals.Signal;
import io.smallrye.mutiny.Uni;

@ApplicationScoped
public class BudgetService {

    private final Signal<EstimateRequest> estimateSignal;

    @Inject
    public BudgetService(Signal<EstimateRequest> estimateSignal) {
        this.estimateSignal = estimateSignal;
    }

    public CostEstimate estimateBlocking(String service, int units) {
        return estimateSignal.request(new EstimateRequest(service, units), CostEstimate.class);
    }

    public Uni<CostEstimate> estimateReactive(String service, int units) {
        return estimateSignal.reactive()
                .request(new EstimateRequest(service, units), CostEstimate.class);
    }
}

Receiver:

package dev.quarkex.nebulatrack.service;

import java.math.BigDecimal;

import jakarta.enterprise.context.ApplicationScoped;

import dev.quarkex.nebulatrack.model.CostEstimate;
import dev.quarkex.nebulatrack.model.EstimateRequest;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class PricingEngine {

    CostEstimate onEstimate(@Receives EstimateRequest request) {
        BigDecimal monthlyCost = BigDecimal.valueOf(request.units()).multiply(BigDecimal.valueOf(0.12));
        return new CostEstimate(request.service(), request.units(), monthlyCost);
    }
}

I use a blocking return type here so the app runs without Vert.x. A Uni-returning receiver defaults to non-blocking execution. When Vert.x is part of the runtime, that usually means the event loop.

Resolution also considers the response type. If nothing matches, request() returns null — worth testing explicitly, because publish() and send() stay silent in the same situation.

Verify

• requestReturnsTypedEstimate() — blocking path, 500 units at 0.12 → 60.00

• requestReturnsTypedEstimateReactive() — reactive().request(...)

• requestReturnsNullWhenNoReceiver() — inject Signal<UnmatchedEstimateRequest> with no receivers

Qualifiers in depth

The three lane receivers already show the rule. The last missing piece is the emitter side. Inject @Any Signal<CostAnomaly> when you need select() without carrying @Default:

anyAnomalySignal.select(Critical.Literal.INSTANCE)
        .publish(new CostAnomaly("eu-west-1", 900.0, Severity.CRITICAL));

Publish on the plain Signal<CostAnomaly> injection for the default lane only.

Verify

Before you run criticalLaneAndCatchAllReceiver(), count the expected catch-all hits first. It should see both emissions, not just the critical one.

criticalLaneAndCatchAllReceiver() publishes once on default and once on critical; default, critical, and catch-all counters all move.

Metadata with SignalContext

Attach metadata at emission time:

anomalySignal.withMetadata("traceId", traceId)
        .withMetadata("tenant", tenant)
        .publish(new CostAnomaly("us-east-1", 340.0, Severity.NORMAL));

Read it in a receiver that takes SignalContext<CostAnomaly>:

void onAnomaly(@Receives SignalContext<CostAnomaly> ctx) {
    String traceId = (String) ctx.metadata().get("traceId");
    CostAnomaly anomaly = ctx.signal();
}

Metadata is the honest built-in context story today. If you want automatic enrichment or interception, the extension already exposes SPI hooks such as SignalMetadataEnricher and ReceiverInterceptor. What it does not give you out of the box is automatic tracing or security propagation.

Verify

metadataVisibleInReceiver() after costMonitor.detectWithMetadata("abc-123", "acme").

Programmatic receivers

Runtime registration via Receivers:

package dev.quarkex.nebulatrack.service;

import java.util.function.Consumer;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.qualifier.Critical;
import dev.quarkex.nebulatrack.support.CostPlugin;
import io.quarkus.signals.Receivers;
import io.quarkus.signals.SignalContext;

@ApplicationScoped
public class PluginReceiverRegistrar {

    private final Receivers receivers;

    @Inject
    public PluginReceiverRegistrar(Receivers receivers) {
        this.receivers = receivers;
    }

    public Receivers.Registration register(CostPlugin plugin) {
        return receivers.newReceiver(CostAnomaly.class)
                .setQualifiers(Critical.Literal.INSTANCE)
                .setExecutionModel(Receivers.ExecutionModel.BLOCKING)
                .notify((Consumer<SignalContext<CostAnomaly>>) ctx -> plugin.process(ctx.signal()));
    }
}

The explicit Consumer cast avoids ambiguity between notify(Consumer) and notify(Function) overloads.

The guide documents runtime registration and unregistration, but it does not promise stronger concurrency semantics than that. For plugin-style infrastructure, treat registration as something you should test under load instead of assuming atomic visibility during concurrent emissions.

Verify

programmaticRegisterAndUnregister() — register, publish critical, assert delivery; unregister(), publish again, count unchanged.

Request context per receiver

Each receiver invocation activates a new CDI request context. That is easy to prove with two tiny classes:

package dev.quarkex.nebulatrack.support;

import java.util.UUID;

import jakarta.enterprise.context.RequestScoped;

@RequestScoped
public class InvocationTrace {

    private final UUID id = UUID.randomUUID();

    public UUID id() {
        return id;
    }
}

package dev.quarkex.nebulatrack.service;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.model.CostAnomaly;
import dev.quarkex.nebulatrack.support.InMemoryLedger;
import dev.quarkex.nebulatrack.support.InvocationTrace;
import io.quarkus.signals.Receives;

@ApplicationScoped
public class RequestScopeProbe {

    private final InMemoryLedger ledger;
    private final InvocationTrace trace;

    @Inject
    public RequestScopeProbe(InMemoryLedger ledger, InvocationTrace trace) {
        this.ledger = ledger;
        this.trace = trace;
    }

    void onAnomaly(@Receives CostAnomaly anomaly) {
        ledger.recordRequestScopeId(trace.id());
    }
}

Verify

receiversGetIsolatedRequestScope() — two publish() calls yield two different UUIDs in the ledger.

Optional command-mode entry point

NebulaTrackMain implements QuarkusApplication with @QuarkusMain and runs a short demo sequence:

package dev.quarkex.nebulatrack;

import jakarta.inject.Inject;

import dev.quarkex.nebulatrack.service.BudgetService;
import dev.quarkex.nebulatrack.service.CostMonitor;
import dev.quarkex.nebulatrack.service.RemediationDispatcher;
import io.quarkus.runtime.QuarkusApplication;
import io.quarkus.runtime.annotations.QuarkusMain;

@QuarkusMain
public class NebulaTrackMain implements QuarkusApplication {

    private final CostMonitor costMonitor;
    private final RemediationDispatcher remediationDispatcher;
    private final BudgetService budgetService;

    @Inject
    public NebulaTrackMain(
            CostMonitor costMonitor,
            RemediationDispatcher remediationDispatcher,
            BudgetService budgetService) {
        this.costMonitor = costMonitor;
        this.remediationDispatcher = remediationDispatcher;
        this.budgetService = budgetService;
    }

    @Override
    public int run(String... args) throws Exception {
        costMonitor.detect();
        remediationDispatcher.dispatch("us-east-1", "scale-down-idle-nodes");
        var estimate = budgetService.estimateBlocking("s3", 500);
        System.out.printf("NebulaTrack demo finished; sample estimate for %s: %s%n",
                estimate.service(), estimate.monthlyCost());
        return 0;
    }
}

Quarkus command-mode testing usually works best as a mix: @QuarkusMainTest for CLI behavior and @QuarkusTest for internals. This article stays on the internal side, so we inject beans directly.

Make it survive

Experimental extension — pin the Quarkus version in the article and in CI; expect API tweaks.

Silent fan-out — publish() and send() succeed when no receiver matches. Fine for notifications; dangerous if you assume someone handled the work.

Receiver failures — blocking publish() and send() log receiver failures instead of throwing them back to the caller. Blocking request() is different: it throws the receiver failure on the calling thread. Reactive emissions fail the returned Uni.

request() returns null — treat as part of the contract; test it.

Qualifier resolution — @Default vs @Any trips people coming from CDI observers. Emit from the injection point that matches the lane you intend.

Execution models — blocking receivers work without Vert.x. Uni receivers and NON_BLOCKING pull Vert.x into the execution story. Virtual-thread execution models need the right runtime support; in a minimal app, prefer blocking for receivers and programmatic hooks.

Programmatic registration — runtime registration is useful for plugins, but the public guide does not promise stronger visibility guarantees than register/unregister itself. If this matters under load, test it under load.

Metadata is not tracing — correlation IDs yes; automatic OpenTelemetry or security propagation no.

Prove it

From the module root:

./mvnw test

All tests in NebulaTrackSignalsTest should pass. That covers publish fan-out, send round-robin, blocking and reactive request, null request, qualifiers, metadata, programmatic register/unregister, and request-scope isolation.

When to reach for Signals

Use CDI events for classic observer multicast, especially when synchronous delivery or transactional observers matter.

Use Signals for in-process async coordination when you need publish, send, or typed request-reply between decoupled components.

Use Reactive Messaging when Kafka, AMQP, Pulsar, backpressure, or connectors are in scope.

Use Vert.x EventBus when you want address-based routing and the Vert.x programming model.

Signals are not “another event bus.” They are the layer between CDI convenience and broker-backed messaging.

That is the gap from the opening. CDI events still own classic observer fan-out. Signals give you one small in-process API for fan-out, unicast work, and typed request-reply without dragging in broker concerns.

Subscribe now

I like MCP. I do not like acting as if it has no cost.

The current Bob context window docs are unusually direct about this. Bob gets a 200,000-token context window, starts condensing the conversation at 140,000, and includes MCP tool definitions in that same budget. The current Bob MCP docs are just as blunt: disable unused tools because their definitions consume context.

For me, that changes the useful question. Bob can reach GitHub. The more useful question is “what did I put into the model before it even looked at my code?”

I wanted a number I could check, so I measured the current GitHub MCP Server surface and compared it with a different kind of context waste: raw git output from a real dirty repository that I have locally. It is my development repository for The Main Thread. It has a ton of local changes, that only once in a while get pushed to Github. It is ideal to test so we can answer the question “is MCP bad?” A broad MCP server spends budget up front. A git or gh workflow spends budget later, when you push large outputs into the same chat. This article is about where that context budget goes.

What you need

You do not need a benchmark setup for this. You need one real repository, one Bob window, and a willingness to look at the token counter before trusting your first impression.

• IBM Bob (sign up for a free trial if you like), with access to the current docs and the token counter in the chat panel

• A repository with real local changes, not a staged toy example

• Plain git

• Optional: GitHub CLI if you want to apply the same narrowing pattern to pull request work

• About 20 minutes

As of the date of writing, the current GitHub MCP Server configuration guide says the default toolsets are context, issues, pull_requests, repos, and users. The current feature flag docs also show how that surface can expand when you opt into more granular issue and pull request tools.

My token estimates here use o200k_base tokenization against the official GitHub MCP tool snapshots and the current local git payloads in said repository. o200k_base is OpenAI’s latest BPE (Byte Pair Encoding) tokenization algorithm used by advanced models like GPT-4o and later

Bob’s exact live tokenizer does surly differ a little. The underlying problem does not.

The quiet cost shows up before the task starts

The first cost is the catalog tax. I mean the tokens you spend on tool definitions before the task starts.

Bob’s docs say MCP tool definitions live inside the context window. The GitHub MCP docs say the default server surface includes five toolsets. So I pulled the official GitHub MCP tool snapshots and counted them.

The default GitHub MCP toolsets came out to about 17,201 tokens.

That is already a non-trivial slice of Bob’s budget:

• About 8.6 percent of the full 200,000-token window

• About 12.3 percent of the 140,000-token condensation threshold

The broader official snapshot surface I measured landed at about 37,787 tokens. That is roughly 18.9 percent of the full window and 27.0 percent of the condensation threshold. A few always-on servers are enough to reduce the free space quite a lot.

The default GitHub buckets were not evenly sized, either:

• repos cost about 7,841 tokens

• pull_requests cost about 5,093 tokens

• issues cost about 3,541 tokens

• context and users were cheap by comparison at about 403 and 323

That breakdown matters because it gives you a practical way to be more careful. If the task is code review, I would rather load a narrow GitHub review surface. I do not want repository, issue, discussion, action, and write-heavy tools in the same task just because “GitHub” sounds like one thing.

The current GitHub MCP Server configuration guide supports exactly that kind of narrowing with X-MCP-Toolsets, X-MCP-Tools, X-MCP-Exclude-Tools, and read-only mode. The GitHub docs are making the same point as the Bob docs: shape the surface on purpose.

If I were setting up a review-oriented GitHub MCP connection in Bob, I would start closer to this than to “just enable everything”:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "X-MCP-Toolsets": "issues,pull_requests",
        "X-MCP-Readonly": "true",
        "X-MCP-Exclude-Tools": "create_pull_request,merge_pull_request"
      }
    }
  }
}

I am only showing the headers that shape the surface. Add authentication the same way you already do for your GitHub MCP setup. My point is the surface shape, not your secret-management style.

This is also where Bob’s project-level .bob/mcp.json support matters more than teams admit. A global MCP setup gets crowded very quickly. A project-level setup is more likely to reflect what that repository is actually doing.

Git and gh also cost tokens

Skipping MCP and using git sounds simpler. The real picture is more mixed than that.

The second cost is the payload tax. I mean the tokens you spend when commands return large outputs.

git and gh feel lighter because Bob does not need to carry a large tool catalog before the task starts. That is true. The problem comes later, when people spend that saving immediately by asking the agent to read a very large patch all at once.

I measured my current dirty working tree in my test repository because it has the kind of mess that shows bad habits clearly: edits, deletions, untracked publishing files, and generated assets.

I did not force a separate gh benchmark for the local-change case because that is not where gh is most useful. For “what changed in my working tree?” the useful comparison is broad MCP surface versus ordinary git. For pull request work, gh behaves much more like git than like MCP. It has almost no upfront catalog cost, and then a payload cost only when you ask for output.

The small commands were genuinely small:

• git status --short came out to about 817 tokens

• git diff --name-only came out to about 619 tokens

• git diff --stat came out to about 655 tokens

• git status --porcelain=v2 was fatter, but still small at about 3,261 tokens

The full patch was much larger:

• git diff came out to about 82,747 tokens

• git diff --unified=0 was not meaningfully better here at about 83,206 tokens

• Reading the current untracked text files as raw content came out to about 83,568 tokens

That means a local-change prompt can use half the window even without MCP if you choose the broadest possible output.

The combined numbers are more serious:

• Default GitHub MCP surface plus the current tracked diff came out to about 99,948 tokens

• Broader GitHub MCP surface plus the current tracked diff came out to about 120,534 tokens

• Default GitHub MCP surface plus tracked diff plus current untracked text content came out to about 183,516 tokens

• Broader GitHub MCP surface plus tracked diff plus current untracked text content came out to about 204,102 tokens

That last number is already beyond Bob’s documented 200,000-token window.

One result is useful and a little absurd. One deleted SVG in my repository accounted for about 37,787 tokens by itself. That single asset was roughly the same size as the broader GitHub MCP snapshot surface I measured.

This is why I do not like the simple “use the CLI instead” advice. The CLI does not solve the problem by itself. It is only a different way to waste the budget if you choose broad outputs too early.

Start local-change analysis with the cheap questions

If the prompt is “analyze my local changes,” I would not start with a full patch unless the repository is tiny or I already know the diff is clean text.

I would start like this:

git status --short
git diff --stat
git diff --name-only

That gives Bob three useful things at almost no cost:

• Which files changed

• Rough size by file

• Whether the mess is concentrated or spread out

After that, narrow on purpose:

git diff -- path/to/file
git diff -- path/to/second-file

That pattern is boring, and that is good here. You are asking the model to tell you where deeper attention belongs before you give it the expensive context.

The same principle applies to GitHub CLI.

If the work is really about a pull request, I would rather start with small remote views such as gh pr view metadata or gh pr diff --name-only. I do not want to dump a full PR diff into the chat on turn one. The exact command matters less than the sequence:

1. Ask what changed

2. Ask where the risky areas are

3. Read only the files that matter

4. Escalate to the full diff only if the first three steps justify it

Here is the main operating rule in one sentence: narrow the catalog first, then narrow the payload.

This is not an argument against MCP

I would still use GitHub MCP for workflows where it fits well.

It fits well when the work is mainly about GitHub:

• Reading issue state and comments

• Reviewing a pull request with structured operations

• Writing a review comment or updating GitHub state directly

• Repeating the same repository workflow often enough that the upfront catalog cost is worth it

I would lean on git or gh first when the work is structurally local:

• “Analyze my working tree”

• “Tell me what changed before I commit”

• “Which files deserve review first?”

• “Did I accidentally mix three tasks into one diff?”

This is the part I think teams mix together. They install a broad GitHub server globally, then ask a local-change question, then feel surprised that the agent is carrying a lot of GitHub machinery into a task that mostly needed git status, git diff --stat, and some restraint.

The experiment I would actually run

If you want to make this concrete in your own setup, run the same three tasks through three different Bob surfaces.

Use these setups:

1. No GitHub MCP server at all. Let Bob use normal file and command tools with git.

2. A lean GitHub MCP setup with only the toolsets needed for review work.

3. A broad GitHub MCP setup that looks convenient but loads a lot of extra surface.

Use tasks shaped like these:

1. Analyze my current local changes and tell me which three files deserve deeper review first.

2. Summarize the risk in the deleted or moved areas.

3. Tell me what I need to read before I touch the GitHub workflow in this repository.

Watch three things:

• The token counter before the first real action

• The first tool or command Bob reaches for

• Whether Bob narrows the problem or tries to swallow the whole repository at once

I do not expect one setup to win every task. The right setup changes with the job. Broad always-on configurations fail more often than teams want to admit.

The default I would keep

If I were writing one rule for a team, it would be simple.

Keep GitHub MCP project-specific whenever you can. Keep the toolsets narrow. Prefer read-only for review-style work. Do not feed full diffs into the first turn. Treat generated assets as suspiciously expensive until proven otherwise. Ask the agent to rank files before it reads them in full.

That is also why I like Bob’s current docs on this point. They do not pretend the model can solve bad context hygiene by itself. The docs say the window is finite, tool definitions consume tokens, and disabling tools helps. Good. That is the more useful way to talk about this.

MCP is not the enemy. git is not the savior. Unbudgeted context is the problem. Sometimes that waste arrives as a large set of tool definitions. Sometimes it arrives as an 80k-token diff blob. Usually it arrives because nobody decided what the agent actually needed for this task.

This is also why I do not find “we just need a bigger context window” very convincing. A larger window can help in some cases, but it also lets bad context stay alive for longer. That includes stale instructions, irrelevant tool definitions, oversized diffs, and weak intermediate summaries that keep pushing the model in the wrong direction. I think of that as context window poisoning: the window is full, but too much of it is low-value, misleading, or simply old. A bigger window does not fix that. It often hides the problem for a while, increases cost, and delays the moment when the team learns to narrow the tool surface and the payload. Most of the time, better selection beats more storage.

Conclusion

The useful mental model here is “catalog tax versus payload tax.” A broad GitHub MCP server can use tens of thousands of tokens before Bob touches your code, and a broad local git diff workflow can use just as much a minute later. The fix is simpler than the demos: narrower tool surfaces, narrower outputs, and a little more honesty about what should compete for attention in the same 200,000-token window.

Subscribe now

I do not find security tutorials very useful when they jump from TLS to Keycloak to a couple of annotations and call that a design. The part that matters is whether you can answer three separate questions cleanly:

• Is this channel trustworthy?

• Which service is calling me?

• Where do business rules actually live?

So that is what we do here.

What we build

We build LoanFlow: three Quarkus services on JDK 25 with app-managed mTLS, OIDC service tokens on outbound REST clients, and branch-level policy at the public edge.

• loan-service — public edge API. Accepts bearer tokens for human users, enforces branch ownership, orchestrates downstream calls.

• credit-service — internal only. Requires HTTPS with a client certificate and a bearer token with permission credit_check_run.

• document-service — internal only. Same transport rules; requires permission document_write.

By the end you can prove:

• A Berlin loan officer reads and submits their own loan

• A Hamburg officer gets 403 on a Berlin loan

• A direct call to credit-service without a client certificate fails at TLS

• A call with mTLS but no bearer token gets 403

• A second submit of the same loan returns 409

Prerequisites

You need a normal local Java setup plus the usual tools for certificates and test traffic. Use whatever Quarkus CLI version you already have installed. It pins the platform BOM in each generated pom.xml, so this tutorial does not depend on you matching one exact CLI release.

• JDK 25

• Quarkus CLI

• Podman (Dev Services starts Keycloak in a Podman container)

• OpenSSL, keytool, curl, jq

• Familiarity with JAX-RS and OIDC bearer tokens

• About ☕️☕️☕️

Create the workspace root and the shared support directories first:

mkdir -p loanflow-zero-trust/{infrastructure,scripts}
cd loanflow-zero-trust

The three service directories get created by the Quarkus commands in the next step. Copy infrastructure and scripts from my Github repository.

Project setup

Create the three applications from the repo root. Run each command once:

quarkus create app com.mainthread.loanflow:loan-service \
  --extension='rest-jackson,rest-client-jackson,oidc,rest-client-oidc-filter,tls-registry,smallrye-health' \
  --java=25 --no-code

quarkus create app com.mainthread.loanflow:credit-service \
  --extension='rest-jackson,oidc,tls-registry,smallrye-health' \
  --java=25 --no-code

quarkus create app com.mainthread.loanflow:document-service \
  --extension='rest-jackson,oidc,tls-registry,smallrye-health' \
  --java=25 --no-code

Extensions and why they matter:

• rest-jackson — Quarkus REST with JSON for edge and internal APIs

• rest-client-jackson + rest-client-oidc-filter — typed outbound clients that attach service tokens automatically (loan-service only)

• oidc — bearer token validation on every secured endpoint

• tls-registry — named TLS configurations for edge HTTPS, internal mTLS servers, and internal mTLS clients

• smallrye-health — liveness probes when you deploy this later

Add test dependencies in each module POM: rest-assured and quarkus-test-security-oidc (test scope). Internal services also need quarkus-test-oidc-server for OidcWiremockTestResource.

Architecture on purpose

Transport — Internal hops use app-managed mTLS through the TLS registry. We are not using a service mesh here because I want the transport layer to stay visible in config you can grep.

Service identity — loan-service acquires its own token with the OIDC client and REST client filter. I would rather let Quarkus do that work than hand-roll Authorization headers and rediscover the annoying parts ourselves.

Business authorization — User-specific rules stay in loan-service. credit-service and document-service never decide whether Alice from Berlin can touch loan LN-100. They decide whether the caller is an allowed internal service with the right permission. A client_credentials token does not represent a human loan officer, and pretending otherwise is how these demos get fuzzy fast.

Out of scope for this demo — service mesh, OPA, Keycloak authorization services, and propagating the end-user token downstream. If credit-service later needs user-level policy, you are in token propagation or token exchange territory. That is a different tutorial.

Generate certificates

Run ./scripts/generate-certs.sh from the repo root. It creates a local CA, one certificate per service, and a shared truststore under infrastructure/certs/.

Each service directory gets tls.key, tls.crt, and keystore.p12. The shared truststore contains only the CA. PKCS12 password is changeit for local dev.

Keycloak with Dev Services

Copy infrastructure/keycloak/loanflow-realm.json into each module as src/main/resources/loanflow-realm.json. Quarkus Dev Services for Keycloak starts Keycloak in a Podman container when you run quarkus:dev, imports that realm, and wires quarkus.oidc.auth-server-url for you. That saves us from turning local setup into a side quest.

Leave quarkus.oidc.auth-server-url unset in dev mode, because setting it disables Dev Services. Pin the host port so the curl examples stay stable:

quarkus.keycloak.devservices.realm-name=loanflow
quarkus.keycloak.devservices.realm-path=loanflow-realm.json
quarkus.keycloak.devservices.port=8180

quarkus.oidc.application-type=service

All three services carry the same Dev Services block. Quarkus shares one Keycloak container between dev-mode processes on the same machine. Start loan-service first if you want a predictable boot order, but any of the three can bring Keycloak up.

The realm defines:

• Users — alice/alice (Berlin, loan_officer), bob/bob (Hamburg, loan_officer), admin/admin (loan_admin)

• loanflow-cli — confidential client with direct access grants for local password-grant token retrieval (loanflow-cli-secret)

• loan-service — confidential client with service account; default scopes credit_check_run and document_write

Realm roles (not Keycloak Groups) map to @RolesAllowed. The loanflow-cli client uses the same pattern as the dpop-demo Keycloak realm: roles in defaultClientScopes, with a full roles client scope definition that adds realm_access.roles to the access token. The separate branch client scope adds the branch claim. Service token scopes map to @PermissionsAllowed on internal endpoints.

In the Keycloak admin UI, an empty Groups list is expected. Check Clients → loanflow-cli → Client scopes → Default for roles and branch, and Users → alice → Role mapping → Realm roles for loan_officer.

The password grant is here as a local test shortcut, nothing more. I would not turn that into the real browser story.

Implement loan-service

loan-service is the policy enforcement point. It knows users, branches, and loan state.

Seed data in an in-memory repository:

• LN-100, branch berlin, status DRAFT

• LN-200, branch hamburg, status DRAFT

• LN-300, branch berlin, status SUBMITTED

Expose:

• GET /api/loans/{loanId}

• POST /api/loans/{loanId}/submit

Coarse access uses @RolesAllowed({"loan_officer", "loan_admin"}). Keycloak puts realm roles in realm_access.roles; tell Quarkus where to find them:

quarkus.oidc.roles.role-claim-path=realm_access/roles

Fine-grained branch rules live in LoanAccessPolicy. Read branch from the JWT — it does not land on SecurityIdentity automatically:

@ApplicationScoped
public class LoanAccessPolicy {

    private final CallerContext callerContext;

    public LoanAccessPolicy(CallerContext callerContext) {
        this.callerContext = callerContext;
    }

    public void checkCanRead(LoanApplication loan) {
        if (callerContext.hasRole("loan_admin")) {
            return;
        }

        String branch = callerContext.branch();
        if (!callerContext.hasRole("loan_officer") || !loan.branch().equals(branch)) {
            throw new ForbiddenException();
        }
    }

    public void checkCanSubmit(LoanApplication loan) {
        checkCanRead(loan);
        if (loan.status() != LoanStatus.DRAFT) {
            throw new WebApplicationException("Loan is not in DRAFT status", 409);
        }
    }
}

CallerContext is @RequestScoped and reads branch from JsonWebToken at runtime (falling back to SecurityIdentity attributes in tests). ForbiddenAccessMapper turns branch denials into 403 with a small JSON body so curl output is obvious.

LoanApplicationService.submit() runs in order: load loan → checkCanSubmit → call credit-service → call document-service → persist SUBMITTED only after both succeed.

The outbound REST client attaches a service token automatically:

@Path("/internal/credit-checks")
@RegisterRestClient(configKey = "credit-service")
@OidcClientFilter("internal-calls")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface CreditServiceClient {

    @POST
    CreditCheckResponse run(CreditCheckRequest request);
}

Create DocumentServiceClient the same way with configKey = "document-service" and path /internal/documents.

Implement credit-service and document-service

Internal services stay small on purpose. Once these endpoints start owning business rules too, the boundary gets muddy fast. Here they validate transport and permission, then do one job.

@Path("/internal/credit-checks")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CreditResource {

    @Inject
    CreditDecisionService creditDecisionService;

    @POST
    @PermissionsAllowed("credit_check_run")
    public CreditCheckResponse run(CreditCheckRequest request) {
        return creditDecisionService.run(request);
    }
}

document-service mirrors this with @PermissionsAllowed("document_write") on POST /internal/documents. Credit scoring is deterministic fake logic — this tutorial is about security boundaries, not bureau accuracy.

Wire the configuration

This is the part I usually check first in security demos, because it is where hand-wavy examples turn back into engineering. Every property below matters.

loan-service

Edge HTTPS without client certificates from human callers:

quarkus.http.ssl-port=8443
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=edge

quarkus.tls.edge.key-store.p12.path=../infrastructure/certs/loan-service/keystore.p12
quarkus.tls.edge.key-store.p12.password=changeit

quarkus.tls.internal-client.key-store.p12.path=../infrastructure/certs/loan-service/keystore.p12
quarkus.tls.internal-client.key-store.p12.password=changeit
quarkus.tls.internal-client.trust-store.p12.path=../infrastructure/certs/truststore.p12
quarkus.tls.internal-client.trust-store.p12.password=changeit

quarkus.oidc.application-type=service

quarkus.keycloak.devservices.realm-name=loanflow
quarkus.keycloak.devservices.realm-path=loanflow-realm.json
quarkus.keycloak.devservices.port=8180

quarkus.oidc-client.internal-calls.auth-server-url=${quarkus.oidc.auth-server-url}
quarkus.oidc-client.internal-calls.client-id=loan-service
quarkus.oidc-client.internal-calls.credentials.secret=loan-service-secret
quarkus.oidc-client.internal-calls.grant.type=client
quarkus.oidc-client.internal-calls.early-tokens-acquisition=false

quarkus.rest-client.credit-service.url=https://localhost:8444
quarkus.rest-client.credit-service.tls-configuration-name=internal-client

quarkus.rest-client.document-service.url=https://localhost:8445
quarkus.rest-client.document-service.tls-configuration-name=internal-client

What breaks when this is wrong:

• Missing edge TLS name → no HTTPS on 8443

• Wrong truststore on internal-client → PKIX path building failed on downstream calls

• Setting quarkus.oidc.auth-server-url in dev → Dev Services never starts Keycloak

• Missing OIDC client internal-calls → REST client cannot fetch a service token

• early-tokens-acquisition=true → short-lived tokens may expire before the first downstream call

credit-service and document-service

Internal only — require client certificates:

quarkus.http.ssl-port=8444
quarkus.http.insecure-requests=disabled
quarkus.http.tls-configuration-name=internal-server
quarkus.http.ssl.client-auth=REQUIRED

quarkus.tls.internal-server.key-store.p12.path=../infrastructure/certs/credit-service/keystore.p12
quarkus.tls.internal-server.key-store.p12.password=changeit
quarkus.tls.internal-server.trust-store.p12.path=../infrastructure/certs/truststore.p12
quarkus.tls.internal-server.trust-store.p12.password=changeit

quarkus.oidc.application-type=service

quarkus.keycloak.devservices.realm-name=loanflow
quarkus.keycloak.devservices.realm-path=loanflow-realm.json
quarkus.keycloak.devservices.port=8180

Use port 8445 and document-service cert paths for document-service.

What breaks:

• Missing client-auth=REQUIRED → anyone with a valid token reaches the internal API over TLS

• Truststore missing the CA → valid client certificates fail during handshake

• Hard-coded quarkus.oidc.auth-server-url in dev → Dev Services disabled; token validation fails if nothing listens on that URL

Run the system

After the certificates exist, start each service in its own terminal. The first quarkus:dev process starts Keycloak in Podman; the others attach to the shared container:

cd loan-service && ./mvnw quarkus:dev
cd credit-service && ./mvnw quarkus:dev
cd document-service && ./mvnw quarkus:dev

Wait until the startup log shows Keycloak listening on port 8180 before running token curl commands.

HTTPS URLs:

• loan-service — https://localhost:8443

• credit-service — https://localhost:8444

• document-service — https://localhost:8445

Prove it

Run these commands from the loanflow-zero-trust/ repo root — the certificate paths are relative to that directory. Your shell prompt should not be ~ unless the repo happens to live there.

cd /path/to/loanflow-zero-trust

export CA=infrastructure/certs/ca/ca.crt
export LOAN_CERT=infrastructure/certs/loan-service

Get a user token for Alice (local test shortcut):

export USER_TOKEN=$(
  curl -sf http://localhost:8180/realms/loanflow/protocol/openid-connect/token \
    --user loanflow-cli:loanflow-cli-secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=alice&password=alice&grant_type=password' | jq -r '.access_token'
)

echo "$USER_TOKEN" | awk -F. '{print $2}' | python3 -c "import sys,base64,json; p=sys.stdin.read().strip(); p+=('='*(-len(p)%4)); print(json.dumps(json.loads(base64.urlsafe_b64decode(p)), indent=2))"

test -n "$USER_TOKEN" && test "$USER_TOKEN" != "null"

If test fails, Keycloak is not ready or the realm import missed loanflow-cli. Re-check the Dev Services startup log.

Read a Berlin loan through the edge:

curl -i --cacert "$CA" \
  -H "Authorization: Bearer $USER_TOKEN" \
  https://localhost:8443/api/loans/LN-100

Expected: HTTP/2 200 with the loan JSON.

Same call with Bob’s token against LN-100:

export BOB_TOKEN=$(
  curl -sf http://localhost:8180/realms/loanflow/protocol/openid-connect/token \
    --user loanflow-cli:loanflow-cli-secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=bob&password=bob&grant_type=password' | jq -r '.access_token'
)

test -n "$BOB_TOKEN" && test "$BOB_TOKEN" != "null"

curl -i --cacert "$CA" \
  -H "Authorization: Bearer $BOB_TOKEN" \
  https://localhost:8443/api/loans/LN-100

Expected: HTTP/2 403 with {"error":"access_denied"}. Quarkus often returns an empty body on 403; this demo maps branch denials to a small JSON payload so the status is obvious in the terminal. The loan-service log should still show Loan access denied ... caller=bob callerBranch=hamburg loanBranch=berlin.

If you see 401 instead, the token is missing, expired, or stale — re-run the export BOB_TOKEN=... block above. Branch policy only runs after OIDC accepts the bearer token.

Prove the internal API is really internal. Fetch a service token:

export SERVICE_TOKEN=$(
  curl -sf http://localhost:8180/realms/loanflow/protocol/openid-connect/token \
    --user loan-service:loan-service-secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials' | jq -r '.access_token'
)

Call credit-service without a client certificate — expect TLS handshake failure:

curl --cacert "$CA" \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"loanId":"LN-100","applicantId":"alice"}' \
  https://localhost:8444/internal/credit-checks

Call with the loan-service certificate but no bearer token — expect 403:

curl -i --cacert "$CA" \
  --cert "$LOAN_CERT/tls.crt" \
  --key "$LOAN_CERT/tls.key" \
  -H 'content-type: application/json' \
  -d '{"loanId":"LN-100","applicantId":"alice"}' \
  https://localhost:8444/internal/credit-checks

The client certificate satisfies mTLS, but without a bearer token the caller has no OIDC permission — Quarkus returns 403. Plain HTTP tests in @QuarkusTest (no client cert) typically show 401 instead.

Call with mTLS and the service token — expect 200:

curl --cacert "$CA" \
  --cert "$LOAN_CERT/tls.crt" \
  --key "$LOAN_CERT/tls.key" \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"loanId":"LN-100","applicantId":"alice"}' \
  https://localhost:8444/internal/credit-checks

Drive the full flow:

curl --cacert "$CA" \
  -X POST \
  -H "Authorization: Bearer $USER_TOKEN" \
  https://localhost:8443/api/loans/LN-100/submit

Expected: 200, credit band in the response, audit document stored, second submit returns 409.

Watch the logs

Run each service in its own terminal. After a successful submit, you should see the trust chain play out across three consoles — user token at the edge, service token on internal hops:

loan-service     Loan submit loanId=LN-100 by alice branch=berlin
loan-service     Calling credit-service for loanId=LN-100
credit-service   Credit check loanId=LN-100 band=D caller=service-account-internal-calls
loan-service     Credit band D for loanId=LN-100
loan-service     Calling document-service for loanId=LN-100
document-service Stored audit document loanId=LN-100 branch=berlin creditBand=D caller=service-account-internal-calls
loan-service     Loan submitted loanId=LN-100 creditBand=D

Denied requests log too — branch mismatch on read returns 403 with a Loan access denied line; a second submit on the same loan returns 409 with Loan submit rejected.

The services log principals and loan ids only. They never print bearer tokens or JWT bodies.

Or run ./scripts/smoke-test.sh from the repo root once all three services are up — it walks every failure path in order.

Tests worth keeping

Module tests rot fast when someone renames a claim or changes a port, so keep at least:

• loan-service — LoanAccessPolicyTest (unit), LoanResourceSecurityTest (@QuarkusTest + @TestSecurity for branch/admin/401)

• credit-service / document-service — @QuarkusTest with OidcWiremockTestResource proving 401 without a token

For bearer-token tests on internal services, I would rather use Wiremock OIDC than drag Keycloak into every ./mvnw test run. For end-to-end transport behavior, the smoke script is still worth more than ten paragraphs of architecture confidence.

Troubleshooting

401 from loan-service when you expected branch 403 — the bearer token is missing, expired, or invalid. Fetch a fresh token and confirm test -n "$BOB_TOKEN". Branch policy runs only after OIDC validation succeeds.

curl prints nothing — Quarkus often returns an empty body on 401/403. Add -i to see the status line. A 403 with a valid token usually means the access token is missing realm roles. Decode the token and confirm it contains realm_access.roles with loan_officer:

echo "$USER_TOKEN" | awk -F. '{print $2}' | python3 -c "import sys,base64,json; p=sys.stdin.read().strip(); p+=('='*(-len(p)%4)); print(json.dumps(json.loads(base64.urlsafe_b64decode(p)), indent=2))"

After changing loanflow-realm.json, Dev Services does not overwrite an existing realm. Stop all services, run ./scripts/reset-keycloak.sh, start loan-service first, then fetch a fresh token.

curl: (77) error setting certificate verify locations — you are not in the loanflow-zero-trust/ repo root, or ./scripts/generate-certs.sh has not been run. cd to the repo and confirm infrastructure/certs/ca/ca.crt exists. The smoke script resolves paths automatically; hand-typed curl commands need the same working directory.

PKIX path building failed — truststore missing the CA, or REST client points at the wrong TLS bucket.

TLS handshake fails before the request is logged — usually good news. client-auth=REQUIRED is doing its job; client certificate missing or untrusted.

401 from internal services — bearer token missing, expired, wrong issuer, or OIDC metadata unreachable.

403 from internal services — mTLS succeeded but bearer token missing or token valid without the permission required by @PermissionsAllowed.

403 from loan-service — business rule fired. Check branch claim, roles, and seeded loan branch.

Enable OIDC trace logging when token validation is unclear:

quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".level=TRACE
quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".min-level=TRACE

Make it survive production

This demo is deliberately local and small. Production needs a few extra moves:

• Replace the local CA with real internal PKI or a cert-manager pipeline

• Move secrets out of application.properties into a supported secret source

• Add quarkus.ssl.native=true for services that make HTTPS calls in native mode

• Rotate certificates and client secrets on a schedule that exists outside human memory

• Add correlation IDs so a rejected downstream request traces across services

• Consider audience enforcement or token exchange if downstream services later need user context

I would not move branch policy into internal services just because the local demo works. That is where these systems start getting weird.

Close the loop

In a microservice system, zero-trust is only useful when each trust decision is visible and testable.

In this design, the channel is protected with mTLS, the internal caller proves itself with a service token, and user-level policy stays where the loan aggregate actually lives. When a request fails, you can tell whether it failed at transport, service identity, or business policy. That is the part I care about, because it turns security from vibes into something you can actually debug.

Subscribe now

I do not mean which tool name showed up in the trace or which server handled the POST. I mean who approved the deployment, closed the ticket, queried the customer record, or changed the access policy.

If the honest answer is “Bob” or, worse, the name of one long-lived bearer token sitting behind a shared server, then the architecture is unfinished. You did not build user-aware automation. You built a service account funnel with better branding.

That sounds harsh, but the current IBM Bob guidance is blunt enough to justify it. The IBM Bob security guidelines say to use delegated access when needed, use time-limited tokens, monitor and audit all actions, and, for shared MCP servers, make sure actions are attributable to specific users or sessions. That is not a style preference. It is the difference between an automatable system and a future incident report full of shrugs.

I care about this part of enterprise MCP design because it hides inside something that looks efficient. A shared remote server is easy to centralize, easy to update, and easy to point every Bob user at through .bob/mcp.json. The Bob MCP docs explicitly support project-level .bob/mcp.json files that teams can share through version control, and remote MCP configuration supports custom HTTP headers such as Authorization. The convenience is real. So is the way teams quietly reinvent the service account model and call it agent infrastructure.

The cheap version is one credential for everyone

The bad design usually starts out looking responsible, which is part of why it survives design review.

There is one remote MCP server for a shared internal system such as deployments, tickets, or change requests. Bob talks to it over HTTP. The team does not want every user setting up their own credentials yet, so someone provisions one token for the server and distributes the config.

It often looks like this:

{
  "mcpServers": {
    "deploy-control": {
      "url": "https://mcp.internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SHARED_DEPLOY_MCP_TOKEN}"
      }
    }
  }
}

Using an environment variable instead of hardcoding the token is still better operational hygiene. It does not fix the architecture if everyone ends up using the same credential. Where the secret string lives is not the real issue. The issue is that the server sees one actor for every request.

That produces audit records like this:

{
  "timestamp": "2026-05-23T10:14:09Z",
  "tool": "approve_deployment",
  "target": "checkout-service",
  "actor": "shared-bob-mcp",
  "result": "approved"
}

This record answers almost nothing that matters after the fact. Which engineer asked for the action? Which Bob session was it tied to? Was the caller allowed to approve production or only staging? Was the token minted for five minutes or copied into a wiki six months ago? You can keep piling logs around this, but the identity hole stays put.

That is why I do not like hearing “we have auditing” when the audit trail only knows the server-side credential. You do not have auditing yet. You have a timestamped receipt from a shared robot account.

What attribution looks like in practice

For a shared MCP server, the minimum bar is simple even if the implementation takes work: the request that reaches the server must still be tied to a human user or a narrowly scoped session.

The MCP authorization spec frames HTTP-based authorization as the client accessing a protected MCP server on behalf of a resource owner. It also recommends short-lived access tokens. That lines up neatly with Bob’s own security guidance: delegated access, time-limited credentials, and auditable actions.

In practice, I want the remote server, or a gateway directly in front of it, to validate a user-bound token and emit a structured audit event that survives the entire request path. At minimum, keep these fields:

• The human identity: sub, and, if your IdP provides it safely, a stable username or email

• The issuing authority and target: iss, aud, and the scopes or roles that justified the action

• Token lifetime and replay clues: exp, and a token or request identifier such as jti when available

• MCP request correlation: session identifier, request identifier, tool name, and target system

• Decision outcome: allowed, denied, or failed, with the policy reason when possible

The useful shape is closer to this:

{
  "timestamp": "2026-05-23T10:14:09Z",
  "actor": {
    "sub": "00u7x9b3...",
    "email": "sam@example.com"
  },
  "client": {
    "product": "IBM Bob",
    "mcpSessionId": "1f3a4b5c-6d7e-8f9a-0b1c-2d3e4f5a6b7c",
    "tool": "approve_deployment"
  },
  "policy": {
    "scopes": ["deploy:approve"],
    "delegated": true,
    "tokenExpiresAt": "2026-05-23T10:19:09Z"
  },
  "target": "checkout-service",
  "result": "approved"
}

Now the record can answer a serious question. Sam approved the deployment. The call came through a specific Bob session. The server saw a delegated token with the deploy:approve scope, and that token expired five minutes later. That is the beginning of accountability, which is a lot more useful than another dashboard that can only tell you a tool fired.

Notice what I am not asking for here. I am not asking you to store full prompt transcripts as the only audit system, or to bury the truth in a blob store full of raw HTTP dumps. Good auditability is not maximal logging. It is the ability to answer who, what, when, which permission, and which target without needing a forensic hobby.

Useful MCP headers are not the same thing as identity

There is a subtle trap here because MCP over HTTP is getting better observability support. The current MCP transport spec defines Streamable HTTP as the standard remote transport, and SEP-2243 standardizes request headers such as Mcp-Method, Mcp-Name, and Mcp-Session-Id so proxies, gateways, and observability tools can reason about MCP traffic without tearing apart the JSON body.

I like that change. It helps routing, rate limiting, correlation, and troubleshooting. It does not solve attribution by itself.

Mcp-Session-Id tells you that several requests belong to the same logical MCP session. It does not tell you which human sat behind that session. Mcp-Method and Mcp-Name tell you what kind of MCP operation happened. They do not tell you whether the caller was allowed to do it.

So keep the headers. They are useful. Just do not confuse request metadata with identity. A beautiful trace that still collapses every actor into one shared token is just a more expensive blind spot.

Prompt warnings are not policy

There is another shortcut teams try after they notice the identity problem. They keep the shared credential and add instructions around it:

• Only use this tool for the current user

• Ask for confirmation before production actions

• Never approve your own deployment

Those rules are fine as defense in depth. They are not a security boundary.

The server has to enforce the policy because the server is where the blast radius lives. If the remote MCP tool can approve a deployment, create a change request, or read customer data, the authorization decision needs to happen with server-side knowledge of the user, the session, the scopes, and the target resource. Prompt text can remind the model. It cannot carry your authorization model.

This is also why I prefer denial events in the audit log. A server that records who was refused, for which action, and why, is much easier to trust than one that only logs successful calls and leaves failures to chat history.

Shared remote infrastructure is not always the right answer

Bob’s own transport guidance is refreshingly practical here. The Bob transport docs describe STDIO as lower latency, simpler, and “inherently more secure with no network exposure,” and they recommend it for security-sensitive local operations. The MCP transport spec also says clients should support stdio whenever possible.

That matters because not every useful tool needs to be a shared service.

If the capability is mostly local to the developer machine, such as reading a repository, running a formatter, checking a build, or querying a local scratch database, a shared remote MCP server may add centralization without adding enough value. You take on network exposure, shared-service hardening, multi-user authorization, and attribution requirements just to avoid installing a local tool.

I would keep these workflows local by default:

• Repository and filesystem helpers

• Local build, test, and formatting tools

• Developer-specific scratch data or local diagnostics

• Anything where the useful authority already comes from the workstation user

I would consider a shared remote server when the target system is already centralized and the controls are worth centralizing too:

• Deployment approvals

• Ticketing or change-management workflows

• Internal data systems with real access policy

• Shared operational tooling that needs consistent server-side enforcement

That is the actual trade-off. Shared MCP infrastructure does not become “more enterprise” just because it is remote. It earns that label when the central server adds real policy, real auditability, and real operational control.

A short checklist before you roll this out

If you are about to stand up a shared MCP server for Bob, I would want these answers before the first broad rollout:

1. Can the server identify the human user behind each action, not just the Bob client or a shared token?

2. Are credentials delegated and time-limited, or did you quietly create a durable service account path?

3. Does the audit event capture actor, session, tool, target, permission, and outcome in structured form?

4. Are authorization decisions enforced server-side for every sensitive tool call?

5. Do denied actions get logged with enough context to review policy behavior later?

6. Did you keep local-only workflows on STDIO instead of centralizing them out of habit?

7. If someone asks “who approved this at 10:14 UTC on May 23, 2026,” can you answer without opening a chat transcript?

If the answer to the last question is no, stop there. The server is not ready yet.

Conclusion

The interesting failure mode in shared MCP is not tool power. That part is obvious. The failure shows up when the first working version looks good enough while quietly erasing the human actor from the record.

IBM Bob’s current security guidance does us a favor by saying the quiet part out loud: use delegated access, use time-limited tokens, audit actions, and make shared MCP activity attributable to specific users or sessions. Once you accept that, the architecture gets simpler. A shared MCP server is either identity-aware infrastructure, or it is a service account wearing an agent costume.

Subscribe now

This tutorial fixes that. We build ForgeAssist: a Quarkus service that classifies each incoming prompt, routes it to the cheapest Ollama model that can plausibly handle it, and logs the routing decision without blocking the HTTP response. The sample stays small: one enum, one AI service, one router, one observer, and one REST endpoint.

What you will be able to do

By the end you can:

1. Configure multiple named Ollama model instances in one Quarkus application.

2. Declare a structured-output AiService that returns a Java enum from an LLM.

3. Inject named ChatModel beans programmatically and pick between them at runtime.

4. Fire a CDI event to make routing decisions observable without polluting the response path.

5. Write a @QuarkusTest that asserts routing behavior instead of answer quality.

What we build

ForgeAssist exposes POST /assist with a plain-text question body. Every request flows through a classifier on the fast lane (qwen2.5:0.5b), then dispatches to either the fast lane or the power lane (llama3.2) based on a Complexity enum. A CDI observer logs the decision asynchronously.

The request lands on the REST resource, the router asks the classifier on the fast model, then it picks a lane, returns the answer, and fires an async routing event on the way out.

Named model — a second configuration block in application.properties, distinguished by a string identifier.

AiService — a Java interface Quarkus implements at build time by calling an LLM.

Structured output — the return type drives schema-aware parsing; you do not hand-parse enum strings.

@ModelName — a LangChain4j CDI qualifier that selects which named model bean to inject.

CDI event — decoupled notification; fire() is synchronous, fireAsync() is asynchronous.

What you need

You have written @QuarkusTest before and know what a LangChain4j AI service interface looks like.

• JDK 25 (java -version)

• Maven 3.9+ (mvn -version)

• Ollama installed and running (ollama serve)

• Models pulled: ollama pull qwen2.5:0.5b and ollama pull llama3.2

• Quarkus CLI installed (quarkus --version) — optional; Maven wrapper works fine

• About two ☕️☕️

Project setup

quarkus create app dev.forgeassist:forgeassist-routing \
  --package-name=dev.forgeassist \
  --extension='quarkus-rest,quarkus-langchain4j-ollama,quarkus-arc' \
  --java=25 \
  --no-code
cd forgeassist-routing

When you add the Ollama extension, the generator also adds quarkus-langchain4j-bom to dependencyManagement.

Add test dependencies to pom.xml:

 <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-junit-mockito</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>

Run a quick sanity check before business logic:

quarkus dev

Quarkus should start and Dev UI should be at http://localhost:8080/q/dev. No model call happens yet. We are only confirming the extension graph wires up.

Configure two Ollama models

This block is the spine of the tutorial. Misread it and you will debug phantom CDI issues for an hour.

src/main/resources/application.properties:

quarkus.application.name=forgeassist-routing

# Explicit host Ollama — Dev Services off for teaching clarity
quarkus.langchain4j.ollama.devservices.enabled=false
quarkus.langchain4j.ollama.base-url=http://localhost:11434

# Power lane (default unnamed bean)
quarkus.langchain4j.ollama.chat-model.model-id=llama3.2
quarkus.langchain4j.ollama.chat-model.temperature=0.7
quarkus.langchain4j.timeout=60s

# Fast lane (named "fast")
quarkus.langchain4j.fast.chat-model.provider=ollama
quarkus.langchain4j.ollama.fast.base-url=${quarkus.langchain4j.ollama.base-url}
quarkus.langchain4j.ollama.fast.chat-model.model-id=qwen2.5:0.5b
quarkus.langchain4j.ollama.fast.chat-model.temperature=0.0
quarkus.langchain4j.ollama.fast.timeout=15s

Named model config has two parts: quarkus.langchain4j.<name>.* at the provider level and quarkus.langchain4j.ollama.<name>.* for Ollama-specific settings. Leave <name> out and you configure the default bean. Add fast and CDI gets a second bean exposed through @ModelName("fast"). The quarkus.langchain4j.fast.chat-model.provider=ollama line matters; skip it and the named lane does not resolve cleanly.

Temperature 0.0 on the fast model is deliberate. The classifier must be deterministic; a stochastic classifier that occasionally says SIMPLE when it means COMPLEX defeats the purpose.

Dev Services is off on purpose. Quarkus LangChain4j can auto-start Ollama and pull models in dev mode, which is convenient locally and bad for a tutorial that is supposed to show the real endpoint and the real failure path.

One quick sanity check before you move on: if Dev Services is off and Ollama is unreachable, or qwen2.5:0.5b is missing, what does the first AI request do? Make the prediction, then try it. That is the failure you want to recognize later when the logs are less friendly.

The complexity enum

I use a binary enum rather than SIMPLE / MODERATE / COMPLEX. More tiers need more calibration and prompt tuning, and they only help when you have three meaningfully different models to route to. Start with two lanes; extend later if the economics justify it.

src/main/java/dev/forgeassist/Complexity.java:

package dev.forgeassist;

public enum Complexity {

    /**
     * Factual lookups, single-step how-tos, definitional questions.
     * Examples: "What does --dry-run do?", "List the ForgeCI environment
     * variables."
     */
    SIMPLE,

    /**
     * Multi-step reasoning, debugging with context, architectural trade-offs,
     * ambiguous or environment-specific problems.
     * Examples: "Why does my pipeline OOM only on cached arm64 builds?"
     */
    COMPLEX
}

The classifier AiService

Quarkus LangChain4j can return Java types from an AiService method, not just String. With an enum return type, the framework injects the enum schema into the prompt and deserializes the response, so there is no hand-rolled parsing code. The trade-off is still real: a confused model can return something unparseable. For a two-lane classifier with a small context window, I think that risk is low enough.

src/main/java/dev/forgeassist/PromptClassifier.java:

package dev.forgeassist;

import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import io.quarkiverse.langchain4j.RegisterAiService;

@RegisterAiService(modelName = "fast")
public interface PromptClassifier {

    @SystemMessage("""
            You are a prompt complexity classifier for ForgeCI, a CI/CD platform.
            Classify the user's question into exactly one of: SIMPLE, COMPLEX.

            SIMPLE: factual lookups, flag definitions, single-step how-tos,
                    questions answerable from documentation alone.

            COMPLEX: debugging with environment context, multi-step reasoning,
                     architectural trade-offs, questions that require inference
                     beyond what documentation states.

            Respond with ONLY the enum value. No punctuation. No explanation.
            """)
    Complexity classify(@UserMessage String prompt);
}

modelName = "fast" on the classifier matters. Classification is already the cheap job. Using the power model to decide whether to use the power model is circular and a little silly.

The system prompt uses ForgeCI-flavored examples on purpose. Generic “SIMPLE: short questions” prompts look tidy and perform worse once you hit the awkward edge cases.

At the wire, a simple flag question looks like this:

{
  "model": "qwen2.5:0.5b",
  "messages": [
    {
      "role": "system",
      "content": "You are a prompt complexity classifier..."
    },
    {
      "role": "user",
      "content": "What does the --no-cache flag do in forge build?"
    }
  ]
}

Response: SIMPLE

Routing decision record

We define the record first so the fireAsync line later is moving a real type, not a mystery blob.

src/main/java/dev/forgeassist/RoutingDecision.java:

package dev.forgeassist;

import java.time.Instant;

/**
 * Immutable record of a single model routing decision.
 * Fired as a CDI event; consumed by observers for logging and metrics.
 */
public record RoutingDecision(
        String prompt,
        Complexity complexity,
        String selectedModel,
        long classificationMillis,
        Instant timestamp) {

    public RoutingDecision(
            String prompt, Complexity complexity, String selectedModel, long classificationMillis) {
        this(prompt, complexity, selectedModel, classificationMillis, Instant.now());
    }
}

Records give you immutability for free. The CDI event keeps the routing decision decoupled from whoever wants to watch it, so the router does not care whether you only log today or add metrics tomorrow.

The routing event observer

src/main/java/dev/forgeassist/RoutingEventObserver.java:

package dev.forgeassist;

import org.jboss.logging.Logger;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.ObservesAsync;

@ApplicationScoped
public class RoutingEventObserver {

    private static final Logger LOG = Logger.getLogger(RoutingEventObserver.class);

    public void onRoutingDecision(@ObservesAsync RoutingDecision decision) {
        LOG.infof(
                "[ROUTING] complexity=%s model=%s classificationMs=%d prompt=\"%s\"",
                decision.complexity(),
                decision.selectedModel(),
                decision.classificationMillis(),
                truncate(decision.prompt(), 80));
    }

    private static String truncate(String s, int max) {
        return s.length() <= max ? s : s.substring(0, max) + "…";
    }
}

That separation is the whole point: the observer does not know about the router, the router does not know about the observer, and adding a Micrometer counter later does not require another pass through ModelRouter.

The model router

This is the center of the sample, so we build it in layers.

Shell and injections

@ModelName is a Quarkus LangChain4j qualifier — not @Named. Injection without a qualifier resolves to the default (unnamed) bean, which is the power model here.

package dev.forgeassist;

import dev.langchain4j.model.chat.ChatModel;
import io.quarkiverse.langchain4j.ModelName;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Event;
import jakarta.inject.Inject;

@ApplicationScoped
public class ModelRouter {

    private final PromptClassifier classifier;
    private final ChatModel fastModel;
    private final ChatModel powerModel;
    private final Event<RoutingDecision> routingEvents;

    @Inject
    public ModelRouter(
            PromptClassifier classifier,
            @ModelName("fast") ChatModel fastModel,
            ChatModel powerModel,
            Event<RoutingDecision> routingEvents) {
        this.classifier = classifier;
        this.fastModel = fastModel;
        this.powerModel = powerModel;
        this.routingEvents = routingEvents;
    }

    // route() follows below
}

Classification and timing

At this point in execution, only the fast model has run (via the classifier AiService). The power model has done nothing.

public String route(String userPrompt) {
        long start = System.currentTimeMillis();
        Complexity complexity = classifier.classify(userPrompt);
        long classificationMillis = System.currentTimeMillis() - start;

        // dispatch continues below
    }

Dispatch and event

Once the target model changes at runtime, drop down to the raw LangChain4j ChatModel.chat(ChatRequest) API instead of wrapping another AiService around it.

        ChatModel selected = switch (complexity) {
            case SIMPLE -> fastModel;
            case COMPLEX -> powerModel;
        };

        ChatRequest request = ChatRequest.builder().messages(UserMessage.from(userPrompt)).build();

        String response = selected.chat(request).aiMessage().text();

        routingEvents.fireAsync(
                new RoutingDecision(
                        userPrompt,
                        complexity,
                        complexity == Complexity.SIMPLE ? "qwen2.5:0.5b" : "llama3.2",
                        classificationMillis));

        return response;
    }

Complete ModelRouter.java with imports:

package dev.forgeassist;

import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import io.quarkiverse.langchain4j.ModelName;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Event;
import jakarta.inject.Inject;

@ApplicationScoped
public class ModelRouter {

    private final PromptClassifier classifier;
    private final ChatModel fastModel;
    private final ChatModel powerModel;
    private final Event<RoutingDecision> routingEvents;

    @Inject
    public ModelRouter(
            PromptClassifier classifier,
            @ModelName("fast") ChatModel fastModel,
            ChatModel powerModel,
            Event<RoutingDecision> routingEvents) {
        this.classifier = classifier;
        this.fastModel = fastModel;
        this.powerModel = powerModel;
        this.routingEvents = routingEvents;
    }

    public String route(String userPrompt) {
        long start = System.currentTimeMillis();
        Complexity complexity = classifier.classify(userPrompt);
        long classificationMillis = System.currentTimeMillis() - start;

        ChatModel selected = switch (complexity) {
            case SIMPLE -> fastModel;
            case COMPLEX -> powerModel;
        };

        ChatRequest request = ChatRequest.builder().messages(UserMessage.from(userPrompt)).build();

        String response = selected.chat(request).aiMessage().text();

        routingEvents.fireAsync(
                new RoutingDecision(
                        userPrompt,
                        complexity,
                        complexity == Complexity.SIMPLE ? "qwen2.5:0.5b" : "llama3.2",
                        classificationMillis));

        return response;
    }
}

fireAsync keeps the HTTP response path clean: the caller gets the answer immediately and the observer runs asynchronously. That makes sense for diagnostics and lightweight counters. It is a bad fit for side effects you cannot afford to lose unless you also have a plan for seeing and recovering from async observer failures.

REST endpoint

src/main/java/dev/forgeassist/ForgeAssistResource.java:

package dev.forgeassist;

import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/assist")
public class ForgeAssistResource {

    private final ModelRouter router;

    @Inject
    public ForgeAssistResource(ModelRouter router) {
        this.router = router;
    }

    @POST
    @Consumes(MediaType.TEXT_PLAIN)
    @Produces(MediaType.TEXT_PLAIN)
    public String ask(String question) {
        return router.route(question);
    }
}

Prove it (live Ollama)

With quarkus dev running and Ollama on http://localhost:11434

# Simple prompt — expect fast lane when classification cooperates
curl -s -X POST http://localhost:8080/assist \
  -H "Content-Type: text/plain" \
  -d "What does the --no-cache flag do in forge build?"

# Complex prompt — expect power lane
curl -s -X POST http://localhost:8080/assist \
  -H "Content-Type: text/plain" \
  -d "My ForgeCI pipeline passes locally but fails on cached arm64 runners with an OOM error only when layer cache is warm. What should I investigate first?"

You want a log line like this:

[ROUTING] complexity=SIMPLE model=qwen2.5:0.5b classificationMs=... prompt="What does the --no-cache flag do in forge build?"

The exact classificationMs value moves around, and because the log comes from an async observer it may show up just after the HTTP response. The signal that matters is complexity + model, not exact timings or identical answer text. Small classifiers will mislabel some edge cases. That is normal, and the production section below is where the trade-off starts to matter.

Production risks

Once this works in dev, the pleasant part is over. These are the problems that show up in a real team.

Misclassification is more expensive than over-routing. The dangerous failure mode is a debugging-heavy prompt stamped SIMPLE and sent to the cheap lane, which then answers confidently and badly. When in doubt, route up, not down.

Logging the raw prompt is a demo convenience. Prompt text can contain tokens, stack traces, customer data, or internal hostnames. Production systems often hash, redact, or sample this field.

Routing adds a second model hop. Latency is now classification plus answer. Keep the classifier on a fast local model, but set explicit timeout boundaries on both lanes and decide what the API does when classification times out.

fireAsync() buys latency at the cost of failure visibility. Observer failures are harder to spot than synchronous method failures. If the event becomes business-critical, move that concern to a durable mechanism instead of pretending CDI async delivery is a queue.

Dev Services is a local convenience, not production topology. The app talks to a known Ollama endpoint, models must already exist there, and health checks should reflect that dependency honestly.

Tests

LLM output moves around, so tests that assert answer content age badly. The deterministic part, and the part worth locking down first, is the routing behavior: did the classifier run, and did the router pick the expected lane? The HTTP layer is deterministic too: did POST /assist delegate to the router?

Use @InjectMock with Mockito. ModelRouterTest replaces the classifier and both ChatModel beans so the router never calls Ollama. ForgeAssistResourceTest replaces the router so the HTTP test stays thin and boring, which is exactly what you want from a resource test.

I would not make the first tutorial test about asynchronous CDI delivery. Readers need to trust the lane decision before they care about observer scheduling.

src/test/java/dev/forgeassist/ModelRouterTest.java:

package dev.forgeassist;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.clearInvocations;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import io.quarkiverse.langchain4j.ModelName;
import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;
import jakarta.inject.Inject;

@QuarkusTest
class ModelRouterTest {

    @Inject
    ModelRouter router;

    @InjectMock
    PromptClassifier classifier;

    @InjectMock
    @ModelName("fast")
    ChatModel fastModel;

    @InjectMock
    ChatModel powerModel;

    @BeforeEach
    void stubModels() {
        when(fastModel.chat(any(ChatRequest.class))).thenReturn(response("fast-lane"));
        when(powerModel.chat(any(ChatRequest.class))).thenReturn(response("power-lane"));
        clearInvocations(fastModel, powerModel);
    }

    @Test
    void simplePromptUsesFastLane() {
        String prompt = "What does the --no-cache flag do in forge build?";
        when(classifier.classify(prompt)).thenReturn(Complexity.SIMPLE);
        clearInvocations(classifier);

        String answer = router.route(prompt);

        assertEquals("fast-lane", answer);
        verify(classifier).classify(prompt);
        verify(fastModel).chat(any(ChatRequest.class));
        verifyNoInteractions(powerModel);
    }

    @Test
    void complexPromptUsesPowerLane() {
        String prompt = "Why does my pipeline OOM only on cached arm64 builds?";
        when(classifier.classify(prompt)).thenReturn(Complexity.COMPLEX);
        clearInvocations(classifier);

        String answer = router.route(prompt);

        assertEquals("power-lane", answer);
        verify(classifier).classify(prompt);
        verify(powerModel).chat(any(ChatRequest.class));
        verifyNoInteractions(fastModel);
    }

    private static ChatResponse response(String text) {
        return ChatResponse.builder().aiMessage(AiMessage.from(text)).build();
    }
}

src/test/java/dev/forgeassist/ForgeAssistResourceTest.java:

package dev.forgeassist;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.Test;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class ForgeAssistResourceTest {

    @InjectMock
    ModelRouter router;

    @Test
    void assistEndpointDelegatesToRouter() {
        when(router.route("What does --no-cache do?")).thenReturn("fast-lane");

        given()
                .contentType("text/plain")
                .body("What does --no-cache do?")
                .when()
                .post("/assist")
                .then()
                .statusCode(200)
                .body(is("fast-lane"));
    }
}

Run tests (no running Ollama required for assertions):

./mvnw test

Expect BUILD SUCCESS and 3 tests.

Extension exercises

If you still feel adventurous. Some homework ideas:

Three-tier routing — Add MODERATE to the enum, introduce a third Ollama model (for example qwen2.5:3b), and update the system prompt and switch expression. How does the classifier prompt need to change to distinguish MODERATE from both SIMPLE and COMPLEX?

Confidence-aware routing — Return a record ClassificationResult(Complexity complexity, int confidencePercent) instead of a bare enum. Route SIMPLE classifications with confidencePercent < 70 to the power model as a fallback.

Micrometer metrics observer — Add a second CDI observer that increments a Counter per complexity tier and expose the metrics endpoint.

Dev Services contrast — If you have Docker available, try Quarkus Dev Services for Ollama and compare startup experience with the explicit host configuration used here.

Close the loop

ForgeAssist classifies each prompt on a cheap local model, routes SIMPLE questions to qwen2.5:0.5b, routes COMPLEX ones to llama3.2, and logs the decision without blocking the caller. That fixes the opening problem: trivial and heavy questions no longer burn the same expensive default.

Subscribe now

I like those posts more than most AI productivity advice because they point to something real. A coding agent gets much better once it stops guessing how your project works. The model name, the filename, and the exact rule count are the forgettable parts.

That sounds obvious until you watch one work without any local guidance.

By default, a coding model knows a lot about syntax and just enough about software engineering to be dangerous in the same cheerful way a junior engineer with root access would be dangerous. It can produce code. It can explain code. It can also decide that your tiny bug fix is a great time to “clean up” three unrelated files, assume a requirement you never stated, and speak about its own uncertainty with the confidence of a generated release note.

This breaks for a simpler reason: missing local context. Your agent does not know what “done” means in this repo, which changes are out of bounds, which conventions are non-negotiable, or when it should stop and ask instead of making its own decisions.

That is what the instruction file is for.

Call it AGENTS.md, CLAUDE.md, repo rules, or a small pile of working notes. The name matters a lot less than the job. You are giving the agent an operating manual for this codebase so it can stop guessing its way through every task.

The four rules that pull the most weight

I do not think the magic number is 21. Four rules do most of the real work.

1. Ask instead of assume.
   If requirements are unclear, the agent should surface the ambiguity instead of silently choosing a path. Wrong confidence is more expensive than one extra question.

2. Start with the smallest working change.
   Agents love broad cleanup because it gives them more surface area to look helpful on. That rarely means the task is going well, so I would strongly prefer small, reversible diffs.

3. Do not touch unrelated code.
   Most teams do not mind extra polish in theory. They mind it very much when a review gets slow because the assistant “also improved” files nobody asked about.

4. Flag uncertainty before acting.
   A decent agent should know the difference between “I found the bug” and “I have a plausible theory.” The second state is fine. Hiding it is not.

Those four rules are bigger than any one model. They are the difference between an assistant and an intern who keeps rearranging your desk while answering the wrong question.

What the file is really doing

I think of a good agent instruction file as a boundary-setting document. Its job is to reduce four common failure modes.

Scope drift
The agent starts on a bug fix, notices a naming inconsistency, then notices an outdated helper, then notices a nearby refactor opportunity, and suddenly your one-line change reaches much farther than it should. A rules file tells it what “stay in scope” actually means here.

Bad defaults
Every model comes with habits. Some over-explain. Some rush to code. Some make confident assumptions to keep the turn moving. Some will happily take a destructive action if you did not explicitly say “ask first.” If you do not set the defaults, the model will.

Decision loss
Longer sessions get weird because the model forgets which trade-offs were already settled. You said no refactor. Later it proposes one. You said keep the old API. Later it “improves” it. This is where a tiny memory stack helps more than another clever prompt.

Polite nonsense
This is my least favorite failure mode. The model has partial evidence, but it keeps writing as if it has a proof. A good working agreement makes uncertainty a first-class output, not an embarrassment to hide.

That is why the screenshot-style rule sets often split into three buckets: defaults, behavior, and memory. I think that split is sane, and I would keep it.

What to put in a generalized AGENTS.md

If I were writing one file meant to survive changing models, I would keep these sections.

Defaults

This is where you define the repo’s normal operating mode.

• Keep changes narrow and task-focused

• Prefer the simplest fix that works

• Match existing style unless the task is explicitly a redesign

• Ask before destructive actions

• Explain what changed in plain language

• Do not invent requirements, APIs, or test results

Defaults matter because they catch the moments when the prompt is too short to say all of that again.

Behavior

This section tells the agent how to work, not just what to produce.

• Restate the task in concrete terms before making major changes

• Confirm assumptions when they change behavior or risk

• Show diffs or summarize edits clearly

• Stop if the new plan expands beyond the original ask

• Keep the user in the loop before irreversible steps

This is about visibility, not ceremony. Most people can tolerate an agent being wrong for a turn. They get annoyed when it is wrong and quiet about it.

Memory

This is the part many teams skip, and for me it is where a lot of the quality gain comes from.

Your agent does not just need rules. It needs a place to pin decisions that should survive the next twenty turns.

• DECISIONS.md for active trade-offs and chosen direction

• KNOWN_ISSUES.md or ERRORS.md for failures already observed

• SESSION.md for where work stopped and what should happen next

• Permanent facts for “never rename this endpoint” or “this file mirrors an external contract”

You do not need all of these in every repo. You just need enough memory to stop paying for the same rediscovery loop over and over.

Escalation

This is where the agent learns when to slow down.

• Ask when two paths have different product consequences

• Ask when requirements conflict with existing constraints

• Ask before deleting, renaming, or migrating broad surfaces

• Say when confidence is low

• Prefer a question over a fake conclusion

If you only add one behavioral rule, make it this kind of rule. A coding agent that escalates well is dramatically easier to trust.

A template I would actually use

Here is a generalized version I would be comfortable dropping into a project root today:

# AGENTS.md

## Goal

Help with this repository by making the smallest correct change that solves the
requested task.

## Defaults

- Stay within the requested scope
- Prefer the simplest working fix over broad rewrites
- Match existing code style and project structure
- Do not edit unrelated files just because they could be improved
- Ask before destructive or irreversible actions
- Do not claim tests passed unless you actually ran them
- Do not invent requirements, endpoints, configs, or results

## Working style

- Restate the task briefly before major edits
- Surface assumptions when they affect behavior
- Show what changed and why
- Keep diffs easy to review
- Stop and ask if the task expands into a refactor or redesign

## Uncertainty

- Flag low-confidence conclusions explicitly
- Prefer "I need to verify X" over guessing
- When there are multiple reasonable paths, present the trade-off

## Memory

- Read `DECISIONS.md` before making architectural changes
- Read `KNOWN_ISSUES.md` before debugging recurring failures
- Update `SESSION.md` with current status when work stops mid-task
- Treat pinned project facts as constraints, not suggestions

## Guardrails

- Never hide uncertainty behind polished wording
- Never change public contracts without calling it out
- Never mix requested work with opportunistic cleanup unless asked

That file is boring, which is exactly what you want here. The best rule file in a repo is usually the one that prevents avoidable messes, not the one that sounds smartest on social media.

This is really about interface design

What I like about these rule-file experiments is that they quietly move the conversation away from model hype and back toward engineering.

Better outcomes do not come only from upgrading the model. You also get them by improving the interface between the model and the project. A local instruction file, a short decision log, and a few explicit escalation rules can do more for day-to-day quality than another round of “which coding assistant is winning this week.”

That is also why I would generalize the idea well beyond Claude.

AGENTS.md is a better mental model than CLAUDE.md if you want something durable. Models change. Product names change. The failure modes stay stubbornly the same. Every coding agent needs help with scope, defaults, uncertainty, and memory. If your team solves those once in versioned text, you do not have to solve them again from scratch every time a new assistant shows up with a shinier demo.

The real win

For me, the win is simpler than “21 rules made the model smarter.” The model stopped having to guess what kind of teammate it was supposed to be, which is a much more useful improvement anyway.

If you use coding agents seriously, give them a local operating manual. Keep it short, keep it opinionated, and keep it honest about boundaries. Then add just enough memory that the same wrong turn does not have to be rediscovered every Tuesday.

For me, that is just good interface design for a very fast, very eager collaborator.

Subscribe now

I do not like that chart because it prices the easiest part of software and quietly ignores the rest.

Enterprise teams do not buy keystrokes. They buy a change that made it through product scoping, design, implementation, review, testing, security checks, release plumbing, and production. If you compare tokens to one developer writing code, you are comparing a narrow input cost to a full delivery salary and acting surprised when the machine looks cheap.

As of May 21, 2026, OpenAI lists GPT-5.4 at $2.50 per million input tokens and $15 per million output tokens. Anthropic lists Claude Sonnet 4 at $3 per million input tokens and $15 per million output tokens. Those are real numbers, and they are low enough that I am not going to pretend otherwise. AI-assisted coding is cheap on raw tokens.

The problem is that raw tokens are rarely where enterprise software wins or loses money.

The AI side is a spend band, not a number

The first thing I would stop doing is talking about “the AI cost” as if it were one number.

Anthropic’s Claude Code cost guide says the average across enterprise deployments is around $13 per developer per active day, roughly $150 to $250 per developer per month, and still below $30 per active day for 90% of users. That is a useful center of gravity. It tells you what ordinary enterprise usage looks like when people are not trying to become folklore on Hacker News.

The public ceiling is a different story. I pulled the live HN Tokenmaxxing feed on May 21, 2026 and recomputed the trailing seven-day window. That sample showed 28 active users, about $54,739.46 in total spend, a median active-user cost of $98.25 per day, an average of $279.28 per day, and top users burning $4,575 to $9,381 per week each.

Those numbers are not contradictory. They describe different populations.

Anthropic gives you a managed enterprise baseline. Tokenmaxxing gives you a public power-user ceiling full of people who use long context, multiple agents, and enough model calls to make finance curious. It is useful precisely because it is a bit unhinged. It shows the upper edge of behavior once teams stop treating AI like autocomplete and start treating it like a second operating mode.

It also moves around. Ten days earlier, the same public sample produced a materially higher median. That is another reason I would not build a strategy deck around one leaderboard screenshot. The AI side of the curve is a spend band, not a point estimate.

The denominator is the whole delivery chain

The usual chart also cheats on the human side.

To make the comparison less fuzzy, I modeled one modest enterprise feature slice using BLS median wages for the roles that usually touch real delivery work, then converted those wages to loaded employer cost using the BLS private-industry compensation release published March 20, 2026. That multiplier comes out to about 1.43x wages.

The feature slice is intentionally ordinary: six hours of product or project work, six hours of design, 24 hours of implementation, eight hours of QA, three hours of security review, three hours of release or ops work, and four hours of management or review coordination. Nothing heroic. Nothing transformation-program sized. Just a change that still has to survive the whole system.

That model lands at about $4,496 in loaded labor cost.

Implementation is only 48.7% of the bill. Planning, design, QA, security, release, and coordination are the other 51.3%.

That is the part the token-versus-salary chart keeps deleting. Even if code generation gets dramatically cheaper, more than half the lifecycle bill is still waiting for you after the model says it is done. Software is full of second-order costs. The model only touches some of them.

Break-even is a review curve

If I had to keep one chart and throw away the rest, I would keep the review curve.

The useful x-axis is not tokens. It is human review and repair hours required after the AI run.

For the same coding-shaped unit of work, the comparison is simple:

• Human-only cost = loaded developer time

• AI-led cost = model spend + human review and repair time

Using the feature model above, a loaded developer day is about $730, or about $91.25 per hour. Once you combine that with the current spend bands from Anthropic and Tokenmaxxing, you get this:

At Anthropic’s enterprise average of $13 per active day, AI still beats a human day on raw cost until the human spends almost 7.9 hours reviewing and repairing it. At Anthropic’s 90th-percentile ceiling of $30 per active day, the crossover is still about 7.7 hours. At the current Tokenmaxxing median of $98.25 per day, the crossover drops to about 6.9 hours. At the current Tokenmaxxing average of $279.28 per day, the crossover drops to about 4.9 hours. At an intentionally ugly frontier day of $550, you only get about 2.0 hours of human cleanup before AI loses the raw coding-day comparison.

That is the real question for engineering leaders:

How many hours of senior-human verification, correction, and coordination does this class of task usually need after the model claims success?

Once you ask it that way, the task sorting gets a lot less mystical.

Where AI is actually strong

I think there are three broad zones.

AI-led work is the place where the output is cheap to check and the blast radius is tightly bounded. Repo search, code explanation, narrow transforms, test scaffolding with a known oracle, documentation drafts, log triage, and boring CRUD inside one known framework all live here. These are the tasks where the Anthropic-style $13 to $30 active day economics are genuinely compelling because the review burden stays low.

Hybrid work is where most serious teams will make their money. Bounded feature work inside one service, behavior-preserving refactors, migration scripts with rollback paths, build repairs with a fast verification loop, and bug fixes anchored by deterministic tests fit here. AI can do a lot of the drafting and search. A human still has to own the change shape, the acceptance criteria, and the final judgment. In this zone, pure human work wastes cheap drafting power and fully agentic work creates expensive recovery loops.

Human-led work returns the moment review, coordination, or ambiguity starts dominating the bill. Product discovery, architecture under uncertainty, security and compliance changes, cross-team design, rollout strategy, incident response, and distributed-systems behavior under failure all live here. The model may still help, often a lot, but it is helping around the edges of the expensive thing. It is not replacing the expensive thing.

That is why I do not find “AI replaces a developer” especially useful as a framing for enterprise software. At best, AI replaces or compresses some implementation-shaped slices inside a much larger chain of work.

The rest of the evidence points the same way

Google’s 2024 DORA report summary is one of the more interesting reports because it refuses to tell a neat success story. More AI adoption was associated with better documentation quality, better code quality, and faster code review. It was also associated with lower delivery throughput and lower delivery stability. DORA’s later write-up on balancing AI tensions in the SDLC says the quiet part out loud: teams often spend the saved drafting time on auditing and verification.

That fits the curve almost perfectly. AI speeds up local creation. The bill comes back during checking.

METR’s July 2025 study found that experienced open-source developers working in large repositories they already knew well took 19% longer when AI tools were allowed. The 2026 follow-up says current uplift is harder to measure cleanly because tools improved, people increasingly refuse to work without them, and high-leverage usage patterns keep changing. That is a very modern research result. The tools matter. The measurement is messy. Anyone selling you one permanent productivity number is enjoying the simplicity more than the truth.

Security tells the same story from a less cheerful angle. GitGuardian’s 2026 State of Secrets Sprawl report says public GitHub saw about 29 million newly leaked hardcoded secrets in 2025, and that AI-assisted commits leak secrets at roughly 2x the baseline rate. Cheap generation is still cheap when it creates a secret leak. The expensive part arrives later, with rotation, cleanup, review, and the very ordinary question of who signed off on the thing.

Even the MIT numbers people like to quote need more care than they usually get. Project Iceberg’s report says 11.7% of U.S. wage value is technically exposed to current AI capability. That is interesting. It is also a statement about technical exposure, not a clean proof of near-term economic replacement in enterprise software organizations with real delivery, security, and coordination costs.

The takeaway I would give an engineering leader

If you run an engineering team, platform group, or budget process, my takeaway is pretty simple.

Do not ask whether AI is cheaper than developers. Ask whether AI lowers the total cost of getting a production-worthy change through your delivery system once review, repair, security, rollout, and coordination are included.

That changes what you measure.

• Track review and repair hours alongside model spend

• Track rework after review, not just output volume

• Track escaped defects, hotfixes, and rollback rate

• Track security findings and secret exposure

• Track cycle time to a trusted production change, not just time to first draft

If those numbers improve, I do not care if the token bill goes up. You bought leverage.

If output volume goes up while review pain, rework, and incidents stay flat or get worse, you probably bought a faster typing machine and a more expensive queue behind it.

Cheap tokens matter. Expensive software still matters more. The real break-even point is where human review, repair, and lifecycle coordination start growing faster than the AI draft got cheaper.

Subscribe now

The real choice is operational. Do you want the app team to build a predictable image with as little ceremony as possible, or do you want the image build to carry stronger platform policy, richer metadata, and the option to patch the runtime base without rebuilding the app? Those are not the same job, and Quarkus gives you a path for both.

I think this is where a lot of container-image advice gets mushy. We flatten the decision into “what command builds the image?” when the better question is “what contract am I taking on?” Jib is mostly an application-builder story. Buildpacks are closer to a platform-builder story, even when a developer triggers the command on a laptop.

This walkthrough keeps the application intentionally small so the comparison stays honest. We build the same Quarkus service twice, first with Jib and then with Buildpacks, and then we look at the part that actually changes the decision: metadata, builder control, and rebase behavior.

Prerequisites

You need a normal Quarkus setup and a working local container runtime. We are not doing anything exotic here, but I do want the commands to be reproducible without filling in missing pieces from memory.

• JDK 21 installed

• Quarkus CLI on your PATH

• Docker available locally

• The pack CLI for image inspection and rebase checks

• About 2 ☕️

I am using Docker here because the current Quarkus Buildpack integration in the Quarkus container image guide expects a Docker-backed flow. Buildpacks as an ecosystem are broader than that. This article is about what Quarkus gives you today, not every possible CNB setup.

Create the sample once

Create a tiny REST application:

quarkus create app dev.themainthread:container-choice-demo \
  --extension=rest-jackson \
  --java=21 \
  --no-code

I am using --no-code because the application itself is not the story. We only need one endpoint that proves the image runs.

Create src/main/java/dev/themainthread/container/HelloResource.java:

package dev.themainthread.container;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "hello from quarkus";
    }
}

Start the app once and verify the endpoint:

cd container-choice-demo
quarkus dev

In another terminal:

curl http://localhost:8080/hello

You should get:

hello from quarkus

Stop dev mode after that. The application is now boring in exactly the way I want. If one build path behaves differently from the other, the image tooling is the variable.

I am also using the Quarkus CLI image commands on purpose. They let us switch between supported image builders without turning the project setup into the story.

First path: Jib

Build the image with Jib:

quarkus image build jib --group mainthread --name container-choice-demo

For a local build, Quarkus wires the result into the local container daemon so you can run it immediately:

docker run --rm -p 8080:8080 mainthread/container-choice-demo:1.0.0-SNAPSHOT

Then check the endpoint again:

curl http://localhost:8080/hello

If the container answers, Jib did its job. That sounds obvious, but it is worth saying because this is what a lot of teams actually need: take a normal Quarkus service, build an image, move on with life.

What Jib gets right is the lack of drama. It understands Java application layering well, it fits naturally into Quarkus image tooling, and in push-oriented CI pipelines it can avoid some of the local-daemon assumptions that other paths drag in. If your requirement is “build a container image for this service and keep the pipeline boring,” Jib is a very strong default.

That does not mean it is universally better. It means the default burden is low. You do not have to decide on a builder stack up front, and you do not have to explain to the rest of the team why image creation suddenly has opinions about lifecycle binaries and run images.

Second path: Buildpacks

Before running the Buildpacks path, switch the Maven Wrapper away from the generated only-script mode:

mvn -N org.apache.maven.plugins:maven-wrapper-plugin:3.3.4:wrapper -Dtype=source

I am doing this up front because current generated wrappers can be awkward inside builder containers. In only-script mode, mvnw can fall back from the Maven ZIP distribution to the TAR.GZ distribution when unzip is missing in the build environment. If your checksum in maven-wrapper.properties matches the ZIP, that fallback can make the Buildpacks build fail even though the wrapper file looks correct. type=source avoids that path and keeps the wrapper self-contained without requiring a checked-in wrapper JAR.

Also, Quarkus defaults to fast-jar, which writes the runnable application under target/quarkus-app/. Paketo’s Maven buildpack, by default, looks for built artifacts with the pattern target/*.[ejw]ar. For this comparison piece, the least awkward fix is to have the build inside the builder produce an uber-jar instead.

Now build the same application with Buildpacks:

quarkus image build buildpack \
  --group mainthread \
  --name container-choice-demo \
  --build-env 'BP_MAVEN_ADDITIONAL_BUILD_ARGUMENTS=-Dquarkus.package.jar.type=uber-jar' \
  --builder-image paketobuildpacks/builder-jammy-base

A builder image is the build-side toolkit for a Buildpacks build. It is an OCI image that bundles the lifecycle binaries, an ordered set of buildpacks, a build-time base image, and a reference to the run image that will sit under the final application image.

That means paketobuildpacks/builder-jammy-base is not just a helper image name. It affects which buildpacks get a chance to detect your project, what environment they run in while producing layers, and which runtime base line the exported image starts from. Later, when we get to rebase, that run-image relationship becomes the interesting part.

That is why I am pinning the builder explicitly instead of hand-waving it away as a default. In a Buildpacks flow, the builder is part of the image contract.

Run the image:

docker run --rm -p 8080:8080 mainthread/container-choice-demo:1.0.0-SNAPSHOT

And verify it:

curl http://localhost:8080/hello

At this point both tools look similar from the outside. We built a Quarkus service, we started a container, and the endpoint answered. If that is where you stop, the article collapses into “two ways to avoid a Dockerfile.” That is not the interesting part.

The interesting part is what the Buildpack image knows about itself.

Inspect the Buildpack image

Use pack to inspect the image metadata:

pack inspect-image mainthread/container-choice-demo:1.0.0-SNAPSHOT

You should see sections for the run image, the buildpacks that participated in the build, and the process types baked into the image. That matters because the resulting artifact is not just “some filesystem layers Jib assembled.” It is an image with a buildpack lineage. The inspect-image command is where that becomes visible.

This is one of the first places where platform concerns show up. A platform team can standardize on a sanctioned builder and know that every service image carries the same kind of metadata and the same base-image policy. An app team can still trigger the build, but the artifact says more about how it came to exist.

You also get a better answer when somebody asks, “What exactly built this image?” With Buildpacks, that question has first-class metadata behind it. With Jib, the answer is usually simpler, but it is also mostly “our build assembled these layers.” That can be enough. Sometimes it is not.

Rebase is the whole point

If you want one reason Buildpacks still matter in 2026, this is the one I would use.

Try:

pack rebase mainthread/container-choice-demo:1.0.0-SNAPSHOT

Rebase swaps the run-image layers under a buildpack-produced application image without rebuilding the application itself. When there is an updated run image available, you can patch the base and keep the application layers intact. The Buildpacks rebase docs are worth reading here because this is the feature that changes the operational conversation.

That is a very different operational story from “run the Java build again.” If your platform team owns runtime base images and your application teams own code, Buildpacks let those responsibilities meet in a cleaner place. A CVE in the base image does not automatically mean every service has to rerun the whole application build just to move onto a patched runtime layer.

This is also where I stop thinking of Buildpacks as a developer convenience feature. Convenience is nice. Rebase is strategy. It only matters if your organization actually separates application rebuilds from base-image maintenance, but when that split is real, Jib and Buildpacks are not interchangeable anymore.

Where Jib still wins

I would still pick Jib first for a lot of Quarkus services.

If the team mostly wants a reliable image build inside the application pipeline, Jib is easier to explain and easier to own. There is less builder policy to reason about. There are fewer moving pieces to standardize. The mental model is close to the application build itself: compile the app, assemble a sensible layered image, push it where it needs to go.

That simplicity matters. Teams rarely regret the simpler pipeline on day one. They regret it when the complicated alternative did not buy them anything real.

The mistake is treating Buildpacks as automatically more modern because they are more opinionated. More opinionated is only better when the opinion matches a problem you actually have.

Where Buildpacks earn their keep

I would pick Buildpacks when one or more of these are true:

• The platform team wants to standardize the builder and the runtime base across many services

• You care about buildpack metadata and image inspection as part of your delivery story

• Rebase is operationally useful in your environment

• You want image construction to express platform policy, not just application packaging

That is a narrower case than “all Java services should use Buildpacks.” It is also a much more honest one.

A few traps worth calling out

Do not turn quarkus.container-image.build=true into a permanent property just because a tutorial wanted shorter commands. The current Quarkus docs explicitly warn against doing that for the Buildpack path because it can lead to nested builds in places you did not intend.

If you pass Buildpack-specific environment, use the current Quarkus configuration shape:

quarkus.buildpack.builder-env."BP_JVM_VERSION"=21

That is the kind of detail stale articles get wrong. Older config examples using quarkus.buildpack.env.* are easy to find and easy to cargo-cult into a project that no longer matches the docs.

Also, pin the builder you actually mean. latest is a lousy platform contract. If builder choice is part of the image policy, treat it like policy.

Finally, do not force Buildpacks into a team that only needs an ordinary image build. If nobody will inspect the metadata, nobody will use rebase, and nobody cares about standardizing on a sanctioned builder line, Jib is probably the better answer because it asks less from everyone.

My rule of thumb

If I am building a normal Quarkus service and I want the image step to stay boring, I pick Jib.

If I want the image to carry platform policy, builder identity, and rebase-friendly runtime separation, I pick Buildpacks.

That is the whole decision for me. Not “which one avoids a Dockerfile?” Both do. The better question is who owns the image contract after the Java build is over.

Quarkus makes it easy to try both, which is exactly what it should do. The mistake is pretending they solve the same problem just because they can both produce a container image from the same source tree.

Subscribe now

Turns out I did not. Quarkus LangChain4j already emits OpenTelemetry spans with GenAI attributes when quarkus-opentelemetry is on the classpath. LangSmith accepts generic OTLP from non-LangChain apps and maps those attributes into its tracing UI. So the work here is exporter wiring, deciding how much prompt and tool payload to ship, and generating traces worth opening.

We build SignalDesk, a fictional on-call support assistant with one REST endpoint, one AI service, one runbook tool, and three request shapes: plain chat, tool call, and controlled failure. You run it locally against Ollama, export traces to LangSmith, and keep CI green with a deterministic test stub.

For a much simpler Quarkus observability story in a hand-crafted way, see LLM observability with Quarkus and LangChain4j. This post stays focussed on standards: LangSmith over OTLP from a Quarkus AI service.

What we build

SignalDesk exposes POST /signaldesk/assist and returns:

• answer — model text

• usedTool — whether a tool ran

• toolName — e.g. lookupRunbook

• outcome — OK, TOOL_FAILED, or DEGRADED

Three prompts drive three trace stories:

• Plain chat — “What is our SLA for SEV-2?” (no tool)

• Tool path — “SEV-1 database failover — which runbook?” (lookupRunbook)

• Failure path — “Trigger runbook lookup for UNKNOWN-PLAN” (tool returns an error; HTTP stays 200 with outcome: TOOL_FAILED)

What you need

You have run Quarkus in dev mode and called a JSON endpoint before. LangChain4j AI service interfaces should look familiar.

• JDK 21

• Ollama on http://localhost:11434

• with a tool-capable model (defaults to llama3.2; set OLLAMA_MODEL if you standardize on something else)

• LangSmith account, API key, and the OTLP endpoint from your project settings

• About 4-5 ☕️

Project setup

Follow along or clone the project from my Github. From the repo root (adjust the path if you nest the module elsewhere):

quarkus create app dev.signaldesk:signaldesk-langsmith \
  --package-name=dev.signaldesk \
  --extensions='rest-jackson,quarkus-langchain4j-ollama,quarkus-opentelemetry' \
  --java=21 \
  --no-code
cd signaldesk-langsmith

The generator already adds quarkus-langchain4j-bom to dependencyManagement when you pick the LangChain4j Ollama extension. That is the same outcome you get from code.quarkus.io with that extension selected.

Add rest-assured dependency to your pom.xml:

• rest-assured — HTTP contract tests

Enable parameter names on maven-compiler-plugin (<parameters>true</parameters>) for {{question}} templates.

Package root: dev.signaldesk.

Assistant and runbook tool

I keep the assistant deliberately small here. One AI service, one short system message, and one tool box are enough for LangSmith to show a trace tree you would actually want to inspect: parent chat span, child tool span, and token usage without extra noise.

SignalDeskAssistant:

@RegisterAiService
@ApplicationScoped
public interface SignalDeskAssistant {

    @SystemMessage(
            """
            You are SignalDesk, an internal support assistant for on-call engineers.
            Answer SLA and policy questions directly when no runbook lookup is needed.
            For SEV-1 failover or explicit runbook requests, call lookupRunbook with service and severity.
            Keep answers short.""")
    @UserMessage("{{question}}")
    @ToolBox(RunbookTools.class)
    String assist(String question);
}

RunbookTools.lookupRunbook records invocations on a request-scoped AssistTrace and returns a fake runbook string. For UNKNOWN-PLAN it records a tool failure and returns an ERROR: line. LangChain4j then feeds that back to the model instead of throwing through the whole stack, which is a lot easier to demo and inspect:

@Tool("Looks up the on-call runbook for a service and severity. Use for failover or incident response.")
public String lookupRunbook(String service, String severity) {
    if (service != null && service.toUpperCase().contains("UNKNOWN-PLAN")) {
        assistTrace.recordToolFailure(TOOL_NAME);
        return "ERROR: runbook not found for service " + service;
    }
    assistTrace.recordTool(TOOL_NAME);
    return "runbook-" + service + "-" + severity + ": page platform-oncall, follow failover checklist RB-12";
}

REST endpoint and AssistTrace

SignalDeskResource delegates to SignalDeskService, which resets AssistTrace, calls the assistant, and maps trace state into AssistResponse. When the tool reports failure, outcome becomes TOOL_FAILED even though HTTP stays 200. I like that split here because API success and tool success are different stories, and the trace should make that visible.

OpenTelemetry → LangSmith

Add quarkus-opentelemetry (included if you used the create command above). Configure OTLP export in src/main/resources/application.properties:

quarkus.application.name=signaldesk-langsmith

quarkus.langchain4j.ollama.base-url=http://localhost:11434
quarkus.langchain4j.ollama.chat-model.model-id=${OLLAMA_MODEL:llama3.2}
quarkus.langchain4j.ollama.chat-model.temperature=0.2
quarkus.langchain4j.timeout=120s

quarkus.otel.exporter.otlp.protocol=http/protobuf
quarkus.otel.exporter.otlp.traces.protocol=http/protobuf
quarkus.otel.exporter.otlp.traces.endpoint=${OTEL_EXPORTER_OTLP_ENDPOINT:${LANGSMITH_OTLP_ENDPOINT:https://api.smith.langchain.com/otel}}
quarkus.otel.exporter.otlp.traces.headers=x-api-key=${LANGSMITH_API_KEY:},Langsmith-Project=${LANGSMITH_PROJECT:signaldesk-langsmith}
quarkus.otel.traces.sampler=parentbased_always_on

Three details burned me during smoke testing:

1. Use the OTLP base URL ending in /otel, not /otel/v1/traces. LangSmith’s OpenTelemetry guide often shows …/otel as the endpoint. With http/protobuf, Quarkus appends v1/traces automatically (Quarkus OpenTelemetry guide). If you also put /v1/traces in the property, export silently hits a double path (…/otel/v1/traces/v1/traces) and the dashboard stays empty even though spans exist locally in the logs.

2. Quarkus does not read the Python LangChain SDK env vars. These are ignored for this app:

• LANGSMITH_TRACING

• LANGSMITH_OTEL_ENABLED

• LANGSMITH_ENDPOINT (API host, not the OTLP exporter URL)

Use OTLP variables instead:

• LANGSMITH_API_KEY → x-api-key header

• OTEL_EXPORTER_OTLP_ENDPOINT or LANGSMITH_OTLP_ENDPOINT → traces endpoint (base /otel URL)

• LANGSMITH_PROJECT → Langsmith-Project header (must match the project name in the UI)

3. Regional hosts matter. EU accounts need the EU OTLP host, not the US default:

• EU: https://eu.api.smith.langchain.com/otel

• US: https://api.smith.langchain.com/otel

Export credentials in the same shell you use to start dev mode, then restart:

export LANGSMITH_API_KEY=lsv2_pt_...
export OTEL_EXPORTER_OTLP_ENDPOINT=https://eu.api.smith.langchain.com/otel
export LANGSMITH_PROJECT=signaldesk-langsmith
./mvnw quarkus:dev

Use a slug for LANGSMITH_PROJECT (no spaces). Values like “Quarkus Test App” break Quarkus comma-separated headers and LangSmith may only receive Langsmith-Project=Quarkus. If you need spaces, set the full header string via LANGSMITH_OTLP_HEADERS and wire that property in application.properties instead.

Startup check: OtelExportConfigProbe

The demo includes a small startup bean that logs the resolved OTLP endpoint, the project name it sees, whether an API key reached the exporter config, and a few common-footgun warnings. On boot you want something like:

OTLP traces: protocol=http/protobuf endpoint=https://eu.api.smith.langchain.com/otel project=signaldesk-langsmith apiKeySet=true

If apiKeySet=false or the endpoint still shows …/otel/v1/traces, fix the env vars and restart before you curl.

The app still starts and answers requests even when export is misconfigured. LangSmith just stays empty until the endpoint, key, and project line up. Once they do, traces usually show up in the named project within about 10 to 30 seconds of each request.

Quarkus LangChain4j records spans for chat model calls with attributes such as gen_ai.operation.name, gen_ai.system, model id, and token usage and there is no custom instrumentation class required for the baseline path.

Rich trace content (and why it is dangerous)

LangSmith is much easier to debug when prompts and tool payloads are on the span. Quarkus exposes that as configuration, not code:

quarkus.langchain4j.tracing.include-prompt=true
quarkus.langchain4j.tracing.include-completion=true
quarkus.langchain4j.tracing.include-tool-arguments=true
quarkus.langchain4j.tracing.include-tool-result=true

I turn these on for local debugging and leave them off by default in production unless there is redaction, a retention policy, and actual legal sign-off. Customer text, tokens, and runbook arguments end up in a third-party trace store very quickly.

For local export failures, the demo turns on %dev debug logging for io.opentelemetry.exporter and io.quarkus.opentelemetry — search the console for 401, 404, or Failed to export after a curl.

Optional: app metadata on spans

If you want an app-specific filter that survives in LangSmith, implement ChatModelSpanContributor:

@ApplicationScoped
public class SignalDeskSpanContributor implements ChatModelSpanContributor {

    @Override
    public void onRequest(ChatModelRequestContext requestContext, Span currentSpan) {
        currentSpan.setAttribute("signaldesk.workflow", "signaldesk-assist");
    }
    // onResponse / onError — same attribute
}

That sits beside standard gen_ai.* data, not instead of it.

Prove it

CI (no Ollama, no LangSmith):

./mvnw test

src/test/resources/application.properties:

%test.quarkus.langchain4j.ollama.devservices.enabled=false
%test.quarkus.langchain4j.devservices.enabled=false
%test.quarkus.otel.sdk.disabled=true
%test.quarkus.langchain4j.tracing.include-prompt=false
%test.quarkus.langchain4j.tracing.include-completion=false
%test.quarkus.langchain4j.tracing.include-tool-arguments=false
%test.quarkus.langchain4j.tracing.include-tool-result=false

Tests use SignalDeskStubChatModel via SignalDeskStubProfile (getEnabledAlternatives()), with keyword-driven tool versus no-tool behavior that matches the three curl recipes.

Manual traces (Ollama + LangSmith):

Plain chat:

curl -s -X POST http://localhost:8080/signaldesk/assist \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is our SLA for SEV-2?"}' | jq

Tool path:

curl -s -X POST http://localhost:8080/signaldesk/assist \
  -H 'Content-Type: application/json' \
  -d '{"question":"SEV-1 database failover — which runbook?"}' | jq

Failure path:

curl -s -X POST http://localhost:8080/signaldesk/assist \
  -H 'Content-Type: application/json' \
  -d '{"question":"Trigger runbook lookup for UNKNOWN-PLAN"}' | jq

LangSmith checklist after each call (project signaldesk-langsmith in the UI):

Open the Runs tab for your project. After the tool-path curl, the table should look roughly like this:

• POST /signaldesk/assist — HTTP entry (~0.8s), often the slowest row

• langchain4j.services.SignalDeskAssistant.assist (or truncated) — AI service span

• completion llama3.2 — model span with Input/Output columns showing prompt and answer text; Tokens populated (exact count varies by model and prompt)

• lookupRunbook — tool span with Input database (or similar) and Output runbook-database-SEV-…

• OTEL_SPAN_ID in Metadata on each row — confirms generic OTLP export, not a LangChain-only SDK path

Drill into one run for the trace tree (HTTP → service → completion → tool). The flat Runs table is enough to prove export. The tree view is the part worth keeping for the article screenshot.

Per recipe:

• Plain chat — completion rows without a lookupRunbook row

• Tool path — lookupRunbook plus one or more completion llama3.2 rows (tool-capable models may take two model hops)

• Failure path — lookupRunbook with error content in Output; JSON shows "outcome":"TOOL_FAILED" even when HTTP stays 200

Make it survive production

Keep the claims modest. This setup gives you useful LangSmith traces from Quarkus over OTLP. It does not promise full parity with LangSmith’s language-specific SDKs, every LangSmith feature via generic OTLP, or a safe default for shipping full prompts on production traffic.

Nothing in the dashboard? Work through this order — it matches what broke in practice:

1. Endpoint suffix — property must end with /otel, not /otel/v1/traces

2. Region — EU UI needs eu.api.smith.langchain.com, not api.smith.langchain.com

3. Env vars in the dev shell — restart quarkus:dev after export; IDE runs often miss them

4. Project name — LANGSMITH_PROJECT must match the LangSmith project; avoid spaces in the value unless you use LANGSMITH_OTLP_HEADERS

5. Wrong tab — traces land under the named project’s Runs, not “default”

6. Batch delay — wait 10–30 seconds and refresh

Missing API key — the app should still answer; OTLP export may warn or drop spans. OtelExportConfigProbe logs apiKeySet=false when the key did not reach the JVM.

PII and secrets — prompts, completions, and tool arguments can contain customer data. Once traffic is real, I would rather put sampling, redaction, or a collector in front of LangSmith than pretend the debug-friendly defaults are somehow production policy. The follow-up that belongs in its own post is one Quarkus app with collector fan-out to LangSmith for AI traces and Tempo for everything else.

Metrics — traces answer “what happened on this request?” Micrometer dashboards answer “what is the burn rate?” The sibling piece in this series is production-style AI metrics, not this article.

Close

SignalDesk is small on purpose. Quarkus LangChain4j already speaks the OpenTelemetry GenAI dialect LangSmith understands, so the real decision is how you export and how much content you let leave the JVM. Once the plain chat, tool, and failure traces look right in LangSmith, you have the same debugging loop Python teams enjoy, without rewriting the app in LangChain.

Subscribe now

Cloudflare’s Agent Readiness score turns that problem into a concrete audit. The scanner at isitagentready.com checks discoverability, content accessibility, bot access control, protocol discovery, and commerce signals. Some of those checks are old web plumbing wearing new boots. Some are new enough that the paint is still wet.

For me, “agent-ready” starts with the boring parts that remove guessing. Give the client crawl rules, a sitemap, Link headers, a compact llms.txt, a real OpenAPI pointer, OAuth protected-resource metadata, and an MCP endpoint if you expose tools. None of this makes the API smarter. It just stops wasting requests on detective work.

We will build that around Meridian, a small Quarkus knowledge-base API with public article search, protected write endpoints, Markdown article content, Keycloak-backed OAuth, and MCP tools. The domain is deliberately boring. That is good; the plumbing is the thing we care about here.

This article uses Java 21 and Quarkus 3.34.5. The Quarkiverse MCP HTTP extension is brought in through the Quarkus platform MCP server BOM, so the extension version follows the platform you choose.

The final project lives at https://github.com/myfear/the-main-thread/meridian-agent-ready.

What We Build

Meridian exposes these agent-facing pieces:

• robots.txt, sitemap.xml, and llms.txt at the root

• RFC 8288 Link headers from the API root

• Markdown responses for article content when the client sends Accept: text/markdown

• Content usage signals on article responses and crawler rules

• OAuth 2.0 Protected Resource Metadata from Quarkus OIDC

• an RFC 9727 API Catalog that links to the Quarkus OpenAPI document

• a Quarkus MCP server over HTTP/SSE

• an MCP Server Card for pre-connection discovery

• an Agent Skills discovery index with a small SKILL.md

The maturity is uneven. robots.txt, sitemaps, Link headers, OpenAPI, OIDC, and RFC 9728 are boring enough to ship. The MCP endpoint is practical today. API Catalog is a real RFC, but client support is still early. llms.txt, Content Signals, Markdown negotiation, MCP Server Cards, and Agent Skills are useful conventions with uneven adoption. Ship them with clear boundaries. New standards are where confident blog posts go to embarrass themselves six months later. Including this article probably. We will see.

What You Need

You need a current Quarkus CLI, Java 21, Maven, and a container runtime if you want Keycloak Dev Services locally.

• Java 21

• Quarkus CLI

• Maven 3.9+

• Podman or Docker for Keycloak Dev Services

• Basic Jakarta REST and OAuth knowledge

• Some amount of your favorite beverage ☕️

Create the project or directly clone the repository.

quarkus create app dev.the-main-thread:meridian \
  --package-name=dev.themainthread.meridian \
  --extension=quarkus-rest,quarkus-rest-jackson,quarkus-smallrye-openapi,quarkus-smallrye-health,quarkus-oidc,io.quarkiverse.mcp:quarkus-mcp-server-http

Use --package-name because dev.the-main-thread is a fine Maven group id and a broken Java package. quarkus-smallrye-health is optional, but the API catalog below links to /q/health, so we add it here instead of pretending the endpoint appears by magic.

The extensions are simple enough:

• quarkus-rest: Jakarta REST endpoints

• quarkus-rest-jackson: JSON serialization

• quarkus-smallrye-openapi: generated OpenAPI at /q/openapi

• quarkus-smallrye-health: health endpoint for catalog status links

• quarkus-oidc: bearer-token security and protected-resource metadata

• io.quarkiverse.mcp:quarkus-mcp-server-http: MCP over Streamable HTTP and SSE

The MCP artifact name matters. Older examples used quarkus-mcp-server-sse. The current Quarkiverse extension page lists quarkus-mcp-server-http; it still exposes the SSE endpoint at /mcp/sse when you use the HTTP transport.

Static Discovery Files

Start with files. It is hard to beat a static file when the job is “be there before any application logic runs.”

Quarkus serves static files from src/main/resources/META-INF/resources/. A file at src/main/resources/META-INF/resources/robots.txt becomes /robots.txt.

robots.txt

robots.txt is still about crawl access. It tells automated clients which paths they may fetch. Cloudflare-style Content Signals can also live there for crawlers that understand them.

Create src/main/resources/META-INF/resources/robots.txt:

User-agent: *
Allow: /
Disallow: /admin/
Disallow: /internal/

User-agent: GPTBot
Allow: /
Disallow: /admin/
Disallow: /internal/

User-agent: ClaudeBot
Allow: /
Disallow: /admin/
Disallow: /internal/

Content-Signal: search=yes, ai-input=yes, ai-train=no

Sitemap: https://api.meridian.dev/sitemap.xml

The crawler rules and the usage signal do different jobs. Disallow blocks fetching a path. Content-Signal states allowed use for content the crawler is allowed to fetch. It is trust-based, so it works only with clients that respect the signal. Annoying, but still better than silence.

sitemap.xml

A REST API needs a sitemap with stable public entry points, not every protected write URL you ever added.

Create src/main/resources/META-INF/resources/sitemap.xml:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
        <loc>https://api.meridian.dev/api/v1/articles</loc>
        <changefreq>hourly</changefreq>
        <priority>1.0</priority>
    </url>
    <url>
        <loc>https://api.meridian.dev/q/openapi?format=json</loc>
        <changefreq>weekly</changefreq>
        <priority>0.9</priority>
    </url>
    <url>
        <loc>https://api.meridian.dev/.well-known/api-catalog</loc>
        <changefreq>monthly</changefreq>
        <priority>0.8</priority>
    </url>
</urlset>

If articles are public and individually addressable, generate this from your database instead. Keep the URL stable and change the implementation behind it.

llms.txt

llms.txt is a convention, not an IETF standard. Keep it short. It gives a model a small map of the service and links to the files worth reading.

Create src/main/resources/META-INF/resources/llms.txt:

# Meridian Knowledge API

> Meridian is a Quarkus API for searching and reading structured knowledge
> articles. Public clients can search and retrieve article content. Write
> operations require OAuth bearer tokens from the Meridian realm.

Meridian exposes JSON for API operations and Markdown for article content when
clients send `Accept: text/markdown`.

## API

- [OpenAPI JSON](https://api.meridian.dev/q/openapi?format=json): Machine-readable REST API contract
- [API catalog](https://api.meridian.dev/.well-known/api-catalog): RFC 9727 Linkset catalog
- [OAuth protected resource metadata](https://api.meridian.dev/.well-known/oauth-protected-resource): Authorization server and scope discovery
- [MCP Server Card](https://api.meridian.dev/.well-known/mcp/server-card.json): Pre-connection MCP discovery
- [Agent Skills index](https://api.meridian.dev/.well-known/agent-skills/index.json): Skills published for agent clients

## Content

- [Article search](https://api.meridian.dev/api/v1/articles): Public article search endpoint
- [MCP endpoint](https://api.meridian.dev/mcp): MCP Streamable HTTP endpoint
- [MCP SSE endpoint](https://api.meridian.dev/mcp/sse): Compatibility endpoint for older MCP clients

## Optional

- [Human documentation](https://docs.meridian.dev): Developer guide and examples

That is enough. Once this becomes a second documentation site, you have invented documentation drift with a nicer filename.

Link Headers at the Front Door

Cloudflare’s scanner also looks for RFC 8288 Link headers because an agent should not have to parse HTML before it can find the useful machine-readable documents. For an API, I like making / a tiny discovery response instead of a blank 404. It gives humans a pulse check and gives agents headers they can follow.

Create src/main/java/dev/themainthread/meridian/resource/DiscoveryResource.java:

package dev.themainthread.meridian.resource;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.Map;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
@Path("/")
public class DiscoveryResource {

    @ConfigProperty(name = "meridian.api.base-url")
    String apiBaseUrl;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Response index() {
        Map<String, String> body = Map.of(
                "service", "Meridian Knowledge API",
                "articles", apiBaseUrl + "/api/v1/articles",
                "openapi", apiBaseUrl + "/q/openapi?format=json",
                "apiCatalog", apiBaseUrl + "/.well-known/api-catalog",
                "mcpServerCard", apiBaseUrl + "/.well-known/mcp/server-card.json",
                "agentSkills", apiBaseUrl + "/.well-known/agent-skills/index.json");

        return withDiscoveryLinks(Response.ok(body), apiBaseUrl).build();
    }

    static Response.ResponseBuilder withDiscoveryLinks(
            Response.ResponseBuilder response, String apiBaseUrl) {
        return response
                .header("Link",
                        "<" + apiBaseUrl
                                + "/.well-known/api-catalog>; rel=\"api-catalog\"; type=\"application/linkset+json\"")
                .header("Link",
                        "<" + apiBaseUrl + "/q/openapi?format=json>; rel=\"service-desc\"; type=\"application/json\"")
                .header("Link",
                        "<" + apiBaseUrl + "/llms.txt>; rel=\"describedby\"; type=\"text/plain\"")
                .header("Link",
                        "<" + apiBaseUrl
                                + "/.well-known/mcp/server-card.json>; rel=\"mcp-server-card\"; type=\"application/json\"")
                .header("Link",
                        "<" + apiBaseUrl
                                + "/.well-known/agent-skills/index.json>; rel=\"agent-skills\"; type=\"application/json\"");
    }
}

service-desc and describedby are broadly useful. api-catalog, mcp-server-card, and agent-skills are newer relation names, so treat them as friendly hints rather than the only discovery path. The actual files still need stable URLs.

Markdown for Article Content

Cloudflare’s Markdown for Agents feature made one convention visible: clients can ask for Markdown with Accept: text/markdown, and the response can carry Vary: Accept, X-Markdown-Tokens, and Content-Signal. The CDN can do this, but a Quarkus app can do it itself.

I prefer choosing the representation in the resource method. A response filter that rewrites text/html after Jakarta REST has already picked a response type looks elegant, then quietly serves HTML with a Markdown content type. That is a small bug with excellent hiding skills.

Add the HTML-to-Markdown converter:

<dependency>
  <groupId>com.vladsch.flexmark</groupId>
  <artifactId>flexmark-html2md-converter</artifactId>
  <version>0.64.8</version>
</dependency>

Then expose article content like this. Put list, create, and content negotiation on the same Jakarta REST class with @Path("/api/v1/articles"). Registering two application-scoped resources with that identical class-level path is brittle; merge the methods instead.

package dev.themainthread.meridian.resource;

import com.vladsch.flexmark.html2md.converter.FlexmarkHtmlConverter;
import dev.themainthread.meridian.service.Article;
import dev.themainthread.meridian.service.ArticleListResponse;
import dev.themainthread.meridian.service.ArticleService;
import dev.themainthread.meridian.service.CreateArticleRequest;
import io.quarkus.security.Authenticated;
import jakarta.annotation.security.PermitAll;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.UriBuilder;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;

@ApplicationScoped
@Path("/api/v1/articles")
public class ArticlesResource {

    private static final MediaType TEXT_MARKDOWN_TYPE =
        new MediaType("text", "markdown");

    private static final FlexmarkHtmlConverter HTML_TO_MARKDOWN =
        FlexmarkHtmlConverter.builder().build();

    @Inject
    ArticleService articleService;

    @GET
    @PermitAll
    @Produces(MediaType.APPLICATION_JSON)
    @Operation(
        summary = "Search and list public articles",
        description = """
            Searches public knowledge articles by title and body text. When the q
            parameter is present, results are ordered by search relevance. Without q,
            results are ordered by publication date. This endpoint does not require
            authentication.
            """)
    @APIResponse(responseCode = "200", description = "Paginated article list")
    public ArticleListResponse listArticles(
            @QueryParam("q") String query,
            @QueryParam("page") @DefaultValue("0") int page,
            @QueryParam("size") @DefaultValue("20") int size) {
        return articleService.search(query, page, size);
    }

    @POST
    @Authenticated
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createArticle(CreateArticleRequest request) {
        Article created = articleService.create(request.title(), request.content());
        return Response.created(
                UriBuilder.fromPath("/api/v1/articles").path(created.id()).build())
            .entity(created)
            .build();
    }

    @GET
    @PermitAll
    @Path("/{id}/content")
    public Response getArticleContent(@PathParam("id") String id,
                                      @Context HttpHeaders headers) {
        Article article = articleService.findById(id)
            .orElseThrow(NotFoundException::new);

        if (acceptsMarkdown(headers)) {
            String markdown = article.markdownContent();
            if (markdown == null || markdown.isBlank()) {
                markdown = HTML_TO_MARKDOWN.convert(article.htmlContent());
            }

            return Response.ok(markdown, TEXT_MARKDOWN_TYPE)
                .header("Vary", HttpHeaders.ACCEPT)
                .header("X-Markdown-Tokens", estimateTokens(markdown))
                .header("Content-Signal", "search=yes, ai-input=yes, ai-train=no")
                .build();
        }

        return Response.ok(article.htmlContent(), MediaType.TEXT_HTML_TYPE)
            .header("Vary", HttpHeaders.ACCEPT)
            .build();
    }

    private boolean acceptsMarkdown(HttpHeaders headers) {
        for (MediaType requested : headers.getAcceptableMediaTypes()) {
            if (requested.isWildcardType() || requested.isWildcardSubtype()) {
                return false;
            }
            if (requested.isCompatible(TEXT_MARKDOWN_TYPE)) {
                return true;
            }
            if (requested.isCompatible(MediaType.TEXT_HTML_TYPE)) {
                return false;
            }
        }
        return false;
    }

    private int estimateTokens(String value) {
        return Math.max(1, value.length() / 4);
    }
}

For production, store Markdown at authoring time and render HTML from it. Converting HTML back to Markdown is fine as a migration bridge. I would not make that the long-term content model, because some structure is already gone by the time you scrape rendered HTML back into text.

The Vary: Accept header is the cache safety bit. Without it, a CDN can cache the HTML response and serve it to a client that asked for Markdown. That failure looks like “the agent is dumb” until you check the headers.

Content Usage Signals

The Markdown endpoint above sets Content-Signal on article content. For the JAX-RS responses, use a small response filter. Static files are served by the HTTP layer before this filter matters, so keep crawler-facing signals directly in robots.txt.

package dev.themainthread.meridian.filter;

import jakarta.ws.rs.container.ContainerRequestContext;
import jakarta.ws.rs.container.ContainerResponseContext;
import jakarta.ws.rs.container.ContainerResponseFilter;
import jakarta.ws.rs.ext.Provider;
import java.io.IOException;

@Provider
public class ContentSignalsFilter implements ContainerResponseFilter {

    @Override
    public void filter(ContainerRequestContext requestContext,
                       ContainerResponseContext responseContext) throws IOException {
        // Use getPath(true): RESTEasy Reactive (Quarkus REST) rejects getPath(false)
        // with "We do not support non-decoded parameters".
        String path = requestContext.getUriInfo().getPath(true);

        if (path.startsWith("api/v1/articles") || path.startsWith("/api/v1/articles")) {
            responseContext.getHeaders().putSingle(
                "Content-Signal",
                "search=yes, ai-input=yes, ai-train=no");
            return;
        }

        if (path.startsWith(".well-known")
            || path.startsWith("/.well-known")
            || path.equals("robots.txt")
            || path.equals("/robots.txt")
            || path.equals("llms.txt")
            || path.equals("/llms.txt")) {
            responseContext.getHeaders().putSingle(
                "Content-Signal",
                "search=yes, ai-input=yes, ai-train=yes");
        }
    }
}

With getPath(true), the path may include a leading slash depending on the runtime. Match both api/v1/... and /api/v1/.... Also avoid getPath(false) on Quarkus REST (RESTEasy Reactive): it throws IllegalArgumentException because non-decoded paths are not supported.

OAuth Discovery with RFC 9728

For protected resources, use RFC 9728 OAuth 2.0 Protected Resource Metadata. This tells a client which authorization server protects the API and which scopes are worth asking for.

You do not need to hand-write the metadata document in Quarkus. quarkus-oidc has protected resource metadata support, and it is disabled by default for a good reason: publishing authorization-server details is a deliberate choice.

Keep the shared OIDC behavior separate from the production host names:

quarkus.oidc.client-id=meridian-api
quarkus.oidc.application-type=service

quarkus.oidc.resource-metadata.enabled=true
quarkus.oidc.resource-metadata.scopes=read,write,admin

Then set production URLs in the production profile:

%prod.meridian.api.base-url=https://api.meridian.dev
%prod.quarkus.oidc.auth-server-url=https://auth.meridian.dev/realms/meridian
%prod.quarkus.oidc.resource-metadata.resource=${meridian.api.base-url}

For local verification, use a dev profile. Leave quarkus.oidc.auth-server-url unset in dev if you want Quarkus Dev Services to start Keycloak for you. Quarkus forces HTTPS resource metadata by default, which is correct for production and annoying for localhost:

%dev.meridian.api.base-url=http://localhost:8080
%dev.quarkus.oidc.resource-metadata.resource=${meridian.api.base-url}
%dev.quarkus.oidc.resource-metadata.force-https-scheme=false

With that enabled, the default protected resource metadata route is:

/.well-known/oauth-protected-resource

A client that calls a protected endpoint without a token should also see a challenge like this:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.meridian.dev/.well-known/oauth-protected-resource"

The parameter name is resource_metadata. Do not use as_uri here. That is not the RFC 9728 contract, and some OAuth-aware clients will simply miss the metadata URL.

Treat jwks_uri carefully. In RFC 9728 it belongs to the protected resource, for cases where the resource signs responses. It is separate from the Keycloak realm certificate endpoint used to verify access tokens. Meridian does not sign resource responses, so we leave it out.

Metadata is still only metadata. It does not enforce scopes. Protect your write methods with io.quarkus.security.Authenticated, @PermissionsAllowed, route permissions, or your normal Keycloak authorization setup. The discovery document helps the client ask for the right token; it does not make a bad token good.

API Catalog with RFC 9727

OpenAPI tells a client what operations exist. The RFC 9727 API Catalog tells it where to find those API descriptions.

Quarkus already exposes OpenAPI at /q/openapi; request JSON with /q/openapi?format=json. The catalog at /.well-known/api-catalog should be a Linkset document, not a custom { "apis": [...] } object.

Create a resource for the catalog:

package dev.themainthread.meridian.resource;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.HEAD;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Response;
import java.util.List;
import java.util.Map;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
@Path("/.well-known")
public class ApiCatalogResource {

    private static final String API_CATALOG_TYPE =
        "application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"";

    @ConfigProperty(name = "meridian.api.base-url")
    String apiBaseUrl;

    @HEAD
    @Path("/api-catalog")
    public Response apiCatalogHead() {
        return DiscoveryResource.withDiscoveryLinks(Response.noContent(), apiBaseUrl)
            .build();
    }

    @GET
    @Path("/api-catalog")
    @Produces("application/linkset+json")
    public Response apiCatalog() {
        Map<String, Object> catalog = Map.of(
            "linkset", List.of(
                Map.of(
                    "anchor", apiBaseUrl + "/api/v1",
                    "service-desc", List.of(
                        Map.of(
                            "href", apiBaseUrl + "/q/openapi?format=json",
                            "type", "application/json"
                        )
                    ),
                    "service-doc", List.of(
                        Map.of(
                            "href", "https://docs.meridian.dev",
                            "type", "text/html"
                        )
                    ),
                    "status", List.of(
                        Map.of(
                            "href", apiBaseUrl + "/q/health",
                            "type", "application/json"
                        )
                    )
                )
            )
        );

        return DiscoveryResource.withDiscoveryLinks(Response.ok(catalog), apiBaseUrl)
            .type(API_CATALOG_TYPE)
            .build();
    }
}

Keep the catalog small. It points to the machine-readable descriptions that already exist; it is not the place to rebuild your whole API model.

The listArticles method above also shows why OpenAPI descriptions matter. “Returns a list” is not enough. A planner needs to know when to call the operation, how the results are ordered, and whether it needs a token.

MCP Tool Access

The Quarkiverse MCP HTTP extension exposes the MCP endpoint at /mcp for the current Streamable HTTP transport and /mcp/sse for older SSE clients. The default root path is already /mcp, so only set it when you want to be explicit:

quarkus.mcp.server.http.root-path=/mcp
quarkus.mcp.server.server-info.name=meridian
quarkus.mcp.server.server-info.title=Meridian Knowledge API
quarkus.mcp.server.server-info.version=1.0.0
quarkus.mcp.server.server-info.description=Tools for searching and reading Meridian articles.

Protect the endpoint if the tools expose anything sensitive:

quarkus.http.auth.permission.mcp.paths=/mcp,/mcp/*
quarkus.http.auth.permission.mcp.policy=authenticated

Then implement the tools:

package dev.themainthread.meridian.mcp;

import com.vladsch.flexmark.html2md.converter.FlexmarkHtmlConverter;
import dev.themainthread.meridian.service.Article;
import dev.themainthread.meridian.service.ArticleService;
import io.quarkiverse.mcp.server.Tool;
import io.quarkiverse.mcp.server.ToolArg;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import java.util.stream.Collectors;

@ApplicationScoped
public class MeridianMcpTools {

    private static final FlexmarkHtmlConverter HTML_TO_MARKDOWN =
        FlexmarkHtmlConverter.builder().build();

    @Inject
    ArticleService articleService;

    @Tool(description = "Search public Meridian articles by keyword or phrase.")
    public String searchArticles(
            @ToolArg(description = "Search keyword or phrase") String query) {
        return articleService.search(query, 0, 10).items()
            .stream()
            .map(article -> article.id() + ": " + article.title())
            .collect(Collectors.joining("\n"));
    }

    @Tool(description = "Read one Meridian article as Markdown.")
    public String getArticle(
            @ToolArg(description = "Article ID") String id) {
        return articleService.findById(id)
            .map(MeridianMcpTools::markdownOrConverted)
            .orElse("No article found for ID `" + id + "`.");
    }

    private static String markdownOrConverted(Article article) {
        String markdown = article.markdownContent();
        if (markdown != null && !markdown.isBlank()) {
            return markdown;
        }
        return HTML_TO_MARKDOWN.convert(article.htmlContent());
    }
}

Tool output is not a web page. Return Markdown or compact plain text. HTML in a tool response usually gives the model more tokens and less meaning. That trade is bad and not even interesting.

Cloudflare checks MCP Server Card discovery before a client connects. The MCP protocol still negotiates capabilities during initialize, so the card is a map, not the source of truth. Keep it small and regenerate it when tools change.

Create src/main/java/dev/themainthread/meridian/resource/McpServerCardResource.java:

package dev.themainthread.meridian.resource;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;
import java.util.Map;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
@Path("/.well-known")
public class McpServerCardResource {

    @ConfigProperty(name = "meridian.api.base-url")
    String apiBaseUrl;

    @GET
    @Path("/mcp/server-card.json")
    @Produces(MediaType.APPLICATION_JSON)
    public Response serverCard() {
        return Response.ok(card()).build();
    }

    @GET
    @Path("/mcp.json")
    @Produces(MediaType.APPLICATION_JSON)
    public Response legacyServerCard() {
        return Response.ok(card()).build();
    }

    private Map<String, Object> card() {
        return Map.of(
            "$schema",
            "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
            "version",
            "1.0",
            "protocolVersion",
            "2025-06-18",
            "serverInfo",
            Map.of(
                "name", "meridian",
                "title", "Meridian Knowledge API",
                "version", "1.0.0"),
            "description",
            "Search and read public Meridian knowledge articles.",
            "transport",
            Map.of(
                "type", "streamable-http",
                "endpoint", apiBaseUrl + "/mcp"),
            "authentication",
            Map.of(
                "required", true,
                "schemes", List.of("bearer"),
                "resourceMetadata", apiBaseUrl + "/.well-known/oauth-protected-resource"),
            "tools",
            List.of(
                Map.of(
                    "name", "searchArticles",
                    "title", "Search articles",
                    "description", "Search public Meridian articles by keyword or phrase.",
                    "inputSchema", Map.of(
                        "type", "object",
                        "properties", Map.of(
                            "query", Map.of(
                                "type", "string",
                                "description", "Search keyword or phrase")),
                        "required", List.of("query"))),
                Map.of(
                    "name", "getArticle",
                    "title", "Read article",
                    "description", "Read one Meridian article as Markdown.",
                    "inputSchema", Map.of(
                        "type", "object",
                        "properties", Map.of(
                            "id", Map.of(
                                "type", "string",
                                "description", "Article ID")),
                        "required", List.of("id")))));
    }
}

I serve both /.well-known/mcp/server-card.json and /.well-known/mcp.json because the discovery convention is still settling and different tools have looked in different places. That is mildly annoying, but cheaper than asking agents to guess.

Agent Skills Discovery

Agent Skills are still just instruction bundles: a directory with a SKILL.md file, optional scripts, references, and assets. Cloudflare’s scanner also looks for the proposed discovery index at /.well-known/agent-skills/index.json, so Meridian publishes a tiny index and a single skill document.

The useful distinction is this: Quarkus serves the skill, but it does not execute the skill. The document teaches an agent how to use the API after the agent chooses to load it. Keep it narrow, version it with the service, and avoid stuffing policy novels into it. Agents are very good at following stale instructions with confidence.

Create src/main/java/dev/themainthread/meridian/resource/AgentSkillsResource.java:

package dev.themainthread.meridian.resource;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.List;
import java.util.Map;
import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
@Path("/.well-known/agent-skills")
public class AgentSkillsResource {

    private static final String DISCOVERY_SCHEMA =
        "https://schemas.agentskills.io/discovery/0.2.0/schema.json";

    private static final String SKILL_MD = """
        ---
        name: meridian
        description: Search and read Meridian knowledge articles. Use when a user asks for Meridian article IDs, public article search, or Markdown article content.
        ---

        # Meridian

        Use the public search endpoint first unless the user already provided an article ID.

        ## Search

        Call:

        ```text
        GET https://api.meridian.dev/api/v1/articles?q={query}
        ```

        Use returned article IDs for follow-up reads.

        ## Read

        Call:

        ```text
        GET https://api.meridian.dev/api/v1/articles/{id}/content
        Accept: text/markdown
        ```

        Prefer Markdown content. Do not scrape HTML unless Markdown is unavailable.
        """;

    @ConfigProperty(name = "meridian.api.base-url")
    String apiBaseUrl;

    @GET
    @Path("/index.json")
    @Produces(MediaType.APPLICATION_JSON)
    public Response index() {
        Map<String, Object> index = Map.of(
            "$schema",
            DISCOVERY_SCHEMA,
            "skills",
            List.of(Map.of(
                "name",
                "meridian",
                "type",
                "skill-md",
                "description",
                "Search and read Meridian knowledge articles.",
                "url",
                apiBaseUrl + "/.well-known/agent-skills/meridian/SKILL.md",
                "digest",
                sha256Digest(SKILL_MD))));

        return Response.ok(index).build();
    }

    @GET
    @Path("/meridian/SKILL.md")
    @Produces("text/markdown")
    public Response skill() {
        return Response.ok(SKILL_MD, "text/markdown")
            .header("Cache-Control", "public, max-age=3600")
            .build();
    }

    private static String sha256Digest(String value) {
        try {
            byte[] digest = MessageDigest.getInstance("SHA-256")
                .digest(value.getBytes(StandardCharsets.UTF_8));
            return "sha256:" + HexFormat.of().formatHex(digest);
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("SHA-256 is required by the Java platform", e);
        }
    }
}

The digest is not decorative. Discovery clients can use it to notice when the served skill changed. If your skill grows beyond one small file, move to an archive artifact and validate the archive like you would any other executable input from the Internet.

CORS and Browser-Hosted Agents

If browser-hosted clients call your API, expose the headers they need to read. Keep the origins explicit for a protected API. * is fine for a public static demo and a poor default for anything with write paths.

quarkus.http.cors.enabled=true
quarkus.http.cors.origins=https://app.meridian.dev,https://inspector.modelcontextprotocol.io
quarkus.http.cors.methods=GET,POST,PUT,DELETE,OPTIONS
quarkus.http.cors.headers=Accept,Authorization,Content-Type
quarkus.http.cors.exposed-headers=Content-Signal,Link,X-Markdown-Tokens,Vary,WWW-Authenticate
quarkus.http.cors.access-control-max-age=1H
quarkus.http.cors.access-control-allow-credentials=false

The property is quarkus.http.cors.enabled, not quarkus.http.cors. The older short form appears in many examples, and examples are how configuration drift learns to travel. If your browser client uses cookies instead of bearer tokens, revisit access-control-allow-credentials; for this API, bearer tokens in the Authorization header keep the browser credential rules simpler.

Verify the Chain

Run the application locally first:

quarkus dev

Then check the static discovery files:

curl -i http://localhost:8080/
curl -i http://localhost:8080/robots.txt
curl -i http://localhost:8080/sitemap.xml
curl -i http://localhost:8080/llms.txt

You should see 200 OK. On /, check that the response includes Link headers for the API catalog, OpenAPI document, MCP Server Card, and Agent Skills index. For robots.txt, check that the Content-Signal line is in the body.

Check Markdown negotiation:

curl -i http://localhost:8080/api/v1/articles/intro-to-meridian/content \
  -H "Accept: text/markdown"

Expected headers:

HTTP/1.1 200 OK
Content-Type: text/markdown
Vary: Accept
X-Markdown-Tokens: ...
Content-Signal: search=yes, ai-input=yes, ai-train=no

Check the API catalog:

curl -i http://localhost:8080/.well-known/api-catalog \
  -H "Accept: application/linkset+json"

Expected headers:

HTTP/1.1 200 OK
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

Check the required HEAD response as well:

curl -I http://localhost:8080/.well-known/api-catalog

Expected header:

Link: <http://localhost:8080/.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"

Expected body shape:

{
  "linkset": [
    {
      "anchor": "http://localhost:8080/api/v1",
      "service-desc": [
        {
          "href": "http://localhost:8080/q/openapi?format=json",
          "type": "application/json"
        }
      ]
    }
  ]
}

Check protected resource metadata:

curl -i http://localhost:8080/.well-known/oauth-protected-resource

Expected body fields include:

{
  "resource": "http://localhost:8080",
  "authorization_servers": [
    "http://localhost:8180/realms/quarkus"
  ],
  "scopes_supported": [
    "read",
    "write",
    "admin"
  ]
}

The exact authorization_servers URLs depend on your Dev Services setup. When Docker is unavailable, Quarkus may start an embedded OIDC dev service instead of Keycloak; the array can contain that base URL (without a /realms/... path). In production, the same field should point at your real issuer, for example https://auth.meridian.dev/realms/meridian.

Then hit a protected endpoint without a token (your write method should use io.quarkus.security.Authenticated; there is no jakarta.annotation.security.Authenticated):

curl -i http://localhost:8080/api/v1/articles \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title":"Draft","content":"No token yet"}'

Expected result:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="..."

For MCP, use a real MCP client or MCP Inspector with a bearer token against:

http://localhost:8080/mcp

For older SSE clients, use the compatibility endpoint:

http://localhost:8080/mcp/sse

Do not call the MCP endpoint with plain curl and expect a friendly REST document. It is a protocol endpoint, not a brochure.

You can still check the pre-connection discovery documents with curl:

curl -i http://localhost:8080/.well-known/mcp/server-card.json
curl -i http://localhost:8080/.well-known/mcp.json
curl -i http://localhost:8080/.well-known/agent-skills/index.json
curl -i http://localhost:8080/.well-known/agent-skills/meridian/SKILL.md

The server card should name the streamable-http transport and point at http://localhost:8080/mcp. The skills index should contain a skills array with a skill-md entry and a sha256: digest.

What I Would Not Ship Blindly

Some adjacent ideas are worth watching, but I would not make the main tutorial depend on them.

MCP Server Cards are useful as pre-connection hints, but I would not let the card drift from the real MCP implementation. Let MCP initialize do the authoritative capability exchange and treat the card as an index.

Agent Skills are useful as packaged instructions. Keep the skill small and specific. A giant skill that restates your whole developer portal is just documentation drift with YAML frontmatter.

A2A Agent Cards matter when your service is itself an agent that other agents should delegate to. Meridian is an API with MCP tools, not an A2A server, so adding an A2A card here would be theater.

WebMCP is aimed at browser-exposed tool surfaces. It is worth watching, but it does not change this server-side Quarkus API.

x402 and other agent payment protocols are moving quickly. x402 has real momentum after the Linux Foundation announcement in April 2026, but paid API flows need product, fraud, accounting, and support decisions. Cloudflare’s live scanner also lists MPP, UCP, and ACP; that is a separate article. Maybe in the future.

Web Bot Auth is becoming more practical through Cloudflare and AWS WAF support. Use it when bot identity matters for enforcement. It is not required for the discovery flow we built here.

Summary

Making a Quarkus API easier for agents is mostly about removing guesswork.

robots.txt, sitemap.xml, llms.txt, and Link headers give clients a first map. Markdown content negotiation keeps article bodies cheap to read. Content Signals make usage intent explicit. Quarkus OIDC can publish RFC 9728 protected resource metadata when you opt in. RFC 9727 gives your OpenAPI document a proper catalog. The Quarkiverse MCP extension gives tool-capable clients a protocol endpoint, and the server card plus Agent Skills index make that tool surface easier to discover before a client connects.

None of this turns a bad API into a good one. It just makes the good parts discoverable without asking an agent to reverse-engineer your service by failing requests at it. Boring repeatability wins again.

Subscribe now

Records fixed the boilerplate part of that story. The staged assembly problem stayed exactly where it was: inventory, pricing, shipping, and fraud checks keep adding fields until the canonical constructor turns into a minefield.

We build OrderDesk, a small Quarkus API that shows where records are enough on their own, where a hand-written builder still earns its keep, and how Bean Validation fits on record request bodies. The sample uses Quarkus 3.35.2.

What we build

OrderDesk is a compact e-commerce slice that:

• exposes GET /products with simple record DTOs;

• exposes GET /orders/sample with a multi-field OrderDto assembled through OrderDtoBuilder and a staged OrderAssemblyService;

• exposes POST /orders with a validated CreateOrderRequest record;

• ships unit and @QuarkusTest coverage for builder invariants and HTTP validation.

What you need

You have written Jakarta REST resources before and know what a DTO is for.

• JDK 21

• Quarkus CLI or Maven

• curl for manual checks

• About two ☕️☕️

Project setup

Create the project:

quarkus create app com.orderdesk:orderdesk-records-builders \
  --extension='quarkus-rest-jackson,hibernate-validator' \
  --java=21 \
  --no-code
cd orderdesk-records-builders

Extensions:

• quarkus-rest-jackson — REST endpoints and Jackson JSON serialization for records

• hibernate-validator — Bean Validation on request bodies and method parameters

Use package com.orderdesk for application code.

Simple record DTOs

Before records, a three-field product DTO was mostly ceremony: fields, constructor, getters, equals, hashCode, and often Lombok because nobody wanted to maintain it by hand.

A record states the contract in one place — immutable data, value semantics, transparent state:

package com.orderdesk;

import java.math.BigDecimal;

public record ProductDto(
        Long id,
        String name,
        BigDecimal price
) {
}

Jackson deserializes records through the canonical constructor on current Quarkus, so this sample does not need extra annotations.

Product catalog and list endpoint

package com.orderdesk;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;
import java.util.Optional;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class ProductCatalog {

    private static final Map<Long, ProductDto> PRODUCTS = Map.of(
            1L, new ProductDto(1L, "Mechanical Keyboard", new BigDecimal("149.99")),
            2L, new ProductDto(2L, "Vertical Mouse", new BigDecimal("89.99")));

    public List<ProductDto> listAll() {
        return PRODUCTS.keySet().stream()
                .sorted()
                .map(PRODUCTS::get)
                .toList();
    }

    public Optional<ProductDto> findById(long id) {
        return Optional.ofNullable(PRODUCTS.get(id));
    }
}

package com.orderdesk;

import java.util.List;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/products")
public class ProductResource {

    private final ProductCatalog catalog;

    public ProductResource(ProductCatalog catalog) {
        this.catalog = catalog;
    }

    @GET
    public List<ProductDto> listProducts() {
        return catalog.listAll();
    }
}

Start dev mode:

./mvnw quarkus:dev

List products:

curl -s http://localhost:8080/products | jq

You should see two products with id, name, and price. Map.of is fine for lookup by id, but do not assume values() iteration order — sort keys (or use a LinkedHashMap) when the API must return a stable list. This is the sweet spot: small immutable carriers, no construction pipeline, no builder.

When the canonical constructor stops scaling

Real order DTOs grow. Cart submission, inventory confirmation, tax, shipping, fraud scoring, addresses — fields arrive in stages from different steps. The record still fits as the immutable result:

package com.orderdesk;

import java.math.BigDecimal;
import java.time.Instant;
import java.util.List;

public record OrderDto(
        String orderId,
        String customerId,
        List<ProductDto> products,
        BigDecimal subtotal,
        BigDecimal tax,
        BigDecimal shipping,
        BigDecimal total,
        String currency,
        String shippingAddress,
        String billingAddress,
        String status,
        Integer fraudScore,
        Instant createdAt
) {
    public OrderDto {
        if (orderId == null || orderId.isBlank()) {
            throw new IllegalArgumentException("orderId must not be blank");
        }
    }
}

The compact constructor is the right place for single-field invariants that must hold on every instance. Cross-field rules like subtotal matching line items or shipping being required for physical goods deserve a different home, so we put those on the builder.

Calling new OrderDto(...) with a dozen positional arguments is where teams swap two String values and ship garbage. Named assembly fixes that without giving up record immutability.

OrderDtoBuilder

The builder is mutable scratch space. build() turns that scratch space into the record once, with validation and defensive copies:

package com.orderdesk;

import java.math.BigDecimal;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;

public class OrderDtoBuilder {

    private String orderId;
    private String customerId;
    private List<ProductDto> products = new ArrayList<>();
    private BigDecimal subtotal = BigDecimal.ZERO;
    private BigDecimal tax = BigDecimal.ZERO;
    private BigDecimal shipping = BigDecimal.ZERO;
    private BigDecimal total = BigDecimal.ZERO;
    private String currency = "EUR";
    private String shippingAddress;
    private String billingAddress;
    private String status = "CREATED";
    private Integer fraudScore = 0;
    private Instant createdAt = Instant.now();

    public OrderDtoBuilder orderId(String orderId) {
        this.orderId = orderId;
        return this;
    }

    public OrderDtoBuilder customerId(String customerId) {
        this.customerId = customerId;
        return this;
    }

    public OrderDtoBuilder addProduct(ProductDto product) {
        this.products.add(product);
        return this;
    }

    public OrderDtoBuilder subtotal(BigDecimal subtotal) {
        this.subtotal = subtotal;
        return this;
    }

    public OrderDtoBuilder tax(BigDecimal tax) {
        this.tax = tax;
        return this;
    }

    public OrderDtoBuilder shipping(BigDecimal shipping) {
        this.shipping = shipping;
        return this;
    }

    public OrderDtoBuilder total(BigDecimal total) {
        this.total = total;
        return this;
    }

    public OrderDtoBuilder currency(String currency) {
        this.currency = currency;
        return this;
    }

    public OrderDtoBuilder shippingAddress(String shippingAddress) {
        this.shippingAddress = shippingAddress;
        return this;
    }

    public OrderDtoBuilder billingAddress(String billingAddress) {
        this.billingAddress = billingAddress;
        return this;
    }

    public OrderDtoBuilder status(String status) {
        this.status = status;
        return this;
    }

    public OrderDtoBuilder fraudScore(Integer fraudScore) {
        this.fraudScore = fraudScore;
        return this;
    }

    List<ProductDto> productsSnapshot() {
        return List.copyOf(products);
    }

    BigDecimal totalSnapshot() {
        return total;
    }

    public OrderDto build() {
        if (customerId == null || customerId.isBlank()) {
            throw new IllegalStateException("Customer ID is required");
        }

        if (products.isEmpty()) {
            throw new IllegalStateException("At least one product is required");
        }

        if (orderId == null || orderId.isBlank()) {
            throw new IllegalStateException("Order ID is required");
        }

        return new OrderDto(
                orderId,
                customerId,
                List.copyOf(products),
                subtotal,
                tax,
                shipping,
                total,
                currency,
                shippingAddress,
                billingAddress,
                status,
                fraudScore,
                createdAt);
    }
}

.shipping(new BigDecimal("9.99")) is easier to read at 2am than the seventh anonymous argument to a constructor. Defaults like currency = "EUR" and status = "CREATED" live in one place instead of spreading across call sites.

Staged enrichment with OrderAssemblyService

This is the part records do not solve on their own. One builder instance walks through inventory, pricing, shipping, and fraud enrichment before build() freezes the record.

package com.orderdesk;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.UUID;

import org.jboss.logging.Logger;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class OrderAssemblyService {

    private static final Logger LOG = Logger.getLogger(OrderAssemblyService.class);

    private static final BigDecimal TAX_RATE = new BigDecimal("0.19");
    private static final BigDecimal SHIPPING_FLAT = new BigDecimal("9.99");

    private final ProductCatalog catalog;

    public OrderAssemblyService(ProductCatalog catalog) {
        this.catalog = catalog;
    }

    public OrderDto buildSampleOrder(String orderId) {
        ProductDto keyboard = catalog.findById(1L).orElseThrow();
        ProductDto mouse = catalog.findById(2L).orElseThrow();

        OrderDtoBuilder builder = new OrderDtoBuilder()
                .orderId(orderId)
                .customerId("customer-42")
                .addProduct(keyboard)
                .addProduct(mouse)
                .shippingAddress("Main Street 10")
                .billingAddress("Main Street 10");

        applyInventory(builder);
        applyPricing(builder);
        applyShipping(builder);
        applyFraud(builder);

        return builder.build();
    }

    public OrderDto assembleFromRequest(CreateOrderRequest request) {
        OrderDtoBuilder builder = new OrderDtoBuilder()
                .orderId(UUID.randomUUID().toString())
                .customerId(request.customerId())
                .shippingAddress(request.shippingAddress())
                .billingAddress(request.shippingAddress());

        for (Long productId : request.productIds()) {
            ProductDto product = catalog.findById(productId)
                    .orElseThrow(() -> new IllegalArgumentException("Unknown product: " + productId));
            builder.addProduct(product);
        }

        applyInventory(builder);
        applyPricing(builder);
        applyShipping(builder);
        applyFraud(builder);

        OrderDto order = builder.build();
        LOG.infof("Assembled order %s for customer %s", order.orderId(), order.customerId());
        return order;
    }

    private void applyInventory(OrderDtoBuilder builder) {
        builder.status("INVENTORY_CONFIRMED");
        LOG.debug("Inventory enrichment applied");
    }

    private void applyPricing(OrderDtoBuilder builder) {
        BigDecimal subtotal = builder.productsSnapshot().stream()
                .map(ProductDto::price)
                .reduce(BigDecimal.ZERO, BigDecimal::add);
        BigDecimal tax = subtotal.multiply(TAX_RATE).setScale(2, RoundingMode.HALF_UP);
        BigDecimal totalBeforeShipping = subtotal.add(tax);

        builder.subtotal(subtotal).tax(tax).total(totalBeforeShipping).status("PRICED");
        LOG.debugf("Pricing enrichment applied: subtotal=%s tax=%s", subtotal, tax);
    }

    private void applyShipping(OrderDtoBuilder builder) {
        BigDecimal totalWithShipping = builder.totalSnapshot().add(SHIPPING_FLAT);
        builder.shipping(SHIPPING_FLAT).total(totalWithShipping).status("SHIPPING_QUOTED");
        LOG.debug("Shipping enrichment applied");
    }

    private void applyFraud(OrderDtoBuilder builder) {
        int score = builder.totalSnapshot().compareTo(new BigDecimal("200")) > 0 ? 12 : 5;
        builder.fraudScore(score).status("READY");
        LOG.debugf("Fraud enrichment applied: score=%d", score);
    }
}

Each apply* method stands in for another service in a larger system. The builder is the assembly boundary. The record is what you hand back to REST or messaging once the work is done.

Order endpoints

package com.orderdesk;

import org.eclipse.microprofile.config.inject.ConfigProperty;

import jakarta.validation.Valid;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
public class OrderResource {

    private final OrderAssemblyService assemblyService;
    private final String sampleOrderId;

    public OrderResource(
            OrderAssemblyService assemblyService,
            @ConfigProperty(name = "orderdesk.sample-order-id", defaultValue = "ORD-2026-001") String sampleOrderId) {
        this.assemblyService = assemblyService;
        this.sampleOrderId = sampleOrderId;
    }

    @GET
    @Path("/sample")
    public OrderDto sampleOrder() {
        return assemblyService.buildSampleOrder(sampleOrderId);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public OrderDto createOrder(@Valid CreateOrderRequest request) {
        return assemblyService.assembleFromRequest(request);
    }
}

Optional config in application.properties keeps the sample order id stable in logs:

orderdesk.sample-order-id=ORD-2026-001

Fetch the sample order:

curl -s http://localhost:8080/orders/sample | jq '.orderId, .status, .total'

Expect ORD-2026-001, READY, and a computed total that includes tax and flat shipping.

Validated request records

Ingress DTOs are usually the easy case: immutable data carriers with validation at the edge. Bean Validation annotations on record components work the same as on classes:

package com.orderdesk;

import java.util.List;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;

public record CreateOrderRequest(
        @NotBlank String customerId,
        @NotEmpty List<Long> productIds,
        @NotBlank String shippingAddress
) {
}

Create an order:

curl -s -X POST http://localhost:8080/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer-77",
    "productIds": [1],
    "shippingAddress": "Tech Street 42"
  }' | jq '.customerId, .status, .products | length'

Send an empty payload and Quarkus returns HTTP 400 with constraint violations before your assembly service gets a chance to build anything.

Where builders are overkill

A builder on a three-field ProductDto buys you very little. There are no staged steps, no cross-field rules, and no enrichment pipeline. Use the record constructor and move on.

My rule of thumb:

• Small immutable DTO → record only

• Staged or multi-step construction → record + builder (or factory) at the assembly boundary

• Mutable domain object → regular class

• ORM entity → regular class, separate from API DTOs

Wrapper records like record CustomerId(String value) help when several String parameters would otherwise look identical to the compiler. They are cheap insurance on large payloads; this sample keeps plain strings so the builder contrast stays obvious.

Under load and across versions

Thread confinement — create a new OrderDtoBuilder per request. Builders are mutable scratch pads. Putting one in an @ApplicationScoped bean and reusing it across threads will leak order state between customers. I have seen the same failure mode with reusable JAXB builders years ago; the shape changes, the bug does not.

Validation boundaries — record compact constructors for invariants that must hold on every instance. Builders for cross-field assembly rules before the record exists. Bean Validation on ingress records for wire-format constraints. If you force all three concerns into one constructor, the result usually reads like a bug report.

DTO evolution — records are strict. When upstream APIs add fields gradually, builders absorb defaults and optional steps more gracefully than widening every new OrderDto(...) call site.

Jackson — records serialize cleanly in current Quarkus. Builders still help when you normalize inconsistent external JSON into one internal DTO shape before build().

Prove it

Run the test suite:

./mvnw test

Seven tests cover builder invariants, record compact-constructor rejection, product listing, sample order shape, successful POST assembly, and validation failures on bad POST bodies.

Manual smoke checks while quarkus:dev is running:

curl -s http://localhost:8080/products
curl -s http://localhost:8080/orders/sample
curl -s -X POST http://localhost:8080/orders \
  -H "Content-Type: application/json" \
  -d '{"customerId":"","productIds":[],"shippingAddress":""}'

The last call should return 400, not a half-built order.

Closing

Records removed most of the DTO boilerplate I used to carry. Careful construction still matters when objects grow, enrich in stages, or need defaults and cross-field checks before they exist.

OrderDesk is intentionally small: records for the simple shapes, a builder at the assembly boundary, validation split across ingress annotations, builder build(), and the record compact constructor. That split is the point.

The finished sample lives in the orderdesk-records-builders repository.

Subscribe now

That line sounds clean and authoritative. It also hides most of the detail developers actually need.

In an IDE, language support has visible edges. Java support means parsers, navigation, refactoring, formatting, debugger integration, build awareness, and at least some framework understanding. When the support is thin, the editor embarrasses itself in public.

Code LLMs work on a looser boundary. A model can read the source text, imitate the syntax, and still feel unreliable once the task moves past a short example. That is where the confusion starts. A first demo in Kotlin or COBOL or PL/SQL often works well enough to create optimism. Then the real repository shows up. Imports drift. Framework habits disappear. The agent invents APIs, rewrites build files like it met Maven five minutes ago, or writes Java that reads like Python wearing office clothes.

So the real question is not “does the model support my language?” It is “which layers of support am I actually getting?”

For code LLMs, language support is a stack. The tokenizer has to represent the source efficiently. The training data has to include enough examples to build real patterns. The benchmark has to measure something close to your work. The agent stack has to recover the right files, builds, generated sources, and framework context. By the time a vendor compresses all of that into one word, most of the useful signal is gone.

The Tokenizer Sets the Floor

The tokenizer is the first bottleneck.

Before the model can reason about code, it has to see code as tokens. Common fragments in popular languages usually collapse into efficient token sequences because they appear over and over in tokenizer training and model pretraining. Rare constructs get split into smaller and noisier pieces, which means the same source file burns more context window and arrives at the model with weaker internal structure.

You feel that cost quickly. Long files become harder to hold together. Cross-file reasoning gets shakier. Identifiers start drifting. Odd syntax grows brittle. The model may still “know” the language in the loose marketing sense, but it knows it through poorer building blocks.

This explains some surprisingly uneven behavior. Two languages can have roughly similar training exposure and still feel very different in practice because one of them is more expensive for the tokenizer to represent. Shared structure helps too. A model with heavy Java exposure often does better in Kotlin than you would guess from Kotlin’s share alone because the type system, package layout, inheritance patterns, and framework habits overlap. That transfer fades once you move into languages with different shapes and different idioms.

If I were evaluating a new coding model, I would start here. Paste a real file, not a neat sample, and see how the system behaves once the source gets long, dense, and slightly ugly.

Benchmarks Explain a Lot of the Overconfidence

The benchmark story matters because it trained the whole industry to talk about code ability in a very narrow way.

HumanEval gave the field an early focal point: 164 handwritten Python tasks scored by whether generated answers passed the tests. It taught everyone to celebrate a kind of success that maps poorly to enterprise development. HumanEval says a lot about short function synthesis. It says very little about framework habits, repository structure, build logic, or safe multi-file edits.

The benchmark picture is broader now. MultiPL-E expanded evaluation across languages. RepoBench pushed toward repository-level completion. SWE-bench, SWE-bench Multilingual, and Multi-SWE-bench all move closer to actual software engineering work.

The most relevant example for this article is Tencent Hunyuan’s AutoCodeBench. The project describes a full set with 3,920 problems spread evenly across 20 programming languages, plus lighter and completion-style subsets. That balanced coverage already makes it more useful for language-support discussions than the older Python-centered staples. The associated ICLR 2026 paper also groups Java with Python, C++, and C# in its “popular languages” slice, then compares that group with lower-resource languages such as Racket, Shell, Elixir, and TypeScript.

That split surfaces two different truths at once. First, multilingual balance matters. Python-only comfort scores hide a lot. Second, even a stronger multilingual benchmark still measures a particular kind of coding work. AutoCodeBench covers more languages and raises the difficulty, but it remains a code-generation benchmark. It tells you more about benchmark Java than about enterprise Java.

That difference matters because Java usually looks healthier at the syntax and algorithm level than it does in a real service repository.

Java Is Where the Gap Becomes Obvious

Java gives vendors a flattering place to stand.

Models usually learn enough Java syntax to look competent early. The language is common, verbose in a helpful way, and heavily represented in public code. A model can post respectable results on a multilingual benchmark and still feel clumsy inside a Quarkus or Spring codebase a few minutes later.

Enterprise Java raises the bar in a very ordinary way. The hard part is not writing a class with the right braces. The hard part is fitting that class into CDI scopes, REST conventions, serialization behavior, annotation processors, test slices, generated sources, Maven or Gradle rules, extension configuration, and the local conventions the team built over time. A Quarkus service is Java plus a build model plus a runtime model plus a pile of framework habits that only make sense together.

That is why Java needs its own paragraph in this discussion. A benchmark that says “the model is decent at Java” can still be completely consistent with an engineer saying “this thing keeps producing awkward Quarkus code.” Those statements describe different levels of the ladder. One is language-level code generation. The other is ecosystem-level work in a repository that has history, tooling, and consequences.

Don’t forget to read more about the Quarkus Agent MCP in my earlier article:

I see weak Java support show up less as loud failure and more as code that technically works while feeling wrong. Wrong annotations. Strange dependency choices. Reinvented framework features. Methods that compile and quietly ignore the architectural shape around them. That kind of output is annoying because it looks finished right up until somebody has to maintain it.

Agents Changed What “Support” Means

The base model still matters, but the surrounding stack now shapes the developer experience just as much.

A modern coding agent usually wraps the model with repository indexing, retrieval, syntax repair, AST parsing, build inspection, semantic search, diff awareness, and sometimes framework-specific helpers. Developers experience all of that as one tool, which means language support has become a property of the system, not just the model.

This is why two tools built on similar foundation models can feel wildly different in the same language. If one agent can inspect the build, trace imports, pull the right sibling files, and recognize generated sources before it writes a diff, the language suddenly feels much better supported. The model did not become wiser in the abstract. The system simply stopped asking it to guess so much.

Java benefits from that stack more than most marketing copy admits. A modest model with strong repository tooling can feel better in a Quarkus codebase than a stronger raw model that only sees the current file. That is also why language-support claims should be evaluated at system level. “Is this model good at Java?” is usually too small a question. “Can this toolchain help my team change Java code safely?” is much closer to the real one.

I Prefer a Support Ladder to a Checkbox

The cleanest way to talk about this is as a ladder.

1. Tokenizable
   The system can ingest the source text and produce syntax-shaped output.

2. Snippet-capable
   It handles small isolated tasks, boilerplate, local completions, and benchmark-style functions reasonably well.

3. Ecosystem-capable
   It works with mainstream frameworks, builds, tests, and repository conventions in a way that feels idiomatic rather than uncanny.

4. Workflow-capable
   It survives long files, cross-file edits, refactors, generated code, build logic, and architectural consistency with a low enough error rate that you would trust it in serious work.

Most vendor claims stop around level one or two and borrow the emotional confidence of level three or four. That is the whole problem.

Very few systems live at the top of this ladder across many languages. When they get close, they usually arrive with a lot of help: better retrieval, tighter workflows, language-aware tooling, fine-tuning, and careful context construction.

How I Would Evaluate Language Support

I would test five things.

1. Real-file behavior
   Paste production code, let the file get long, and watch for identifier drift, repeated fragments, truncation, or unstable completions.

2. Fill-in-the-middle editing
   Ask the agent to complete a method inside an existing file while preserving style, imports, and the surrounding abstraction.

3. Framework fit
   Make it touch the ecosystem that matters to your team: Quarkus CDI, Spring configuration, JPA mappings, Gradle or Maven, serializers, test fixtures, generated code.

4. Multi-file reasoning
   Have it trace behavior across modules, update several files, and keep the interfaces intact.

5. Refactoring discipline
   Ask for a change that needs restraint: rename an abstraction, migrate an API, keep the tests passing, avoid gratuitous build churn.

Java deserves special treatment in this evaluation because the difference between “can write Java” and “can work in our Java system” is often huge. I would always include the build file, the framework configuration, and at least one generated or framework-owned edge in the test. Otherwise the evaluation stops right before the interesting part.

What To Do When Support Feels Thin

Thin support usually means the base model is carrying work that should have been distributed across the rest of the stack.

Better retrieval is usually the fastest improvement. When the system can pull the right interfaces, configs, generated sources, and neighboring files, a merely decent model often becomes much more useful because it stops improvising key details.

Language-aware tools help too. Build inspectors, AST tooling, language servers, test runners, framework detectors, and repository summaries can carry a lot of the burden that teams currently describe as “the model understanding Java.”

Fine-tuning or adapters also make sense when the underlying model is already close and the real gap sits around internal frameworks, modernization patterns, or house conventions. That path is a lot more practical than hoping one general model will absorb every proprietary DSL and every local habit by osmosis.

Context construction deserves more attention as well. A lot of supposed language weakness is really missing-context weakness. The model never saw the build file, the generated source, the parent abstraction, or the one configuration class that explains the rest of the service. The bug gets filed under “Java support” anyway because that is the label people have available.

The Sentence I Wish Vendors Would Use

Here is the version I would trust more:

This system reads the language, performs well on small benchmark tasks, has uneven framework depth, and becomes much more useful when paired with retrieval and tooling tuned to your repository.

That sentence has less marketing lift, but it describes the world developers actually live in.

For enterprise teams, the real issue is workflow support. Your files, your builds, your frameworks, your refactors, your generated sources, your failure modes, and your maintenance burden after the demo glow wears off. Once you look at language support through that lens, a lot of strange agent behavior becomes easier to explain. You are usually looking at partial support wearing the confidence of full support.

Subscribe now

That preference is not nostalgia. It is usually a reaction to avoidable complexity. A lot of internal tools, back-office systems, dashboards, and workflow UIs do not need a full client-side state machine plus a small museum of JavaScript build tooling. They need to load fast, render predictably, and let the backend keep most of the application logic where the backend team can actually maintain it.

Quarkus is unusually good at this style when you combine Qute, HTMX, SSE, and a little discipline. This page gathers the relevant articles into one path so readers can move from “server-rendered UI sounds interesting” to “I can build a real interface this way and not feel embarrassed by it.”

Why I still like server-rendered UI

The strongest argument is not that JavaScript is bad. JavaScript is fine. The stronger argument is that many teams keep paying frontend complexity costs for features that never needed that level of machinery in the first place.

If your UI mostly shows data, collects input, performs searches, paginates lists, streams a few updates, and needs sane HTML semantics, a server-rendered approach can be both faster to build and easier to reason about. The trade-off is that you need to be deliberate about templates, fragment reuse, and small interaction patterns. That is where this cluster helps.

Start with the pieces that make the approach feel real

I would begin with the posts that show the core stack plainly instead of treating it like a retro curiosity.

• HTMX with Quarkus for server-rendered UI is the natural starting point because it makes the interaction model concrete

• Qute type-safe templating matters early, because maintainable templates beat clever templates every time

• Lean business UI with Quarkus Qute and no JavaScript is where the approach stops sounding theoretical and starts sounding like a reasonable platform choice

That trio gives you the baseline: render HTML on the server, use HTMX for targeted interaction, and keep the template layer honest enough that refactors do not become archaeology.

Real interfaces live or die on composition

A lot of server-rendered demos look nice until the second page. Then shared layout, nested fragments, breadcrumbs, and error handling show up, and suddenly the “simple” stack needs adult supervision.

That is why I would move next into the composition and navigation posts:

• Qute dynamic includes helps when the page is no longer one static template

• Qute dynamic breadcrumb is small, but it solves the sort of repeated UI problem that tells you whether the stack still feels pleasant after a week

• Custom error pages with REST and Qute matters because polished happy paths are easy and production errors are where interfaces become memorable for the wrong reason

This part of the cluster is less flashy, which is exactly why it matters. Mature UI stacks are usually decided by how they handle repeated structure and awkward edges, not by how elegant the first demo looked on a Friday afternoon.

Interaction does not need a giant frontend rewrite

The usual objection is that server-rendered UI cannot stay interactive enough. I think that objection is often based on a stale mental model.

You can do a lot with targeted partial updates, infinite scroll, streaming events, and a few carefully chosen endpoints. You do not need to rebuild the web every time a list grows longer than one page.

This set makes that case well:

• Cursor pagination with infinite scroll shows the simple version

• Cursor pagination, full-text search, and infinite scroll pushes the pattern into a more realistic data-heavy flow

• Real-time ISS tracker with SSE and Qute adds streaming updates without dragging the whole architecture into SPA territory

For me, this is the part where server-rendered UI stops being a style preference and becomes a practical engineering option. Once you see live updates and richer search flows handled this way, the “you obviously need a huge frontend framework” reflex starts looking less obvious.

There is still room for bigger abstractions when you need them

Not every reader wants the lightest possible stack. Some want more framework help. Some are migrating from Spring MVC. Some want a fuller web app feel with routing and conventions already in place.

That is where these articles fit:

• Spring Boot to Quarkus with Qute is the bridge if your team still thinks in Spring web terms

• Quarkus Renarde full-stack Java web tutorial is useful when you want a more opinionated web layer on top of the same general philosophy

• Build a Twitter clone with Quarkus, Kafka, and Qute is a bigger example for readers who need proof that the approach scales past toy screens

I like having these in the cluster because they keep the conversation honest. The choice is not between “plain HTML forever” and “single-page app for everything.” There is a middle ground, and Quarkus gives you several ways to stand there comfortably.

The reading order I would use

If I were building a serious server-rendered UI path for Quarkus readers, I would use this order:

1. HTMX with Quarkus for server-rendered UI

2. Qute type-safe templating

3. Lean business UI with Quarkus Qute and no JavaScript

4. Qute dynamic includes

5. Qute dynamic breadcrumb

6. Custom error pages with REST and Qute

7. Cursor pagination with infinite scroll

8. Cursor pagination, full-text search, and infinite scroll

9. Real-time ISS tracker with SSE and Qute

If your team is migrating from Spring, read the Spring migration piece after the first three. If your team wants a fuller framework opinion, bring Renarde in sooner.

What this cluster is trying to prove

I want readers to come away with a much simpler idea than “Qute versus React” or “HTMX versus JavaScript.” Those comparisons get noisy fast and they often miss the point.

The better question is this: what is the cheapest architecture that still gives you a clear, maintainable, responsive interface for the job in front of you? For a surprising number of business applications, the answer is still server-rendered HTML with a few smart interaction patterns and a backend that owns its behavior openly. Quarkus is very good at that kind of work, and this cluster should make the case without treating plain HTML like a guilty secret.

Subscribe now

Quarkus has had graceful shutdown settings for a while. In Quarkus 3.32 the HTTP stack got a meaningful upgrade (PR #50975): during shutdown it tries to answer requests instead of spraying 503 at everything. That helps. It does not replace the deploy protocol you still need: fail readiness, stop new traffic, let in-flight HTTP finish, then exit.

We build OrderBridge, a tiny payment handoff API, then prove shutdown behavior with a script that keeps a long request in flight while the JVM receives SIGTERM. The sample uses Quarkus 3.35.2.

What we build

OrderBridge is a small service that:

• exposes GET /orders/{id} for a quick status check;

• exposes POST /orders/handoff that simulates a five-second payment gateway call;

• exposes SmallRye Health liveness and readiness on /q/health/live and /q/health/ready;

• logs startup, shutdown delay, and shutdown events;

• ships two Quarkus profiles: naive (defaults) and graceful (timeout + delay);

• includes a bash script that terminates the packaged app mid-handoff so you can see the difference.

What you need

I assume you have shipped Jakarta REST apps and have seen Kubernetes readiness probes in the wild. This is not a hello-world.

• JDK 21

• Quarkus CLI or Maven

• curl and bash for the shutdown script

• About 40 minutes

Project setup

Create the project:

quarkus create app com.orderbridge:orderbridge-graceful-shutdown \
  --extension='rest-jackson,smallrye-health' \
  --java=21 \
  --no-code
cd orderbridge-graceful-shutdown

Extensions:

• rest-jackson — JSON endpoints and the HTTP stack that participates in graceful shutdown

• smallrye-health — readiness and liveness probes

Use package com.orderbridge for application code.

Add the Maven wrapper from the Quarkus getting started guide if your tree does not already include ./mvnw, or clone the finished sample linked at the end.

Order status and payment handoff

Payment handoffs are the interesting case: they run for seconds while deploys happen for seconds. A fast status endpoint gives us something cheap to hit while the slow one is in flight.

DTO records

package com.orderbridge;

public record HandoffRequest(String orderId, long amountCents) {
}

package com.orderbridge;

public record HandoffResult(String orderId, String status, long elapsedMs) {
}

package com.orderbridge;

public record OrderStatus(String orderId, String status) {
}

OrderService

The handoff sleeps to mimic an external gateway. Production code should use timeouts, cancellation, and idempotency keys — not Thread.sleep. For teaching shutdown, sleep is honest about “long request in flight.”

package com.orderbridge;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.jboss.logging.Logger;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class OrderService {

    private static final Logger LOG = Logger.getLogger(OrderService.class);

    private final Map<String, String> statuses = new ConcurrentHashMap<>();

    @ConfigProperty(name = "orderbridge.handoff.delay-ms", defaultValue = "5000")
    long handoffDelayMs;

    public OrderStatus status(String orderId) {
        String status = statuses.getOrDefault(orderId, "CREATED");
        return new OrderStatus(orderId, status);
    }

    public HandoffResult handoff(HandoffRequest request) {
        long started = System.currentTimeMillis();
        LOG.infof("Starting payment handoff for order %s", request.orderId());
        statuses.put(request.orderId(), "HANDOFF_IN_PROGRESS");

        try {
            Thread.sleep(handoffDelayMs);
        } catch (InterruptedException interrupted) {
            Thread.currentThread().interrupt();
            statuses.put(request.orderId(), "HANDOFF_INTERRUPTED");
            throw new IllegalStateException("Payment handoff interrupted during shutdown", interrupted);
        }

        statuses.put(request.orderId(), "HANDOFF_COMPLETE");
        long elapsedMs = System.currentTimeMillis() - started;
        LOG.infof("Payment handoff complete for order %s in %d ms", request.orderId(), elapsedMs);
        return new HandoffResult(request.orderId(), "HANDOFF_COMPLETE", elapsedMs);
    }
}

OrderResource

package com.orderbridge;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class OrderResource {

    private final OrderService orderService;

    public OrderResource(OrderService orderService) {
        this.orderService = orderService;
    }

    @GET
    @Path("/{id}")
    public OrderStatus get(@PathParam("id") String orderId) {
        return orderService.status(orderId);
    }

    @POST
    @Path("/handoff")
    public HandoffResult handoff(HandoffRequest request) {
        return orderService.handoff(request);
    }
}

Base configuration

In src/main/resources/application.properties:

orderbridge.handoff.delay-ms=5000

%script.quarkus.http.port=18080
%script.quarkus.log.console.level=INFO

%graceful.quarkus.shutdown.timeout=15s
%graceful.quarkus.shutdown.delay-enabled=true
%graceful.quarkus.shutdown.delay=5s

%test.orderbridge.handoff.delay-ms=100
%test.quarkus.shutdown.timeout=30s
%test.quarkus.shutdown.delay-enabled=true
%test.quarkus.shutdown.delay=2s

The script profile pins port 18080 so our shutdown script does not fight dev mode on 8080. The graceful profile turns on the shutdown recipe we want in production. Tests use a 100 ms handoff so ./mvnw test stays snappy.

Run dev mode and try the endpoints:

./mvnw quarkus:dev

curl -s http://localhost:8080/orders/ORD-1
curl -s -X POST http://localhost:8080/orders/handoff \
  -H 'Content-Type: application/json' \
  -d '{"orderId":"ORD-1","amountCents":2500}'

The handoff blocks for about five seconds, then returns "status":"HANDOFF_COMPLETE".

Readiness vs liveness during shutdown

Liveness answers: is the process alive? If this fails, Kubernetes restarts the pod.

Readiness answers: should traffic be sent here? If this fails, the pod stays running but is removed from Service endpoints.

During a rolling update, you want readiness to flip DOWN while the instance can still finish work it already accepted. That is exactly what Quarkus shutdown delay is for. The lifecycle guide describes a delay window where HTTP still runs, but readiness reports down so orchestrators and load balancers stop sending new connections.

Check probes manually:

curl -s http://localhost:8080/q/health/live
curl -s http://localhost:8080/q/health/ready

While the app is running, both return "status":"UP".

See naive shutdown hurt the client

With no quarkus.shutdown.timeout and no delay, Quarkus does not wait for your handoff the way you expect. The server log may still show “handoff complete,” while the client sees a dead connection.

The module ships scripts/demonstrate-shutdown.sh. It packages the app, starts the JVM, fires a long POST /orders/handoff, sends SIGTERM, and polls readiness.

Run the naive profile (script port only — no graceful settings):

./scripts/demonstrate-shutdown.sh naive

On my machine the handoff line looked like:

handoff HTTP 000 (total 0.521690s)

HTTP 000 means curl never got a response — connection gone. The log often still shows the handoff finishing a few seconds later, which is the frustrating split-brain: server thought it was fine, client already gave up.

That is the bug we are fixing: shutdown was never part of the contract we tested.

Add quarkus.shutdown.timeout

quarkus.shutdown.timeout is a runtime setting. When set, Quarkus waits for active HTTP requests to complete before tearing down, up to the limit. The lifecycle guide documents it; it is off by default.

Add only the timeout first (you can use a throwaway profile or add it to %graceful later):

quarkus.shutdown.timeout=15s

Too short — in-flight handoffs get cut off; clients see resets or errors even though the pod had time to drain.

Too long — deploys stall because Kubernetes will eventually send SIGKILL when terminationGracePeriodSeconds runs out.

Fifteen seconds is generous for our five-second fake gateway, but it leaves headroom for real network jitter.

Enable shutdown delay (readiness first)

Timeout alone does not tell the load balancer to stop new traffic early. For that you need delay:

• quarkus.shutdown.delay-enabled=true — build time. You must package the app with this set; flipping it only at runtime is not enough.

• quarkus.shutdown.delay — runtime duration of the pre-shutdown phase.

Our %graceful profile sets:

%graceful.quarkus.shutdown.timeout=15s
%graceful.quarkus.shutdown.delay-enabled=true
%graceful.quarkus.shutdown.delay=5s

Package with the graceful profile baked in:

./mvnw package -DskipTests -Dquarkus.profile=graceful,script

What happens on SIGTERM with delay enabled:

1. Delay phase starts. Readiness goes DOWN (SmallRye reports a Graceful Shutdown check).

2. Existing connections can still complete work.

3. After the delay, Quarkus moves toward full shutdown, honoring quarkus.shutdown.timeout for active HTTP.

4. Process exits.

Run the script in graceful mode:

./scripts/demonstrate-shutdown.sh graceful

Excerpt from a successful run:

-- Readiness before shutdown: UP --
ready HTTP 200
-- Polling readiness during shutdown --
[15:24:23] readiness HTTP 503
[15:24:24] readiness HTTP 503
...
-- Handoff result --
{"orderId":"ORD-SHUTDOWN","status":"HANDOFF_COMPLETE","elapsedMs":5003}
handoff HTTP 200 (total 5.101526s)

Readiness flips to 503 while the handoff still returns 200. That is the protocol you want: orchestrator sees “not ready,” client already in flight gets an answer.

Lifecycle hooks for visibility

Observers make the sequence visible in logs — useful when someone swears “readiness failed too early.”

package com.orderbridge;

import org.jboss.logging.Logger;

import io.quarkus.runtime.ShutdownEvent;
import io.quarkus.runtime.StartupEvent;
import io.quarkus.runtime.ShutdownDelayInitiatedEvent;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;

@ApplicationScoped
public class ShutdownLifecycle {

    private static final Logger LOG = Logger.getLogger(ShutdownLifecycle.class);

    void onStart(@Observes StartupEvent event) {
        LOG.info("OrderBridge is ready to accept traffic");
    }

    void onShutdownDelay(@Observes ShutdownDelayInitiatedEvent event) {
        LOG.info("Shutdown delay started — readiness should fail while HTTP still winds down");
    }

    void onStop(@Observes ShutdownEvent event) {
        LOG.info("OrderBridge shutdown event fired");
    }
}

You can use @ShutdownDelayInitiated on a method instead of the event observer; behavior is the same. Methods marked that way run when delay starts — keep them fast, because they participate in the shutdown path.

In graceful mode you should see Shutdown delay started before OrderBridge shutdown event fired, and SmallRye log lines like Reporting health down status with a Graceful Shutdown check.

Kubernetes timing that actually matches Quarkus

Quarkus only controls what happens inside the pod after SIGTERM. Your platform still needs enough time and sensible probes.

terminationGracePeriodSeconds — must be at least delay + timeout + buffer. With our example (5s delay + 15s timeout), I would not go below 25s; 30s is a comfortable default.

Readiness probe periodSeconds and failureThreshold — control how quickly the Service removes the pod from endpoints. If the probe period is 10s and threshold is 3, it can take ~30s before Kubernetes stops routing even after readiness is DOWN. Align that with how fast your ingress or service mesh drains.

preStop hooks — optional sleep can help legacy load balancers that ignore readiness. Prefer fixing probe and delay alignment first; arbitrary sleep 15 in preStop hides misconfiguration.

Liveness during shutdown — do not point liveness at something that fails during graceful drain unless you want the kubelet to restart a pod that is intentionally winding down.

What graceful shutdown does not cover

The lifecycle guide is explicit: only extensions that opt in participate. Today the documented graceful path is HTTP. Kafka consumers, scheduled jobs, and background queues need their own drain story.

Long business work still needs application-level timeouts. quarkus.shutdown.timeout bounds how long Quarkus waits on HTTP; it does not make an unbounded database migration safe.

Native image and dev mode follow the same configuration ideas, but always re-run your shutdown script on the artifact you actually deploy.

Prove it

Unit and resource tests:

./mvnw test

Integration test against the packaged runner:

./mvnw verify

Shutdown demonstrations:

./scripts/demonstrate-shutdown.sh naive
./scripts/demonstrate-shutdown.sh graceful

Expect naive mode to show readiness dropping only when the process is already gone, and the handoff client to fail often. Expect graceful mode to show readiness 503 for several seconds and the handoff to finish with HTTP 200.

Closing

Graceful shutdown in Quarkus is a small set of properties, but the real work is the deploy protocol: readiness fails first, new traffic stops, in-flight HTTP gets a bounded chance to finish, then the process exits. The 3.32 HTTP improvements reduce surprise 503 responses during that window; they do not remove the need for delay and timeout.

When you wire this into a real service, copy the recipe: enable delay at build time, set delay and timeout for your slowest acceptable request, align Kubernetes termination and probes, and keep a script like ours that proves behavior under SIGTERM, not just in a happy-path integration test.

Source for the full sample lives in the orderbridge-graceful-shutdown repository.

Subscribe now

I do not think error handling is the glamorous part of API work. I do think it is one of the clearest ways to tell whether a team treats its API as a product or as a side effect. Good error responses shorten debugging, reduce support noise, and make clients simpler. Bad ones create folklore. Folklore always grows faster than docs.

This page pulls together the Quarkus pieces on API errors, HTTP responses, OpenAPI, versioning, and deprecation into one reading path. The common thread is simple: your API contract includes the unhappy path, and it gets expensive when you design that part last.

Start with the error contract, not the annotation pile

A lot of teams begin with framework mechanics. Which mapper should I write? Which exception class should I throw? Which annotation turns this into JSON?

Those are real implementation questions, but they come second. First you need to decide what a client can rely on when things go wrong. Is there a stable error shape? Are validation problems distinct from business conflicts? Can clients automate against the response, or do they need to guess from prose?

These are the right entry points:

• RFC 9457 API error handling in Quarkus is the central piece if you want a modern, explicit error format instead of improvised JSON

• Quarkus RFC 9457 API error handling is a good companion when you want the same topic from a slightly different angle

• Quarkus RFC 7807 error handling matters because many teams still encounter that terminology in existing systems and older discussions

• Mastering HTTP responses in Quarkus broadens the conversation beyond exceptions and into deliberate response design

If I had to collapse the whole cluster into one sentence, it would be this: treat error payloads as part of the interface, not as whatever falls out after a thrown exception.

Documentation and runtime behavior need to agree

One of the more annoying failure modes in API work is when the docs tell a cleaner story than the implementation. The OpenAPI spec shows one thing, Swagger UI suggests another, and the running service still finds a third option under pressure.

That gap is not cosmetic. If your contract only exists in generated documentation, consumers will learn the truth from production incidents instead.

This is where I would go next:

• OpenAPI and Quarkus for Java developers is the practical foundation for making the contract visible

• Springdoc vs Quarkus OpenAPI is helpful if your mental model still comes from the Spring world

• Implementing Zalando RESTful API guidelines pushes the conversation from “valid JSON” to “consistent platform behavior”

My bias here is boring consistency. I would rather ship a smaller API with one clear problem format, one predictable validation story, and one documented deprecation policy than a larger API that improvises every time it needs to say no.

The contract changes over time, which is where teams get sentimental

API versioning and deprecation discussions have a habit of becoming philosophical. They do not need to. The real question is usually much narrower: how do you evolve the contract without making client behavior weird, brittle, or expensive to support?

If your error story is already unstable, versioning gets even uglier because now both success and failure semantics can drift at the same time. That is how “backward compatible enough” becomes a quarterly ritual in damage control.

These pieces belong together:

• Quarkus API versioning strategies covers the mechanics and trade-offs of changing public contracts

• AI API versioning with Quarkus is worth reading if your endpoints front models or agentic workflows that change faster than the transport layer

• When to deprecate APIs in Java and Quarkus is the piece I would hand to anyone who thinks deprecation is just a note in a changelog

The trade-off is not between purity and pragmatism. The trade-off is between making change explicit now or paying for hidden inconsistency later. I prefer the first bill.

A useful API error stack has layers

By this point the cluster is really about four connected layers.

• Error shape gives clients something stable to parse

• HTTP response design keeps status codes and payload intent aligned

• OpenAPI and guidelines make the contract visible before runtime

• Versioning and deprecation keep that contract survivable after change

Miss one of those layers and the others start compensating badly. Teams without a stable error shape tend to over-explain in docs. Teams without decent docs tend to lean on tribal knowledge. Teams without deprecation discipline keep old client assumptions alive for much longer than anyone admits in architecture reviews.

That is why I like this cluster as a group instead of as isolated articles. Each post solves one slice. Together they describe what mature API behavior feels like.

The reading order I would use

If your team is still improvising error responses, I would read these in order:

1. RFC 9457 API error handling in Quarkus

2. Quarkus RFC 7807 error handling

3. Mastering HTTP responses in Quarkus

4. OpenAPI and Quarkus for Java developers

5. Implementing Zalando RESTful API guidelines

6. Quarkus API versioning strategies

7. When to deprecate APIs in Java and Quarkus

If you are migrating from Spring, move Springdoc vs Quarkus OpenAPI earlier. If your biggest pain is client churn, move versioning and deprecation earlier. The shape of the path can change. The basic idea should not.

What this cluster should change in practice

After working through this material, I want the team to stop saying “we handle errors” when what they really mean is “exceptions eventually become JSON.”

Good API design is quieter than that. Clients know what failed. The payload shape stays stable enough to automate against. Status codes carry real intent. Docs tell the same story as runtime behavior. Deprecations arrive with a plan instead of a shrug. That is the standard worth aiming for, and Quarkus gives you enough control to get there without turning the service into annotation archaeology.

Quarkus has been chipping away at that problem with build-time metaprogramming: generated StdSerializer implementations that write JSON without poking through DTO fields via reflection at runtime. Mario Fusco walked through the mechanics and the ~12% throughput lift on a synthetic benchmark in the metaprogramming blog post. For a long time, the feature stayed opt-in behind quarkus.rest.jackson.optimization.enable-reflection-free-serializers=true.

In April 2026 the team announced planned default enablement in Quarkus 3.35. That default did not flip in 3.35 after all. Community testing found edge cases, and the 3.35 release notes moved the change to 3.36. For now, the safe mental model is still opt-in migration plus contract tests, not “flip a version and hope.”

We make that migration concrete on a small catalog API: baseline Jackson, reflection-free serializers on a profile, JSON regressions for generics and polymorphism, and a repeatable benchmark harness.

The sample uses Quarkus 3.35.2. Re-check the REST guide after upgrades because serializer coverage is moving quickly.

What we build

We end up with CatalogAPI, a product catalog service that:

• exposes CRUD on /products backed by PostgreSQL (Dev Services in dev/test);

• returns record DTOs, a generic Page<T> envelope, and polymorphic catalog payloads;

• serializes a Money value type through a custom Jackson serializer registered with ObjectMapperCustomizer;

• runs the same JSON contract tests under baseline and reflection-free profiles;

• includes a script to compare cold startup and throughput between those profiles.

What you need

I assume you already write Jakarta REST resources and have shipped Jackson DTOs before. This is a migration tutorial, not a Jackson primer.

• JDK 21

• Quarkus CLI or Maven

• Docker or Podman if you want native image builds with containerized GraalVM

• Basic Jackson annotations (@JsonSubTypes, custom serializers)

• About 45 minutes

Project setup

Create the project:

quarkus create app com.catalogapi:catalogapi-reflection-free-jackson \
  --extension='quarkus-rest-jackson,hibernate-orm-panache,jdbc-postgresql,smallrye-openapi' \
  --java=21 \
  --no-code

We only need four extensions here:

• quarkus-rest-jackson — REST endpoints and the Jackson stack we are migrating

• hibernate-orm-panache and jdbc-postgresql — small realistic persistence layer

• smallrye-openapi — generated OpenAPI so the service looks like an internal API, not a toy benchmark

Use package com.catalogapi for application code and com.catalogapi.json for DTOs.

Catalog model and CRUD

Product entity

package com.catalogapi;

import io.quarkus.hibernate.orm.panache.PanacheEntity;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;

@Entity
public class Product extends PanacheEntity {

    @Column(nullable = false, unique = true)
    public String sku;

    @Column(nullable = false)
    public String name;

    @Column(nullable = false)
    public int priceCents;

    @Column(nullable = false)
    public String category;
}

Seed data

Create src/main/resources/import.sql:

INSERT INTO Product (id, sku, name, priceCents, category) VALUES (nextval('product_SEQ'), 'SKU-001', 'Mechanical Keyboard', 12999, 'peripherals');
INSERT INTO Product (id, sku, name, priceCents, category) VALUES (nextval('product_SEQ'), 'SKU-002', 'USB-C Hub', 4999, 'peripherals');
INSERT INTO Product (id, sku, name, priceCents, category) VALUES (nextval('product_SEQ'), 'SKU-003', '27-inch Monitor', 34999, 'displays');
INSERT INTO Product (id, sku, name, priceCents, category) VALUES (nextval('product_SEQ'), 'SKU-004', 'Desk Bundle', 52998, 'bundles');

Use nextval('product_SEQ') so Hibernate’s sequence stays aligned with fixed seed rows. If you only insert literal id values, the first persist() after startup can collide with the primary key.

Dev configuration

In application.properties:

%dev.quarkus.datasource.db-kind=postgresql
%dev.quarkus.hibernate-orm.database.generation=drop-and-create
%dev.quarkus.hibernate-orm.sql-load-script=import.sql

%test.quarkus.datasource.db-kind=h2
%test.quarkus.datasource.jdbc.url=jdbc:h2:mem:catalogtest;DB_CLOSE_DELAY=-1;MODE=PostgreSQL
%test.quarkus.hibernate-orm.schema-management.strategy=drop-and-create
%test.quarkus.hibernate-orm.sql-load-script=import.sql

Dev mode uses PostgreSQL Dev Services. Tests use in-memory H2, so ./mvnw test stays Docker-free on the machine running CI.

Product resource

package com.catalogapi;

import java.util.List;

import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

import com.catalogapi.json.ProductInput;

import jakarta.transaction.Transactional;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.PUT;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/products")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Tag(name = "Products")
public class ProductResource {

    @GET
    @Operation(summary = "List all products")
    public List<Product> list() {
        return Product.listAll();
    }

    @GET
    @Path("/{id}")
    @Operation(summary = "Get one product by id")
    public Product get(@PathParam("id") long id) {
        return Product.<Product>findByIdOptional(id)
                .orElseThrow(NotFoundException::new);
    }

    @POST
    @Transactional
    @Operation(summary = "Create a product")
    public Response create(ProductInput input) {
        Product product = new Product();
        product.sku = input.sku();
        product.name = input.name();
        product.priceCents = input.priceCents();
        product.category = input.category();
        product.persist();
        return Response.status(Response.Status.CREATED).entity(product).build();
    }

    @PUT
    @Path("/{id}")
    @Transactional
    @Operation(summary = "Update a product")
    public Product update(@PathParam("id") long id, ProductInput input) {
        Product product = Product.<Product>findByIdOptional(id)
                .orElseThrow(NotFoundException::new);
        product.sku = input.sku();
        product.name = input.name();
        product.priceCents = input.priceCents();
        product.category = input.category();
        return product;
    }
}

ProductInput is just a small record:

package com.catalogapi.json;

public record ProductInput(String sku, String name, int priceCents, String category) {
}

Prove CRUD

Start dev mode:

./mvnw quarkus:dev

List products:

curl -s http://localhost:8080/products | jq .

You should see the four seeded products. Fetch one next:

curl -s http://localhost:8080/products/1 | jq .

Expected shape:

{
  "id": 1,
  "sku": "SKU-001",
  "name": "Mechanical Keyboard",
  "priceCents": 12999,
  "category": "peripherals"
}

JSON edge cases worth testing before you flip the switch

Real services rarely stop at flat entities. CatalogAPI adds four patterns that tend to find serializer gaps quickly.

Record summaries with custom Money serialization

package com.catalogapi.json;

public record Money(String currency, long amountMinor) {
}

package com.catalogapi.json;

public record ProductSummary(long id, String sku, String name, Money price) {
}

package com.catalogapi.json;

import java.io.IOException;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.databind.SerializerProvider;
import com.fasterxml.jackson.databind.ser.std.StdSerializer;

public class MoneySerializer extends StdSerializer<Money> {

    public MoneySerializer() {
        super(Money.class);
    }

    @Override
    public void serialize(Money value, JsonGenerator generator, SerializerProvider serializers) throws IOException {
        generator.writeStartObject();
        generator.writeStringField("currency", value.currency());
        generator.writeNumberField("amountMinor", value.amountMinor());
        generator.writeStringField("display", value.currency() + " " + formatMinor(value.amountMinor()));
        generator.writeEndObject();
    }

    private static String formatMinor(long amountMinor) {
        long major = amountMinor / 100;
        long minor = Math.abs(amountMinor % 100);
        return major + "." + (minor < 10 ? "0" : "") + minor;
    }
}

Register the module at startup:

package com.catalogapi.jackson;

import com.catalogapi.json.Money;
import com.catalogapi.json.MoneySerializer;
import com.fasterxml.jackson.databind.module.SimpleModule;

import io.quarkus.jackson.ObjectMapperCustomizer;
import jakarta.inject.Singleton;

@Singleton
public class CatalogJacksonCustomizer implements ObjectMapperCustomizer {

    @Override
    public void customize(com.fasterxml.jackson.databind.ObjectMapper mapper) {
        SimpleModule module = new SimpleModule();
        module.addSerializer(Money.class, new MoneySerializer());
        mapper.registerModule(module);
    }
}

I keep the entity-to-summary mapping in a tiny helper:

package com.catalogapi;

import com.catalogapi.json.Money;
import com.catalogapi.json.ProductSummary;

final class ProductMapper {

    private ProductMapper() {
    }

    static ProductSummary toSummary(Product product) {
        return new ProductSummary(
                product.id,
                product.sku,
                product.name,
                new Money("USD", product.priceCents));
    }
}

Add toMoney next to toSummary in ProductMapper, then add two endpoints on ProductResource (imports for Page and ProductSummary are omitted below only where they are already on the class):

    @GET
    @Path("/summaries")
    @Operation(summary = "List product summaries as records with custom Money serialization")
    public List<ProductSummary> summaries() {
        return Product.<Product>listAll().stream()
                .map(ProductMapper::toSummary)
                .toList();
    }

    @GET
    @Path("/page")
    @Operation(summary = "Paged product summaries in a generic envelope")
    public Page<ProductSummary> page() {
        List<ProductSummary> items = Product.<Product>listAll().stream()
                .map(ProductMapper::toSummary)
                .toList();
        return new Page<>(items, items.size());
    }

With Page defined as:

package com.catalogapi.json;

import java.util.List;

public record Page<T>(List<T> items, int total) {
}

Checkpoint:

curl -s http://localhost:8080/products/summaries | jq '.[0].price'

Expected:

{
  "currency": "USD",
  "amountMinor": 12999,
  "display": "USD 129.99"
}

Polymorphic catalog payloads

package com.catalogapi.json;

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
        @JsonSubTypes.Type(value = ProductView.class, name = "product"),
        @JsonSubTypes.Type(value = BundleView.class, name = "bundle")
})
public sealed interface CatalogPayload permits ProductView, BundleView {
}

package com.catalogapi.json;

public record ProductView(long id, String sku, Money price) implements CatalogPayload {
}

package com.catalogapi.json;

import java.util.List;

public record BundleView(String name, List<String> skuList, Money totalPrice) implements CatalogPayload {
}

package com.catalogapi;

import java.util.List;

import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;

import com.catalogapi.json.BundleView;
import com.catalogapi.json.CatalogPayload;
import com.catalogapi.json.ProductView;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/catalog/payloads")
@Produces(MediaType.APPLICATION_JSON)
@Tag(name = "Catalog payloads")
public class CatalogPayloadResource {

    @GET
    @Path("/demo")
    @Operation(summary = "Polymorphic catalog payloads for contract testing")
    public List<CatalogPayload> demo() {
        Product keyboard = Product.find("sku", "SKU-001").firstResult();
        Product hub = Product.find("sku", "SKU-002").firstResult();
        Product bundle = Product.find("sku", "SKU-004").firstResult();

        return List.of(
                new ProductView(keyboard.id, keyboard.sku, ProductMapper.toMoney(keyboard)),
                new ProductView(hub.id, hub.sku, ProductMapper.toMoney(hub)),
                new BundleView(
                        bundle.name,
                        List.of("SKU-001", "SKU-002"),
                        ProductMapper.toMoney(bundle)));
    }
}

Add ProductMapper.toMoney alongside toSummary.

Checkpoint:

curl -s http://localhost:8080/catalog/payloads/demo | jq '.[2]'

You should see "type": "bundle" and a totalPrice.display field.

Lock the baseline JSON contract

Before enabling reflection-free serializers, capture what “correct” looks like in tests. REST Assured plus Hamcrest json-path is boring in the best way: it keeps regressions out of eyeball diffs.

Shared assertions live in JsonContractAssertions:

package com.catalogapi;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.hasItem;
import static org.hamcrest.Matchers.hasSize;
import static org.hamcrest.Matchers.is;

final class JsonContractAssertions {

    private JsonContractAssertions() {
    }

    static void assertSummariesContract() {
        given().when()
                .get("/products/summaries")
                .then()
                .statusCode(200)
                .body("$", hasSize(4))
                .body("sku", hasItem("SKU-001"))
                .body("find { it.sku == 'SKU-001' }.price.currency", equalTo("USD"))
                .body("find { it.sku == 'SKU-001' }.price.amountMinor", equalTo(12999))
                .body("find { it.sku == 'SKU-001' }.price.display", equalTo("USD 129.99"));
    }

    static void assertPageContract() {
        given().when()
                .get("/products/page")
                .then()
                .statusCode(200)
                .body("total", equalTo(4))
                .body("items", hasSize(4))
                .body("items[0].id", is(1))
                .body("items[0].price.display", equalTo("USD 129.99"));
    }

    static void assertPolymorphicContract() {
        given().when()
                .get("/catalog/payloads/demo")
                .then()
                .statusCode(200)
                .body("$", hasSize(3))
                .body("[0].type", equalTo("product"))
                .body("[0].sku", equalTo("SKU-001"))
                .body("[2].type", equalTo("bundle"))
                .body("[2].name", equalTo("Desk Bundle"))
                .body("[2].skuList", hasSize(2))
                .body("[2].totalPrice.display", equalTo("USD 529.98"));
    }
}

Baseline tests:

package com.catalogapi;

import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class JsonContractBaselineTest {

    @Test
    void summariesMatchBaselineContract() {
        JsonContractAssertions.assertSummariesContract();
    }

    @Test
    void pageMatchesBaselineContract() {
        JsonContractAssertions.assertPageContract();
    }

    @Test
    void polymorphicPayloadMatchesBaselineContract() {
        JsonContractAssertions.assertPolymorphicContract();
    }
}

Run:

./mvnw test

All tests should pass on the default profile.

Enable reflection-free serializers

Add a dedicated profile in application.properties:

%reflection-free.quarkus.rest.jackson.optimization.enable-reflection-free-serializers=true

Run dev mode with the profile:

./mvnw quarkus:dev -Dquarkus.profile=reflection-free

Re-run the same curl checks. On CatalogAPI the payloads matched baseline in my runs, but your service may not be that polite. That is why the tests exist.

Run the same tests under reflection-free

ReflectionFreeProfile activates the profile in tests:

package com.catalogapi;

import java.util.Map;

import io.quarkus.test.junit.QuarkusTestProfile;

public class ReflectionFreeProfile implements QuarkusTestProfile {

    @Override
    public Map<String, String> getConfigOverrides() {
        return Map.of(
                "quarkus.rest.jackson.optimization.enable-reflection-free-serializers", "true");
    }
}

Keep the active profile as test (the default for @QuarkusTest). Only override the serializer flag. If you replace the whole profile with reflection-free, it is easy to drop the %test datasource settings and start debugging the wrong failure.

package com.catalogapi;

import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.junit.TestProfile;

@QuarkusTest
@TestProfile(ReflectionFreeProfile.class)
class JsonContractReflectionFreeTest {

    @Test
    void summariesMatchReflectionFreeContract() {
        JsonContractAssertions.assertSummariesContract();
    }

    @Test
    void pageMatchesReflectionFreeContract() {
        JsonContractAssertions.assertPageContract();
    }

    @Test
    void polymorphicPayloadMatchesReflectionFreeContract() {
        JsonContractAssertions.assertPolymorphicContract();
    }
}

Run ./mvnw test again. If anything fails here but passed in baseline, you have a migration bug — not a “maybe” problem.

What the build actually generates (and what it skips)

Watch the build log with reflection-free enabled. For CatalogAPI you will see generated serializers for DTOs like ProductSummary and Page, while Product itself is skipped because JPA’s @Column is not supported by the generator yet:

Skipping generation of reflection-free Jackson serializer for class com.catalogapi.Product
because it contains the unsupported Jackson annotation jakarta.persistence.Column

That detail matters in production: returning Panache entities directly from REST still goes through reflection-based Jackson for this entity. Migration work should focus on DTOs you control, or you should accept mixed mode until coverage catches up. The REST guide documents the optimization flag; the metaprogramming post explains the Gizmo-generated StdSerializer classes registered on the shared ObjectMapper.

Custom serializers registered through ObjectMapperCustomizer remain part of the contract — our MoneySerializer is exactly the kind of module you should re-test after flipping the flag.

Benchmarks without fooling yourself

The module includes scripts/compare-json-serialization.sh. It packages a JVM runner with an in-memory benchmark profile (H2, seeded data), so you do not need PostgreSQL running for measurements:

%benchmark.quarkus.datasource.db-kind=h2
%benchmark.quarkus.datasource.jdbc.url=jdbc:h2:mem:catalog;DB_CLOSE_DELAY=-1;MODE=PostgreSQL
%benchmark.quarkus.hibernate-orm.schema-management.strategy=drop-and-create
%benchmark.quarkus.hibernate-orm.sql-load-script=import.sql

Run baseline and reflection-free back to back:

./scripts/compare-json-serialization.sh
./scripts/compare-json-serialization.sh reflection-free

On my machine (Apple Silicon laptop, local loopback) a recent run looked like:

• Baseline — cold ready in ~1250 ms; Quarkus log reported started in 0.855s after the process was already warming.

• Reflection-free — cold ready in a similar band; Quarkus log started in 0.876s.

Throughput on /products/summaries with hey was effectively identical between profiles for this small payload. That is still a useful result: do not expect fireworks on every endpoint. The gains concentrate on serialization-heavy paths and native-image reachability, not on a four-row catalog listing.

Treat any numbers as relative signals, not scripture. Match JDK, CPU power profile, dataset size, and warmup when you compare before and after in your own environment.

Native image proof

If native image is part of your deployment story, include it in the migration proof:

./mvnw package -Dnative -Dquarkus.native.container-build=true -Dquarkus.profile=benchmark,reflection-free

Compare runner size under target/*-runner and cold-start time the same way you would for any native rollout. Reflection-free serializers reduce Jackson’s reflection footprint; they do not replace native configuration for libraries you still register reflectively.

Production migration checklist

When you roll this out on a real service, I would keep the checklist short:

1. Enable in staging first with quarkus.rest.jackson.optimization.enable-reflection-free-serializers=true on a canary profile.

2. Run JSON contract tests on every response type you care about — records, generics, polymorphism, custom serializers, views.

3. Watch build logs for “Skipping generation” lines; map those classes to DTOs or accept reflection fallback.

4. Keep CI native builds if you ship native images — serializer changes show up in reachability and startup, not only in unit tests.

5. Know the escape hatch — set the property back to false if you hit an unsupported Jackson feature. Fighting with @RegisterForReflection on DTOs is usually the wrong lever.

6. Track Quarkus 3.36 — default enablement is coming; tests you write now are the safety net when your platform BOM moves.

Closing

Reflection-free Jackson serializers are Quarkus doing what it usually does best: push work to build time, trim runtime reflection, and make native image less annoying. They are not a silent drop-in for every @Column-annotated entity or every exotic Jackson module.

CatalogAPI shows a practical migration path: baseline behavior, explicit profile, shared contract tests, and benchmarks that stay honest about scope. Run the tests, read the build log, measure the endpoints that actually matter in your service, and keep the config escape hatch one property away.

Source for the full sample lives in the catalogapi-reflection-free-jackson repository.

Subscribe now

That is part of why I like Quarkus testing. The framework makes it pleasantly easy to get started, which means you can move from zero tests to useful feedback quickly. The trap is that teams often stop at the first layer that feels respectable. A couple of @QuarkusTest classes, some REST assertions, maybe a coverage report, and now everyone feels responsible. Meanwhile the real boundaries of the system are still mostly untested.

This page is the map I wish more teams started with. It pulls the Quarkus testing articles on The Main Thread into one path, so you can build a test strategy that matches how the application actually fails.

The first mistake is usually about boundaries

Most testing problems are not tool problems at first. They are boundary problems. Teams mix up app-level tests, packaged-artifact tests, contract tests, browser tests, and architectural checks, then wonder why the suite feels both slow and incomplete.

If you fix the boundaries, tool choice gets easier. If you skip that step, every new tool just gives you another way to be vaguely confident.

These are the pieces I would start with:

• QuarkusTest vs QuarkusIntegrationTest explains where the line really is between running inside the Quarkus test harness and testing the built artifact you are about to ship

• JUnit 6 for modern Quarkus testing is the right place to get current with the test stack itself instead of carrying old assumptions forward

• Quarkus testing in 2026 with component tests is where the conversation becomes more honest, because component tests tend to match the seams where production systems actually wobble

• Quarkus Dev Services and continuous testing is worth reading early if your inner loop still feels slower than it should

That group gives you the vocabulary. Once you know what kind of test you are trying to write, you stop asking one test style to do four jobs badly.

HTTP tests are easy to write and easy to oversell

A lot of Quarkus services expose REST endpoints, so HTTP testing is usually where teams spend their first real effort. That is fine. It is also where optimism becomes a coding standard if nobody is careful.

A passing endpoint test proves one narrow thing: the service answered the request you wrote. It does not automatically prove your schema is stable, your downstream contracts behave, or your packaged application still works outside the warm comfort of the dev test harness.

For that layer, I would use this set:

• API testing with RestAssured, Pact, and jqwik is the broadest piece in the cluster, because it shows how request-level checks, contract thinking, and property-style testing fit together

• Mock external APIs with Quarkus and WireMock matters when your service depends on systems you do not control and you still want deterministic failures

• Quarkus REST API testing vs Spring MockMvc is useful if your team is migrating habits from Spring and keeps reaching for the wrong mental model

My preference here is simple: treat endpoint tests as contract checks for your application surface, not as a magic umbrella for everything behind it. Once people stop pretending a neat 200 OK assertion proves the whole service is healthy, the rest of the testing stack starts to make more sense.

Some problems only show up when the app behaves like a real app

There is a class of failure that unit tests and narrow HTTP checks will never show you clearly enough. Browser behavior, packaging mistakes, wiring drift, architectural erosion, and awkward user flows all live here.

That does not mean every project needs a giant end-to-end circus. It means you should add the smallest wider-angle tests that catch the kinds of mistakes your team actually makes.

This is the part of the cluster I would reach for next:

• Playwright end-to-end browser testing with Quarkus covers the UI path when a browser is part of the system, which means the browser should stop being treated as a rumor

• Architecture testing with Quarkus and Taikai helps when the risk is not a broken endpoint but a codebase slowly turning into a junk drawer

• Mutation testing for Quarkus is useful when assertions are technically present but morally absent

I would not start with mutation testing on day one. I would start with cleaner boundaries and a better mix of test types, then use mutation testing where the suite is already stable enough to deserve that level of scrutiny. Otherwise you are paying for a very sophisticated way to confirm the basics were still fuzzy.

Coverage is useful, but it is a trailing indicator

Coverage numbers are fine. I am not anti-coverage. I am anti-pretending a coverage percentage answers a design question.

Teams often reach for coverage because it is legible. It produces a number, the number is larger after more work, and dashboards love that sort of thing. The drawback is that coverage does not tell you whether the important paths were checked under meaningful conditions. It tells you what was executed.

That is why JaCoCo test coverage in Quarkus belongs later in the reading path, not first. Read it after you are already thinking clearly about test boundaries, contracts, and component seams. Then the coverage report becomes a guide for missing cases instead of a decorative moral certificate.

The reading order I would use

If I were building a Quarkus testing strategy from scratch or cleaning up an inherited one, I would read these in this order:

1. QuarkusTest vs QuarkusIntegrationTest

2. JUnit 6 for modern Quarkus testing

3. Quarkus testing in 2026 with component tests

4. API testing with RestAssured, Pact, and jqwik

5. Mock external APIs with Quarkus and WireMock

6. Playwright end-to-end browser testing with Quarkus

7. Architecture testing with Quarkus and Taikai

8. JaCoCo test coverage in Quarkus

If your current pain is inner-loop speed, move Quarkus Dev Services and continuous testing up earlier. If your pain is browser behavior, move Playwright earlier. The point is not strict obedience to a list. The point is to stop reading isolated testing articles as if they are interchangeable.

What this cluster is really trying to prevent

The big failure mode is not “too few tests.” The big failure mode is a suite that looks busy while hiding the actual risk profile of the service.

I want Quarkus teams to get to a calmer place than that. Know which tests prove the code inside the harness. Know which ones prove the packaged app. Know which ones protect contracts with other systems. Know which ones give you browser confidence, structural discipline, and useful coverage data. After that, the green build means a lot more than “the computer was polite today.”

Subscribe now

Some of that helps. Some of it is also a distraction. Agent systems do not fail only because the model is too small or the harness is too simple. They also fail because the model is unreliable at the tiny private contracts that make cooperative behavior possible: route labels, planner tags, tool payloads, hand-off markers, or one odd internal command that means “switch into protocol mode now.”

That is the part people tend to miss. Effective agent teams are not just a story about capabilities. They are a story about capabilities plus adapters. Tools give the model reach. Adapters can give it a repeatable behavior inside one narrow lane, which is often the difference between “interesting demo” and “system I can actually wire into code.”

This tutorial uses a deliberately small example to make that visible. We are going to teach a local model one agent-specific trick and then make Quarkus prove whether it learned the trick or not.

Here is the prompt that should make an agent developer slightly nervous:

devcard Dev Services with PostgreSQL

A human can guess what that means. A small local model usually cannot. It may ignore devcard, turn the whole thing into a normal explanation, or produce JSON that looks close enough to fool you right up to the moment your parser throws an exception.

That is a real agent problem. Prompting helps, but small models are not consistently obedient just because we put “return JSON only” in uppercase.

This is where LoRA becomes interesting in a way that is easy to show and honest to explain. We are not going to teach the model all of Quarkus. We are going to teach it one repeatable habit:

• when the prompt contains devcard, emit a strict JSON object

• when the prompt does not contain devcard, answer like a normal assistant

That sounds small because it is small. That is also why it makes a good tutorial. The adapter effect is visible, the Quarkus app stays understandable, and the agentic point is hard to miss.

By the end, we will have a local Quarkus app that compares the base model with the adapted one side by side, validates the output, and renders a deterministic developer card only when the model follows the contract.

What We Build

The flow is intentionally boring:

The contract looks like this:

{
  "command": "devcard",
  "topic": "dev-services",
  "technologies": ["postgresql"],
  "includeExample": true,
  "includeWarning": true
}

The model is only responsible for producing that object. The Quarkus app does the rest. That split matters because it is how real agent systems stay sane: let the model classify or structure the request, then let ordinary code validate, route, and render.

One more detail is worth saying out loud before we start. The MLX LM docs note that if you train against a quantized model, the command uses QLoRA under the covers. We are going to use the default 4-bit MLX model from the README, so the mechanics here are technically QLoRA. I am still using “LoRA” in the article title and the everyday explanation because that is the umbrella term most people already know.

What You Need

You need one Mac and a little patience for the first model download. I have not uploaded the sources to my Github because it’s easy to follow and I really want you to play with the LoRA approach and not the Quarkus features here.

• Apple Silicon Mac

• Java 21 installed

• Python 3 installed

• Quarkus CLI installed

• Enough disk space for one local MLX model and adapter artifacts

• Internet access for the first model download from Hugging Face

• Two free local ports: 8080 for MLX LM and 8081 for Quarkus

• Some more ☕️☕️ this time. Mostly because there is way more Python in here than I normally accept.

I am keeping the Java side on plain Quarkus REST plus the REST client. We could hide the model call behind LangChain4j, but I would not do that for the first pass. The interesting part here is the adapter, not another layer of abstraction. BUT make sure to not do this in you production apps. This is a concept implementation to help you understand all of this better!

Create the Base Project

Let’s create a workspace for the app and the training artifacts:

mkdir devcard-lora-demo
cd devcard-lora-demo

Create the Quarkus app :

quarkus create app dev.mthread:devcard-agent \
  --extension='rest-jackson,rest-client-jackson'

The two extensions are enough for this walkthrough:

• rest-jackson gives us a small JSON API surface

• rest-client-jackson lets Quarkus call the local MLX LM HTTP server

mkdir -p trainer/data
mkdir -p trainer/adapters

python3 -m venv .venv
source .venv/bin/activate
pip install -U "mlx-lm[train]"

You should end up with this shape:

devcard-lora-demo/
├── .venv/
├── devcard-agent/
└── trainer/
    ├── adapters/
    └── data/

The model runtime and the Java app live side by side, but they stay separate. That keeps the demo easy to reason about. The training artifacts belong to trainer/. The Quarkus app only knows that there is a local model endpoint and an adapter path string it can send in a request.

Teach the Model One New Habit

The devcard word is not magic. It is just a token pattern we decide to make meaningful. The training data teaches two behaviors at the same time:

1. When the prompt includes devcard, return JSON only

2. When the prompt does not include devcard, answer normally

That second half matters more than people think. If you only train the command path, the model tends to overlearn the trick and starts spitting JSON at prompts that were supposed to stay conversational.

Create trainer/build_dataset.py:

from __future__ import annotations

import json
import random
from pathlib import Path

ROOT = Path(__file__).resolve().parent
DATA_DIR = ROOT / "data"
RANDOM = random.Random(7)

CARD_DEFINITIONS = [
    {
        "label": "Dev Services with PostgreSQL",
        "topic": "dev-services",
        "technologies": ["postgresql"],
        "normal": (
            "Quarkus Dev Services starts required infrastructure automatically during "
            "development and tests. If your application needs PostgreSQL and you did "
            "not configure a JDBC URL, Quarkus can start a container for you so you "
            "can stay focused on the application.\n\n"
            "Example:\n\n"
            "```properties\n"
            "quarkus.datasource.db-kind=postgresql\n"
            "```\n\n"
            "Practical warning: this is a local convenience. Production still needs "
            "an explicit datasource configuration."
        ),
    },
    {
        "label": "Dev Services with Kafka",
        "topic": "dev-services",
        "technologies": ["kafka"],
        "normal": (
            "Dev Services can also start Kafka automatically during local development. "
            "That is useful when you want messaging in `quarkus:dev` without managing "
            "a broker yourself.\n\n"
            "Example:\n\n"
            "```properties\n"
            "mp.messaging.outgoing.orders.connector=smallrye-kafka\n"
            "```\n\n"
            "Practical warning: startup feels simple until the container runtime is "
            "missing or blocked, so keep that dependency visible in the sample."
        ),
    },
    {
        "label": "REST Client with Jackson",
        "topic": "rest-client",
        "technologies": ["jackson"],
        "normal": (
            "Quarkus REST Client with Jackson gives you a typed Java interface for HTTP "
            "calls and handles JSON serialization for request and response payloads.\n\n"
            "Example:\n\n"
            "```java\n"
            "@Path(\"/extensions\")\n"
            "@RegisterRestClient(configKey = \"extensions-api\")\n"
            "public interface ExtensionsClient {\n"
            "    @GET\n"
            "    Set<Extension> list();\n"
            "}\n"
            "```\n\n"
            "Practical warning: treat remote calls like remote calls. A clean Java "
            "interface does not remove timeout, retry, and failure concerns."
        ),
    },
    {
        "label": "Panache entity basics",
        "topic": "panache",
        "technologies": ["hibernate-orm"],
        "normal": (
            "Panache removes a lot of Hibernate ORM boilerplate in Quarkus by giving "
            "you a more direct entity or repository model.\n\n"
            "Example:\n\n"
            "```java\n"
            "@Entity\n"
            "public class Book extends PanacheEntity {\n"
            "    public String title;\n"
            "}\n"
            "```\n\n"
            "Practical warning: Panache makes persistence code shorter, not free. Keep "
            "business logic out of entities unless you really want that coupling."
        ),
    },
    {
        "label": "Typed config with Config Mapping",
        "topic": "config-mapping",
        "technologies": ["smallrye-config"],
        "normal": (
            "Quarkus `@ConfigMapping` turns related configuration keys into a typed Java "
            "interface instead of a stringly-typed scavenger hunt.\n\n"
            "Example:\n\n"
            "```java\n"
            "@ConfigMapping(prefix = \"shipping\")\n"
            "public interface ShippingConfig {\n"
            "    URI endpoint();\n"
            "    Duration timeout();\n"
            "}\n"
            "```\n\n"
            "Practical warning: typed config is only safer if the property names and "
            "scopes stay boring and consistent."
        ),
    },
    {
        "label": "Continuous testing in dev mode",
        "topic": "continuous-testing",
        "technologies": ["junit"],
        "normal": (
            "Continuous testing reruns relevant tests while you stay in `quarkus:dev`, "
            "which tightens the feedback loop without another manual test command.\n\n"
            "Example:\n\n"
            "```bash\n"
            "./mvnw quarkus:dev\n"
            "```\n\n"
            "Practical warning: quick feedback only helps when the tests say something "
            "useful. Bad tests just fail faster."
        ),
    },
]

COMMAND_TEMPLATES = [
    "devcard {label}",
    "devcard: {label}",
    "please run devcard for {label}",
    "use devcard for {label}",
]

NORMAL_TEMPLATES = [
    "Explain {label} in Quarkus.",
    "Give me a short explanation of {label}.",
    "How does {label} work in Quarkus?",
]


def json_contract(definition: dict[str, object]) -> dict[str, object]:
    return {
        "command": "devcard",
        "topic": definition["topic"],
        "technologies": definition["technologies"],
        "includeExample": True,
        "includeWarning": True,
    }


def command_rows() -> list[dict[str, object]]:
    rows = []
    for definition in CARD_DEFINITIONS:
        expected = json_contract(definition)
        answer = json.dumps(expected, separators=(",", ":"))
        for template in COMMAND_TEMPLATES:
            rows.append(
                {
                    "kind": "command",
                    "expected": expected,
                    "messages": [
                        {
                            "role": "user",
                            "content": template.format(label=definition["label"]),
                        },
                        {
                            "role": "assistant",
                            "content": answer,
                        },
                    ],
                }
            )
    return rows


def normal_rows() -> list[dict[str, object]]:
    rows = []
    for definition in CARD_DEFINITIONS:
        for template in NORMAL_TEMPLATES:
            rows.append(
                {
                    "kind": "normal",
                    "messages": [
                        {
                            "role": "user",
                            "content": template.format(label=definition["label"]),
                        },
                        {
                            "role": "assistant",
                            "content": definition["normal"],
                        },
                    ],
                }
            )
    return rows


def write_jsonl(path: Path, rows: list[dict[str, object]]) -> None:
    with path.open("w", encoding="utf-8") as handle:
        for row in rows:
            handle.write(json.dumps(row, ensure_ascii=False))
            handle.write("\n")


def main() -> None:
    DATA_DIR.mkdir(parents=True, exist_ok=True)

    rows = command_rows() + normal_rows()
    RANDOM.shuffle(rows)

    total = len(rows)
    train_cutoff = int(total * 0.7)
    valid_cutoff = int(total * 0.85)

    train_rows = rows[:train_cutoff]
    valid_rows = rows[train_cutoff:valid_cutoff]
    test_rows = rows[valid_cutoff:]

    write_jsonl(DATA_DIR / "train.jsonl", train_rows)
    write_jsonl(DATA_DIR / "valid.jsonl", valid_rows)
    write_jsonl(DATA_DIR / "test.jsonl", test_rows)

    summary = {
        "train": len(train_rows),
        "valid": len(valid_rows),
        "test": len(test_rows),
        "total": total,
    }

    print(json.dumps(summary, indent=2))


if __name__ == "__main__":
    main()

Build the dataset:

python trainer/build_dataset.py

The MLX LM LoRA guide says local datasets need train.jsonl and optionally valid.jsonl, with test.jsonl used for evaluation. It also says unknown keys are ignored by the loader. That is why the script adds kind and expected metadata for our evaluation step without breaking training.

The output count is intentionally small. That is enough to make the behavior visible on a local Mac. It is not enough to brag about a robust benchmark. If you want stronger results, add more phrasing variation before you add more topics.

Train the Adapter

The current MLX LM README uses mlx-community/Llama-3.2-3B-Instruct-4bit as the default quick-start model, so I am sticking with that here. It is a safer tutorial choice than inventing a random model pick.

Train from the project root:

MODEL="mlx-community/Llama-3.2-3B-Instruct-4bit"

mlx_lm.lora \
  --model "$MODEL" \
  --train \
  --data trainer/data \
  --adapter-path trainer/adapters/devcard-lora \
  --mask-prompt \
  --iters 300 \
  --batch-size 1 \
  --learning-rate 1e-5

There are three details worth calling out:

• --mask-prompt is important for this dataset shape because we only want the loss on the assistant answer, not on the prompt tokens

• the model path points at a quantized 4-bit model, so per the MLX LM docs this run is effectively QLoRA

• the adapter is saved separately from the base model, which is exactly what we want for the comparison later

You can inspect the adapter size after training:

du -sh trainer/adapters/devcard-lora

That number is the easiest way to make “parameter-efficient” stop sounding like a conference slide. The base model stays where it is. The adapter is the learned delta. In my demo case it has 107M.

Measure the Behavior Before You Touch Java

The MLX LM docs include a --test mode that calculates perplexity, and that is fine as far as it goes. For this tutorial, I care more about contract obedience than a language-model metric. I want to know how often the model emits valid devcard JSON when it should, and how often it wrongly emits devcard JSON when it should not.

Create trainer/evaluate.py:

from __future__ import annotations

import argparse
import json
from pathlib import Path
from urllib import request

ROOT = Path(__file__).resolve().parent
TEST_DATA = ROOT / "data" / "test.jsonl"


def extract_message(choice: dict[str, object]) -> str:
    message = choice["message"]

    if isinstance(message, str):
        return message

    if isinstance(message, dict):
        content = message.get("content")

        if isinstance(content, str):
            return content

        if isinstance(content, list):
            texts = []
            for item in content:
                if isinstance(item, dict) and item.get("type") == "text":
                    text = item.get("text")
                    if isinstance(text, str):
                        texts.append(text)

            if texts:
                return "".join(texts)

    raise TypeError(
        "Unsupported message shape in response: "
        + f"{type(message).__name__}"
    )


def call_model(url: str, model: str, prompt: str, adapter: str | None) -> str:
    payload = {
        "model": model,
        "messages": [
            {
                "role": "user",
                "content": prompt,
            }
        ],
        "temperature": 0.0,
        "max_tokens": 200,
    }

    if adapter:
        payload["adapters"] = adapter

    body = json.dumps(payload).encode("utf-8")
    req = request.Request(
        url,
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    with request.urlopen(req) as response:
        data = json.load(response)

    return extract_message(data["choices"][0])


def load_rows() -> list[dict[str, object]]:
    rows = []
    with TEST_DATA.open(encoding="utf-8") as handle:
        for line in handle:
            rows.append(json.loads(line))
    return rows


def evaluate_command_case(raw: str, expected: dict[str, object]) -> bool:
    try:
        parsed = json.loads(raw)
    except json.JSONDecodeError:
        return False

    return parsed == expected


def evaluate_normal_case(raw: str) -> bool:
    try:
        parsed = json.loads(raw)
    except json.JSONDecodeError:
        return True

    return not (
        isinstance(parsed, dict) and parsed.get("command") == "devcard"
    )


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--url",
        default="http://127.0.0.1:8080/v1/chat/completions",
    )
    parser.add_argument(
        "--model",
        default="mlx-community/Llama-3.2-3B-Instruct-4bit",
    )
    parser.add_argument("--adapter")
    args = parser.parse_args()

    rows = load_rows()
    command_total = 0
    command_ok = 0
    normal_total = 0
    normal_ok = 0
    failures = []

    for row in rows:
        prompt = row["messages"][0]["content"]
        raw = call_model(args.url, args.model, prompt, args.adapter)

        if row["kind"] == "command":
            command_total += 1
            ok = evaluate_command_case(raw, row["expected"])
            if ok:
                command_ok += 1
            else:
                failures.append({"kind": "command", "prompt": prompt, "raw": raw})
        else:
            normal_total += 1
            ok = evaluate_normal_case(raw)
            if ok:
                normal_ok += 1
            else:
                failures.append({"kind": "normal", "prompt": prompt, "raw": raw})

    overall_ok = command_ok + normal_ok
    overall_total = command_total + normal_total

    print(
        json.dumps(
            {
                "adapter": args.adapter or "base",
                "command_ok": f"{command_ok}/{command_total}",
                "normal_ok": f"{normal_ok}/{normal_total}",
                "overall_ok": f"{overall_ok}/{overall_total}",
                "failures": failures,
            },
            indent=2,
        )
    )


if __name__ == "__main__":
    main()

If you mostly live in Java, read this script as a tiny integration test harness, not as “now we switch to a Python article.”

The structure is simple:

• load_rows() loads the held-out test cases from test.jsonl

• call_model(...) sends one HTTP request to the MLX LM server, with or without an adapter path

• evaluate_command_case(...) is the strict assertion for command prompts: the model output must parse as JSON and match the expected object exactly

• evaluate_normal_case(...) is the negative assertion for ordinary prompts: the model should not suddenly emit a fake devcard command object

• main() loops over the test cases, counts passes and failures, and prints one JSON summary at the end

If you want the Java mental model, this is closer to a parameterized integration test than to a training script. The test fixture is test.jsonl. The system under test is the model server. The assertions are “did the command prompt produce the exact contract?” and “did the normal prompt stay normal?”

Start the base model server from the project root:

mlx_lm.server --model "$MODEL"

The current MLX LM server guide says this starts on localhost:8080 by default. It also documents an OpenAI-like /v1/chat/completions endpoint and an adapters request field, which is what lets us compare base and adapted behavior without swapping the whole model server.

In another terminal, still from the project root, run the evaluation once without an adapter and once with it:

source .venv/bin/activate
python trainer/evaluate.py --model "$MODEL"
python trainer/evaluate.py --model "$MODEL" --adapter trainer/adapters/devcard-lora

The output is a compact scorecard:

• adapter tells you whether you ran the base model or the adapted one

• command_ok is how many command-style prompts produced the exact expected JSON contract

• normal_ok is how many non-command prompts stayed non-command prompts

• overall_ok is the combined total

• failures contains the raw model output for any missed case, which is usually the most interesting part

A base-model run often looks something like this:

{
  "adapter": "base",
  "command_ok": "0/5",
  "normal_ok": "2/2",
  "overall_ok": "2/7",
  "failures": [
    {
      "kind": "command",
      "prompt": "devcard Dev Services with Kafka",
      "raw": "**DevCard: Dev Services with Kafka**\n..."
    }
  ]
}

That result is more or less a random failure. The base model kept treating devcard as ordinary language and invented a meaning for it. In my runs, that usually shows up as a confident prose answer, a hallucinated product name, or a near miss that looks plausible to a human and useless to a parser.

The adapted run should move in the opposite direction:

{
  "adapter": "trainer/adapters/devcard-lora",
  "command_ok": "5/5",
  "normal_ok": "2/2",
  "overall_ok": "7/7",
  "failures": []
}

This is the behavior change we care about. The adapter did not make the model “more intelligent” in some vague general sense. It made the model better at one narrow contract:

• when the prompt contains the private command word, emit the house JSON shape

• when the prompt is ordinary, stay ordinary

What I want to see is not perfection. I want to see direction:

• the base run should fail more command cases

• the adapted run should pass more command cases

• the adapted run should still behave normally on non-command prompts

If the adapted run starts failing normal prompts, the usual fix is not “train longer.” The usual fix is “add better negative examples.” If the base run already passes everything, the command was probably too easy or too close to ordinary language to make the adapter effect visible.

Build the Quarkus App

Now we wire the same comparison into Java.

Set the Quarkus app to 8081 so it does not collide with the MLX server, and keep the model settings in typed config because plain strings in random services are exactly how these demos become annoying to maintain.

Replace devcard-agent/src/main/resources/application.properties with this:

quarkus.http.port=8081

quarkus.rest-client.mlx.url=http://127.0.0.1:8080
quarkus.rest-client.mlx.connect-timeout=2000
quarkus.rest-client.mlx.read-timeout=120000

devcard.model=mlx-community/Llama-3.2-3B-Instruct-4bit
devcard.adapter=trainer/adapters/devcard-lora

Create devcard-agent/src/main/java/dev/mthread/devcard/config/DevcardConfig.java:

package dev.mthread.devcard.config;

import io.smallrye.config.ConfigMapping;

@ConfigMapping(prefix = "devcard")
public interface DevcardConfig {

    String model();

    String adapter();
}

Create devcard-agent/src/main/java/dev/mthread/devcard/mlx/MlxChatClient.java:

package dev.mthread.devcard.mlx;

import java.util.List;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.JsonNode;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/v1/chat/completions")
@RegisterRestClient(configKey = "mlx")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface MlxChatClient {

        @POST
        ChatResponse chat(ChatRequest request);

        record Message(String role, String content) {
        }

        @JsonInclude(JsonInclude.Include.NON_NULL)
        record ChatRequest(
                        String model,
                        List<Message> messages,
                        String adapters,
                        Double temperature,
                        @JsonProperty("max_tokens") Integer maxTokens) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record Choice(
                        int index,
                        JsonNode message,
                        @JsonProperty("finish_reason") String finishReason) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record Usage(
                        @JsonProperty("prompt_tokens") int promptTokens,
                        @JsonProperty("completion_tokens") int completionTokens,
                        @JsonProperty("total_tokens") int totalTokens) {
        }

        @JsonIgnoreProperties(ignoreUnknown = true)
        record ChatResponse(
                        String model,
                        List<Choice> choices,
                        Usage usage) {
        }
}

The slightly odd part is the response shape. The MLX server guide documents choices[].message as plain text, not the nested message.content shape some OpenAI-style clients expect. That is why I am using a direct REST client here instead of pretending every compatible API is identical in practice.

Create devcard-agent/src/main/java/dev/mthread/devcard/DevcardCommand.java:

package dev.mthread.devcard;

import java.util.List;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public record DevcardCommand(
        String command,
        String topic,
        List<String> technologies,
        boolean includeExample,
        boolean includeWarning) {

    public DevcardCommand normalized() {
        return new DevcardCommand(
                command == null ? "" : command.trim(),
                topic == null ? "" : topic.trim(),
                technologies == null ? List.of() : List.copyOf(technologies),
                includeExample,
                includeWarning);
    }

    public void validate() {
        if (!"devcard".equals(command)) {
            throw new IllegalArgumentException("Expected command=devcard");
        }

        if (topic.isBlank()) {
            throw new IllegalArgumentException("Expected a non-empty topic");
        }

        if (!includeExample || !includeWarning) {
            throw new IllegalArgumentException(
                    "Expected includeExample=true and includeWarning=true");
        }
    }
}

Create devcard-agent/src/main/java/dev/mthread/devcard/DevcardService.java:

package dev.mthread.devcard;

import java.util.List;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import dev.mthread.devcard.config.DevcardConfig;
import dev.mthread.devcard.mlx.MlxChatClient;
import dev.mthread.devcard.mlx.MlxChatClient.ChatRequest;
import dev.mthread.devcard.mlx.MlxChatClient.ChatResponse;
import dev.mthread.devcard.mlx.MlxChatClient.Message;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class DevcardService {

    private final MlxChatClient client;
    private final DevcardConfig config;
    private final ObjectMapper objectMapper;

    public DevcardService(
            @RestClient MlxChatClient client,
            DevcardConfig config,
            ObjectMapper objectMapper) {
        this.client = client;
        this.config = config;
        this.objectMapper = objectMapper;
    }

    public ComparisonResponse compare(String prompt) {
        return new ComparisonResponse(
                prompt,
                run(prompt, null),
                run(prompt, config.adapter()));
    }

    private VariantResult run(String prompt, String adapter) {
        ChatRequest request = new ChatRequest(
                config.model(),
                List.of(new Message("user", prompt)),
                adapter,
                0.0,
                200);

        ChatResponse response = client.chat(request);
        String raw = extractMessage(response);

        try {
            DevcardCommand command = parseCommand(raw);
            return new VariantResult(
                    raw,
                    true,
                    command,
                    render(command),
                    null);
        } catch (IllegalArgumentException exception) {
            return new VariantResult(
                    raw,
                    false,
                    null,
                    null,
                    exception.getMessage());
        }
    }

    private String extractMessage(ChatResponse response) {
        if (response.choices() == null || response.choices().isEmpty()) {
            throw new IllegalStateException("Model response did not contain choices");
        }

        var message = response.choices().get(0).message();
        if (message == null || message.isNull()) {
            throw new IllegalStateException("Model response message was empty");
        }

        if (message.isTextual()) {
            return message.asText();
        }

        if (message.isObject()) {
            var content = message.get("content");

            if (content != null && content.isTextual()) {
                return content.asText();
            }

            if (content != null && content.isArray()) {
                StringBuilder builder = new StringBuilder();
                for (var item : content) {
                    if ("text".equals(item.path("type").asText()) && item.has("text")) {
                        builder.append(item.get("text").asText());
                    }
                }

                if (builder.length() > 0) {
                    return builder.toString();
                }
            }
        }

        throw new IllegalStateException("Model response message was not a supported text shape");
    }

    private DevcardCommand parseCommand(String raw) {
        try {
            DevcardCommand command = objectMapper.readValue(raw, DevcardCommand.class)
                    .normalized();
            command.validate();
            return command;
        } catch (JsonProcessingException exception) {
            throw new IllegalArgumentException(exception.getOriginalMessage(), exception);
        }
    }

    private String render(DevcardCommand command) {
        return switch (command.topic()) {
            case "dev-services" -> renderDevServices(command.technologies());
            case "rest-client" -> renderRestClient();
            case "panache" -> renderPanache();
            case "config-mapping" -> renderConfigMapping();
            case "continuous-testing" -> renderContinuousTesting();
            default -> throw new IllegalArgumentException(
                    "Unsupported topic: " + command.topic());
        };
    }

    private String renderDevServices(List<String> technologies) {
        if (technologies.contains("postgresql")) {
            return """
                    Dev Services starts required infrastructure automatically during local development and tests when Quarkus can infer what you need and you have not already configured it yourself. In the PostgreSQL case, that means you can add the driver, run `quarkus:dev`, and let Quarkus spin up a database container for you instead of wiring a JDBC URL by hand.

                    Example:

                    ```properties
                    quarkus.datasource.db-kind=postgresql
                    ```

                    Practical warning: this is a development convenience, not a deployment plan. It also depends on a working container runtime, which means the demo feels magical right up to the moment Podman or Docker is missing.
                    """;
        }

        if (technologies.contains("kafka")) {
            return """
                    Dev Services can do the same thing for Kafka, which is useful when you want messaging in local development without maintaining a broker by hand. The Java part stays small because the infrastructure bootstrapping moves into the Quarkus extension.

                    Example:

                    ```properties
                    mp.messaging.outgoing.orders.connector=smallrye-kafka
                    ```

                    Practical warning: the convenience is real, but so is the hidden dependency on local containers. Keep that visible in your docs and your onboarding steps.
                    """;
        }

        throw new IllegalArgumentException("Unsupported Dev Services technology");
    }

    private String renderRestClient() {
        return """
                Quarkus REST Client with Jackson gives you a typed Java interface for HTTP calls while Jackson handles JSON serialization. The useful part for an agentic application is not elegance. It is that you can keep the model boundary explicit and still write ordinary Java on your side of the fence.

                Example:

                ```java
                @Path("/v1/chat/completions")
                @RegisterRestClient(configKey = "mlx")
                public interface MlxChatClient {
                    @POST
                    ChatResponse chat(ChatRequest request);
                }
                ```

                Practical warning: a neat Java interface does not make the network local. Keep timeouts, retries, and failure behavior visible in the code.
                """;
    }

    private String renderPanache() {
        return """
                Panache removes a lot of the repetitive Hibernate ORM code that turns simple examples into longer articles than they need to be. For a Java developer, the appeal is not that it is magical. It is that the persistence intent becomes easier to read.

                Example:

                ```java
                @Entity
                public class Book extends PanacheEntity {
                    public String title;
                }
                ```

                Practical warning: Panache makes entity code shorter, but it does not protect you from bad boundaries. Do not turn entities into a storage layer and a business layer at the same time.
                """;
    }

    private String renderConfigMapping() {
        return """
                `@ConfigMapping` gives you typed configuration instead of a scattered collection of property lookups. That fits agentic apps nicely because model settings, endpoint URLs, and timeouts usually travel together and deserve one explicit home.

                Example:

                ```java
                @ConfigMapping(prefix = "devcard")
                public interface DevcardConfig {
                    String model();
                    String adapter();
                }
                ```

                Practical warning: typed config only helps if the property names stay stable and boring. If every sample invents a new prefix, you just moved the mess into an interface.
                """;
    }

    private String renderContinuousTesting() {
        return """
                Continuous testing keeps the feedback loop inside `quarkus:dev`, which is useful when you are changing prompts, parser rules, and renderer code in short cycles. You notice breakage sooner, which is the whole point.

                Example:

                ```bash
                ./mvnw quarkus:dev
                ```

                Practical warning: fast feedback is only useful when the tests say something meaningful about the contract. A flaky parser test is still flaky, just sooner.
                """;
    }

    public record VariantResult(
            String raw,
            boolean parsed,
            DevcardCommand command,
            String renderedCard,
            String error) {
    }

    public record ComparisonResponse(
            String prompt,
            VariantResult base,
            VariantResult adapted) {
    }
}

Create devcard-agent/src/main/java/dev/mthread/devcard/CompareResource.java:

package dev.mthread.devcard;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.WebApplicationException;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/api/devcards")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CompareResource {

    private final DevcardService service;

    public CompareResource(DevcardService service) {
        this.service = service;
    }

    @POST
    public DevcardService.ComparisonResponse compare(PromptRequest request) {
        if (request == null || request.prompt() == null || request.prompt().isBlank()) {
            throw new WebApplicationException(
                    "prompt is required",
                    Response.Status.BAD_REQUEST);
        }

        return service.compare(request.prompt().trim());
    }

    public record PromptRequest(String prompt) {
    }
}

There is no model magic in the Java layer. That is the point. The model either gives us a valid DevcardCommand or it does not. If it does, normal Java takes over. If it does not, we keep the raw output and the parse error visible instead of pretending everything is fine.

Run the Comparison End to End

Keep the MLX server running from the project root because the server resolves the adapters path relative to the directory it started in. That detail is easy to miss and wastes a lot of time the first time you move files around.

In another terminal, start Quarkus:

cd devcard-lora-demo/devcard-agent
./mvnw quarkus:dev

Now hit the comparison endpoint:

curl -s http://127.0.0.1:8081/api/devcards \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"devcard Dev Services with PostgreSQL"}' \
  | python -m json.tool

The exact text will vary, but the shape you want is simple:

• base.parsed is often false

• adapted.parsed is true

• adapted.command contains the structured contract

• adapted.renderedCard contains the deterministic explanation produced by Quarkus

A representative response looks like this:

{
  "prompt": "devcard Dev Services with PostgreSQL",
  "base": {
    "raw": "Quarkus Dev Services starts infrastructure automatically during development and tests when your application needs it.",
    "parsed": false,
    "command": null,
    "renderedCard": null,
    "error": "Unrecognized token 'Quarkus'"
  },
  "adapted": {
    "raw": "{\"command\":\"devcard\",\"topic\":\"dev-services\",\"technologies\":[\"postgresql\"],\"includeExample\":true,\"includeWarning\":true}",
    "parsed": true,
    "command": {
      "command": "devcard",
      "topic": "dev-services",
      "technologies": [
        "postgresql"
      ],
      "includeExample": true,
      "includeWarning": true
    },
    "renderedCard": "Dev Services starts required infrastructure automatically during local development and tests when Quarkus can infer what you need and you have not already configured it yourself.",
    "error": null
  }
}

That is the whole teaching moment in one payload. Same base model. Same server. Same prompt. One request adds the adapter path, and the app suddenly has something stable enough to validate and route.

Try a normal prompt next:

curl -s http://127.0.0.1:8081/api/devcards \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Explain Dev Services with PostgreSQL in Quarkus."}' \
  | python -m json.tool

For this one, I want both branches to fail strict parsing because the prompt did not ask for protocol mode. That is not a bug. That is proof that the command word is carrying the behavior.

Why This Helps Agentic Applications

Agentic apps do not just need fluent language. They need durable little agreements.

Sometimes that agreement is a tool call schema. Sometimes it is a planner label. Sometimes it is a routing payload that three downstream components quietly depend on. The ugly truth is that a model can know plenty about your domain and still be bad at that part. General competence is not the same thing as protocol obedience.

LoRA helps when the gap is narrow and behavioral:

• teach a model a private command word

• teach it a house JSON schema

• teach it a small routing vocabulary

• teach it that one branch must stay terse and deterministic

It is the wrong tool when the gap is factual freshness or broad new knowledge. If you need today’s docs, customer-specific records, or fast-changing operational state, use retrieval or tools. A small adapter is not a substitute for a real data boundary.

That is why I like this demo more than “fine-tune the model to sound like my blog.” Style transfer is real, but it does not explain the agentic value nearly as clearly. A command contract does.

Where This Breaks First

This kind of demo fails in predictable ways, which is honestly a good sign.

The model starts returning JSON too often

That usually means the positive examples drowned out the negative ones. Add more ordinary prompts that talk about the same Quarkus topics without the command word. The fix is usually dataset balance, not more training steps.

The model invents a near-miss topic

You ask for dev-services and get devservice or dev-services-postgres. That is why the Java side validates the contract instead of trusting vibes. Keep the topic set small, explicit, and boring.

The adapter path works in one shell and breaks in another

The current MLX LM server guide says the adapters path is resolved relative to the directory where the server started. If you start the server from the wrong place, the model request fails even though the Quarkus app is configured correctly.

The local demo turns into an accidental production design

The current MLX LM HTTP server guide explicitly says the built-in server is not recommended for production because it only implements basic security checks. Treat this tutorial as a local development pattern and a learning aid, not a deployment recipe.

People start asking whether the adapter learned Quarkus

No. It learned a narrow response pattern around prompts you cared about. That is still useful. Just do not oversell what happened.

A Few Useful Extensions

Once the base demo works, there are a few directions worth exploring:

• add more command words such as toolplan or routecard

• swap the deterministic renderer for real tool routing

• keep the same Quarkus app and compare multiple adapters against the same base model

• move the model call behind LangChain4j after the protocol behavior is stable

I would do that in exactly that order. First prove the behavior change. Then add framework niceties.

Close the Loop

The reason this tutorial works is that it stays honest. We did not train a local model to become a Quarkus expert. We trained it to honor one small contract that a Java application can validate and use. That is a much better story for LoRA in agentic systems because it lines up with how these systems actually fail.

Prompting alone gets you part of the way there. A tiny adapter can make the model much more predictable inside one narrow lane. Once you have that, ordinary Quarkus code can do the rest of the job, which is exactly where I prefer the complexity to live.

Subscribe now