Eclipse Vert.x

Eclipse Vert.x — Reactive Layered + Event-Driven Guideline

House standard for JVM services built on Eclipse Vert.x 4.x. This guideline codifies the layered N-tier reactive + event-driven style for production Vert.x services. It is descriptive of that architecture, not a hexagonal port — Vert.x services here are organized by technical layer and glued by the EventBus, not by ports-and-adapters.

Examples use a neutral Order domain and com.example.app package — they are illustrative, not lifted from any specific service.

Where this conflicts with the hexagonal guidelines (no ports, framework types in the service layer, anemic models), that is intentional: Vert.x services optimize for the reactor model and throughput. Apply hexagonal-architecture.md only when a bounded context grows a rich domain worth isolating.

1. Stack (locked baseline)

2. Architecture style

1
                       ┌──────────── EventBus (in-process) ────────────┐
2
                       │   audit · metrics · async offload to workers   │
3
                       └───────▲───────────────────────────▲───────────┘
4
                               │ send/publish              │ consumer
5
  HTTP ──► Router ──► Handler ─┼─► Service ──► Repository ──┼─► Pg / Mongo / Redis
6
           (DSL)    (RoutingCtx) (Future chain) (raw SQL/Tuple)
7
           §4.1      §4.2         §4.3            §4.4

Two backbones:

1. Synchronous request path (N-tier): Router → Handler → Service → Repository → Model. Strict top-down dependency; a layer only calls the one below. No layer-skipping (handler never touches a repository).
2. Asynchronous event path (event-driven): the EventBus decouples cross-cutting concerns (audit, metrics) and offloads heavy work to worker Verticles via named topics. In-process only — not an external broker.

Deployment is a modular monolith: one fat jar, multiple Verticles. Feature modules under modules/ mirror the core layering and carry their own MainVerticle so they can be extracted to a standalone service later.

Package layout (by technical layer, then feature)

1
com.example.app.core
2
├── verticle/            # bootstrap + HTTP server + workers/
3
├── api/
4
│   ├── router/          # route definitions (extend AbstractApiRouter)
5
│   ├── handler/         # HTTP entry (extend AbstractHandler)
6
│   ├── validation/      # request validation handlers (v2/ for versioned)
7
│   ├── service/         # business logic (extend AbstractService)
8
│   ├── repository/      # data access (concrete classes) + mapper/
9
│   └── model/           # DTOs: <feature>/{request,response,enums}
10
├── client/              # outbound integrations (WebClient wrappers)
11
├── exceptions/          # exception hierarchy + HandlerError mapper
12
├── enums/               # EventBusTopic, error codes
13
├── utils/               # ConfigUtils, DbUtils, ResponseUtils, RequestUtils
14
└── configuration/       # shared client/managers
15
modules/<feature>/       # self-contained feature (handler→service→repository→router + MainVerticle)

3. Bootstrap & Verticles

A custom Launcher sets the main verticle; MainVerticle builds shared clients once and deploys the rest. Clients (Pool, MongoClient, RedisAPI) are built once and passed by constructor into every Verticle — never rebuilt per request.

1
public class MainVerticle extends AbstractVerticle {
2
    @Override
3
    public void start() {
4
        final Pool dbClient = DbUtils.buildDbClient(vertx);
5
        final MongoClient mongoClient = DbUtils.buildMongoClient(vertx);
6
        final RedisAPI redisClient = RedisAPI.api(DbUtils.buildRedisClient(vertx));
7

8
        deployApiVerticle(vertx, dbClient, mongoClient, redisClient, /* ... */)
9
                .onSuccess(id -> logger.info("API verticle started in {} ms", elapsed()))
10
                .onFailure(Throwable::printStackTrace);
11

12
        deployWorkerVerticle(vertx, dbClient, mongoClient, redisClient, /* ... */);
13
    }
14

15
    private Future<String> deployApiVerticle(Vertx vertx, Pool db, /* ... */) {
16
        return vertx.deployVerticle(new ApiVerticle(db, /* ... */));
17
    }
18
}

