Building a High‑Performance Netty WebSocket Client for Large‑Scale Performance Testing

In WebSocket protocol performance testing, the standard org.java_websocket.client.WebSocketClient meets most scenarios, but for massive connections its thread consumption becomes a bottleneck. Each client creates multiple threads, which can exhaust JVM thread limits. Netty‑WebSocket offers a high‑performance, low‑resource solution.

5.3.1 Introduction to Netty

Netty is a Java‑based high‑performance network application framework that uses an asynchronous non‑blocking model and a flexible API. Compared with raw Java NIO, Netty simplifies development for protocols such as TCP, UDP, HTTP, and WebSocket. It follows the Reactor pattern, using event‑driven mechanisms to handle high concurrency. Its core components include:

Boss Group : accepts incoming client connections, usually configured with few threads for optimal performance.

Worker Group : processes read/write events of established connections, thread count typically matches CPU cores.

ChannelHandler and ChannelPipeline : a pipeline of handlers that process events and data, such as encoding/decoding and message parsing.

In performance tests, Netty’s asynchronous nature and thread‑pool design excel at handling tens of thousands of concurrent connections.

5.3.2 Creating WebSocketIOHandler

To build a Netty‑WebSocket client, implement a custom WebSocketIOHandler that handles handshake and message reception. It is recommended to extend SimpleChannelInboundHandler<Object> to process various message types. The implementation steps are described below.

Generic Type Selection

Using Object as the generic type allows the handler to process all message kinds (HTTP responses, WebSocket frames, etc.), increasing code flexibility.

Defining Core Attributes

Two essential fields are required:

WebSocketClientHandshaker : manages the client‑server WebSocket handshake.

ChannelPromise : represents the asynchronous result of the handshake, returning Void on success or Throwable on failure.

Message Processing Implementation

Override channelRead0 to handle incoming messages. If the handshake is incomplete, cast the message to FullHttpResponse and complete the handshake; otherwise, process WebSocketFrame types such as text or close frames. The full handler code is shown below:

package org.funtester.performance.books.chapter05.section3;

import io.netty.channel.Channel;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.SimpleChannelInboundHandler;
import io.netty.handler.codec.http.FullHttpResponse;
import io.netty.handler.codec.http.websocketx.*;

/**
 * FunTester WebSocket客户端处理器
 */
public class WebSocketIOHandler extends SimpleChannelInboundHandler
{
    /**
     * WebSocket客户端握手处理器
     */
    private final WebSocketClientHandshaker handShaker;
    /**
     * 握手响应的promise，用于异步记录连接结果
     */
    private ChannelPromise handshakeFuture;
    /**
     * 构造函数，初始化握手处理器
     * @param webSocketClientHandshaker 握手处理器实例
     */
    public WebSocketIOHandler(WebSocketClientHandshaker webSocketClientHandshaker) {
        this.handShaker = webSocketClientHandshaker;
    }
    /**
     * 处理WebSocket消息
     * @param ctx 上下文
     * @param msg 消息对象
     * @throws Exception
     */
    @Override
    protected void channelRead0(ChannelHandlerContext ctx, Object msg) throws Exception {
        Channel channel = ctx.channel(); // 获取当前Channel
        if (!handShaker.isHandshakeComplete()) { // 握手未完成
            try {
                FullHttpResponse response = (FullHttpResponse) msg; // 转换为HTTP响应
                System.out.println("FunTester: 握手响应: " + response); // 打印响应信息
                handShaker.finishHandshake(channel, response); // 完成握手
                handshakeFuture.setSuccess(); // 标记握手成功
            } catch (WebSocketHandshakeException e) {
                handshakeFuture.setFailure(e); // 标记握手失败
            }
            return;
        }
        WebSocketFrame frame = (WebSocketFrame) msg; // 转换为WebSocket帧
        if (frame instanceof TextWebSocketFrame) { // 处理文本消息
            TextWebSocketFrame textFrame = (TextWebSocketFrame) frame;
            System.out.println("FunTester: 收到消息: " + textFrame.text());
        } else if (frame instanceof CloseWebSocketFrame) { // 处理关闭帧
            System.out.println("FunTester: 收到关闭帧，关闭连接");
            channel.close();
        }
    }
    /**
     * Handler添加到Pipeline时触发，初始化promise
     */
    @Override
    public void handlerAdded(ChannelHandlerContext ctx) {
        System.out.println("FunTester: Handler已添加到ChannelPipeline");
        handshakeFuture = ctx.newPromise();
    }
    /**
     * 连接激活时触发，发起握手请求
     */
    @Override
    public void channelActive(ChannelHandlerContext ctx) {
        handShaker.handshake(ctx.channel()); // 发送握手请求
        System.out.println("FunTester: WebSocket连接成功");
    }
    /**
     * 连接断开时触发，关闭Channel
     */
    @Override
    public void channelInactive(ChannelHandlerContext ctx) {
        System.out.println("FunTester: WebSocket连接断开");
        ctx.close();
    }
    /**
     * 异常发生时触发，记录并关闭连接
     */
    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        System.out.println("FunTester: WebSocket异常: " + cause.getMessage());
        if (!handshakeFuture.isDone()) {
            handshakeFuture.setFailure(cause);
        }
        ctx.close();
    }
}

