fix(httpclient): correct factory priorities and add Vert.x 5 runtime validation (7442)

fix(httpclient): correct HTTP client factory priorities

VertxHttpClientFactory is now the default HTTP client but was missing
the priority -1 that indicates it's the project default. OkHttpClientFactory
was still using priority -1 from when it was the default.

This fix:
- Adds priority() returning -1 to VertxHttpClientFactory (new default)
- Removes priority() override from OkHttpClientFactory (now uses default 0)

This ensures deterministic factory selection when multiple HTTP clients
are on the classpath - the default Vert.x client will always be preferred
unless a higher priority client is present.

Fixes #7174

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
fix(httpclient-vertx-5): add runtime check and documentation for Vert.x version compatibility

Add runtime validation in Vertx5HttpClientFactory.newBuilder() to detect
when Vert.x 5 classes are not available on the classpath.
This provides a clear error message instead of cryptic NoClassDefFoundError
when both kubernetes-httpclient-vertx (Vert.x 4) and kubernetes-httpclient-vertx-5
(Vert.x 5) are present but Maven resolves Vert.x 4 JARs.

Also add detailed documentation in CHANGELOG explaining:
- The mutual exclusivity of the two Vert.x HTTP client modules
- How to properly configure Vert.x 5 with exclusions and property override
- The root cause of the classpath conflict

Fixes #7174

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: manusa

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 #### Bugs
 * Fix #5292: Cluster() configuration should use tlsServerName
+* Fix #7174: (httpclient) Fix HTTP client factory priority - VertxHttpClientFactory (default) now has priority -1, OkHttpClientFactory restored to priority 0
+* Fix #7174: (httpclient-vertx-5) Add runtime check for Vert.x 5 classes to provide clear error when Vert.x 4/5 conflict occurs
+* Fix #7174: (chaos-tests) Fix classpath conflict when testing with Vert.x 5 HTTP client
 * Fix #7415: (java-generator) Fix generic type erasure for array of enums with default values
 
 #### Improvements
@@ -16,6 +19,42 @@
 
 #### _**Note**_: Breaking changes
 
+#### _**Note**_: Vert.x HTTP Client Compatibility (Issue #7174)
+
+The `kubernetes-httpclient-vertx` (Vert.x 4.x) and `kubernetes-httpclient-vertx-5` (Vert.x 5.x) modules are **mutually exclusive**.
+They must not be included together in your project dependencies.
+Both modules provide an implementation of `HttpClient.Factory` and use the same `io.vertx` artifact coordinates but with incompatible major versions.
+
+**Problem**: If both modules are present on the classpath, Maven's dependency resolution may pick Vert.x 4.x JARs while the `Vertx5HttpClientFactory` is selected at runtime.
+This causes `NoClassDefFoundError` for Vert.x 5-specific classes like `io.vertx.core.impl.SysProps`.
+
+**Solution**: Ensure your project includes only ONE of these modules:
+- `kubernetes-httpclient-vertx` (default, uses Vert.x 4.x) - included transitively via `kubernetes-client`
+- `kubernetes-httpclient-vertx-5` (optional, uses Vert.x 5.x) - requires explicit dependency and exclusion of vertx-4
+
+When using Vert.x 5, exclude the default Vert.x 4 client and set the `vertx.version` property:
+```xml
+<properties>
+  <vertx.version>${vertx5.version}</vertx.version> <!-- or explicit 5.0.7 -->
+</properties>
+<dependencies>
+  <dependency>
+    <groupId>io.fabric8</groupId>
+    <artifactId>kubernetes-client</artifactId>
+    <exclusions>
+      <exclusion>
+        <groupId>io.fabric8</groupId>
+        <artifactId>kubernetes-httpclient-vertx</artifactId>
+      </exclusion>
+    </exclusions>
+  </dependency>
+  <dependency>
+    <groupId>io.fabric8</groupId>
+    <artifactId>kubernetes-httpclient-vertx-5</artifactId>
+  </dependency>
+</dependencies>
+```
+
 ### 7.5.2 (2026-01-22)
 
 #### Dependency Upgrade

