WebSocket 서버 구현

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

// WebSocket 경로와 옵션을 지정하면 핸드셰이크를 자동으로 처리한다
new WebSocketServerProtocolHandler(
    "/chat",     // WebSocket 경로
    null,        // 서브프로토콜 (null이면 없음)
    true,        // allowExtensions
    65536        // 최대 프레임 크기 (바이트)
)

바이트 스트림
    ↓
[HttpServerCodec]                ← HTTP 인코딩/디코딩 (핸드셰이크용)
    ↓
[HttpObjectAggregator]           ← HTTP 조각을 FullHttpRequest로 합침
    ↓
[WebSocketServerProtocolHandler] ← 핸드셰이크 자동 처리 + Ping/Pong
    ↓
[비즈니스 핸들러]                 ← TextWebSocketFrame 처리

import io.netty.channel.ChannelInitializer;
import io.netty.channel.ChannelPipeline;
import io.netty.channel.socket.SocketChannel;
import io.netty.handler.codec.http.HttpObjectAggregator;
import io.netty.handler.codec.http.HttpServerCodec;
import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;

// WebSocket 서버의 파이프라인 초기화
public class WebSocketServerInitializer extends ChannelInitializer<SocketChannel> {

    @Override
    protected void initChannel(SocketChannel ch) {
        ChannelPipeline pipeline = ch.pipeline();

        // 1. HTTP 코덱 — 핸드셰이크 요청을 파싱하기 위해 필요
        pipeline.addLast("httpCodec", new HttpServerCodec());

        // 2. HTTP 어그리게이터 — 조각난 HTTP 메시지를 하나로 합침
        pipeline.addLast("httpAggregator", new HttpObjectAggregator(65536));

        // 3. WebSocket 프로토콜 핸들러 — 핸드셰이크 + Ping/Pong 자동 처리
        pipeline.addLast("wsProtocol",
            new WebSocketServerProtocolHandler("/chat", null, true, 65536));

        // 4. 비즈니스 핸들러 — 실제 WebSocket 메시지 처리
        pipeline.addLast("wsHandler", new ChatWebSocketHandler());
    }
}

[HttpServerCodec] → [HttpObjectAggregator] → [WebSocketServerProtocolHandler] → [ChatWebSocketHandler]

[WebSocketFrameDecoder] → [WebSocketFrameEncoder] → [WebSocketServerProtocolHandler] → [ChatWebSocketHandler]

import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.SimpleChannelInboundHandler;
import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;

// WebSocket 텍스트 프레임을 처리하는 핸들러
public class WebSocketFrameHandler extends SimpleChannelInboundHandler<TextWebSocketFrame> {

    @Override
    protected void channelRead0(ChannelHandlerContext ctx, TextWebSocketFrame frame) {
        String text = frame.text();
        System.out.println("수신: " + text);

        // 에코 — 받은 메시지를 그대로 돌려보냄
        // 주의: 원본 frame을 그대로 write하면 참조 카운트 문제가 생길 수 있으므로
        //       새 TextWebSocketFrame을 생성한다
        ctx.writeAndFlush(new TextWebSocketFrame("에코: " + text));
    }

    @Override
    public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
        // 핸드셰이크 완료 이벤트 감지
        if (evt instanceof WebSocketServerProtocolHandler.HandshakeComplete) {
            WebSocketServerProtocolHandler.HandshakeComplete complete =
                (WebSocketServerProtocolHandler.HandshakeComplete) evt;
            System.out.println("WebSocket 연결 완료 — 경로: " + complete.requestUri());
        }
        super.userEventTriggered(ctx, evt);
    }

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        cause.printStackTrace();
        ctx.close();
    }
}

import io.netty.channel.Channel;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.SimpleChannelInboundHandler;
import io.netty.channel.group.ChannelGroup;
import io.netty.channel.group.DefaultChannelGroup;
import io.netty.handler.codec.http.websocketx.TextWebSocketFrame;
import io.netty.handler.codec.http.websocketx.WebSocketServerProtocolHandler;
import io.netty.util.concurrent.GlobalEventExecutor;

// ChannelGroup을 활용한 채팅 브로드캐스트 핸들러
public class ChatWebSocketHandler extends SimpleChannelInboundHandler<TextWebSocketFrame> {

    // 모든 연결된 WebSocket 채널을 담는 그룹
    // static으로 선언해서 모든 핸들러 인스턴스가 공유한다
    private static final ChannelGroup channels =
        new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);

    @Override
    public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
        if (evt instanceof WebSocketServerProtocolHandler.HandshakeComplete) {
            // 핸드셰이크가 완료된 시점에 그룹에 추가한다
            // 핸드셰이크 전에 추가하면 HTTP 메시지가 브로드캐스트될 수 있다
            channels.add(ctx.channel());
            System.out.println("새 클라이언트 접속. 현재 " + channels.size() + "명");
        }
        super.userEventTriggered(ctx, evt);
    }

    @Override
    protected void channelRead0(ChannelHandlerContext ctx, TextWebSocketFrame frame) {
        String text = frame.text();
        Channel sender = ctx.channel();

        System.out.println("메시지 수신 [" + sender.remoteAddress() + "]: " + text);

        // 모든 채널에 브로드캐스트
        // 각 채널마다 새 TextWebSocketFrame을 생성해야 한다
        // ChannelGroup.writeAndFlush()가 내부적으로 각 채널에 대해
        // 메시지를 retain()하므로 새 프레임 하나만 만들면 된다
        channels.writeAndFlush(new TextWebSocketFrame(
            "[" + sender.remoteAddress() + "] " + text
        ));
    }

    @Override
    public void channelInactive(ChannelHandlerContext ctx) {
        // 채널이 닫히면 ChannelGroup에서 자동 제거되지만
        // 로그를 남기기 위해 오버라이드한다
        System.out.println("클라이언트 퇴장. 현재 " + channels.size() + "명");
    }

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) {
        cause.printStackTrace();
        ctx.close();
    }
}