ApiVerticle owns the HTTP server and the root router. Global handlers run before routes; error handlers map status codes; feature routers mount via mount(router).

1
final Router router = Router.router(vertx);
2
router.route()
3
        .handler(BodyHandler.create())
4
        .handler(loggingHandler::handler)   // correlationId + request log
5
        .handler(i18nHandler)               // resolve Locale
6
        .failureHandler(errorHandler::handleFailure);
7
router.errorHandler(500, errorHandler::handleError500);
8
router.errorHandler(400, errorHandler::handleError400);
9

10
orderRouter.mount(router);
11
userRouter.mount(router);                   // one feature router per resource
12

13
vertx.createHttpServer(options).requestHandler(router).listen(port, host);

Rules

• One HTTP ApiVerticle; deploy event-loop count = CPU cores (Vert.x default).
• Blocking / CPU-heavy work goes to a worker Verticle (§6), never the API verticle.
• Build shared clients in MainVerticle.start(); inject downward. Never call DbUtils.buildDbClient inside a handler/service.

4. Layer responsibilities

4.1 Router — extend AbstractApiRouter

Declarative routes only. Each route = (path, policy, validationHandler, handlerMethod). mount() calls init() then mountSubRouter(basePath, router). Authorization policy is a role string; "public"/"*" skips role checks.

1
public class OrderRouter extends AbstractApiRouter {
2
    public OrderRouter(Vertx vertx, OrderHandler handler, OrderValidationHandler validation,
3
                       JwkHandler jwtAuth, AuthorizeResourceHandler authz) {
4
        super(vertx, jwtAuth, authz, "/api/v1/orders");
5
        this.orderHandler = handler;
6
        this.validation = validation;
7
    }
8

9
    @Override
10
    protected void init() {
11
        get("/", "order.read", validation.readAll(), orderHandler::readAll);
12
        post("/", "order.write", validation.create(), orderHandler::create);
13
        get("/:id", "order.read", validation.readOne(), orderHandler::readOne);
14
        put("/:id", "order.write", validation.update(), orderHandler::update);
15
    }
16
}

Authorization is built once per route from the policy string:

1
public AuthorizationHandler authorize(String policy) {
2
    var roleAuthorization = OrAuthorization.create();
3
    if (!policy.equals("*")) {
4
        roleAuthorization.addAuthorization(RoleBasedAuthorization.create(policy));
5
    }
6
    return AuthorizationHandler.create(roleAuthorization)
7
            .addAuthorizationProvider(JWTAuthorization.create("realm_access/roles"));
8
}

4.2 Handler — extend AbstractHandler

Inbound adapter. Reads RoutingContext, extracts/parses params, calls one service method, writes the response via ResponseUtils, and routes failure to ResponseUtils.buildErrorResponse. No business logic, no SQL, no EventBus business calls here — only request/response translation, audit, and metrics.

1
public Future<OrderListResponse> readAll(RoutingContext rc) {
2
    final UUID correlationId = RequestUtils.getCorrelationId(rc);
3
    final String status = rc.queryParams().get(Constants.STATUS);
4
    final int offset = RequestUtils.intParam(rc, Constants.OFFSET_PARAMETER, 0);
5
    final int limit  = RequestUtils.intParam(rc, Constants.LIMIT_PARAMETER, 100);
6
    return orderService
7
            .readAll(correlationId, status, offset, limit)
8
            .onSuccess(result -> ResponseUtils.buildOkResponse(rc, result))
9
            .onFailure(t -> ResponseUtils.buildErrorResponse(rc, t));
10
}

Cross-cutting via EventBus lives in the base class (fire-and-forget):

1
public void auditMessage(JsonObject message) {
2
    eventBus.send(Constants.INPUT_AUDIT_EVENT, message);
3
}

4.3 Service — extend AbstractService

Owns business logic and the unit of work. Composes Futures; opens a connection via pool.withConnection(...) so all repository calls in one use case share a transaction-scoped connection. Returns DTOs, never RoutingContext.