httpclient-okhttp/src/main/java/io/fabric8/kubernetes/client/okhttp/OkHttpClientFactory.java

@@ -27,11 +27,6 @@
 
 public class OkHttpClientFactory implements HttpClient.Factory {
 
-  @Override
-  public int priority() {
-    return -1;
-  }
-
   /**
    * Subclasses may use this to apply a base configuration to the builder
    */

httpclient-vertx-5/src/main/java/io/fabric8/kubernetes/client/vertx5/Vertx5HttpClientFactory.java

@@ -19,16 +19,25 @@
 import io.vertx.core.Vertx;
 
 /**
- * Vert.x implementation of {@link io.fabric8.kubernetes.client.http.HttpClient.Factory}.
+ * Vert.x 5 implementation of {@link io.fabric8.kubernetes.client.http.HttpClient.Factory}.
  *
  * <p>
  * When constructed with a non‑null {@link Vertx} the same instance is reused for every
  * client; otherwise each {@link #newBuilder()} call will lazily create (and own) its own
  * Vert.x runtime.
  * </p>
+ *
+ * <p>
+ * <strong>Important:</strong> This HTTP client requires Vert.x 5.x runtime classes.
+ * It is mutually exclusive with {@code kubernetes-httpclient-vertx} (Vert.x 4.x).
+ * Including both on the classpath will cause runtime errors due to incompatible
+ * Vert.x API versions. Ensure your project excludes one or the other.
+ * </p>
  */
 public class Vertx5HttpClientFactory implements HttpClient.Factory {
 
+  private static final String VERTX5_MARKER_CLASS = "io.vertx.core.impl.SysProps";
+
   final Vertx vertx;
 
   /**
@@ -53,9 +62,37 @@ public Vertx5HttpClientFactory(final Vertx vertx) {
   /**
    * {@inheritDoc} – reuses the shared Vert.x when present, otherwise defers creation to the
    * builder.
+   *
+   * @throws IllegalStateException if Vert.x 5 runtime classes are not available on the classpath
    */
   @Override
   public Vertx5HttpClientBuilder<Vertx5HttpClientFactory> newBuilder() {
+    validateVertx5Runtime();
     return new Vertx5HttpClientBuilder<>(this, vertx);
   }
+
+  /**
+   * Validates that Vert.x 5 runtime classes are available on the classpath.
+   *
+   * <p>
+   * This check prevents cryptic {@link NoClassDefFoundError} when both
+   * {@code kubernetes-httpclient-vertx} (Vert.x 4) and {@code kubernetes-httpclient-vertx-5}
+   * are on the classpath, but Maven dependency resolution picks Vert.x 4 JARs.
+   * </p>
+   *
+   * @throws IllegalStateException if Vert.x 5 runtime is not available
+   */
+  private static void validateVertx5Runtime() {
+    try {
+      Class.forName(VERTX5_MARKER_CLASS);
+    } catch (ClassNotFoundException e) {
+      throw new IllegalStateException(
+          "Vert.x 5 runtime classes not found. The kubernetes-httpclient-vertx-5 module requires "
+              + "Vert.x 5.x on the classpath. This error typically occurs when both kubernetes-httpclient-vertx "
+              + "(Vert.x 4) and kubernetes-httpclient-vertx-5 (Vert.x 5) are present, causing Maven to resolve "
+              + "Vert.x 4 JARs. These modules are mutually exclusive - please exclude one from your dependencies "
+              + "and ensure vertx.version property is set appropriately (5.x for vertx-5, 4.x for vertx).",
+          e);
+    }
+  }
 }

httpclient-vertx/src/main/java/io/fabric8/kubernetes/client/vertx/VertxHttpClientFactory.java

@@ -23,6 +23,11 @@ public class VertxHttpClientFactory implements io.fabric8.kubernetes.client.http
 
   final Vertx sharedVertx;
 
+  @Override
+  public int priority() {
+    return -1;
+  }
+
   public VertxHttpClientFactory() {
     this(null);
   }