HTTP server builder.

Motivation:

The new TCP configuration still references the SSL engine options, we should externalize that and make it a separate side of the actual TCP configuration.

Changes:

Add a new HTTP server builder that allows to configure various aspects of an HTTP server.

HTTP client builder also gets augmented with SSL engine options configurability.

Author: vietj

vertx-core/src/main/asciidoc/net.adoc

@@ -515,22 +515,6 @@ NOTE: The options object is compared (using `equals`) against the existing optio
 are equals since loading options can be costly. When object are equals, you can use the `force` parameter to force
 the update.
 
-==== SSL engine
-
-The engine implementation can be configured to use https://www.openssl.org[OpenSSL] instead of the JDK implementation.
-Before JDK started to use hardware intrinsics (CPU instructions) for AES in Java 8 and for RSA in Java 9,
-OpenSSL provided much better performances and CPU usage than the JDK engine.
-
-The engine options to use is
-
-- the {@link io.vertx.core.net.TCPSSLOptions#getSslEngineOptions()} options when it is set
-- otherwise {@link io.vertx.core.net.JdkSSLEngineOptions}
-
-[source,$lang]
-----
-{@link examples.NetExamples#exampleSSLEngine}
-----
-
 === Using a proxy for client connections
 
 The {@link io.vertx.core.net.NetClient} supports either an HTTP/1.x _CONNECT_, _SOCKS4a_ or _SOCKS5_ proxy.

vertx-core/src/main/asciidoc/ssl.adoc

@@ -55,3 +55,14 @@ Protocol versions can be specified on the {@link io.vertx.core.net.ServerSSLOpti
 
 NOTE: TLS 1.0 (TLSv1) and TLS 1.1 (TLSv1.1) are widely deprecated and have been disabled by default since Vert.x 4.4.0.
 
+=== SSL engine
+
+The engine implementation can be configured to use https://www.openssl.org[OpenSSL] instead of the JDK implementation.
+Before JDK started to use hardware intrinsics (CPU instructions) for AES in Java 8 and for RSA in Java 9,
+OpenSSL provided much better performances and CPU usage than the JDK engine.
+
+[source,$lang]
+----
+{@link examples.SslExamples#exampleSSLEngine}
+----
+

vertx-core/src/main/generated/io/vertx/core/net/JdkSSLEngineOptionsConverter.java

@@ -0,0 +1,31 @@
+package io.vertx.core.net;
+
+import io.vertx.core.json.JsonObject;
+import io.vertx.core.json.JsonArray;
+
+/**
+ * Converter and mapper for {@link io.vertx.core.net.JdkSSLEngineOptions}.
+ * NOTE: This class has been automatically generated from the {@link io.vertx.core.net.JdkSSLEngineOptions} original class using Vert.x codegen.
+ */
+public class JdkSSLEngineOptionsConverter {
+
+   static void fromJson(Iterable<java.util.Map.Entry<String, Object>> json, JdkSSLEngineOptions obj) {
+    for (java.util.Map.Entry<String, Object> member : json) {
+      switch (member.getKey()) {
+        case "useWorkerThread":
+          if (member.getValue() instanceof Boolean) {
+            obj.setUseWorkerThread((Boolean)member.getValue());
+          }
+          break;
+      }
+    }
+  }
+
+   static void toJson(JdkSSLEngineOptions obj, JsonObject json) {
+    toJson(obj, json.getMap());
+  }
+
+   static void toJson(JdkSSLEngineOptions obj, java.util.Map<String, Object> json) {
+    json.put("useWorkerThread", obj.getUseWorkerThread());
+  }
+}

vertx-core/src/main/java/examples/NetExamples.java

@@ -362,23 +362,6 @@ public void updateSSLOptions(HttpServer server) {
           setPassword("password-of-your-keystore")));
   }
 
-  public void exampleSSLEngine(Vertx vertx, JksOptions keyStoreOptions) {
-
-    // Use JDK SSL engine
-    TcpServerConfig options = new TcpServerConfig().
-      setSsl(true);
-
-    // Use JDK SSL engine explicitly
-    options = new TcpServerConfig().
-      setSsl(true).
-      setSslEngineOptions(new JdkSSLEngineOptions());
-
-    // Use OpenSSL engine
-    options = new TcpServerConfig().
-      setSsl(true).
-      setSslEngineOptions(new OpenSSLEngineOptions());
-  }
-
   public void example46(Vertx vertx, String verificationAlgorithm, TrustOptions trustOptions) {
     TcpClientConfig config = new TcpClientConfig().
       setSsl(true);

vertx-core/src/main/java/examples/SslExamples.java

@@ -3,17 +3,22 @@
 import io.vertx.core.Vertx;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.http.ClientAuth;
+import io.vertx.core.http.HttpServer;
+import io.vertx.core.http.HttpServerConfig;
 import io.vertx.core.net.ClientSSLOptions;
+import io.vertx.core.net.JdkSSLEngineOptions;
 import io.vertx.core.net.JksOptions;
 import io.vertx.core.net.KeyStoreOptions;
 import io.vertx.core.net.NetClient;
 import io.vertx.core.net.NetClientOptions;
 import io.vertx.core.net.NetServer;
 import io.vertx.core.net.NetServerOptions;
+import io.vertx.core.net.OpenSSLEngineOptions;
 import io.vertx.core.net.PemKeyCertOptions;
 import io.vertx.core.net.PemTrustOptions;
 import io.vertx.core.net.PfxOptions;
 import io.vertx.core.net.ServerSSLOptions;
+import io.vertx.core.net.TcpServerConfig;
 
 import java.util.Arrays;
 
@@ -304,4 +309,29 @@ public void configureSNIServerWithPems(Vertx vertx) {
         ))
       .setSni(true);
   }
+
+  public void exampleSSLEngine(Vertx vertx, JksOptions keyStoreOptions) {
+
+    ServerSSLOptions sslOptions = new ServerSSLOptions()
+      .setKeyCertOptions(keyStoreOptions);
+    HttpServerConfig config = new HttpServerConfig()
+      .setSsl(true);
+
+    // Use JDK SSL engine
+    HttpServer server = vertx.createHttpServer(config);
+
+    // Use JDK SSL engine explicitly
+    server = vertx.httpServerBuilder()
+      .with(config)
+      .with(sslOptions)
+      .with(new JdkSSLEngineOptions())
+      .build();
+
+    // Use OpenSSL engine
+    server = vertx.httpServerBuilder()
+      .with(config)
+      .with(sslOptions)
+      .with(new OpenSSLEngineOptions())
+      .build();
+  }
 }

