Use the new NetServer/NetClient configuration layer in documentation

Author: vietj

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

@@ -13,7 +13,7 @@ The simplest way to create a TCP server, using all default options is as follows
 
 === Configuring a TCP server
 
-If you don't want the default, a server can be configured by passing in a {@link io.vertx.core.net.NetServerOptions}
+If you don't want the default, a server can be configured by passing in a {@link io.vertx.core.net.TcpServerConfig}
 instance when creating it:
 
 [source,$lang]
@@ -254,7 +254,7 @@ The simplest way to create a TCP client, using all default options is as follows
 
 === Configuring a TCP client
 
-If you don't want the default, a client can be configured by passing in a {@link io.vertx.core.net.NetClientOptions}
+If you don't want the default, a client can be configured by passing in a {@link io.vertx.core.net.TcpClientConfig}
 instance when creating it:
 
 [source,$lang]
@@ -285,8 +285,8 @@ When running on JDK 16+, or using a <<_native_transports,native transport>>, a c
 === Configuring connection attempts
 
 A client can be configured to automatically retry connecting to the server in the event that it cannot connect.
-This is configured with {@link io.vertx.core.net.NetClientOptions#setReconnectInterval(long)} and
-{@link io.vertx.core.net.NetClientOptions#setReconnectAttempts(int)}.
+This is configured with {@link io.vertx.core.net.TcpClientConfig#setReconnectInterval(java.time.Duration)} and
+{@link io.vertx.core.net.TcpClientConfig#setReconnectAttempts(int)}.
 
 NOTE: Currently, Vert.x will not attempt to reconnect if a connection fails, reconnect attempts and interval
 only apply to creating initial connections.
@@ -377,7 +377,7 @@ You should read the <<netty-logging>> section.
 
 TCP server (Net/Http) can be configured with traffic shaping options to enable bandwidth limiting. Both inbound and outbound
 bandwidth can be limited through {@link io.vertx.core.net.TrafficShapingOptions}. For NetServer, traffic shaping options can be set
-through {@link io.vertx.core.net.NetServerOptions} and for HttpServer it can be set through {@link io.vertx.core.http.HttpServerOptions}.
+through {@link io.vertx.core.net.TcpServerConfig} and for HttpServer it can be set through {@link io.vertx.core.http.HttpServerOptions}.
 
 [source,$lang]
 ----
@@ -408,12 +408,12 @@ TCP clients and servers can be configured to use http://en.wikipedia.org/wiki/Tr
 - earlier versions of TLS were known as SSL.
 
 The APIs of the servers and clients are identical whether SSL/TLS is used, and it's enabled by configuring
-the {@link io.vertx.core.net.NetClientOptions} or {@link io.vertx.core.net.NetServerOptions} instances used
+the {@link io.vertx.core.net.TcpClientConfig} or {@link io.vertx.core.net.TcpServerConfig} instances used
 to create the servers or clients.
 
 ==== Enabling SSL/TLS on the server
 
-Server SSL/TLS is enabled with the `NetServerOptions` {@link io.vertx.core.net.NetServerOptions#setSsl(boolean) ssl} setting.
+Server SSL/TLS is enabled with the `TcpServerConfig` {@link io.vertx.core.net.TcpServerConfig#setSsl(boolean) ssl} setting.
 
 By default, it is disabled.
 
@@ -426,7 +426,7 @@ You can read more about <<server_ssl,SSL server configuration>>
 
 ==== Enabling SSL/TLS on the client
 
-Client SSL/TLS is enabled with the `NetClientOptions` {@link io.vertx.core.net.NetClientOptions#setSsl(boolean) ssl} property or {@link io.vertx.core.net.ConnectOptions#setSsl(boolean) ssl} property.
+Client SSL/TLS is enabled with the `TcpClientConfig` {@link io.vertx.core.net.TcpClientConfig#setSsl(boolean) ssl} property or {@link io.vertx.core.net.ConnectOptions#setSsl(boolean) ssl} property.
 
 The former defines the default client behavior.
 
@@ -535,7 +535,7 @@ The engine options to use is
 
 The {@link io.vertx.core.net.NetClient} supports either an HTTP/1.x _CONNECT_, _SOCKS4a_ or _SOCKS5_ proxy.
 
-The proxy can be configured in the {@link io.vertx.core.net.NetClientOptions} by setting a
+The proxy can be configured in the {@link io.vertx.core.net.TcpClientConfig} by setting a
 {@link io.vertx.core.net.ProxyOptions} object containing proxy type, hostname, port and optionally username and password.
 
 Here's an example:
@@ -549,7 +549,7 @@ Here's an example:
 The DNS resolution is always done on the proxy server, to achieve the functionality of a SOCKS4 client, it is necessary
 to resolve the DNS address locally.
 
-You can use {@link io.vertx.core.net.NetClientOptions#setNonProxyHosts} to configure a list of host bypassing
+You can use {@link io.vertx.core.net.TcpClientConfig#setNonProxyHosts} to configure a list of host bypassing
 the proxy. The lists accepts `*` wildcard for matching domains:
 
 [source,$lang]
@@ -564,7 +564,7 @@ https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt[HA PROXY protocol] p
 information such as a client's address across multiple layers of NAT or TCP
 proxies.
 
-HA PROXY protocol can be enabled by setting the option {@link io.vertx.core.net.NetServerOptions#setUseProxyProtocol(boolean)}
+HA PROXY protocol can be enabled by setting the option {@link io.vertx.core.net.TcpServerConfig#setUseProxyProtocol(boolean)}
 and adding the following dependency in your classpath:
 
 [source,xml]

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

@@ -17,13 +17,11 @@
 import io.vertx.core.VerticleBase;
 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.HttpServerOptions;
 import io.vertx.core.net.*;
 
-import java.security.cert.CertificateException;
-import java.util.Arrays;
+import java.time.Duration;
 import java.util.concurrent.TimeUnit;
 
 /**
@@ -38,8 +36,10 @@ public void example1(Vertx vertx) {
 
   public void example2(Vertx vertx) {
 
-    NetServerOptions options = new NetServerOptions().setPort(4321);
-    NetServer server = vertx.createNetServer(options);
+    TcpServerConfig config = new TcpServerConfig()
+      .setPort(4321);
+
+    NetServer server = vertx.createNetServer(config);
   }
 
   public void example3(Vertx vertx) {
@@ -206,13 +206,16 @@ public void example13(Vertx vertx) {
 
   public void example14(Vertx vertx) {
 
-    NetClientOptions options = new NetClientOptions().setConnectTimeout(10000);
-    NetClient client = vertx.createNetClient(options);
+    TcpClientConfig config = new TcpClientConfig()
+      .setConnectTimeout(Duration.ofSeconds(10));
+
+    NetClient client = vertx.createNetClient(config);
   }
 
   public void example15(Vertx vertx) {
 
-    NetClientOptions options = new NetClientOptions().setConnectTimeout(10000);
+    TcpClientConfig options = new TcpClientConfig()
+      .setConnectTimeout(Duration.ofSeconds(10));
     NetClient client = vertx.createNetClient(options);
     client
       .connect(4321, "localhost")
@@ -228,32 +231,34 @@ public void example15(Vertx vertx) {
 
   public void example16(Vertx vertx) {
 
-    NetClientOptions options = new NetClientOptions().
+    TcpClientConfig options = new TcpClientConfig().
       setReconnectAttempts(10).
-      setReconnectInterval(500);
+      setReconnectInterval(Duration.ofMillis(500));
 
     NetClient client = vertx.createNetClient(options);
   }
 
   public void exampleNetworkActivityLoggingOnServer(Vertx vertx) {
 
-    NetServerOptions options = new NetServerOptions().setLogActivity(true);
+    TcpServerConfig options = new TcpServerConfig()
+      .setNetworkLogging(new NetworkLogging());
 
     NetServer server = vertx.createNetServer(options);
   }
 
   public void exampleNetworkActivityLoggingFormat(Vertx vertx) {
 
-    NetServerOptions options = new NetServerOptions()
-      .setLogActivity(true)
-      .setActivityLogDataFormat(ByteBufFormat.SIMPLE);
+    TcpServerConfig options = new TcpServerConfig()
+      .setNetworkLogging(new NetworkLogging()
+        .setDataFormat(ByteBufFormat.SIMPLE));
 
     NetServer server = vertx.createNetServer(options);
   }
 
   public void exampleNetworkActivityLoggingOnClient(Vertx vertx) {
 
-    NetClientOptions options = new NetClientOptions().setLogActivity(true);
+    TcpClientConfig options = new TcpClientConfig()
+      .setNetworkLogging(new NetworkLogging());
 
     NetClient client = vertx.createNetClient(options);
   }
@@ -266,18 +271,18 @@ public void sslServerConfiguration(Vertx vertx) {
           setPassword("password-of-your-keystore")
       );
 
-    NetServerOptions options = new NetServerOptions()
-      .setSsl(true)
-      .setSslOptions(sslOptions);
+    TcpServerConfig config = new TcpServerConfig()
+      .setSsl(true);
 
-    NetServer server = vertx.createNetServer(options);
+    NetServer server = vertx.createNetServer(config, sslOptions);
   }
 
   public void example29(Vertx vertx) {
-    NetClientOptions options = new NetClientOptions().
-      setSsl(true).
-      setTrustAll(true);
-    NetClient client = vertx.createNetClient(options);
+    TcpClientConfig config = new TcpClientConfig()
+      .setSsl(true);
+    ClientSSLOptions sslOptions = new ClientSSLOptions()
+      .setTrustAll(true);
+    NetClient client = vertx.createNetClient(config, sslOptions);
   }
 
   public void sslClientConfiguration(Vertx vertx) {
@@ -287,11 +292,10 @@ public void sslClientConfiguration(Vertx vertx) {
         setPassword("password-of-your-truststore")
       );
 
-    NetClientOptions options = new NetClientOptions()
-      .setSsl(true)
-      .setSslOptions(sslOptions);
+    TcpClientConfig config = new TcpClientConfig()
+      .setSsl(true);
 
-    NetClient client = vertx.createNetClient(options);
+    NetClient client = vertx.createNetClient(config, sslOptions);
   }
 
   public void sslClientSocketConfiguration(Vertx vertx, int port, String host) {
@@ -301,9 +305,9 @@ public void sslClientSocketConfiguration(Vertx vertx, int port, String host) {
         setPassword("password-of-your-truststore")
       );
 
-    NetClientOptions options = new NetClientOptions().setSslOptions(sslOptions);
+    TcpClientConfig config = new TcpClientConfig();
 
-    NetClient client = vertx.createNetClient(options);
+    NetClient client = vertx.createNetClient(config, sslOptions);
 
     Future<NetSocket> future = client.connect(new ConnectOptions()
       .setHost(host)
@@ -358,60 +362,53 @@ public void updateSSLOptions(HttpServer server) {
   public void exampleSSLEngine(Vertx vertx, JksOptions keyStoreOptions) {
 
     // Use JDK SSL engine
-    NetServerOptions options = new NetServerOptions().
-      setSsl(true).
-      setKeyCertOptions(keyStoreOptions);
+    TcpServerConfig options = new TcpServerConfig().
+      setSsl(true);
 
     // Use JDK SSL engine explicitly
-    options = new NetServerOptions().
+    options = new TcpServerConfig().
       setSsl(true).
-      setKeyCertOptions(keyStoreOptions).
       setSslEngineOptions(new JdkSSLEngineOptions());
 
     // Use OpenSSL engine
-    options = new NetServerOptions().
+    options = new TcpServerConfig().
       setSsl(true).
-      setKeyCertOptions(keyStoreOptions).
       setSslEngineOptions(new OpenSSLEngineOptions());
   }
 
-  public void example46(Vertx vertx, String verificationAlgorithm, ClientSSLOptions sslOptions) {
-    NetClientOptions options = new NetClientOptions().
-      setSsl(true).
-      setSslOptions(sslOptions).
-      setHostnameVerificationAlgorithm(verificationAlgorithm);
+  public void example46(Vertx vertx, String verificationAlgorithm, TrustOptions trustOptions) {
+    TcpClientConfig config = new TcpClientConfig().
+      setSsl(true);
 
-    NetClient client = vertx.createNetClient(options);
+    ClientSSLOptions sslOptions = new ClientSSLOptions()
+      .setTrustOptions(trustOptions)
+      .setHostnameVerificationAlgorithm(verificationAlgorithm);
+
+    NetClient client = vertx.createNetClient(config, sslOptions);
   }
 
   public void example47(Vertx vertx) {
-    NetClientOptions options = new NetClientOptions()
+    TcpClientConfig config = new TcpClientConfig()
       .setProxyOptions(new ProxyOptions().setType(ProxyType.SOCKS5)
         .setHost("localhost").setPort(1080)
         .setUsername("username").setPassword("secret"));
-    NetClient client = vertx.createNetClient(options);
+    NetClient client = vertx.createNetClient(config);
   }
 
   public void nonProxyHosts(Vertx vertx) {
 
-    NetClientOptions options = new NetClientOptions()
+    TcpClientConfig config = new TcpClientConfig()
       .setProxyOptions(new ProxyOptions().setType(ProxyType.SOCKS5)
         .setHost("localhost").setPort(1080)
         .setUsername("username").setPassword("secret"))
       .addNonProxyHost("*.foo.com")
       .addNonProxyHost("localhost");
-    NetClient client = vertx.createNetClient(options);
-  }
-
-  public void example49() {
-    NetClientOptions clientOptions = new NetClientOptions()
-      .setSsl(true)
-      .setTrustAll(true);
+    NetClient client = vertx.createNetClient(config);
   }
 
   public void example51(Vertx vertx) {
-    NetServerOptions options = new NetServerOptions().setUseProxyProtocol(true);
-    NetServer server = vertx.createNetServer(options);
+    TcpServerConfig config = new TcpServerConfig().setUseProxyProtocol(true);
+    NetServer server = vertx.createNetServer(config);
     server.connectHandler(so -> {
       // Print the actual client address provided by the HA proxy protocol instead of the proxy address
       System.out.println(so.remoteAddress());
@@ -421,34 +418,11 @@ public void example51(Vertx vertx) {
     });
   }
 
-  public void configureSNIServer(Vertx vertx) {
-    JksOptions keyCertOptions = new JksOptions().setPath("keystore.jks").setPassword("wibble");
-
-    NetServer netServer = vertx.createNetServer(new NetServerOptions()
-        .setKeyCertOptions(keyCertOptions)
-        .setSsl(true)
-        .setSni(true)
-    );
-  }
-
-  public void configureSNIServerWithPems(Vertx vertx) {
-    PemKeyCertOptions keyCertOptions = new PemKeyCertOptions()
-        .setKeyPaths(Arrays.asList("default-key.pem", "host1-key.pem", "etc..."))
-        .setCertPaths(Arrays.asList("default-cert.pem", "host2-key.pem", "etc...")
-        );
-
-    NetServer netServer = vertx.createNetServer(new NetServerOptions()
-        .setKeyCertOptions(keyCertOptions)
-        .setSsl(true)
-        .setSni(true)
-    );
-  }
-
   public void useSNIInClient(Vertx vertx, JksOptions trustOptions) {
 
-    NetClient client = vertx.createNetClient(new NetClientOptions()
-        .setTrustOptions(trustOptions)
-        .setSsl(true)
+    NetClient client = vertx.createNetClient(
+      new TcpClientConfig().setSsl(true),
+      new ClientSSLOptions().setTrustOptions(trustOptions)
     );
 
     // Connect to 'localhost' and present 'server.name' server name
@@ -465,25 +439,25 @@ public void useSNIInClient(Vertx vertx, JksOptions trustOptions) {
   }
 
   public void configureTrafficShapingForNetServer(Vertx vertx) {
-    NetServerOptions options = new NetServerOptions()
+    TcpServerConfig config = new TcpServerConfig()
       .setHost("localhost")
       .setPort(1234)
       .setTrafficShapingOptions(new TrafficShapingOptions()
         .setInboundGlobalBandwidth(64 * 1024)
         .setOutboundGlobalBandwidth(128 * 1024));
 
-    NetServer server = vertx.createNetServer(options);
+    NetServer server = vertx.createNetServer(config);
   }
 
   public void dynamicallyUpdateTrafficShapingForNetServer(Vertx vertx) {
-    NetServerOptions options = new NetServerOptions()
+    TcpServerConfig config = new TcpServerConfig()
       .setHost("localhost")
       .setPort(1234)
       .setTrafficShapingOptions(new TrafficShapingOptions()
         .setInboundGlobalBandwidth(64 * 1024)
         .setOutboundGlobalBandwidth(128 * 1024));
 
-    NetServer server = vertx.createNetServer(options);
+    NetServer server = vertx.createNetServer(config);
 
     TrafficShapingOptions update = new TrafficShapingOptions()
       .setInboundGlobalBandwidth(2 * 64 * 1024) // twice