During performance testing, logging should be minimized to avoid affecting throughput; use metrics instead of console output.

5.3.3 Creating Netty‑WebSocket Client

Creating a Netty‑WebSocket client is more involved than using Java‑WebSocket. It requires configuring a Bootstrap , an EventLoopGroup , and a ChannelGroup . The steps are:

Configuring Thread Groups and Bootstrap

Use NioEventLoopGroup (default threads = 2 × CPU cores) and set up Bootstrap with NioSocketChannel and TCP options like TCP_NODELAY for better real‑time performance.

Creating Channel Group

ChannelGroup manages multiple channels, enabling batch operations such as mass message sending or connection closing.

Client Creation Code

The following example demonstrates a complete Netty‑WebSocket client:

package org.funtester.performance.books.chapter05.section3;

import io.netty.bootstrap.Bootstrap;
import io.netty.channel.*;
import io.netty.channel.group.ChannelGroup;
import io.netty.channel.group.DefaultChannelGroup;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.nio.NioSocketChannel;
import io.netty.handler.codec.http.DefaultHttpHeaders;
import io.netty.handler.codec.http.HttpClientCodec;
import io.netty.handler.codec.http.HttpObjectAggregator;
import io.netty.handler.codec.http.websocketx.WebSocketClientHandshakerFactory;
import io.netty.handler.codec.http.websocketx.WebSocketVersion;
import io.netty.util.concurrent.GlobalEventExecutor;

import java.net.URI;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * FunTester Netty-WebSocket客户端示例
 */
public class NettyWebSocketClientDemo {
    private static final Bootstrap bootstrap = new Bootstrap();
    private static final EventLoopGroup group = new NioEventLoopGroup(new ThreadFactory() {
        private final AtomicInteger index = new AtomicInteger(0);
        @Override
        public Thread newThread(Runnable r) {
            Thread thread = new Thread(r);
            thread.setName("FunTester-Client-" + index.incrementAndGet());
            return thread;
        }
    });
    private static final ChannelGroup channels = new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);

    public static void main(String[] args) throws Exception {
        URI uri = new URI("ws://localhost:12345/websocket/FunTester"); // WebSocket服务端地址
        WebSocketIOHandler handler = new WebSocketIOHandler(
                WebSocketClientHandshakerFactory.newHandshaker(
                        uri, WebSocketVersion.V13, null, true, new DefaultHttpHeaders())); // 初始化Handler
        bootstrap.group(group).channel(NioSocketChannel.class)
                .option(ChannelOption.SO_KEEPALIVE, true) // 启用TCP保活
                .option(ChannelOption.TCP_NODELAY, true) // 禁用Nagle算法，提升实时性
                .handler(new ChannelInitializer
() {
                    @Override
                    protected void initChannel(SocketChannel channel) {
                        ChannelPipeline pipeline = channel.pipeline();
                        pipeline.addLast(new HttpClientCodec()); // HTTP消息编解码
                        pipeline.addLast(new HttpObjectAggregator(1024 * 1024)); // 聚合HTTP消息
                        pipeline.addLast(handler); // 自定义WebSocket处理器
                    }
                });
        Channel channel = bootstrap.connect(uri.getHost(), uri.getPort()).sync().channel(); // 连接服务端
        channels.add(channel); // 添加到通道组
        handler.handshakeFuture.get(); // 等待握手完成
    }
}

The configuration of Bootstrap and ChannelPipeline provides an efficient client; options SO_KEEPALIVE and TCP_NODELAY improve stability and latency for high‑concurrency tests.

5.3.4 Sending Messages

Messages are sent via Channel.writeAndFlush using a TextWebSocketFrame . Example:

ChannelFuture future = channel.writeAndFlush(new TextWebSocketFrame("Hello FunTester"));
future.get(); // wait for send completion

Because Netty is asynchronous, the get() call can be omitted to increase throughput in performance tests.

5.3.5 Closing Connections

Close a connection with Channel.close() , either synchronously ( sync() ) or asynchronously. Asynchronous closing is preferred in performance testing to avoid thread blocking.

// async close
ChannelFuture closeFuture = channel.close();
closeFuture.get(); // wait for close

5.3.6 Batch Operations

ChannelGroup supports batch operations combined with ChannelMatcher . Example of sending a message only to localhost channels:

channels.writeAndFlush(new TextWebSocketFrame("Hello FunTester"),
    channel -> {
        InetSocketAddress address = (InetSocketAddress) channel.remoteAddress();
        String hostName = address.getHostName();
        System.out.println("FunTester: 主机名: " + hostName);
        return hostName.equals("localhost"); // 仅发送给localhost
    });

In performance testing, ChannelGroup can simulate large numbers of clients, sending heartbeats or closing connections to evaluate server concurrency.

5.3.7 Client Wrapper

To simplify test code, encapsulate the Netty‑WebSocket client into a reusable class, enhancing maintainability and reuse.