1
public Future<OrderListResponse> readAll(UUID cid, String status, int offset, int limit) {
2
    final List<String> statuses = (status == null)
3
            ? List.of("NEW", "PAID", "CANCELLED") : List.of(status);
4
    return dbClient.withConnection(conn -> orderRepository
5
            .count(cid, conn, statuses)
6
            .flatMap(total -> orderRepository
7
                    .selectAll(cid, conn, statuses, limit, offset)
8
                    .map(rows -> {
9
                        var orders = rows.stream().map(OrderResponse::new).toList();
10
                        return new OrderListResponse(total, limit, offset, orders);
11
                    })))
12
            .onFailure(t -> LOGGER.error("readAll failed cid={} {}", cid, t.getMessage()));
13
}

Large reads chunk to bound memory and pool pressure:

1
return AbstractService.fetchAll(totalLimit, (off, lim) ->
2
        orderRepository.selectPage(cid, conn, off, lim));   // CompositeFuture.all under the hood

4.4 Repository — concrete class

Raw parameterized SQL with Tuple; map rows with a dedicated mapper function. Always parameterized ($1,$2) — never string concatenation. Column-level crypto handled in SQL (pgp_sym_decrypt).

1
private static final String SQL_SELECT_ALL_ORDERS =
2
        "SELECT id, reference, status, total FROM orders WHERE status = ANY($1) LIMIT $2 OFFSET $3";
3

4
public Future<List<Order>> selectAll(UUID cid, SqlConnection conn,
5
                                     List<String> status, int limit, int offset) {
6
    return conn.preparedQuery(SQL_SELECT_ALL_ORDERS)
7
            .execute(Tuple.of(status.toArray(), limit, offset))
8
            .map(orderMapper::apply)
9
            .onFailure(t -> LOGGER.error("selectAll failed cid={}", cid, t));
10
}

Layer rules (enforced in review)

5. Reactive patterns (Future API)

• Never block the event loop. No JDBC, Thread.sleep, .result(), or busy CPU on an event-loop verticle. Use the async Vert.x clients; offload blocking libraries with vertx.executeBlocking(...) or a worker verticle.
• Compose, don’t nest. flatMap for dependent async steps, map for pure transforms, CompositeFuture.all/any for fan-out, recover for fallback, eventually for cleanup.
• Propagate failure, don’t swallow. Return the Future; let it fail up to the handler’s onFailure. A bare onFailure(log) that doesn’t rethrow hides errors — only the handler terminates the chain into an HTTP response.
• onSuccess/onFailure are side-effect observers (log/metric), not control flow. Transform with map/flatMap.

1
// ✅ dependent steps compose linearly
2
return orderRepository.findById(cid, conn, id)
3
        .flatMap(order -> paymentService.authorize(order))
4
        .map(OrderResponse::new);
5

6
// ❌ callback pyramid / blocking
7
var order = orderRepository.findById(...).result();   // blocks event loop — forbidden

6. Event-driven (EventBus + workers)

Use the EventBus to (a) decouple cross-cutting concerns and (b) offload long-running work off the request path. Topics are typed constants, never inline strings.

1
public final class EventBusTopic {
2
    interface Topic { String getTopic(); }
3

4
    public enum ORDERS implements Topic {
5
        BULK_IMPORT("orders.bulk.import");
6
        private final String topic;
7
        ORDERS(String topic) { this.topic = topic; }
8
        @Override public String getTopic() { return topic; }
9
    }
10
}

A worker Verticle owns its repositories/services and registers consumers in start(). Deploy with setWorker(true) and a bounded pool.

1
DeploymentOptions options = new DeploymentOptions()
2
        .setWorker(true)
3
        .setWorkerPoolSize(10)
4
        .setMaxWorkerExecuteTime(5).setMaxWorkerExecuteTimeUnit(TimeUnit.SECONDS);
5
vertx.deployVerticle(new BulkImportWorkerVerticle(dbClient, mongoClient, /* ... */), options);
6

7
// inside BulkImportWorkerVerticle.start():
8
eventBus.consumer(ORDERS.BULK_IMPORT.getTopic(), importHandler::handleBulkImport);

