Mastering Java NIO: Build a Mini Netty Server with Heartbeat and Idle Detection

This article continues the Java I/O series and focuses on designing server‑side read/write idle detection and heartbeat mechanisms to ensure long‑living connections in a Mini‑Netty framework.

1. What Is Heartbeat Detection

Heartbeat (or PING/PONG) is a periodic small packet sent by both sides of a connection to confirm that the link is still alive. It is a key fault‑detection mechanism in distributed systems such as service registries (Zookeeper, Nacos), cluster nodes (Redis Cluster), and message‑queue consumers (RocketMQ).

In TCP long connections, intermediate devices (NAT, firewalls) may close idle links without notifying the application; heartbeats actively discover such disconnections, allowing the server to mark the channel offline within seconds.

2. Designing Read/Write Idle Events

Idle detection is needed only when there is a long period without any read or write activity. The implementation records the timestamp of the last read/write operation and uses a scheduled task to compare the current time with the stored timestamps. If the difference exceeds a configured idle timeout, an idle event is triggered.

Using the responsibility‑chain model, a custom IdleStateEvent can be defined and propagated through the pipeline:

public void fireUserEventTriggered(Object evt) { pipeline.fireUserEventTriggered(evt, index + 1); }

A MiniIdleStateHandler updates the last read/write timestamps on each event and, when the idle timeout is reached, fires READ_IDLE or WRITE_IDLE events.

3. Scheduler Based on a Priority Queue

The scheduler is integrated into each worker and uses a PriorityQueue<ScheduledTask> ordered by ScheduledTask.deadline. The queue head can be retrieved with peek() in O(1) time, similar to Redis SortedSet, guaranteeing tasks are executed in chronological order.

Idle detection tasks are recursively rescheduled: after a task runs, the next execution is added back to the queue; when a channel closes, its tasks stop automatically.

private final PriorityQueue<ScheduledTask> scheduledTasks =
    new PriorityQueue<>(Comparator.comparingLong(ScheduledTask::getDeadline));

public void schedule(Runnable task, long delayMillis) {
    scheduledTasks.add(new ScheduledTask(System.currentTimeMillis() + delayMillis, task));
    selector.wakeup();
}

public void fireIdleCheck(MiniChannel channel, long initialDelayMillis, long periodMillis) {
    schedule(() -> {
        if (!channel.isActive()) return;
        System.out.println("[ScheduledTask] idle check...");
        channel.pipeline().fireIdleCheck();
        fireIdleCheck(channel, periodMillis, periodMillis);
    }, initialDelayMillis);
}

4. Heartbeat Handler

The HeartbeatHandler processes idle events. On a write‑idle event it sends a PING packet; on a read‑idle event it increments a missed‑heartbeat counter. If the counter reaches the configured maximum (e.g., 3), the channel is closed. Receiving a PONG resets the counter to zero.

public void userEventTriggered(MiniHandlerContext ctx, Object evt) {
    if (evt instanceof MiniIdleState) {
        MiniIdleState idle = (MiniIdleState) evt;
        if (MiniIdleState.WRITE_IDLE.equals(idle)) {
            System.out.println("[HeartbeatHandler] send PING");
            ctx.channel().write(HearbeatState.PING.getState());
        } else if (MiniIdleState.READ_IDLE.equals(idle)) {
            missedHeartbeats++;
            System.out.println("[HeartbeatHandler] read idle, count=" + missedHeartbeats);
            if (missedHeartbeats >= maxMissed) {
                System.out.println("[HeartbeatHandler] connection lost, close channel");
                ctx.fireChannelInactive();
            }
        }
    } else {
        ctx.fireUserEventTriggered(evt);
    }
}

public void channelRead(MiniHandlerContext ctx, Object msg) {
    if (HearbeatState.PONG.getState().equals(msg)) {
        System.out.println("[HeartbeatHandler] received PONG, reset counter");
        missedHeartbeats = 0;
    } else {
        ctx.fireChannelRead(msg);
    }
}

5. Complete Server Bootstrap

The final starter assembles the pipeline with the idle handler, length‑field encoder/decoder, heartbeat handler, logger, and business handlers. The server binds to port 10030 and runs with a 4‑thread event‑loop group.

public static void main(String[] args) {
    MiniEventLoopGroup workGroup = new MiniEventLoopGroup(4);
    try {
        MiniServerBootstrap bootstrap = new MiniServerBootstrap();
        bootstrap.group(workGroup)
            .childHandler(new MiniChannelInitializer() {
                @Override
                public void initChannel(MiniChannel ch) {
                    ch.pipeline().addLast("MiniIdleStateHandler", new MiniIdleStateHandler(6000, 6000));
                    ch.pipeline().addLast("Encoder", new LengthFieldMessageEncoder());
                    ch.pipeline().addLast("Decoder", new LengthFieldMessageDecoder());
                    ch.pipeline().addLast("HeartbeatHandler", new HeartbeatHandler(3));
                    ch.pipeline().addLast("LoggerHandler", new LoggerHandler());
                    ch.pipeline().addLast("ServerCheckHandler", new ServerCheckHandler());
                    ch.pipeline().addLast("ServerEchoHandler", new ServerEchoHandler());
                }
            })
            .bind(10030)
            .sync();
    } catch (Exception e) {
        e.printStackTrace();
    } finally {
        workGroup.shutdownGracefully();
    }
}

With these components, the Mini‑Netty framework provides multi‑threaded event loops, non‑blocking I/O, a responsibility‑chain processing model, and built‑in heartbeat detection, demonstrating that a lightweight high‑performance network library can be built from scratch.