vertx-core/src/main/java/io/vertx/core/Vertx.java

@@ -19,6 +19,7 @@
 import io.vertx.core.eventbus.EventBus;
 import io.vertx.core.file.FileSystem;
 import io.vertx.core.http.*;
+import io.vertx.core.http.impl.HttpServerBuilderImpl;
 import io.vertx.core.impl.VertxImpl;
 import io.vertx.core.internal.ContextInternal;
 import io.vertx.core.dns.impl.DnsAddressResolverProvider;
@@ -34,6 +35,7 @@
 import io.vertx.core.net.QuicClientConfig;
 import io.vertx.core.net.QuicServer;
 import io.vertx.core.net.QuicServerConfig;
+import io.vertx.core.net.SSLEngineOptions;
 import io.vertx.core.net.ServerSSLOptions;
 import io.vertx.core.net.TcpClientConfig;
 import io.vertx.core.net.TcpServerConfig;
@@ -324,7 +326,25 @@ default QuicClient createQuicClient(QuicClientConfig config) {
    * @param options  the options to use
    * @return the server
    */
-  HttpServer createHttpServer(HttpServerOptions options);
+  default HttpServer createHttpServer(HttpServerOptions options) {
+    HttpServerConfig config = new HttpServerConfig(options);
+    ServerSSLOptions sslOptions = options.getSslOptions();
+    if (sslOptions != null) {
+      sslOptions = sslOptions.copy();
+    } else if (options.isSsl()) {
+      sslOptions = new ServerSSLOptions();
+    }
+    SSLEngineOptions sslEngineOptions = options.getSslEngineOptions();
+    if (sslEngineOptions != null) {
+      sslEngineOptions = sslEngineOptions.copy();
+    }
+    HttpServerBuilder builder = ((HttpServerBuilderImpl)httpServerBuilder())
+      .with(config)
+      .with(sslOptions)
+      .with(sslEngineOptions)
+      .registerWebSocketWriteHandlers(options.isRegisterWebSocketWriteHandlers());
+    return builder.build();
+  }
 
   /**
    * Create an HTTP server using the specified config
@@ -342,7 +362,9 @@ default HttpServer createHttpServer(HttpServerConfig config) {
    * @param config  the config to use
    * @return the server
    */
-  HttpServer createHttpServer(HttpServerConfig config, ServerSSLOptions sslOptions);
+  default HttpServer createHttpServer(HttpServerConfig config, ServerSSLOptions sslOptions) {
+    return httpServerBuilder().with(config).with(sslOptions).build();
+  }
 
   /**
    * Create an HTTP/HTTPS server using default options
@@ -353,6 +375,14 @@ default HttpServer createHttpServer() {
     return createHttpServer(new HttpServerOptions());
   }
 
+  /**
+   * Provide a builder for {@link HttpServer}, it can be used to configure advanced
+   * HTTP servre settings like a connection handler.
+   * <p>
+   * Example usage: {@code HttpServer server = vertx.httpServerBuilder().with(options).withConnectHandler(conn -> ...).build()}
+   */
+  HttpServerBuilder httpServerBuilder();
+
   /**
    * Create a WebSocket client using default options
    *

vertx-core/src/main/java/io/vertx/core/eventbus/impl/clustered/ClusteredEventBus.java

@@ -129,11 +129,7 @@ public static String defaultAddress() {
   }
 
   private NetClient createNetClient(VertxInternal vertx, NetClientOptions clientOptions) {
-    TcpClientConfig config = new TcpClientConfig(clientOptions);
-    NetClientBuilder builder = new NetClientBuilder(vertx, config)
-      .sslOptions(clientOptions.getSslOptions())
-      .registerWriteHandler(clientOptions.isRegisterWriteHandler());
-    return builder.build();
+    return new NetClientBuilder(vertx, clientOptions).build();
   }
 
   private NetServerOptions getServerOptions() {

vertx-core/src/main/java/io/vertx/core/http/HttpClientBuilder.java

@@ -16,6 +16,7 @@
 import io.vertx.core.Future;
 import io.vertx.core.Handler;
 import io.vertx.core.net.ClientSSLOptions;
+import io.vertx.core.net.SSLEngineOptions;
 import io.vertx.core.net.endpoint.LoadBalancer;
 import io.vertx.core.net.AddressResolver;
 
@@ -61,6 +62,14 @@ public interface HttpClientBuilder {
   @Fluent
   HttpClientBuilder with(ClientSSLOptions options);
 
+  /**
+   * Configure the client with the given SSL {@code engine}.
+   * @param engine the SSL engine options
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HttpClientBuilder with(SSLEngineOptions engine);
+
   /**
    * Set a connection handler for the client. This handler is called when a new connection is established.
    *

vertx-core/src/main/java/io/vertx/core/http/HttpServerBuilder.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+package io.vertx.core.http;
+
+import io.vertx.codegen.annotations.Fluent;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.core.Handler;
+import io.vertx.core.net.SSLEngineOptions;
+import io.vertx.core.net.ServerSSLOptions;
+
+/**
+ * A builder for {@link HttpServer}.
+ *
+ * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
+ */
+@VertxGen
+public interface HttpServerBuilder {
+
+  /**
+   * Configure the server.
+   * @param config the server config
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HttpServerBuilder with(HttpServerConfig config);
+
+  /**
+   * Configure the server with the given SSL {@code options}.
+   * @param options the SSL options
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HttpServerBuilder with(ServerSSLOptions options);
+
+  /**
+   * Configure the server with the given SSL {@code engine}.
+   * @param engine the SSL engine options
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HttpServerBuilder with(SSLEngineOptions engine);
+
+  /**
+   * Set a connection handler for the server. This handler is called when a new connection is established.
+   *
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HttpServerBuilder withConnectHandler(Handler<HttpConnection> handler);
+
+  /**
+   * Build and return the server.
+   * @return the server as configured by this builder
+   */
+  HttpServer build();
+
+}

vertx-core/src/main/java/io/vertx/core/http/impl/HttpClientBuilderInternal.java

@@ -19,6 +19,7 @@
 import io.vertx.core.net.ClientSSLOptions;
 import io.vertx.core.net.NetworkLogging;
 import io.vertx.core.net.ProxyOptions;
+import io.vertx.core.net.SSLEngineOptions;
 import io.vertx.core.net.endpoint.LoadBalancer;
 import io.vertx.core.net.AddressResolver;
 import io.vertx.core.net.endpoint.impl.EndpointResolverImpl;
@@ -37,6 +38,7 @@ public final class HttpClientBuilderInternal implements HttpClientBuilder {
   private HttpClientConfig clientConfig;
   private HttpClientOptions clientOptions; // To be removed
   private ClientSSLOptions sslOptions;
+  private SSLEngineOptions sslEngineOptions;
   private PoolOptions poolOptions;
   private Handler<HttpConnection> connectHandler;
   private Function<HttpClientResponse, Future<RequestOptions>> redirectHandler;
@@ -58,6 +60,7 @@ public HttpClientBuilder with(HttpClientConfig config) {
   public HttpClientBuilder with(HttpClientOptions options) {
     this.clientConfig = new HttpClientConfig(options);
     this.sslOptions = options.getSslOptions();
+    this.sslEngineOptions = options.getSslEngineOptions();
     this.clientOptions = options;
     return this;
   }
@@ -74,6 +77,12 @@ public HttpClientBuilder with(ClientSSLOptions options) {
     return this;
   }
 
+  @Override
+  public HttpClientBuilder with(SSLEngineOptions engine) {
+    this.sslEngineOptions = engine;
+    return this;
+  }
+
   @Override
   public HttpClientBuilder withConnectHandler(Handler<HttpConnection> handler) {
     this.connectHandler = handler;
@@ -255,6 +264,7 @@ public HttpClientAgent build() {
       NetClientInternal tcpClient = new NetClientBuilder(vertx, clientConfig)
         .protocol("http")
         .sslOptions(sslOptions)
+        .sslEngineOptions(sslEngineOptions)
         .build();
       NetworkLogging networkLogging = co.getTcpConfig().getNetworkLogging();
       transport = new TcpHttpClientTransport(