Rules

• Messages cross the bus as JsonObject/String (codec-friendly). Register a codec for custom types; don’t ship framework objects.
• In-process bus = at-most-once, no durability. For exactly-once / cross-service delivery use a real broker + the outbox pattern — the EventBus is not a substitute.
• A consumer must reply or fail explicitly on request/reply, else the sender times out.

7. Persistence

PostgreSQL is primary (relational, Flyway-migrated); MongoDB holds document-shaped collections (e.g. notifications); Redis for cache/ephemeral. Build pools once in DbUtils:

1
final PgConnectOptions connectOptions = new PgConnectOptions()
2
        .setHost(host).setPort(port).setDatabase(db).setUser(user).setPassword(password);
3
final PoolOptions poolOptions = new PoolOptions()
4
        .setMaxSize(maxPoolSize).setIdleTimeout(maxIdle).setIdleTimeoutUnit(TimeUnit.SECONDS);
5
return PgBuilder.pool().with(poolOptions).connectingTo(connectOptions).using(vertx).build();

• Unit of work: pool.withConnection(conn -> ...) per use case; pass conn down to every repository call so they share it. Use pool.withTransaction(...) when multiple writes must commit atomically.
• Migrations: Flyway in a dedicated module; forward-only; V<timestamp>__<desc>.sql; never edit an applied migration (see liquibase.md for the same immutability rule applied to Flyway).
• Secrets in columns: encrypt at the SQL boundary (pgp_sym_encrypt/ pgp_sym_decrypt), key injected as a bind param — never logged.
• Mongo: MongoClient.createShared(vertx, config) for pool reuse; mongodb+srv connection strings use MongoClient.create.

8. Error handling

Typed exception hierarchy → single mapper → HTTP. Services throw domain exceptions; the router’s failure handler converts them.

1
public static ErrorResponse getErrorResponse(Throwable t, Locale locale) {
2
    if (t instanceof BusinessException be)        return new ErrorResponse(be.gHttpResponseError(), be.getCode(), ...);
3
    if (t instanceof ClientException ce)          return new ErrorResponse(ce.gHttpResponseError(), ...);
4
    if (t instanceof PgException pg)              return handlePgException(pg);   // 23505 → UNIQUE_VIOLATION
5
    if (t instanceof EntityNotFoundException)     return new ErrorResponse(HttpResponseError.ENTITY_NOT_EXIST, ...);
6
    if (t instanceof IllegalArgumentException)    return new ErrorResponse(HttpResponseError.ILLEGAL_ARGUMENT_PARAMETERS, ...);
7
    return new ErrorResponse(HttpResponseError.INTERNAL_SERVER_ERROR, ...);
8
}

• Throw BusinessException (with an HTTP-mapped error enum) for rule violations; ClientException for downstream failures.
• Never catch (Exception) and continue silently; let the Future fail to the handler, which calls ResponseUtils.buildErrorResponse.
• Map DB constraint codes centrally (e.g. 23505 → 409), don’t leak PgException.
• Responses are localized (Locale from the i18n handler).

9. Validation & security

• Validation handlers run before the business handler (per route), one per operation (validation.readOne(), versioned under validation/v2/). Reject malformed input at the edge; the handler assumes valid input.
• AuthN: JWT via JWKS (JwkHandler); reject unauthenticated on protected routes.
• AuthZ: role-based from the route policy string (RoleBasedAuthorization + JWTAuthorization.create("realm_access/roles")), plus resource-level checks (AuthorizeResourceHandler). Never hand-roll if (role.equals(...)) in handlers.
• Transport: TLS by default; mTLS optional via server key/cert config.
• Never log tokens, PII, decrypted secrets, or full request bodies. Log with correlationId.

10. Configuration & JSON

ConfigUtils loads application.properties then overrides with env vars (a.b.c → A_B_C) in non-dev, and transparently decrypts ENC(...) values (AES/CBC) using BASE64_KEY/BASE64_IV.

