Skip to content

Expose NetServer/NetClient configuration layer #5986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vietj merged 2 commits into from
Feb 19, 2026
Merged

Expose NetServer/NetClient configuration layer #5986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6b0e2e
Allow the creation of NetServer/NetClient using config objects
vietj Feb 19, 2026
00584bf
Use the new NetServer/NetClient configuration layer in documentation
vietj Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions vertx-core/src/main/asciidoc/net.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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]
----
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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:
Expand All @@ -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]
Expand All @@ -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]
Expand Down
142 changes: 58 additions & 84 deletions vertx-core/src/main/java/examples/NetExamples.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand All @@ -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) {
Expand Down Expand Up @@ -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")
Expand All @@ -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);
}
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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)
Expand Down Expand Up @@ -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());
Expand All @@ -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
Expand All @@ -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
Expand Down
Loading
Loading