Migration to Vert.x 5 and Netty 4.2

[jponge]

Description

This epic is to track the migration from Vert.x 4 to Vert.x 5 in Quarkus and across its wider ecosystem. Switching to Netty 4.2 is also part of this effort as Vert.x 5 depends on it, and this Netty branch has substantial changes compared to Netty 4.1.

Analysis

Switching to Vert.x 5 and Netty 4.2 is not a simple dependency bump, there are modules, APIs and runtime breaking changes.

The migration effort will require a multi-step approach to migrate the direct dependency components first (likely with beta releases for downstream consumption), then Quarkus itself, then "major" projects in the Quarkiverse ecosystem.

Vert.x 5 and Netty 4.2 migration guides

See:

• https://vertx.io/docs/guides/vertx-5-migration-guide/
• https://github.com/netty/netty/wiki/Netty-4.2-Migration-Guide
• https://vertx.io/blog/whats-new-in-vert-x-5-1/

Roadmap

The initial roadmap is the following.

1. Smallrye Mutiny Vert.x Bindings

Many drivers and user-facing APIs consume Vert.x 5 through the Mutiny bindings, so it has to be migrated first (tracked by smallrye/smallrye-mutiny-vertx-bindings#1045)

• New bindings generator that supports Vert.x 5 APIs
• Reconsideration of what modules we should support in this project, and what modules we should drop
• Alignment with the latest Vert.x 5 releases
• Release a first public beta for downstream consumption

2. Direct Quarkus dependencies ecosystem

Each project will need to publish beta releases when it has performed its migration.

• https://github.com/smallrye/smallrye-fault-tolerance
  • Upgrade to Vert.x 5 smallrye/smallrye-fault-tolerance#1193
  • Upgrade to Vert.x 5 smallrye/smallrye-fault-tolerance#1188
• https://github.com/smallrye/smallrye-opentelemetry
  • Upgrade to Vert.x 5 smallrye/smallrye-opentelemetry#542
  • Upgrade to Vert.x 5 smallrye/smallrye-opentelemetry#540
• https://github.com/smallrye/smallrye-common
  • Upgrade to Vert.x 5 smallrye/smallrye-common#515
  • Upgrade to Vert.x 5 smallrye/smallrye-common#513
• https://github.com/smallrye/smallrye-stork
  • Upgrade to Vert.x 5 smallrye/smallrye-stork#1155
  • Upgrade to Vert.x 5 with address resolver integration sample smallrye/smallrye-stork#1171
• https://github.com/smallrye/smallrye-reactive-messaging
  • Upgrade to Vert.x 5 smallrye/smallrye-reactive-messaging#3287
• https://github.com/hibernate/hibernate-reactive
  • Already upgraded to Vert.x 5
• https://github.com/quarkusio/quarkus-http
  • Upgrade to Vert.x 5 quarkus-http#185
  • Update to Vert.x 5.0.6 and Netty 4.2.9 quarkus-http#184
• https://github.com/fabric8io/kubernetes-client
  • Already upgraded to Vert.x 5 in https://github.com/fabric8io/kubernetes-client/tree/main/httpclient-vertx-5
• https://github.com/smallrye/smallrye-graphql
  • Migration to Vert.x 5.0.11 smallrye/smallrye-graphql#2444

3. Quarkus "independent projects"

At this stage we will be able to create a long-running branch to prepare https://github.com/quarkusio/quarkus itself to migrate.

There are 2 projects to migrate under the independent-projects/ folder of the Quarkus repository:

• https://github.com/quarkusio/quarkus/tree/main/independent-projects/vertx-utils
  • Migrated vertx-utils to Vert.x 5.0.8 #53008
  • Migration of vertx-utils to Vert.x 5.0.9 #53292
• https://github.com/quarkusio/quarkus/tree/main/independent-projects/resteasy-reactive
  • Migration of RestEasy Reactive to Vert.x 5 #53340

4. Quarkus initial migration (JVM)

At this stage we will migrate https://github.com/quarkusio/quarkus itself to Vert.x 5 and Netty 4.2 in the vertx-5-migration branch.

We focus on correctness, not technical debt reduction. We don't focus on performance either.

• Migrate the code base to Vert.x 5 in the https://github.com/quarkusio/quarkus/tree/vertx-5-migration branch
• Ensure every extension builds
• Cleanup temporary fixes:
  • Revisit [4.0] migrate reactive datasources to vertx 5 #53436 as had to move from resteasy to reactive-routes in the interim
  • Revisit [4.0] Rework context local registration #53506 (ContextLocal registration hack to make progress)
  • Bump to smallrye-common beyond 2.17.1 for fixed ContextLocal registration
  • gRPC migration leftovers:
    • Deadlines are not working
    • Async Clients are on Vert.x context (even root context)
    • Port extraction is not implemented
  • Forward port Make all Vert.x executeBlocking ordering requirement explicit #54314

5. Quarkus full migration (JVM + native + 4.0 features)

Notable attention points once we have a vertx-5-migration branch "migrated" as a baseline:

• Ensure Vert.x has a flexible dependency on Jackson (2 vs 3)
  • Jackson v3 support eclipse-vertx/vert.x#5531
• Fix having to use UserContextInternal to set user context in Vert.x routing contexts (see [4.0] Websocket migrations #53717 (comment))
• Support Jackson 3 (see Update to Jackson 3 #52036)
• Support HTTP/3 (see Support http/3 #26852)
• Support native transports and io_uring (see Support native transports in native executables  #35799)
• Use the Netty pooled allocator on VirtualThread(s) (see Quarkus 4 should use the Netty pooled allocator on VirtualThread(s) too #53862)
• Hibernate Reactive to use ContextLocal (see Switch to Vert.x 5 API for ContextLocal storage hibernate/hibernate-reactive#3793)
  • See [4.3] Use Vert.x 5 Context local storage API hibernate/hibernate-reactive#3813
• Netty 4.2 integration (see Integration of Netty 4.2 #34202)
  • Rework Netty virtual server
  • Address Netty 4.2 and shared Arenas performance issues (see Netty 4.2 and shared Arenas performance issues #54011)
• Rework Vertx{Input,Output}Stream implementation and usage (see Unify and rework the Vertx{Input,Output}Stream code #53618)
• Native compilation fixes to the core extensions
• Fix having to use UserContextInternal to set user context in Vert.x routing contexts
• Review the documentation about Unix Domain Sockets (see Quarkus 4: review documentation about Unix Domain Sockets #54528)
• Address idiomatic usage of the new Vert.x LocalContext API across all the code base (see Need to integrate with the new Vert.x Local Data SPI #39710)
• Technical debt reduction: revisit Vert.x and asynchronous APIs usage and refactor to idiomatic Vert.x code
• Improve or drop our Vert.x event-bus support
  • see Improve Event bus #50583
  • see Introduce quarkus-signals experimental extension #53788
• Remove the Vert.x clustering configuration + support

Finalization:

• Fix and ensure all tests pass in JVM mode
• Fix and ensure native compilation so all tests pass in native mode
• Fix and ensure all integration tests
• Ensure everything passes in upstream CI
• Evaluate performance and coordinate possible upstream fixes
• Document breaking changes and have a migration guide related to the impact of this migration

6. Quarkiverse

• Select a few priority projects to coordinate and migrate
  • https://github.com/quarkiverse/quarkus-langchain4j
  • Migrate to Vert.x 5 and Netty 4.2 quarkiverse/quarkus-cxf#2062

7. The big merge

• Green flag for all dependency projects to leave beta and perform proper releases
• Merge into main
• Celebrate!

Initial stakeholders

Stakeholders related to the components and steps above: @jponge @anavarr @vietj @tsegismont @ozangunalp @franz1981 @DavideD @lucamolteni @geoand @gsmet @cescoffier @aureamunoz @radcortez @dmlloyd @brunobat @Ladicek @mkouba

Migrated artifacts version tracking

These projects have Vert.x 5 artifacts available from Maven Central starting from these releases:

• org.hibernate.reactive:hibernate-reactive: 4.2.1.Final
• io.fabric8:kubernetes-httpclient-vertx-5: 7.6.1
• io.smallrye.reactive:smallrye-mutiny-*: 4.0.0-beta0
• io.smallrye.common:smallrye-common-vertx5-context: 2.17.0
• io.smallrye:smallrye-fault-tolerance (and related): 7.0.0-RC1
• io.quarkus.http:quarkus-http: 6.0.0.Alpha3
• io.smallrye.reactive:smallrye-reactive-messaging-*: 5.0.0-beta0
• io.smallrye.opentelemetry:smallrye-opentelemetry-*: 2.12.0
• io.smallrye:smallrye-graphql: 3.0.0.Beta1
• io.smallrye.reactive:smallrye-reactive-messaging: 5.0.0-beta1

[quarkus-bot]

/cc @cescoffier (netty), @franz1981 (netty)