1
String host = ConfigUtils.getStringProperty(Constants.HTTP_HOST);
2
boolean mtls = ConfigUtils.getBooleanProperty(Constants.MTLS_SERVER_ENABLED);

• Read config once at bootstrap where practical; avoid per-request lookups in hot paths.
• Secrets come from env/k8s secrets/volume-mounted keystores — never committed.
• JSON: prefer Vert.x-native Json.encode/JsonObject.mapFrom (Jackson via DatabindCodec). Configure the shared DatabindCodec.mapper() once at startup (JSR-310, no-timestamps, ignore-unknown). Do not allocate a new ObjectMapper() per call. (This stack pins Jackson 2.x; the JsonMapper-only rule from java-code-style.md applies to Jackson 3.x stacks.)

11. Observability

• Metrics: vertx-micrometer-metrics → Prometheus. Domain metrics emitted off the request path via EventBus (sendMetricIncrement(...) in AbstractHandler).
• Health: vertx-health-check endpoints for liveness/readiness (DB ping).
• Logging: SLF4J + Logback, structured, always carry correlationId (extracted in the logging handler, propagated through service/repository logs).
• Tracing: propagate W3C traceparent when calling downstream via WebClient.

12. Testing

vertx-junit5 + VertxTestContext; real dependencies via Testcontainers (PostgreSQL, MongoDB). Async assertions complete the context explicitly.

1
@ExtendWith(VertxExtension.class)
2
class OrderApiTest extends AbstractApiTest {
3

4
    @Test
5
    void readAll_returns200(Vertx vertx, VertxTestContext testContext) {
6
        WebClient.create(vertx)
7
            .get(PORT, "localhost", "/api/v1/orders")
8
            .bearerTokenAuthentication(token)
9
            .as(BodyCodec.jsonObject())
10
            .send(testContext.succeeding(res -> testContext.verify(() -> {
11
                assertEquals(200, res.statusCode());
12
                testContext.completeNow();
13
            })));
14
    }
15
}

• Deploy the verticle once in @BeforeAll(Vertx, VertxTestContext); share clients.
• Use testContext.succeeding(...)/failing(...) + completeNow() / failNow(); never assert outside testContext.verify(...) (assertion errors inside raw callbacks are swallowed).
• Testcontainers for DB; no mocks for repositories (test real SQL). Mock only outbound HTTP clients (mockito-inline) when the remote is out of scope.
• Set a per-test timeout; don’t leave @Disabled tests in main — fix or delete.

13. Build & deploy

• Gradle Kotlin DSL, shadowJar produces a single app-all.jar (mergeServiceFiles(), exclude key material *.jks/*.pem).
• Main class: the custom Launcher; run as java -jar app.jar run com....MainVerticle.
• Spotless + SpotBugs must pass before commit.
• Container: eclipse-temurin:17-jre base; copy the fat jar; set the SLF4J log delegate. Run as non-root and mount secrets read-only (k8s) — add a non-root USER to the Dockerfile if missing.
• Config via env in k8s (ConfigMap + Secrets); keystores/certs as read-only volume mounts.

14. Naming conventions

15. Anti-patterns

16. Pre-merge checklist

• No blocking on the event loop; heavy work on a worker verticle.
• Handler thin: parse → one service call → ResponseUtils (success + failure).
• Service composes Futures; one withConnection/withTransaction per use case.
• Repository uses parameterized SQL + Tuple; SQL as static final constants.
• EventBus topics are enum constants; consumers reply/fail on request.
• Errors are typed exceptions mapped centrally; no silent catches; no PgException leaks.
• Validation handler covers the new route; authZ policy set (not public by accident).
• Config via ConfigUtils; secrets from env/volumes; nothing committed.
• vertx-junit5 test with Testcontainers; assertions in verify; no @Disabled left behind.
• Spotless + SpotBugs clean; fat jar builds; container runs non-root.
• No tokens/PII in logs; correlationId propagated.

Style: layered N-tier reactive + event-driven (Eclipse Vert.x 4.x). For rich-domain contexts that warrant ports-and-adapters, see hexagonal-architecture.md; for reliable cross-service eventing see messaging.md.