import io.netty.bootstrap.ServerBootstrap;
import io.netty.channel.ChannelFuture;
import io.netty.channel.EventLoopGroup;
import io.netty.channel.nio.NioEventLoopGroup;
import io.netty.channel.socket.nio.NioServerSocketChannel;

public class WebSocketChatServer {

    private static final int PORT = 8080;

    public static void main(String[] args) throws InterruptedException {
        // boss: 연결 수락, worker: I/O 처리
        EventLoopGroup bossGroup = new NioEventLoopGroup(1);
        EventLoopGroup workerGroup = new NioEventLoopGroup();

        try {
            ServerBootstrap bootstrap = new ServerBootstrap();
            bootstrap.group(bossGroup, workerGroup)
                .channel(NioServerSocketChannel.class)
                .childHandler(new WebSocketServerInitializer());

            ChannelFuture future = bootstrap.bind(PORT).sync();
            System.out.println("WebSocket 채팅 서버 시작 — ws://localhost:" + PORT + "/chat");

            future.channel().closeFuture().sync();
        } finally {
            bossGroup.shutdownGracefully();
            workerGroup.shutdownGracefully();
        }
    }
}

# wscat 설치
npm install -g wscat

# 클라이언트 1 접속
wscat -c ws://localhost:8080/chat

# 클라이언트 2 접속 (다른 터미널에서)
wscat -c ws://localhost:8080/chat

[클라이언트]                                      [서버]

1. HTTP Upgrade 요청  ──────────────────→  [HttpServerCodec]
   GET /chat HTTP/1.1                            ↓
   Upgrade: websocket                     [HttpObjectAggregator]
                                                 ↓
                                          [WebSocketServerProtocolHandler]
                                                 ↓ 핸드셰이크 처리
2. HTTP 101 응답  ←──────────────────────  101 Switching Protocols

   ── 여기서 파이프라인 전환 ──
   HttpServerCodec 제거 → WebSocketFrameDecoder/Encoder 추가
   HttpObjectAggregator 제거

3. TextWebSocketFrame  ─────────────────→  [WebSocketFrameDecoder]
   {"msg": "안녕하세요"}                         ↓
                                          [WebSocketServerProtocolHandler]
                                            (Ping/Pong/Close 자동 처리)
                                                 ↓
                                          [ChatWebSocketHandler]
                                                 ↓ 브로드캐스트
4. TextWebSocketFrame  ←─────────────────  [WebSocketFrameEncoder]
   [addr] 안녕하세요

// WebSocketServerProtocolHandler 생성자에서 maxFrameSize를 지정한다
new WebSocketServerProtocolHandler("/chat", null, true, 65536)
//                                                      ↑ 최대 64KB

import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelInboundHandlerAdapter;
import io.netty.handler.codec.http.websocketx.PingWebSocketFrame;
import io.netty.handler.timeout.IdleState;
import io.netty.handler.timeout.IdleStateEvent;

// 일정 시간 동안 읽기 이벤트가 없으면 Ping을 보내는 핸들러
public class WebSocketPingHandler extends ChannelInboundHandlerAdapter {

    @Override
    public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
        if (evt instanceof IdleStateEvent) {
            IdleStateEvent e = (IdleStateEvent) evt;
            if (e.state() == IdleState.READER_IDLE) {
                // 읽기 타임아웃 — Ping을 보내서 연결 확인
                ctx.writeAndFlush(new PingWebSocketFrame());
            }
        }
        super.userEventTriggered(ctx, evt);
    }
}

// 60초 동안 읽기 이벤트가 없으면 IdleStateEvent 발생
pipeline.addLast("idleState", new IdleStateHandler(60, 0, 0));
pipeline.addLast("pingHandler", new WebSocketPingHandler());

import io.netty.handler.ssl.SslContext;
import io.netty.handler.ssl.SslContextBuilder;

import java.io.File;

// SSL 컨텍스트를 만들고 파이프라인 맨 앞에 추가한다
SslContext sslCtx = SslContextBuilder.forServer(
    new File("cert.pem"),     // 인증서
    new File("key.pem")       // 개인 키
).build();

// 파이프라인 구성 — SslHandler가 반드시 맨 앞에 와야 한다
pipeline.addLast("ssl", sslCtx.newHandler(ch.alloc()));
pipeline.addLast("httpCodec", new HttpServerCodec());
pipeline.addLast("httpAggregator", new HttpObjectAggregator(65536));
pipeline.addLast("wsProtocol",
    new WebSocketServerProtocolHandler("/chat", null, true, 65536));
pipeline.addLast("wsHandler", new ChatWebSocketHandler());