llms-full.txt

# SOOPAPI - 비공식 SOOP 채팅 API (전체 레퍼런스)

> SOOP(한국 라이브 스트리밍 플랫폼) 채팅 시스템과 상호작용하기 위한 비공식 Java 25+ 라이브러리.
> WebSocket 기반 실시간 채팅 연결, 92개 서버 이벤트의 타입 안전한 디코딩, 이벤트 기반 아키텍처를 제공합니다.

## 핵심 정보

- GitHub: https://github.com/getCurrentThread/soopapi
- 버전: v0.15.0
- 라이선스: MIT
- 언어: Java 25 이상
- 빌드: Gradle 9.3.1
- 배포: JitPack (com.github.getCurrentThread:soopapi)
- 런타임 의존성: Gson

## 설치

### Gradle (JitPack)

```groovy
repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.getCurrentThread:soopapi:v0.15.0' // 최신 버전은 핵심 정보 참조
}
```

## 빠른 시작

### 통합 클라이언트 (SOOPClient) - 권장

```java
import com.github.getcurrentthread.soopapi.SOOPClient;
import com.github.getcurrentthread.soopapi.api.model.*;
import com.github.getcurrentthread.soopapi.client.SOOPChatClient;
import com.github.getcurrentthread.soopapi.event.ChatEvent;
import com.github.getcurrentthread.soopapi.event.model.*;

public class Example {
    public static void main(String[] args) throws Exception {
        try (SOOPClient client = new SOOPClient()) {
            // 방송/채널 정보 조회 (HTTP API)
            LiveDetail detail = client.live().detail("streamerId").join();
            System.out.println("방송 제목: " + detail.title());
            StationInfo station = client.channel().station("streamerId").join();
            System.out.println("스테이션: " + station.stationName());

            // 글로벌 리스너 — 이후 add()되는 모든 스트림에 자동 attach. 핸들러: (streamerId, event)
            client.on(ChatEvent.CHAT_MESSAGE, (String bid, ChatMessageEvent e) -> {
                System.out.println("[" + bid + "] " + e.senderNickname() + ": " + e.message());
            });

            client.on(ChatEvent.SEND_BALLOON, (String bid, SendBalloonEvent e) -> {
                System.out.println("[" + bid + "] " + e.senderNickname()
                        + "님이 풍선 " + e.count() + "개 선물!");
            });

            // add() 호출 즉시 비동기 연결 — 별도 connectToChat() 불필요
            client.add("streamerId");

            // 등록된 모든 세션이 끝날 때까지 대기
            client.connectAll().join();
        }
    }
}
```

### 직접 연결 (익명/읽기 전용)

```java
SOOPChatConfig config = new SOOPChatConfig.Builder()
        .bid("streamerId")
        .build();

SOOPChatClient client = new SOOPChatClient(config);

client.on(ChatEvent.CHAT_MESSAGE, (ChatMessageEvent e) -> {
    System.out.println(e.senderNickname() + ": " + e.message());
});

// connectAndAwait()는 세션이 끝날 때까지 블로킹합니다 (연결 실패 시 ConnectionException)
client.connectAndAwait();
```

authCookie 없이 연결하면 익명 모드로 동작합니다. 채팅 수신은 가능하지만 sendChat() 호출 시 AuthenticationException이 발생합니다.
19금 방송은 익명으로 들어갈 수 없습니다. 서버가 채팅 접속 정보를 주지 않으므로, 세션은 재시도 없이 DISCONNECTED(causedByError=true)로 끝나고 connectToChat()·ready()는 AdultBroadcastException을 원인으로 둔 ConnectionException으로 실패합니다. 연령 인증된 계정으로 로그인한 authCookie를 넘기면 방송 정보 조회가 채팅 접속 정보를 받고 채팅에도 연결됩니다(실제 계정으로 확인). 19금 방송을 여는 것은 로그인 쿠키이며, 라이브러리는 19금 확인(confirm_adult)을 사용자 대신 하지 않고 늘 false로 요청합니다.
SOOPChatClient 생성자는 네트워크 호출을 하지 않습니다. BNO를 설정하지 않았으면 connectToChat() 때 자동으로 조회합니다.

### 인증 + 채팅 전송

```java
SOOPClient client = new SOOPClient();

// 1. 로그인 (실패하면 join()이 AuthenticationException을 원인으로 담은 CompletionException을 던짐)
AuthCookie cookie = client.auth().signIn("userId", "password").join();

// 2. 인증된 설정으로 채팅 클라이언트 생성
SOOPChatConfig config = new SOOPChatConfig.Builder()
        .bid("streamerId")
        .authCookie(cookie)
        .build();

SOOPChatClient chat = new SOOPChatClient(config);

chat.on(ChatEvent.CHAT_MESSAGE, (ChatMessageEvent e) -> {
    System.out.println(e.senderNickname() + ": " + e.message());
});

// 3. 연결 시작. 반환된 future는 세션이 끝날 때 완료되므로 여기서 기다리지 않습니다
chat.connectToChat();

// 4. 채널에 입장하면(ready) 전송합니다
chat.ready().thenRun(() -> {
    chat.sendChat("Hello!")
            .exceptionally(ex -> { System.err.println("전송 실패: " + ex); return null; });

    // 특정 사용자에게 귓말 전송 ("targetUser" = 받는 사람 로그인 ID, 닉네임/(n) 형태 아님)
    chat.sendWhisper("targetUser", "안녕하세요");
}).exceptionally(ex -> { System.err.println("채널 입장 전에 세션이 끝남: " + ex); return null; });
```

- `ready()`는 `connectToChat()` 뒤에 부릅니다. 세션이 없으면 `IllegalStateException`으로 실패합니다. 완료 콜백은 대개 JOIN 응답을 받은 수신 스레드에서 실행되므로 오래 걸리는 작업은 `thenRunAsync`로 넘깁니다.
- 인증 연결의 ENTER_INFO는 `ready()`가 완료되기 전에 송신 체인에 들어가므로, 완료되자마자 보낸 메시지도 ENTER_INFO 뒤에 나갑니다.
- `JOIN_CHANNEL` 리스너(`chat.once(ChatEvent.JOIN_CHANNEL, (JoinChannelEvent e) -> ...)`)에서 보내도 됩니다. `JOIN_CHANNEL`은 재연결로 채널에 다시 들어갈 때마다 다시 발생하므로, 한 번만 보내려면 `once()`를 씁니다.
- 메시지가 `null`·공백이거나 제어 문자 `U+000C`·`U+001B`를 포함하면 `IllegalArgumentException`으로 실패합니다.
- 리스너 안에서 `sendChat(..).join()`이나 `ready().join()`처럼 기다리는 것은 안전합니다. 하지만 **세션 future**(`connectToChat()`, `connectAndAwait()`, `forceReconnect()`)를 기다리면 이벤트 전달이 멈춰 교착 상태가 됩니다.

### 연결 상태 이벤트

```java
// 세션 종료 감지 (세션마다 정확히 한 번)
client.on(ChatEvent.DISCONNECTED, (DisconnectedEvent e) -> {
    System.out.println("연결 해제: code=" + e.statusCode()
            + ", reason=" + e.reason()
            + ", error=" + e.causedByError());
});

// 직접 끝낸 경우가 아니면 5초 뒤 새 세션 시작 (첫 연결 실패도 포함되므로 방송이 꺼져 있으면 5초마다 다시 시도)
client.on(ChatEvent.DISCONNECTED, (DisconnectedEvent e) -> {
    if (e.isClientInitiated()) {
        return; // disconnect()/close()로 직접 끝낸 경우
    }
    CompletableFuture.runAsync(
            client::connectToChat, CompletableFuture.delayedExecutor(5, TimeUnit.SECONDS));
});

// 재연결 시도 감지 (재시도를 예약할 때마다)
client.on(ChatEvent.RECONNECTING, (ReconnectingEvent e) -> {
    System.out.println("재연결 시도 " + e.attemptNumber()
            + "/" + e.maxAttempts()
            + " (" + e.delayMs() + "ms 후)");
});

// 재연결 완료 감지
client.on(ChatEvent.RECONNECTED, (ReconnectedEvent e) -> {
    System.out.println("재연결 완료 (총 " + e.totalAttempts() + "회 시도)");
});
```

close()된 클라이언트는 DISCONNECTED 리스너에서 connectToChat()을 불러도 다시 연결되지 않습니다(실패한 future 반환).

### 에러 핸들링

```java
import com.github.getcurrentthread.soopapi.exception.EventEmitterException;

client.getEventEmitter().setErrorHandler((EventEmitterException ex) -> {
    System.err.println("이벤트 처리 중 오류: " + ex.getChatEvent());
    ex.printStackTrace();
});
```

## API 레퍼런스

### SOOPClient (파사드)

통합 진입점. AutoCloseable 구현.

- SOOPClient() - 기본 설정(SOOPClientConfig 기본값)으로 생성
- SOOPClient(SOOPClientConfig config) - 커스텀 설정. connectionTimeout은 REST API(auth()/live()/channel())에만, maxRetryAttempts는 add(String)으로 등록하는 스트림의 재연결 한도에 쓰입니다.
- auth() -> SOOPAuth - 인증 API
- live() -> SOOPLive - 방송 정보 API
- channel() -> SOOPChannel - 채널 정보 API
- add(String streamerId) -> SOOPChatClient - 등록 + 즉시 비동기 연결(connectToChat() 자동 호출). bid 기준 dedup: 이미 등록된 bid면 기존 인스턴스를 반환하고, 그 인스턴스의 세션이 끝나 있었으면 새 세션을 시작합니다. 재연결 한도는 SOOPClientConfig.maxRetryAttempts.
- add(SOOPChatConfig config) -> SOOPChatClient - 커스텀 설정으로 등록 + 자동 연결. 이미 등록된 bid면 전달한 config는 무시됩니다. 연결 실패는 DISCONNECTED(causedByError=true)로 알려지며, 세션 future가 필요하면 반환된 클라이언트에서 connectToChat()을 호출합니다(진행 중인 세션이면 같은 future).
- remove(String streamerId) -> boolean - 세션 종료 + 등록 해제(클라이언트를 close()). 제거된 클라이언트는 DISCONNECTED 리스너가 재연결을 시도해도 다시 연결되지 않습니다. 등록돼 있었으면 true.
- get(String streamerId) -> SOOPChatClient - 등록된 핸들 반환(없으면 null).
- streamerIds() -> Set<String> - 등록된 bid 스냅샷.
- clients() -> Collection<SOOPChatClient> - 등록된 클라이언트 스냅샷.
- <T extends BaseEvent> on(ChatEvent, StreamEventListener<T>) -> SOOPClient - 글로벌 리스너 등록. 모든 스트림 + 이후 추가되는 스트림에 자동 attach. 핸들러: (streamerId, event).
- <T extends BaseEvent> off(ChatEvent, StreamEventListener<T>) -> SOOPClient - 글로벌 리스너 해제.
- connectAll() -> CompletableFuture<Void> - 등록된 모든 세션이 끝날 때 완료. 끝난 세션은 새로 시작하며, 하나라도 연결 실패나 재시도 소진으로 끝나면 예외로 완료.
- reconnect(String streamerId) -> CompletableFuture<Void> - 방송 정보 조회부터 새 연결로 강제 재연결(SOOPChatClient.forceReconnect()). 현재 상태/진행 중 backoff 무시. 세션은 유지되며 RECONNECTING(1/1, 0ms)→RECONNECTED만 emit(DISCONNECTED 없음). 새 연결이 실패하면 세션이 DISCONNECTED(causedByError=true)로 끝나고, 세션이 없으면 RECONNECTING 없이 새 세션을 시작. 반환값은 세션 future. 미등록 bid면 IllegalArgumentException으로 실패.
- reconnectAll() -> CompletableFuture<Void> - 등록된 모든 스트림을 강제 재연결하고, 모든 세션이 끝날 때 완료되는 future 반환.
- chat(String streamerId) -> SOOPChatClient - add()의 별칭(편의 메서드).
- chat(SOOPChatConfig config) -> SOOPChatClient - add()의 별칭(편의 메서드).
- close() - 모든 클라이언트 종료(close()) + 등록·글로벌 리스너 정리 + REST용 HTTP 클라이언트 해제. 닫힌 클라이언트는 다시 연결되지 않습니다. try-with-resources 권장.

remove()/close()는 글로벌 리스너를 먼저 떼어 낸 뒤 클라이언트를 닫으므로, 그 스트림의 마지막 DISCONNECTED는 글로벌 리스너에 전달되지 않습니다(클라이언트에 직접 등록한 리스너에는 전달).

### SOOPChatClient (채팅 클라이언트)

채팅 연결 및 이벤트 구독. AutoCloseable 구현.

생성:
- SOOPChatClient(SOOPChatConfig config) - 기본 팩토리(ConnectionManager.getInstance()) 사용. 네트워크 호출 없음. config가 null이거나 bid가 공백이면 IllegalArgumentException.
- SOOPChatClient(SOOPChatConfig config, ChatConnectionFactory factory) - 연결 생성 방식을 주입(테스트, 고급 사용).

이벤트 관리:
- <T extends BaseEvent> on(ChatEvent event, EventListener<T> listener) -> SOOPChatClient - 이벤트 구독
- <T extends BaseEvent> once(ChatEvent event, EventListener<T> listener) -> SOOPChatClient - 일회성 구독
- <T extends BaseEvent> off(ChatEvent event, EventListener<T> listener) -> SOOPChatClient - 구독 해제

연결 (세션):
- connectToChat() -> CompletableFuture<Void> - 세션 시작. 세션이 끝날 때 완료(disconnect()·서버 종료면 정상, 연결 실패·재시도 소진이면 ConnectionException). 진행 중인 세션이 있으면 같은 future 반환. close() 뒤에는 실패한 future.
- connectAndAwait() - connectToChat().join()의 편의 메서드(블로킹). 실패 시 ConnectionException.
- ready() -> CompletableFuture<Void> - 현재 세션이 채널에 들어가면(서버가 JOIN에 응답하면) 완료. 지금 들어가 있으면 이미 완료된 future, 연결 중·backoff 대기 중이면 다음 JOIN 응답에서 완료. reconnect()·forceReconnect()로 소켓이나 연결이 바뀌어도 실패하지 않고 새 연결의 입장을 기다림. 그 전에 세션이 끝나면(disconnect()·close()·서버 종료·연결 실패·재시도 소진) ConnectionException으로 예외 완료. 세션이 없으면(연결 전, 세션이 끝난 뒤) IllegalStateException, close() 뒤에는 IllegalStateException("Client is closed")으로 실패한 future. lane을 거치지 않고 대개 수신 스레드에서 JOIN_CHANNEL 리스너보다 먼저 완료되므로 리스너 안에서 기다려도 교착되지 않음(기다리는 동안 이 클라이언트의 이벤트 전달은 멈춤). 입장을 기다리는 동안 받은 future는 다음 입장이나 세션 종료까지 연결에 남으므로, 제한 시간을 두고 반복해서 부르지 말고 받은 future 하나를 재사용.
- disconnect() - 연결 중·재연결 대기 중을 포함해 어떤 상태에서도 세션 종료. 블로킹하지 않으며 DISCONNECTED(isClientInitiated()=true)는 이벤트 lane에서 비동기로 전달. 이후 새 세션 시작 가능. 세션이 없으면 아무 일도 하지 않음.
- close() - 세션 종료 후 클라이언트를 닫음(최종). 이후 connectToChat()·forceReconnect()·ready()는 실패한 future 반환.
- reconnect() -> CompletableFuture<Void> - 방송 정보 재조회 없이 현재 연결에서 WebSocket만 다시 엶. 새 소켓이 채널에 입장하면 완료. RECONNECTING(0ms)→RECONNECTED emit. 세션이 없으면 IllegalStateException으로 실패.
- forceReconnect() -> CompletableFuture<Void> - 방송 정보 조회부터 새 연결로 교체. 현재 상태/backoff 무시. 세션 유지(반환값은 connectToChat()과 같은 세션 future), RECONNECTING(attempt 1, max 1, delay 0)→RECONNECTED(1) emit, DISCONNECTED 없음(새 연결이 실패하면 DISCONNECTED(causedByError=true)로 세션 종료). 세션이 없으면 RECONNECTING 없이 새로 시작. 실측상 재입장까지 1~3초 걸릴 수 있음.
- isConnected() -> boolean - 서버가 현재 소켓의 채널 입장(JOIN)에 응답했으면 true
- getConnectionStatus() -> CompletableFuture<ConnectionStatus> - (connected, reconnecting, retryCount). 세션이 없으면 (false, false, 0)

채팅 (인증 필요, 채널 입장 뒤 호출: ready() 완료 또는 JOIN_CHANNEL 이후):
- sendChat(String message) -> CompletableFuture<Void> - 채팅 전송
- sendWhisper(String targetId, String message) -> CompletableFuture<Void> - 귓말 전송. targetId는 받는 사람의 로그인 ID(닉네임이나 런타임 (n) 접미사 형태가 아님)

송신 검증 순서(모든 거부는 실패한 future로 돌아오며 소켓에는 영향이 없습니다):
1. sendWhisper는 targetId가 null/공백이면 IllegalArgumentException
2. message가 null/공백이면 IllegalArgumentException (인증·연결 확인보다 먼저)
3. 미인증이면 AuthenticationException
4. 세션이 없으면 IllegalStateException
5. 사용자 필드에 U+000C(필드 구분자)·U+001B(ESC)·짝 없는 surrogate가 있거나 payload가 999,999바이트를 넘으면 IllegalArgumentException
6. 소켓이 아직 열리지 않았으면 IllegalStateException

이전 버전의 calculateByteSize 헬퍼는 제거되었습니다(길이 계산은 내부의 SOOPChatUtils.utf8ByteLength()).

기타:
- getBid() -> String - 방송인 ID
- getEventEmitter() -> EventEmitter - 이벤트 에미터 직접 접근

### SOOPChatConfig.Builder (설정)

| 메서드 | 타입 | 기본값 | 설명 |
|--------|------|--------|------|
| bid(String) | String | (필수) | 방송인 ID. null/공백이면 build()에서 IllegalArgumentException |
| bno(String) | String | null (자동 해석) | 방송 번호 |
| authCookie(AuthCookie) | AuthCookie | null (익명 모드) | 인증 쿠키. isAuthenticated()가 true일 때만 인증 연결 |
| connectionTimeout(Duration) | Duration | 30초 | 방송 정보 조회·WebSocket 연결·송신·닫기 타임아웃. 0보다 커야 함(null·0·음수는 IllegalArgumentException). JOIN 응답 대기는 min(이 값, 10초) |
| maxRetryAttempts(int) | int | 5 | backoff 자동 재연결 최대 재시도 횟수 (0 이상) |
| pingIntervalSeconds(long) | long | 60 | 핑 전송 간격(초), 0보다 커야 함 |
| sslContext(SSLContext) | SSLContext | null (SSLContextProvider 기본값) | 커스텀 SSL 컨텍스트 |
| initialPacketDelayMs(long) | long | 1000 | `@Deprecated(forRemoval = true)`. 효과 없음(CONNECT와 JOIN은 대기 없이 연달아 전송). 호환을 위해 음수만 build()에서 거부 |

getInitialPacketDelayMs()도 같은 이유로 `@Deprecated(forRemoval = true)`입니다. 새 코드에서는 쓰지 않습니다.

### SOOPClientConfig.Builder (전역 설정)

| 메서드 | 타입 | 기본값 | 설명 |
|--------|------|--------|------|
| connectionTimeout(Duration) | Duration | 15초 | REST API(auth()/live()/channel())에만 적용. 0보다 커야 함(null·0·음수는 IllegalArgumentException). 채팅 연결은 SOOPChatConfig 값을 따름 |
| maxRetryAttempts(int) | int | 5 | add(String)/chat(String)으로 등록한 스트림의 재연결 한도 (0 이상). add(SOOPChatConfig)는 그 config의 값을 사용 |

### SOOPAuth (인증)

- signIn(String userId, String password) -> CompletableFuture<AuthCookie>
  - RESULT가 1이 아니면 AuthenticationException("Login failed: " + REASON). RESULT·REASON이 없거나 JSON null이면 기본값(0 / "unknown error")으로 처리
  - HTTP 200이 아니거나 응답을 파싱할 수 없으면 SOOPChatException
  - 로그인 폼(szUid·szPassword), Set-Cookie 값, 응답 본문은 로그와 예외 메시지에 남기지 않음. 파싱할 수 없는 Set-Cookie 헤더는 예외 종류만 FINE으로 남기고 건너뜀. 응답이 JSON 객체가 아니면 본문 없이 실패(Gson의 "Not a JSON Object: <본문>" 메시지를 쓰지 않음). SOOPLive의 방송 정보 응답도 같음
  - 로그인 응답 JSON에는 연령 인증 여부가 없으므로 19금 방송을 볼 수 있는 계정인지는 조회해 봐야 알 수 있음

AuthCookie record 필드: userId, success, rawResponse, authTicket, abroadChk, abroadVod, bbsTicket, rdb, userTicket, au, au3rd, ausa, ausb
- isAuthenticated() -> boolean - success이고 authTicket이 비어 있지 않으면 true
- toString() - 로그에 자격 증명이 남지 않도록 티켓·쿠키 값은 `<redacted>`(비어 있으면 `<empty>`)로 가리고 rawResponse는 출력하지 않음

### SOOPLive (방송 정보)

- getBno(String streamerId) -> CompletableFuture<String> - 방송 중이 아니면 SOOPChatException
- detail(String streamerId) -> CompletableFuture<LiveDetail>
- detail(String streamerId, String bno) -> CompletableFuture<LiveDetail>
- detail(String streamerId, String bno, AuthCookie authCookie) -> CompletableFuture<LiveDetail> - 인증 쿠키로 조회(인증된 FTK를 받음). isAuthenticated()가 true인 쿠키면 로그인 쿠키(AuthTicket, _au, UserTicket, RDB)를 Cookie 헤더로 보내고, 아니면 익명으로 요청. 연령 인증된 계정의 로그인 쿠키면 19금 방송도 채팅 접속 정보가 옴(실제 계정으로 확인)
- confirm_adult는 쿠키와 상관없이 늘 false. 19금 방송을 여는 것은 로그인 쿠키이고 confirm_adult는 결과를 바꾸지 않으므로(익명은 true여도 CHANNEL.RESULT -6, 연령 인증된 로그인은 false여도 1), 19금 확인을 사용자 대신 하지 않음
- toChannelInfo(LiveDetail detail) -> ChannelInfo - WebSocket 연결 정보로 변환

LiveDetail record 필드: bjId, bno, title, chatDomain, chatNo, ftk, chatPort, result, bps, geoCC, geoRC, acptLang, svcLang
- chatDomain은 응답의 CHDOMAIN을 `Locale.ROOT`로 소문자화한 값(기본 Locale과 무관)
- chatPort는 응답의 CHPT에 1을 더한 값
- 필수 필드(BJID, TITLE, CHDOMAIN, CHATNO, FTK, CHPT)가 없거나 RESULT가 1이 아니면 SOOPChatException. 메시지는 "API error: " + REASON이고, REASON이 없으면 "API error: RESULT=<코드>"
- CHANNEL.RESULT가 -6이면 AdultBroadcastException: 19금 방송인데 볼 수 있는 로그인이 아닌 요청(익명, 연령 인증 없는 계정, 만료된 로그인). 이 응답에는 REASON과 채팅 접속 정보(BJID, CHDOMAIN, CHATNO, FTK, CHPT)가 없고 TITLE·BPS 같은 방송 정보만 옵니다. 메시지에 스트리머 ID가 들어가며, 익명 요청이면 연령 인증된 로그인의 AuthCookie를 넘기라고, 인증 요청이면 그 계정이 막혔다고 알려 줍니다
- LiveDetail.toString()과 ChannelInfo.toString()은 FTK를 `<redacted>`(비어 있으면 `<empty>`)로 가림

### SOOPChannel (채널 정보)

- station(String streamerId) -> CompletableFuture<StationInfo>
  - 응답의 중첩 JSON을 읽습니다: user_id·user_nick·station_no·station_name·station_title은 `station.*`, totalFollowers는 `station.upd.fan_cnt`, isLive는 루트의 `broad`가 JSON 객체인지 여부
  - `station` 객체가 없으면 SOOPChatException("Station info missing in response"). HTTP 200이 아니거나 파싱에 실패해도 SOOPChatException

StationInfo record 필드: userId, userNickname, stationNo(long), stationName, stationTitle, isLive, totalFollowers

## 이벤트 시스템

### 이벤트 계층 (Sealed Interface)

BaseEvent (sealed)
├── ChatBaseEvent - 채팅 관련 (메시지, 입퇴장)
├── DonationBaseEvent - 후원 관련 (풍선, 초콜릿, 구독)
├── SystemBaseEvent - 시스템 (연결, 서버 상태)
├── ModerationBaseEvent - 관리 (킥, 채금, 차단)
├── ItemBaseEvent - 아이템 (구매, 드롭)
├── NotificationBaseEvent - 알림 (공지, 미션)
└── UnknownEvent - 알 수 없는 타입

모든 이벤트는 Java Record이며 공통 필드: eventType(), raw(), timestamp()

ChatEvent는 상수 97개입니다: 서비스 코드 0~128의 서버 이벤트 92개 + 클라이언트 이벤트 5개(RAW -2, DISCONNECTED -3, RECONNECTING -4, RECONNECTED -5, NONE_TYPE -1). ChatEvent.fromCode(int)는 모르는 코드에 NONE_TYPE을 반환하며, 그런 패킷은 NONE_TYPE 리스너에 UnknownEvent(code = 원래 서비스 코드, originalMessage = raw = 패킷 전체)로 전달됩니다. UnknownEvent는 SystemBaseEvent가 아니라 BaseEvent를 직접 구현하므로 NONE_TYPE 리스너는 UnknownEvent나 BaseEvent로 받습니다.

이벤트 Record의 목록·맵 컴포넌트(BanWordEvent.banWordList, ChatUserEvent.userList, AdminChatUserEvent.users, KickUserListEvent.kickedUsers, ChuserExtendEvent.userStatus의 바깥·안쪽 맵)는 compact 생성자에서 수정할 수 없는 복사본으로 바뀝니다. null은 빈 목록·맵이 되고 null 요소(키·값)는 거부됩니다(NullPointerException). 모든 리스너가 같은 이벤트 객체를 받으므로 한 리스너가 목록을 바꿔 다음 리스너에 영향을 줄 수 없습니다. JSON Map payload(MISSION, MISSION_SETTLE, AD_IN_BROAD_JSON의 data)는 그대로입니다.

### 변경 사항 (호환성)

v0.14.0에서 올리는 경우:

- BanWordEvent.banWordList()는 String[] 대신 List<String>(수정 불가)을 반환합니다. BanWordDecoder의 토큰 규칙(두 번째 필드를 ","로 나누고 빈 토큰은 버리며 trim하지 않음)은 같습니다.
- BanWordEvent·ChatUserEvent·AdminChatUserEvent·KickUserListEvent·ChuserExtendEvent의 목록·맵은 수정하면 UnsupportedOperationException이 발생하고, 생성자는 null 요소를 거부합니다. 고쳐 쓰려면 `new ArrayList<>(e.userList())`처럼 복사합니다.
- 모르는 서비스 코드는 NONE_TYPE에 UnknownEvent로 전달되며 code()가 원래 서비스 코드입니다. 이전에는 NoneTypeDecoder가 첫 필드를 정수로 읽은 NoneTypeEvent(value)를 만들고 코드는 raw()의 헤더에만 남았습니다. NoneTypeEvent와 NoneTypeDecoder는 제거되었고, DefaultMessageDecoderFactory는 NONE_TYPE 항목 없이 서버 이벤트 92개만 등록합니다.
- UnknownEvent는 BaseEvent를 직접 구현합니다. NONE_TYPE 리스너를 SystemBaseEvent로 받고 있었다면 UnknownEvent나 BaseEvent로 바꿉니다(그대로 두면 캐스팅에 실패).
- 커스텀 디코더 맵으로 MessageDispatcher를 쓰는 경우, 디코더가 빠진 알려진 코드도 NONE_TYPE으로 전달됩니다. 이전처럼 그 이벤트의 타입 지정 리스너가 UnknownEvent를 받는 일은 없습니다.
- 내부 클래스 WebSocketManager의 공개 메서드 sendEnterInfo()는 제거되었습니다. ENTER_INFO는 WebSocketManager가 JOIN 응답을 받은 수신 스레드에서 직접 보냅니다.
- 새 API: SOOPChatClient.ready() — 채널 입장을 기다린 뒤 전송하는 기본 패턴은 `chat.connectToChat(); chat.ready().thenRun(() -> chat.sendChat("Hello!"));`입니다.

### EventEmitter

- on(ChatEvent, EventListener) - 이벤트 구독
- once(ChatEvent, EventListener) - 일회성 구독. 등록마다 독립적이며, 동시에 emit되어도 최대 한 번만 호출
- off(ChatEvent, EventListener) - 구독 해제. 호출 한 번에 등록 하나(once() 등록도 원본 리스너로 해제 가능)
- setErrorHandler(Consumer<EventEmitterException>) - 에러 핸들러 설정
- clear() - 모든 리스너 제거
- clear(ChatEvent) - 특정 이벤트의 리스너 제거
- hasListeners(ChatEvent) -> boolean

## connectToChat() 동작 방식

`SOOPClient.add()`는 등록과 동시에 비동기 연결을 시작하므로 보통은 직접 연결 메서드를 부를 필요가 없습니다. 저수준 `SOOPChatClient`를 직접 쓸 때만 아래 메서드를 사용합니다.

connectToChat()은 **세션**을 시작합니다. 반환된 CompletableFuture는 세션이 **끝날 때** 완료됩니다. disconnect()나 서버의 연결 종료로 끝나면 정상 완료, 연결 실패나 재시도 소진으로 끝나면 ConnectionException으로 예외 완료됩니다. 세션이 진행 중일 때 다시(또는 동시에) 호출하면 같은 future를 돌려줍니다. 채널에 들어간 시점은 ready()로 기다리거나 JOIN_CHANNEL 이벤트·isConnected()로 확인합니다.

| 메서드 | 동작 |
|--------|------|
| connectToChat() | 세션 시작. 세션이 끝날 때 완료되는 CompletableFuture<Void> 반환 |
| connectToChat().join() | 세션이 끝날 때까지 현재 스레드를 블로킹 |
| connectAndAwait() | connectToChat().join()의 편의 메서드 (블로킹) |
| ready() | 현재 세션이 채널에 들어가면 완료. 이미 들어가 있으면 즉시, 연결 중·backoff·reconnect()·forceReconnect() 중이면 다음 JOIN 응답에서. 세션이 끝나면 ConnectionException, 세션이 없거나 close() 뒤면 IllegalStateException |
| disconnect() | 어떤 상태에서도 세션 종료. non-blocking, DISCONNECTED는 비동기로 전달. 이후 새 세션 시작 가능 |
| close() | 세션 종료 + 클라이언트 종료(최종). 이후 connectToChat()·forceReconnect()·ready()는 실패한 future |
| forceReconnect() | 방송 정보 조회부터 새 연결로 교체. 세션 유지, RECONNECTING(1/1)→RECONNECTED, DISCONNECTED 없음(새 연결이 실패하면 세션 종료). 세션이 없으면 새로 시작 |
| reconnect() | WebSocket만 다시 엶. 새 소켓이 채널에 입장하면 완료. 세션이 없으면 IllegalStateException |

### 끊김과 재연결

- **"연결됨"**(isConnected(), 내부 connect() 완료, ready(), RECONNECTED)은 서버가 그 소켓의 채널 입장(JOIN, 서비스 코드 0002)에 응답한 시점입니다.
- ready()는 끊김과 재연결을 지나도 실패하지 않습니다. 수립된 소켓이 끊겨 backoff로 복구하는 동안, reconnect()로 소켓을 바꾸는 동안, forceReconnect()로 연결을 바꾸는 동안 받은(또는 이미 기다리던) ready()는 새 소켓·연결이 채널에 들어갈 때 완료됩니다. 실패하는 경우는 세션이 끝날 때뿐입니다(disconnect()·close()·서버의 Close 프레임·연결 실패·재시도 소진, 모두 ConnectionException).
- 서버는 같은 클라이언트의 이전 세션이 그 채널에서 정리되기 전(실측상 닫은 뒤 약 1~3초)에 온 JOIN을 조용히 무시합니다. 그래서 응답이 올 때까지 같은 소켓에 JOIN을 1초마다 다시 보내고, min(connectionTimeout, 10초) 안에 응답이 없으면 그 시도를 실패로 보고 backoff로 넘어갑니다. forceReconnect() 직후 재입장까지 1~3초가 걸릴 수 있습니다.
- **서버가 수립된 연결을 닫으면**(Close 프레임) 세션이 끝납니다. DISCONNECTED(causedByError=false, 서버의 종료 코드·사유)가 발생하며 자동으로 다시 연결하지 않습니다.
- **네트워크 오류·비정상 종료(1006)·송신/핑 실패·채널 입장 응답 없음**이면 backoff로 자동 재연결합니다. 대기 시간은 min(30초, 2초 << (n-1)), 즉 2·4·8·16·30·30…초입니다. 재시도를 예약할 때마다 RECONNECTING(attemptNumber, maxAttempts, delayMs)이, 수립된 연결을 복구하면 RECONNECTED가 발생합니다.
- 초기 연결이 재시도 끝에 성공한 경우에도 RECONNECTING은 발생하지만 RECONNECTED는 발생하지 않습니다.
- maxRetryAttempts를 다 쓰면 DISCONNECTED(causedByError=true)와 함께 세션 future가 ConnectionException으로 예외 완료됩니다.
- 방송 정보 조회(HTTP)가 실패하면(방송 종료 등) 재시도 없이 곧바로 연결 실패로 세션이 끝납니다. 기다리던 ready()도 그 조회 실패(ConnectionException)로 실패합니다.

### 이벤트 전달 규칙

- 이벤트는 클라이언트(스트림)마다 **도착 순서대로 한 번에 하나씩** 전달됩니다. 공유 가상 스레드 풀 위의 클라이언트별 직렬 lane에서 실행되며, 리스너가 느리면 그 스트림의 이벤트만 늦어집니다.
- DISCONNECTED는 세션마다 **정확히 한 번** 발생하고, 그 뒤로는 해당 세션의 이벤트가 오지 않습니다. DISCONNECTED 리스너는 세션 future가 완료되기 전에 실행됩니다.
- disconnect()/close()로 직접 끝낸 경우는 DisconnectedEvent.isClientInitiated()가 true입니다(`!causedByError && reason == DisconnectedEvent.CLIENT_DISCONNECT_REASON`, 값 "Client disconnect", statusCode 1000).
- 리스너 안에서 세션 future(connectToChat(), connectAndAwait(), forceReconnect())를 기다리면 교착 상태가 됩니다. 세션 future는 같은 lane에서 완료되기 때문입니다. 송신 결과(sendChat(..).join()), reconnect().join(), ready().join()은 기다려도 됩니다. 이 future들은 lane을 거치지 않고 완료되며, ready()는 대개 JOIN 응답을 받은 수신 스레드에서 JOIN_CHANNEL 리스너보다 먼저 완료됩니다. 다만 기다리는 동안 그 클라이언트의 이벤트 전달은 멈춥니다.
- JOIN_CHANNEL은 재연결로 채널에 다시 들어갈 때마다 다시 발생합니다. 입장할 때마다 할 일은 JOIN_CHANNEL 리스너에, 한 번만 할 일은 ready()나 once()에 둡니다.

## 에러 처리

### 예외 계층

SOOPChatException (RuntimeException) - REST 응답 오류(HTTP 오류, 필수 필드 누락, 파싱 실패, station 누락 등)
├── AuthenticationException - 로그인 실패, 미인증 sendChat()/sendWhisper()
│   └── AdultBroadcastException - 19금 방송을 볼 수 없는 요청(익명, 연령 인증 없는 계정, 만료된 로그인)의 방송 정보 조회
├── ConnectionException - 연결 실패(방송 정보 조회 실패, 채널 정보 오류, 재시도 소진). 세션 future와 ready()의 예외 원인
└── EventEmitterException - 이벤트 리스너 예외 래핑

EventEmitterException 추가 메서드: getChatEvent() -> ChatEvent

### 실패가 전달되는 방식

| 상황 | 결과 |
|------|------|
| 세션 연결 실패·재시도 소진 | DISCONNECTED(causedByError=true, statusCode=-1) 후 세션 future가 ConnectionException으로 예외 완료. connectAndAwait()는 ConnectionException을 던짐 |
| 19금 방송에 익명(또는 볼 수 없는 계정)으로 연결 | 방송 정보 조회에서 실패해 재시도 없이 끝남. DISCONNECTED(causedByError=true, reason에 19금 안내) 1회, 세션 future와 ready()는 ConnectionException(원인 AdultBroadcastException)으로 예외 완료 |
| 채널에 들어가기 전에 세션이 끝남(disconnect()·close()·서버 종료·연결 실패·재시도 소진) | 기다리던 ready()가 ConnectionException으로 예외 완료. 방송 정보 조회·검증에서 실패했으면 그 ConnectionException |
| close()된 클라이언트의 connectToChat()/forceReconnect()/ready() | IllegalStateException("Client is closed")으로 실패한 future |
| sendChat()/sendWhisper() 입력 오류 | IllegalArgumentException으로 실패한 future (소켓 영향 없음) |
| 미인증 전송 | AuthenticationException으로 실패한 future |
| 세션 없음·소켓 미개방 상태의 전송, 세션 없는 reconnect()·ready() | IllegalStateException으로 실패한 future |
| 송신 실패·타임아웃 | 그 송신 future가 실패하고, 연결은 backoff 재연결 |
| SOOPClient.reconnect(미등록 bid) | IllegalArgumentException으로 실패한 future |
| 설정 값 오류 | 빌더가 IllegalArgumentException을 던짐 |
| 리스너 예외 | 로그 + errorHandler(EventEmitterException) 호출. 다른 리스너와 이후 이벤트 전달은 계속 |
| 잘못된 수신 패킷 | 예외 없이 버림. 서비스 코드 불량·디코딩 실패(필드 부족 등)·JSON 파싱 실패는 FINE 로그, 구분자(F)가 없는 패킷은 로그 없이 |

---

## 아키텍처 개요 (기여자용)

### 패키지 구조

```
lib/src/main/java/com/github/getcurrentthread/soopapi/
├── SOOPClient.java                          # 파사드 진입점
├── api/                                     # HTTP API 통신
│   ├── SOOPAuth.java                        #   로그인/인증
│   ├── SOOPLive.java                        #   방송 정보 API
│   ├── SOOPChannel.java                     #   채널 정보 API
│   ├── SOOPHttpClient.java                  #   HTTP 클라이언트 (쿠키, 타임아웃)
│   ├── JsonFields.java                      #   JSON 필드 null-safe 헬퍼 (package-private)
│   └── model/                               #   데이터 모델 (AuthCookie, LiveDetail, StationInfo)
├── client/                                  # 사용자 대면 클라이언트
│   └── SOOPChatClient.java                  #   이벤트 구독 + 세션 관리
├── config/                                  # 설정
│   ├── SOOPChatConfig.java                  #   채팅 연결 설정 (Builder)
│   └── SOOPClientConfig.java                #   전역 클라이언트 설정 (Builder)
├── connection/                              # 연결 추상화와 구현
│   ├── ChatConnection.java                  #   연결 하나의 공개 인터페이스
│   ├── ChatConnectionFactory.java           #   연결·lane 생성 공개 인터페이스
│   ├── ConnectionManager.java               #   공유 실행 자원 + 기본 팩토리 (싱글톤)
│   └── SOOPConnection.java                  #   연결 하나: 방송 정보 조회(주입 가능) + WebSocket
├── decoder/                                 # 메시지 파싱/디스패치
│   ├── MessageDispatcher.java               #   메시지 라우팅 (lane에서 실행), 디코더 없는 코드 → UnknownEvent
│   ├── message/                             #   디코더 구현 91개 + IMessageDecoder + JsonPayloadDecoder
│   │   ├── IMessageDecoder.java             #     디코더 인터페이스
│   │   ├── JsonPayloadDecoder.java          #     JSON payload 공통 베이스 (package-private)
│   │   ├── ChatMessageDecoder.java          #     채팅 메시지 디코더 (대표 예시)
│   │   └── ...                              #     SendBalloonDecoder, ChocolateDecoder 등
│   └── factory/                             #   디코더 팩토리
│       ├── MessageDecoderFactory.java        #     팩토리 인터페이스
│       └── DefaultMessageDecoderFactory.java #     92개 등록 (서버 이벤트 92, NONE_TYPE 없음)
├── event/                                   # 이벤트 시스템
│   ├── ChatEvent.java                       #   이벤트 열거형 97개 (서버 92 + 클라이언트 5)
│   ├── EventEmitter.java                    #   Pub/Sub 이벤트 버스
│   ├── EventListener.java                   #   리스너 함수형 인터페이스
│   ├── StreamEventListener.java             #   (streamerId, event) 글로벌 리스너
│   └── model/                               #   이벤트 타입 103개 파일 (record 96 + sealed 인터페이스 7)
│       ├── BaseEvent.java                   #     sealed 루트 인터페이스
│       ├── ChatBaseEvent.java               #     채팅 카테고리
│       ├── DonationBaseEvent.java           #     후원 카테고리
│       ├── SystemBaseEvent.java             #     시스템 카테고리
│       ├── ModerationBaseEvent.java         #     관리 카테고리
│       ├── ItemBaseEvent.java               #     아이템 카테고리
│       ├── NotificationBaseEvent.java       #     알림 카테고리
│       └── UnknownEvent.java                #     디코더가 없는 코드용 (NONE_TYPE, code = 원래 서비스 코드)
├── code/                                    # 소켓 코드표
│   ├── UserFlag.java                        #   사용자 등급 비트 - 주 그룹
│   ├── UserFlag2.java                       #   사용자 등급 비트 - 보조 그룹
│   ├── UserLevel.java                       #   "주|보조" 파싱 컨테이너 (record)
│   ├── ChatIceType.java                     #   아이스/제한 모드 (+ 중첩 Flag)
│   └── ChatQuitStatus.java                  #   채널 퇴장 사유
├── exception/                               # 예외
│   ├── SOOPChatException.java               #   기본 예외 (RuntimeException)
│   ├── AuthenticationException.java
│   ├── AdultBroadcastException.java         #   19금 방송 조회 실패 (AuthenticationException 하위)
│   ├── ConnectionException.java
│   └── EventEmitterException.java
├── model/                                   # 도메인 모델
│   ├── ChannelInfo.java                     #   WebSocket 엔드포인트 정보 (toString은 FTK 가림)
│   └── ConnectionStatus.java                #   연결 상태 스냅샷
├── constant/                                # 프로토콜 상수
│   └── SOOPConstants.java                   #   패킷 구분자, ESC 헤더
├── util/                                    # 유틸리티
│   ├── SOOPChatUtils.java                   #   파싱(서비스 코드, 필드 분할), UTF-8 길이, 예외 언래핑
│   ├── SerialExecutor.java                  #   클라이언트별 직렬 실행기 (lane)
│   ├── GsonUtil.java                        #   JSON → Map 변환
│   └── SSLContextProvider.java              #   SSL/TLS 컨텍스트
└── websocket/                               # WebSocket 계층
    ├── WebSocketManager.java                #   소켓 시도·핸드셰이크·송신 체인·재연결·핑·준비 게이트·ENTER_INFO
    ├── WebSocketListener.java               #   수신 프레임 조립, JOIN 응답 감지, 백프레셔
    └── WebSocketPacketBuilder.java          #   패킷 직렬화 + 사용자 입력 검증
```

### 핵심 컴포넌트 관계

```
SOOPClient (파사드)
├── SOOPHttpClient (REST 공용) ─── SOOPAuth / SOOPLive / SOOPChannel
└── SOOPChatClient (bid당 1개)
    ├── EventEmitter ─── 사용자 리스너
    ├── SerialExecutor (lane, 평생 1개) ─── ConnectionManager의 공유 가상 스레드 풀
    └── Session ─── ChatConnection (= SOOPConnection, 팩토리가 생성, forceReconnect로 교체)
        ├── ChannelLookup (방송 정보 조회, 테스트에서 주입) ─── SOOPHttpClient (조회 전용, 조회가 끝나면 shutdown) ─── SOOPLive
        ├── MessageDispatcher ─── IMessageDecoder 맵 (static 공유)
        └── WebSocketManager ─── Socket (시도마다) ─── WebSocketListener
                              ├── 준비 게이트 (ready(), JOIN 응답에서 완료)
                              └── ConnectionManager의 공유 스케줄러 (JOIN 재전송·핑·backoff)

ConnectionManager (싱글톤): 공유 자원만 소유 + 기본 ChatConnectionFactory
```

### 메시지 처리 파이프라인

```
JDK WebSocket 수신 스레드
    → WebSocketListener.onText()/onBinary(): 프래그먼트 조립 (조각나지 않은 프레임은 버퍼 생략)
    → JOIN 응답(서비스 코드 0002)이면 dispatcher보다 먼저 Callbacks.onJoinReply(reply) → WebSocketManager:
        a. [인증 시] 응답의 chatNo가 이 연결의 CHATNO와 같고 userFlag(synAck)가 비어 있지 않으면 ENTER_INFO를 송신 체인에 넣음 (JOIN 응답마다)
        b. 소켓의 첫 JOIN 응답이면 수립 처리 후 lock 밖에서 준비 게이트 완료 → ready()를 기다리던 작업이 대개 이 스레드에서 실행
    → MessageDispatcher.dispatchMessage() → lane.execute(...)
    → 소켓의 첫 JOIN 응답을 받은 뒤, lane 대기 태스크가 10,000을 넘으면 다음 프레임 요청 보류 (1,000 이하에서 재개)

클라이언트 lane (SerialExecutor, FIFO, 한 번에 하나):
    1. RAW 리스너가 있으면 RawEvent 발행 (없으면 할당 생략)
    2. 첫 F(\u000c)의 위치를 찾고, 그 앞 헤더에서 parseServiceCode()로 4자리 코드 파싱 (할당 없음)
       → F가 없는 패킷은 버리고, 서비스 코드를 읽을 수 없는 헤더는 FINE 로그 후 버림
    3. ChatEvent.fromCode() → 디코더 조회. 모르는 코드이거나 디코더가 없으면 NONE_TYPE으로 보냄
    4. 그 이벤트의 리스너가 없으면 조기 반환 (분할·디코딩 생략)
    5. 디코더가 있으면 splitFields() → IMessageDecoder.decode(parts, raw) (null이면 FINE 로그 후 버림)
       없으면 UnknownEvent(code = 헤더의 원래 서비스 코드, originalMessage = raw = 패킷 전체)
    6. EventEmitter.emit(chatEvent, event)
        → internalListeners 먼저 호출
        → listeners 호출
```

그래서 ready()를 기다리던 작업이나 JOIN_CHANNEL 리스너가 보낸 메시지는 항상 ENTER_INFO 뒤에 송신 체인에 들어갑니다.

연결 상태 이벤트(RECONNECTING·RECONNECTED·DISCONNECTED)도 같은 lane에 제출되므로 수신 이벤트와 순서가 섞이지 않습니다.

## 내부 구조 상세

### ConnectionManager (공유 실행 자원)

파일: connection/ConnectionManager.java

- Initialization-on-demand Holder(IODH) 패턴을 사용한 lazy 싱글톤
- 연결을 소유하지 않습니다. 모든 클라이언트가 공유하는 실행 자원만 가집니다:
  - pool: Executors.newVirtualThreadPerTaskExecutor() — 모든 lane이 drain을 제출하는 가상 스레드 풀
  - scheduler: ScheduledThreadPoolExecutor(1), 데몬 스레드 "SOOP-Scheduler", setRemoveOnCancelPolicy(true) — JOIN 재전송 타이머, 핑, backoff 재시도 예약
- bid별 연결 맵, connect/disconnect/getConnection/shutdown 메서드, JVM shutdown hook은 없습니다. 스레드가 모두 데몬(가상 스레드 포함)이라 JVM 종료를 막지 않으므로 별도의 종료 절차가 필요 없습니다.
- ChatConnectionFactory 기본 구현:
  - createConnection(config, emitter, lane) → new SOOPConnection(config, scheduler, emitter, lane)
  - newLane() → new SerialExecutor(pool)

### ChatConnection / ChatConnectionFactory

파일: connection/ChatConnection.java, connection/ChatConnectionFactory.java (공개 인터페이스)

- ChatConnection: 채팅 서버와의 연결 하나. SOOPChatClient가 세션마다 만들어 쓰고 끝나면 버립니다.
  - connect(): 수립되면 완료, 실패하면 예외. 두 번째 호출부터는 첫 호출의 결과를 따름
  - ready(): 채널에 들어갔음을(서버가 JOIN에 응답했음을) 알리는 future. 호출마다 새 future. 현재 소켓이 입장해 있으면 이미 완료, 연결 중·재연결 대기 중이면(connect() 전 포함) 다음 JOIN 응답에서 완료, 그 전에 연결이 끝나면(방송 정보 조회 실패, close(), 서버의 연결 종료, 재시도 소진 등 모든 종료 경로) ConnectionException으로 예외 완료하고 끝난 뒤의 호출도 곧바로 실패. 연결이 끝나지 않았으면 실패해서는 안 됨(클라이언트는 이 실패를 연결 종료 신호로 보고 세션을 정리). 연결 수명 내내 남는 future(terminated() 등)에 호출마다 의존 작업을 붙여서는 안 됨
  - reconnect(): 현재 소켓을 버리고 다시 연결, 수립되면 완료
  - terminated(): connect 결과가 정해진 뒤 모든 경로에서 정확히 한 번 완료. 서버 종료·close()면 DisconnectedEvent로 정상 완료, 연결 실패·재시도 소진이면 예외 완료
  - sendChat(), sendWhisper(), status(), isConnected()
  - close(): 여러 번 호출해도 안전하며 블로킹하지 않음
  - 계약: 모든 이벤트는 생성 시 받은 lane에서 emit하고, 반환하는 future는 lane 밖에서, lock을 쥐지 않은 채 완료
- ChatConnectionFactory: createConnection(config, emitter, lane)(아직 시작하지 않은 연결), newLane()(클라이언트가 평생 쓸 lane)
- 주입: SOOPChatClient(SOOPChatConfig, ChatConnectionFactory). SOOPClient도 package-private 생성자로 팩토리를 받습니다. 테스트는 connection/FakeConnectionFactory·FakeChatConnection으로 네트워크 없이 연결 성공·실패·서버 종료와 입장·끊김(ready() 게이트)을 일으킵니다.

### SOOPChatClient (세션 관리)

파일: client/SOOPChatClient.java

- 생성 시 factory.newLane()으로 lane 하나를 받아 평생 사용합니다. EventEmitter도 클라이언트당 하나.
- Session { done, publicDone, connection, ended }: publicDone(= done.copy())을 사용자에게 돌려주므로 외부에서 세션 future를 완료할 수 없습니다. session·closed는 ReentrantLock으로 보호합니다.
- connectToChat(): closed면 실패, 세션이 있으면 publicDone 반환, 없으면 createConnection → Session 생성 → start()
- start(s, c): c.terminated().whenCompleteAsync(onTerminated, lane)을 걸고 c.connect() 호출
- onTerminated(lane에서 실행): s.connection == c이고 아직 끝나지 않았을 때만 세션을 끝냅니다 → DISCONNECTED emit(오류면 DisconnectedEvent(-1, 메시지, true)) → done 완료. 세션은 **현재 연결의 terminated()로만** 끝납니다.
- forceReconnect(): 같은 임계구역에서 s.connection을 새 연결로 바꿔 끼움(이후 옛 연결의 종료는 무시) → RECONNECTING(1, 1, 0)을 lane에 제출 → 옛 연결 close() → start(s, 새 연결) → 성공하고 여전히 현재 연결이면 lane에서 RECONNECTED(1). 새 연결이 실패하면 세션이 DISCONNECTED(causedByError=true)로 끝납니다.
- disconnect(): session을 null로 떼어 낸 뒤 연결을 close(). 곧바로 새 세션을 시작할 수 있고, 옛 세션의 DISCONNECTED는 lane에서 뒤따라 옵니다.
- close(): closed=true 후 disconnect(). 이후 connectToChat()/forceReconnect()/ready()는 IllegalStateException("Client is closed")로 실패.
- ready(): closed면 IllegalStateException("Client is closed"), 세션이 없으면 IllegalStateException. 있으면 그 세션의 현재 연결 c의 ready()를 기다립니다(awaitReady). c.ready()가 실패하면(c가 끝났으면) lock 안에서 확인합니다:
  - 세션에 forceReconnect()로 다른 연결이 붙어 있으면 그 연결의 ready()를 이어서 기다림
  - c가 아직 세션의 연결이면 세션은 c와 함께 끝나므로, lane의 onTerminated를 기다리지 않고 그 자리에서 session을 null로 떼어 낸 뒤 ConnectionException으로 실패. 그래서 그 사이에 온 forceReconnect()는 ready()가 이미 끝났다고 알린 세션을 되살리지 않고 새 세션을 시작합니다. DISCONNECTED는 disconnect() 때처럼 lane에서 뒤따라 옵니다.
  - 세션이 이미 바뀌었으면(disconnect() 등) ConnectionException으로 실패
  - onTerminated(lane)를 거치지 않으므로 lane에서 ready()를 기다려도 막히지 않습니다. 반복 호출은 수명이 짧은 준비 게이트에만 작업을 걸고 terminated()에는 걸지 않습니다.

### SOOPConnection (연결 하나)

파일: connection/SOOPConnection.java

- SHARED_DECODERS: static final Map — DefaultMessageDecoderFactory의 디코더 맵을 모든 연결이 공유
- 연결마다 자체 MessageDispatcher(SHARED_DECODERS, lane, emitter)와 WebSocketManager를 가집니다.
- ENTER_INFO는 연결이 직접 보내지 않습니다. 인증 설정이면 WebSocketManager가 JOIN 응답을 받은 수신 스레드에서 송신 체인에 넣습니다(§ WebSocketManager).
- 방송 정보 조회는 package-private 함수형 인터페이스 ChannelLookup(lookup(config) → CompletableFuture<ChannelInfo>)입니다. 공개 생성자는 기본 조회(lookupChannel)를 쓰고, package-private 생성자로 조회를 주입하면 테스트가 네트워크 없이 조회 결과·실패를 넣을 수 있습니다(SOOPConnectionTest).
- connect() 흐름 (한 번만 실행, 이후 호출은 첫 결과의 복사본):
  1. channelLookup.lookup(config). 기본 조회는:
     a. 조회 전용 SOOPHttpClient(config.connectionTimeout)를 연결마다 새로 만듦(쿠키를 섞지 않음)
     b. BNO: config.bno가 없으면 soopLive.getBno(bid)로 조회
     c. soopLive.detail(bid, bno, authCookie) → LiveDetail (authCookie를 넘겨야 인증된 FTK를 받음. 익명 FTK와 인증 CONNECT를 섞으면 서버가 JOIN을 조용히 거부)
     d. toChannelInfo() → ChannelInfo(CHDOMAIN, CHATNO, FTK, CHPT 등)
     e. 조회가 끝나면(성공·실패 무관) 조회용 HTTP 클라이언트를 바로 shutdown() (블로킹하지 않음). WebSocket 연결을 기다리지 않습니다.
  2. CHPT/CHDOMAIN 유효성 검증 (비어 있으면 ConnectionException)
  3. webSocketManager.connect(channelInfo) — 서버가 JOIN에 응답하면 완료 (소켓 단계 실패는 이 안에서 backoff 재시도)
  - 조회·검증 단계(1~2)의 실패는 재시도하지 않고 곧바로 연결 실패입니다. ConnectionException이 아닌 원인은 ConnectionException("Cannot connect to channel <bid>: <원인 메시지>", 원인)으로 감싸므로, 원인을 풀지 않아도 실패 메시지와 DISCONNECTED 사유에서 이유(예: 19금 안내)가 보입니다.
  - connect가 실패하면(close()로 중단된 경우 제외) 그 실패를 connectFailure로 기억하고 WebSocketManager를 닫습니다. 조회·검증에서 실패했으면 WebSocketManager는 시작한 적이 없으므로, 이렇게 닫아야 기다리던 ready()가 끝납니다.
- ready(): WebSocketManager.ready()를 이어받아 실패를 ConnectionException으로 바꿉니다. connect가 실패했으면 WebSocketManager가 닫힌 이유 대신 그 실패(connectFailure, 예: 방송 정보 조회 실패)로 실패하며, 이후 호출도 같습니다.
- terminated(): connect 결과가 정해진 뒤(settle) 정확히 한 번 완료. 성공했으면 WebSocketManager.terminated()를 이어받고, 실패했으면 ConnectionException으로 예외 완료(close()로 중단된 경우는 client-disconnect 이벤트로 정상 완료)
- close(): dispatcher.deactivate()(아직 전달되지 않은 패킷 버림) → WebSocketManager.close()(기다리던 ready() 실패) → 진행 중인 connect를 실패 처리 → terminated를 DisconnectedEvent(1000, "Client disconnect", false)로 호출 스레드에서 즉시 완료
- 오류는 ConnectionException으로 감쌉니다.

### WebSocketManager

파일: websocket/WebSocketManager.java

- WebSocket용 HttpClient: SSLContext(config.sslContext, 없으면 SSLContextProvider)마다 하나를 static 맵에서 공유하며 닫지 않습니다(스레드는 모두 데몬).
- URI: wss://{CHDOMAIN}:{CHPT}/Websocket/{bid}, 서브프로토콜 "chat", 열기 타임아웃 = connectionTimeout
- 소켓 식별: 시도마다 Socket 객체(id, listener, ws, 송신 체인 tail, ping, joinTimer, ready)를 만들어 **열기 전에** current로 등록합니다. 교체되거나 닫힌 소켓의 콜백은 모두 무시하고, 늦게 열린 소켓은 abort합니다.
- 송신 체인: 소켓마다 CompletableFuture 체인으로 송신을 직렬화합니다(JDK WebSocket은 미완료 텍스트 송신을 하나만 허용). 앞 송신이 끝나야(성공·실패 무관) 다음 송신이 나가고, 각 송신에 connectionTimeout이 걸립니다. 소켓이 열리는 임계구역에서 CONNECT·JOIN을 체인 맨 앞에 넣어 어떤 송신도 앞서지 않습니다. 송신 실패는 전송 장애로 처리합니다.
- JOIN 응답(onJoinReply, 수신 스레드): WebSocketListener가 JOIN 응답마다 dispatcher보다 먼저 알립니다. 인증 연결이면 먼저 ENTER_INFO를 처리하고, 그다음 수립 처리를 합니다.
- ENTER_INFO(인증 연결만): JOIN 응답마다 응답을 JoinChannelDecoder로 읽어, chatNo가 connect() 때 받은 CHATNO와 같고 userFlag(synAck)가 비어 있지 않으면 ENTER_INFO 패킷을 그 소켓의 송신 체인에 넣습니다(패킷 생성은 lock 밖, 체인에 넣는 것만 lock 안. 교체되거나 닫힌 소켓이면 넣지 않음). 준비 게이트를 열기 전, dispatcher에 넘기기 전이므로 ready()나 JOIN_CHANNEL 리스너에서 보낸 메시지는 항상 ENTER_INFO 뒤에 나갑니다.
- 수립(ready) = 소켓의 첫 JOIN 응답. 이때 JOIN 타이머를 취소하고, 핑을 예약하고, retryCount를 0으로 되돌리고, 복구 중이었으면 RECONNECTED(max(1, retryCount))를 lane에 emit합니다. 마지막으로 lock 밖에서 준비 게이트를 완료합니다. 같은 소켓의 이후 JOIN 응답은 수립 처리를 다시 하지 않습니다.
- 준비 게이트(readyGate, lock으로 보호): ready()는 현재 게이트의 복사본을 돌려줍니다(호출자가 완료해도 내부 상태는 바뀌지 않음).
  - 수립된 소켓을 복구하려고 내릴 때(전송 장애 backoff, reconnect()) 새 게이트로 바꿔, 이후 ready()가 다음 JOIN을 기다리게 합니다. 게이트의 완료 여부가 아니라 소켓의 ready 플래그로 판단합니다. 수립 처리는 lock을 놓은 뒤에 게이트를 완료하므로, 그 사이에 끊기면 게이트가 아직 대기 상태일 수 있기 때문입니다.
  - 수립 전 시도의 실패(backoff 재시도)는 게이트를 건드리지 않으므로 기다리던 ready()는 계속 기다립니다.
  - 연결이 끝나면(close(), 수립된 소켓의 서버 Close 프레임, 재시도 소진) 게이트를 ConnectionException으로 실패시키고, 이후 ready()도 곧바로 실패하도록 실패한 future로 바꿉니다. 기다리던 쪽은 lock 밖에서 실패시킵니다.
- JOIN 타이머: 소켓이 열리면 1초 간격으로 JOIN을 다시 송신 체인에 넣고, 누적 대기가 min(connectionTimeout, 10초)에 이르면 그 시도를 실패("Server did not answer JOIN within …ms")로 처리합니다.
- 끊김 정책:

| 상황 | 처리 |
|------|------|
| 수립된 소켓이 Close 프레임 수신 (1006 제외) | 연결 종료: terminated를 DisconnectedEvent(서버 코드·사유, causedByError=false)로 완료, ready()는 ConnectionException("Connection closed by server: …"). 재연결 안 함 |
| 수립 전(핸드셰이크 중) Close 프레임 수신 | 그 시도 실패 → backoff (ready()는 계속 대기) |
| 1006(Close 프레임 없이 끊김)·onError·송신/핑 실패 | 수립된 소켓이면 abort 후 backoff 재연결(복구, 준비 게이트를 새로 둠), 수립 전이면 그 시도 실패 → backoff |
| 소켓 열기 실패·JOIN 응답 기한 초과 | 그 시도 실패 → backoff |
| 재시도 한도 초과 | terminated와 ready()를 ConnectionException("Connection failed after N retries")으로 예외 완료 |

- backoff: 실패마다 retryCount를 올리고, 한도를 넘으면 소진 처리, 아니면 delay = min(30초, 2초 << (n-1)). RECONNECTING(n, max, delay)을 lane에 먼저 넣은 뒤 스케줄러에 재시도를 예약합니다(재시도 결과 이벤트가 RECONNECTING보다 앞서지 않게).
- reconnect(): 채널 정보가 아직 없으면 IllegalStateException. 진행 중인 연결 시도가 있으면 그 결과를 따름. 현재 소켓이 수립돼 있었으면 준비 게이트를 새로 두고, 소켓을 정상 종료(closeGracefully)하고 RECONNECTING(retryCount+1, max, 0) 뒤 새 시도. 수립되면 RECONNECTED.
- close(): 멱등. 예약된 재시도 취소, 진행 중 시도와 기다리던 ready() 실패, terminated를 client-disconnect(1000)로 완료. 현재 소켓은 sendClose(1000)를 보내고 완료되거나 connectionTimeout이 지나면 abort. 이후 connect·송신·ready()는 모두 실패.
- ReentrantLock 안에서는 상태만 바꾸고, WebSocket 호출·future 완료(준비 게이트 포함)·lane 제출은 lock 밖에서 합니다.
- getStatus() → WebSocketStatus(connected, reconnecting, retryCount, maxRetries)

### WebSocketListener

파일: websocket/WebSocketListener.java (소켓마다 새로 생성)

- onText()/onBinary(): 프래그먼트 조립. 조각나지 않은 프레임은 버퍼를 거치지 않고 바로 전달합니다.
- 바이너리 프레임은 UTF-8로 디코딩합니다. JDK가 넘기는 ByteBuffer는 배열 오프셋이 0이 아닌 slice일 수 있으므로 arrayOffset()+position()부터 읽습니다(배열에 접근할 수 있는 heap 버퍼는 복사 없이, direct·읽기 전용 버퍼는 복사).
- 버퍼: 기본 16KB. textBuffer는 4배(64KB) 초과 시 trimToSize(), binaryBuffer는 64KB 초과 시 새로 할당
- JOIN 응답(서비스 코드 0002)마다 Callbacks.onJoinReply(reply)로 **먼저** 알린 뒤 dispatcher에 넘깁니다. 소켓의 첫 응답이 수립 시점입니다. 그래서 JOIN_CHANNEL 리스너는 이미 수립된 연결(isConnected()=true)을 보고, 인증 연결의 ENTER_INFO와 ready() 완료는 JOIN_CHANNEL 리스너보다 앞섭니다.
- 예외 격리: 처리·콜백 예외는 여기서 로그로 막습니다(JDK까지 전파되면 연결이 onError로 끊김). 처리에 실패해도 다음 프레임 요청은 항상 합니다.
- detach(): 이후 데이터와 onClose/onError 알림을 버리되, 닫힘 응답을 읽을 수 있도록 다음 프레임 요청은 계속합니다.
- 백프레셔: 소켓의 첫 JOIN 응답을 받은 뒤 lane.pending()이 10,000을 넘으면 다음 프레임 요청을 보류하고, lane.whenPendingAtMost(1,000, …)로 다시 요청합니다. 첫 JOIN 응답 전에는 보류하지 않습니다. 리스너가 lane을 붙잡고 ready()를 기다려도 재연결 소켓이 JOIN 응답을 읽게 하기 위해서이며, 그 전에 오는 프레임은 몇 개뿐입니다.
- onClose(statusCode, reason) → Callbacks.onClosed, onError → Callbacks.onFailed. DISCONNECTED 발행은 SOOPChatClient가 세션 종료 시 담당합니다.

### SerialExecutor (lane)

파일: util/SerialExecutor.java

- 공유 풀 위에서 태스크를 제출 순서대로 하나씩 실행하는 Executor. 클라이언트마다 하나. 여러 lane이 같은 풀을 써도 lane끼리는 병렬로 진행
- ConcurrentLinkedQueue + AtomicBoolean draining: 한 번에 drain 하나만 풀에 제출
- drain 한 번에 최대 256개를 실행하고, 대기열이 남았으면 풀에 다시 제출해 다른 lane에 양보
- 태스크 예외는 WARNING 로그로 격리하고 다음 태스크를 계속 실행
- 풀이 거부하면(RejectedExecutionException) 태스크를 버리지 않고 제출한 스레드에서 직접 실행
- pending(): 제출됐지만 끝나지 않은 태스크 수. whenPendingAtMost(threshold, callback): 대기 수가 threshold 이하가 되면 한 번 실행(이미 이하면 즉시, 등록은 하나만 유지) — WebSocketListener 백프레셔에 사용

## WebSocket 프로토콜

### 패킷 구조

```
[ESC][command:4][length:6][suffix:2][payload]

ESC     = \u001b\t (ESC + TAB 두 문자)
command = 4자리 서비스 코드
length  = payload의 UTF-8 바이트 길이, 6자리 0-패딩 (최대 999,999)
suffix  = "00" (고정)
payload = F(\u000c)로 시작하고 F로 필드를 구분
```

수신 패킷도 같은 구조입니다. MessageDispatcher는 첫 F 앞을 헤더로 보고, 헤더의 마지막 TAB 뒤 네 글자를 서비스 코드로 읽습니다(네 글자가 모두 ASCII 숫자가 아니면 버림). 첫 F 뒤의 필드가 디코더의 parts[]가 됩니다.

### 명령 코드 (WebSocketPacketBuilder)

| 코드 | 상수 | 용도 |
|------|------|------|
| 0000 | CMD_PING | 송신 실패 감지용 핑 (payload: F) |
| 0001 | CMD_CONNECT | 초기 연결 핸드셰이크 (서버는 LOGIN, 코드 1로 응답) |
| 0002 | CMD_JOIN | 채팅 채널 입장 (서버는 JOIN_CHANNEL, 코드 2로 응답 = 수립) |
| 0005 | CMD_CHAT | 채팅 메시지 전송 |
| 0009 | CMD_DIRECT_CHAT | 귓말(다이렉트 채팅) 전송 |
| 0012 | CMD_ENTER_INFO | 인증된 사용자 입장 정보 |

### 필드 구분자 (SOOPConstants)

| 상수 | 값 | 용도 |
|------|------|------|
| F | \u000c | 기본 필드 구분자 (폼 피드) |
| F_CHAR | \u000c | char 타입 (성능 최적화) |
| ESC | \u001b\t | 패킷 헤더 접두사 |
| ELEMENT_START | \u0011 | 메타데이터 블록 시작 |
| ELEMENT_END | \u0012 | 메타데이터 블록 끝 |
| SPACE | \u0006 | 메타데이터 내 연산자 공백 |

### 연결 핸드셰이크 시퀀스

1. 소켓이 열리면 CONNECT와 JOIN을 송신 체인 맨 앞에 넣어 대기 없이 연달아 보냅니다(initialPacketDelayMs는 쓰지 않음).

   Connect 패킷 (CMD_CONNECT=0001, "16" = 프로토콜 버전):
   - 익명: F×3 + "16" + F
   - 인증: F + AuthTicket + F×2 + "16" + F

   Join 패킷 (CMD_JOIN=0002):
   - 익명: F + CHATNO + F×5
   - 인증: F + CHATNO + F + FTK + F + "0" + F + log{…}pwd{}auth_info{AuthTicket}pver{1}access_system{html5} + F
     - {…}는 ELEMENT_START(\u0011) … ELEMENT_END(\u0012)
     - log 쿼리는 `SPACE&SPACE키SPACE=SPACE값` 반복: set_bps·view_bps(=BPS), quality=normal, uuid(=AuthCookie의 _au), geo_cc, geo_rc, acpt_lang, svc_lang, subscribe=0, lowlatency=0, mode=landing

2. 서버가 CONNECT에 LOGIN(서비스 코드 1)으로 응답합니다.

3. 서버가 JOIN에 JOIN_CHANNEL(서비스 코드 2)로 응답하면 그 소켓이 수립된 것으로 봅니다.
   - 같은 클라이언트의 이전 세션이 정리되기 전(실측상 닫은 뒤 약 1~3초)에 온 JOIN은 조용히 무시되므로, 응답이 올 때까지 같은 소켓에 JOIN을 1초마다 다시 보냅니다.
   - min(connectionTimeout, 10초) 안에 응답이 없으면 그 시도를 실패로 보고 backoff로 재시도합니다.

4. [인증 시] EnterInfo 패킷 (CMD_ENTER_INFO=0012):
   - JOIN 응답(JOIN_CHANNEL)을 받을 때마다 WebSocketManager가 수신 스레드에서 그 userFlag(synAck)로 만들어 송신 체인에 넣음. 응답의 chatNo가 이 연결의 CHATNO와 같고 synAck가 비어 있지 않을 때만 보냄
   - 준비 게이트를 열고 dispatcher에 넘기기 전에 넣으므로, ready()나 JOIN_CHANNEL 리스너에서 보낸 메시지보다 항상 먼저 나감
   - F + synAck + F + "0" + F

### 송신 패킷

- CHAT (0005): F + message + F×6
- DIRECT_CHAT (0009): F + message + F + targetId + F (targetId = 받는 사람 로그인 ID)
- 사용자 필드 검증: null, U+000C(서버가 뒤를 다른 필드로 읽음), U+001B(패킷 헤더 시작), 짝 없는 surrogate(UTF-8 길이와 실제 바이트 수가 어긋남)는 IllegalArgumentException
- payload가 999,999바이트를 넘으면 IllegalArgumentException(길이 필드로 표현 불가)

### Ping 메커니즘

- 연결이 수립되면 pingIntervalSeconds(기본 60초) 간격으로 CMD_PING 패킷을 송신 체인에 넣습니다(스케줄러 스레드는 블로킹하지 않음).
- 실측(150초 관찰)에서 서버는 이 핑에 응답(KEEP_ALIVE)하지 않았습니다. 그래서 핑은 송신 실패를 감지하는 용도로만 쓰고, 수신이 멈춘 것을 감지하는 inbound watchdog은 두지 않습니다(조용한 방송을 끊김으로 오판하지 않도록).
- 핑 송신이 실패하거나 connectionTimeout을 넘기면 전송 장애로 보고 backoff 재연결합니다.

## 디코더 시스템

### IMessageDecoder 인터페이스

```java
@FunctionalInterface
public interface IMessageDecoder {
    BaseEvent decode(String[] parts, String raw);
}
```

### DefaultMessageDecoderFactory

파일: decoder/factory/DefaultMessageDecoderFactory.java

디코더 92개(서비스 코드가 있는 서버 이벤트마다 하나)를 Map.ofEntries()로 등록한 static final 맵을 createDecoders()로 돌려줍니다. SOOPConnection은 이를 static SHARED_DECODERS로 받아 모든 연결에서 공유합니다.
NONE_TYPE에는 디코더를 두지 않습니다. 모르는 서비스 코드의 패킷은 MessageDispatcher가 원래 코드를 담은 UnknownEvent로 전달합니다.
디코더 구현 클래스는 91개입니다(ChocolateDecoder는 CHOCOLATE·CHOCOLATE_SUB 겸용).

### 디코더 구현 패턴 (ChatMessageDecoder 예시)

```java
public class ChatMessageDecoder implements IMessageDecoder {
    private static final int MIN_PARTS = 8;

    @Override
    public BaseEvent decode(String[] parts, String raw) {
        if (parts.length < MIN_PARTS) {
            return null;  // 필드 부족 시 무시
        }
        return new ChatMessageEvent(
                parts[0],                              // message
                parts[1],                              // senderId
                SOOPChatUtils.safeParseInt(parts[3], 0), // type
                SOOPChatUtils.safeParseInt(parts[4], 0), // chatLang
                parts[5],                              // senderNickname
                parts[6],                              // senderFlag
                parts[7],                              // subscriptionMonth
                parts.length > 8 ? parts[8] : "",      // randomNicknameColor (선택)
                parts.length > 9 ? parts[9] : "",      // randomNicknameColorDarkmode (선택)
                ChatEvent.CHAT_MESSAGE,
                raw,
                System.currentTimeMillis());
    }
}
```

규칙:
1. MIN_PARTS로 최소 필드 수 검증, 부족하면 null 반환(예외를 던지지 않음)
2. parts[] 인덱스로 필드 매핑
3. SOOPChatUtils.safeParseInt()로 안전한 정수 파싱
4. 선택적 필드: parts.length > N ? parts[N] : ""
5. 공통 3개 필드 항상 포함: ChatEvent, raw, timestamp. eventType()은 팩토리에 등록한 키와 같아야 함

### 특수 디코더

- ChocolateDecoder: 생성자로 태그(ChatEvent)를 받습니다. 기본 생성자는 CHOCOLATE, 팩토리는 CHOCOLATE_SUB에 `new ChocolateDecoder(ChatEvent.CHOCOLATE_SUB)`를 등록하므로 CHOCOLATE_SUB 이벤트의 eventType()은 CHOCOLATE_SUB입니다.
- JsonPayloadDecoder(package-private 추상 클래스): MissionDecoder·MissionSettleDecoder·AdInBroadJsonDecoder의 공통 베이스. parts[0]을 GsonUtil.fromJson()으로 파싱해 create(data, raw)에 넘기며, 필드가 없거나 JSON null이거나 파싱에 실패하면 null(파싱 실패는 payload 앞 200자와 함께 FINE 로그).
- OGQEmoticonDecoder: 필드가 6개 미만이면 버림. 선택 필드(color·chatLang·type)는 각각 따로 읽으므로 뒤쪽 필드가 빠져도 앞 필드는 유지됩니다.
- StationAdconDecoder: 필드가 7개 미만이면 버림.
- BanWordDecoder: 두 번째 필드를 ","로 나누고 빈 토큰은 버림(공백은 trim하지 않음). 결과는 List<String>(수정 불가), 필드가 없거나 비어 있으면 빈 리스트.

### MessageDispatcher 처리 흐름

파일: decoder/MessageDispatcher.java

1. null/빈 메시지, 비활성(deactivate()된) 디스패처면 무시
2. 생성 시 받은 Executor(클라이언트 lane)에 제출. 실행 시점에 다시 활성 여부 확인 — deactivate()는 닫힌 연결의 대기 중·이후 패킷을 모두 버림
3. lane에서 실행:
   a. RAW 리스너 확인 → 있으면 RawEvent 발행 (없으면 할당 스킵)
   b. F_CHAR로 첫 구분자 인덱스 찾기 → 없으면 반환
   c. parseServiceCode(message, 0, firstSep)로 헤더를 복사하지 않고 코드 파싱 → 음수(헤더 불량)면 FINE 로그 후 버림
   d. ChatEvent.fromCode()로 이벤트를 찾고 디코더 맵에서 디코더 조회. 모르는 코드이거나 디코더가 없으면 NONE_TYPE으로 보냄(커스텀 맵에서 디코더가 빠진 알려진 코드도 NONE_TYPE이므로, 그 이벤트의 타입 지정 리스너가 UnknownEvent를 받지 않음)
   e. hasListeners(chatEvent)가 false면 조기 반환 (분할·디코딩 스킵)
   f. 디코더가 있으면 splitFields(message, firstSep + 1) → decoder.decode(parts, raw)
      - 없으면 UnknownEvent(code = 헤더에서 읽은 원래 서비스 코드, originalMessage = raw = 패킷 전체, eventType = NONE_TYPE) 생성
   g. 결과가 null이면 FINE 로그 후 버림
   h. eventEmitter.emit(chatEvent, event)
   i. 처리 중 예외는 WARNING 로그 후 다음 패킷으로

## 전체 이벤트 목록

서비스 코드 0~128의 서버 이벤트 92개와 클라이언트가 만드는 특수 이벤트 5개, 합계 97개입니다(ChatEvent 상수 수와 같음).

### 기본 연결 (0~2)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 0 | KEEP_ALIVE | 핑퐁 |
| 1 | LOGIN | 로그인 핸드셰이크 |
| 2 | JOIN_CHANNEL | 채널 입장 핸드셰이크 |

### 채팅 / 사용자 (3~9)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 3 | QUIT_CHANNEL | 채널 퇴장 |
| 4 | CHAT_USER | 사용자 입퇴장 |
| 5 | CHAT_MESSAGE | 채팅 메시지 |
| 6 | SET_CHANNEL_NAME | 채널 이름 설정 |
| 7 | SET_BJ_STAT | BJ 상태 설정 |
| 8 | SET_DUMB | 채금 |
| 9 | DIRECT_CHAT | 귓속말 |

### 공지 / 관리 (10~17)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 10 | NOTICE | 공지 |
| 11 | KICK | 강제 퇴장 |
| 12 | SET_USER_FLAG | 사용자 플래그 설정 |
| 13 | SET_SUB_BJ | 서브 BJ 설정 |
| 14 | SET_NICKNAME | 닉네임 설정 |
| 15 | SERVER_STAT | 서버 상태 |
| 16 | NULL_16 | 미사용 |
| 17 | CLUB_COLOR | 클럽 색상 |

### 후원 / 별풍선 (18~22)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 18 | SEND_BALLOON | 별풍선 후원 |
| 19 | ICE_MODE | 아이스 모드 |
| 20 | SEND_FAN_LETTER | 팬레터 전송 |
| 21 | ICE_MODE_EX | 확장 아이스 모드 |
| 22 | GET_ICE_MODE_RELAY | 아이스 모드 릴레이 |

### 채팅 제어 (23~27)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 23 | SLOW_MODE | 슬로우 모드 |
| 24 | RELOAD_BURN_LEVEL | 번 레벨 리로드 |
| 25 | BLIND_KICK | 블라인드 킥 |
| 26 | MANAGER_CHAT | 매니저 채팅 |
| 27 | APPEND_DATA | 데이터 추가 |

### 이벤트 / 아이템 (28~48)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 28 | BASEBALL_EVENT | 야구 이벤트 |
| 29 | PAID_ITEM | 유료 아이템 |
| 30 | TOP_FAN | 열혈 팬 |
| 31 | SNS_MESSAGE | SNS 메시지 |
| 32 | SNS_MODE | SNS 모드 |
| 33 | SEND_BALLOON_SUB | 별풍선 (서브) |
| 34 | SEND_FAN_LETTER_SUB | 팬레터 (서브) |
| 35 | TOP_FAN_SUB | 열혈 팬 (서브) |
| 36 | BJ_STICKER_ITEM | BJ 스티커 아이템 |
| 37 | CHOCOLATE | 초콜릿 후원 |
| 38 | CHOCOLATE_SUB | 초콜릿 (서브) |
| 39 | TOP_CLAN | 탑 클랜 |
| 40 | TOP_CLAN_SUB | 탑 클랜 (서브) |
| 41 | SUPER_CHAT | 슈퍼챗 |
| 42 | UPDATE_TICKET | 티켓 업데이트 |
| 43 | NOTI_GAME_RANKER | 게임 랭커 알림 |
| 44 | STAR_COIN | 스타 코인 |
| 45 | SEND_QUICK_VIEW | 퀵뷰 선물 |
| 46 | ITEM_STATUS | 아이템 상태 |
| 47 | ITEM_USING | 아이템 사용 중 |
| 48 | USE_QUICK_VIEW | 퀵뷰 사용 |

### 투표 / 차단 / 방송 정보 (50~58)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 50 | NOTIFY_POLL | 투표 알림 |
| 51 | CHAT_BLOCK_MODE | 채팅 차단 모드 |
| 52 | BDM_ADD_BLACK_INFO | 블랙리스트 추가 |
| 53 | SET_BROAD_INFO | 방송 정보 설정 |
| 54 | BAN_WORD | 금지어 설정 |
| 58 | SEND_ADMIN_NOTICE | 관리자 공지 |

### 프리캣 / 상품 / 프로모션 (65~75)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 65 | FREECAT_OWNER_JOIN | 프리캣 오너 입장 |
| 70 | BUY_GOODS | 상품 구매 |
| 71 | BUY_GOODS_SUB | 상품 구매 (서브) |
| 72 | SEND_PROMOTION | 프로모션 |
| 74 | NOTIFY_VR | VR 알림 |
| 75 | NOTIFY_MOBBROAD_PAUSE | 모바일 방송 일시정지 |

### 강퇴 / 관리자 (76~79)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 76 | KICK_AND_CANCEL | 강퇴 + 취소 |
| 77 | KICK_USERLIST | 강퇴 사용자 목록 |
| 78 | ADMIN_CHAT_USER | 관리자 채팅 사용자 |
| 79 | CLI_DOBAE_INFO | 스팸 정보 |

### 후원 / 애드콘 (86~87)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 86 | VOD_BALLOON | VOD 풍선 |
| 87 | ADCON_EFFECT | 애드콘 효과 |

### 구독 / 번역 (90~95)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 90 | KICK_MSG_STATE | 강퇴 메시지 상태 |
| 91 | FOLLOW_ITEM | 신규 구독 |
| 92 | ITEM_SELL_EFFECT | 아이템 판매 효과 |
| 93 | FOLLOW_ITEM_EFFECT | 연속 구독 |
| 94 | TRANSLATION_STATE | 번역 상태 |
| 95 | TRANSLATION | 번역 |

### 티켓 / 공지 / 영상 후원 (102~109)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 102 | GIFT_TICKET | 선물 티켓 |
| 103 | VOD_ADCON | VOD 애드콘 |
| 104 | BJ_NOTICE | BJ 공지 |
| 105 | VIDEO_BALLOON | 영상 후원 |
| 107 | STATION_ADCON | 스테이션 애드콘 |
| 108 | SEND_SUBSCRIPTION | 구독 선물 |
| 109 | OGQ_EMOTICON | OGQ 이모티콘 |

### 아이템 / 이모티콘 / 광고 (110~122)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 110 | EMOTICON_TICKET | 이모티콘 티켓 |
| 111 | ITEM_DROPS | 아이템 드롭 |
| 117 | VIDEO_BALLOON_LINK | 영상 풍선 링크 |
| 118 | OGQ_EMOTICON_GIFT | OGQ 이모티콘 선물 |
| 119 | AD_IN_BROAD_JSON | 방송 내 광고 JSON |
| 120 | GEM_ITEM_SEND | 보석 아이템 전송 |
| 121 | MISSION | 챌린지 미션 |
| 122 | LIVE_CAPTION | 실시간 자막 |

### 미션 / 관리자 / 사용자 확장 (125~128)

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| 125 | MISSION_SETTLE | 미션 정산 |
| 126 | SET_ADMIN_FLAG | 관리자 플래그 설정 |
| 127 | CHUSER_EXTEND | 구독자 목록 |
| 128 | ADMIN_CHUSER_EXTEND | 관리자 채팅 사용자 확장 |

### 특수 이벤트

| 코드 | 이벤트 | 설명 |
|------|--------|------|
| -2 | RAW | 모든 원시 패킷 |
| -3 | DISCONNECTED | 세션 종료 (세션마다 한 번) |
| -4 | RECONNECTING | 재연결 시도 예약 |
| -5 | RECONNECTED | 재연결 완료 |
| -1 | NONE_TYPE | 알 수 없는 서비스 코드 (UnknownEvent, code()에 원래 코드) |

## 이벤트 Record 필드 상세

모든 Record의 공통 필드: ChatEvent eventType, String raw, long timestamp
아래 필드 목록에서는 공통 필드를 생략하고 이벤트 고유 필드만 표기합니다. "접근자"는 원시 필드를 호출 시점에 해석하는 메서드입니다.
List·Map 컴포넌트(JSON Map payload 제외)는 수정할 수 없는 복사본이며, null을 넘기면 빈 목록·맵이 되고 null 요소는 거부됩니다(§ 이벤트 시스템).

### ChatBaseEvent (채팅)

CHAT_MESSAGE (5) — ChatMessageEvent
  String message, String senderId, int type, int chatLang, String senderNickname, String senderFlag, String subscriptionMonth, String randomNicknameColor, String randomNicknameColorDarkmode
  접근자: senderLevel() -> UserLevel

DIRECT_CHAT (9) — DirectChatEvent
  String message, String senderId, String receiverId, int type, String senderNickname, String receiverNickname, String flag

MANAGER_CHAT (26) — ManagerChatEvent
  String message, String senderId, int isAdmin, int chatLang, String senderNickname, String senderFlag, String subscriptionMonth
  접근자: senderLevel() -> UserLevel

SNS_MESSAGE (31) — SnsMessageEvent
  String message

SUPER_CHAT (41) — SuperChatEvent
  (공통 필드만)

### DonationBaseEvent (후원)

SEND_BALLOON (18) — SendBalloonEvent
  String bjId, String senderId, String senderNickname, int count, int fanOrder, String fileName, boolean isDefault, int isTopFan, String ttsData

SEND_BALLOON_SUB (33) — SendBalloonSubEvent
  String bjId, String senderId, String senderNickname, int count, int fanOrder, String fileName, boolean isDefault, int isTopFan

SEND_FAN_LETTER (20) — SendFanLetterEvent
  String bjId, String bjNickname, String senderId, String senderNickname, int type, int count, String supporterOrder

SEND_FAN_LETTER_SUB (34) — SendFanLetterSubEvent
  String bjId, String bjNickname, String senderId, String senderNickname, int type, int count, String supporterOrder

CHOCOLATE (37) — ChocolateEvent
  String bjId, String senderId, String senderNickname, int count

CHOCOLATE_SUB (38) — ChocolateEvent (eventType()은 CHOCOLATE_SUB)
  String bjId, String senderId, String senderNickname, int count

SEND_SUBSCRIPTION (108) — SendSubscriptionEvent
  String senderId, String senderNickname, String receiverId, String receiverNickname, String subscriptionId, String subscriptionNickname, int itemType, String itemCode, int isSubscription, String subscriptionType, String subscriptionPeriod, int subscriptionRemain, int subscriptionPaycount

VIDEO_BALLOON (105) — VideoBalloonEvent
  String chatNo, String bjId, String userId, String userNickname, int balloonCount, int fanOrder, int isTopFan, String relay, String fileName, boolean isDefault, String extraData

VOD_BALLOON (86) — VodBalloonEvent
  String bjId, String senderId, String senderNickname, int balloonCount

ADCON_EFFECT (87) — AdconEffectEvent
  int chatNo, String bjId, String senderId, String senderNickname, String message, String message2, String title, String urlImg, String urlDefault, int adconCount, int fanOrder, int isTopFan, int isFanChief, int isSubRoom

STATION_ADCON (107) — StationAdconEvent
  String bjId, String userId, String userNickName, int adconCount, String isDefault, String adconMsg, String chatNumber
  (필드가 7개 미만인 패킷은 버림)

GIFT_TICKET (102) — GiftTicketEvent
  String senderId, String senderNickname, String receiverId, String receiverNickname, String ticketData

OGQ_EMOTICON_GIFT (118) — GiftOGQEmoticonEvent
  String senderId, String senderNick, String receivedId, String receivedNick, String ogqTitle, String ogqImageUrl

GEM_ITEM_SEND (120) — GemItemSendEvent
  String receiverId, String receiverNick, String itemName

STAR_COIN (44) — StarCoinEvent
  (공통 필드만)

SEND_PROMOTION (72) — SendPromotionEvent
  (공통 필드만)

TOP_FAN (30) — TopFanEvent
  (공통 필드만)

TOP_FAN_SUB (35) — TopFanSubEvent
  (공통 필드만)

TOP_CLAN (39) — TopClanEvent
  (공통 필드만)

TOP_CLAN_SUB (40) — TopClanSubEvent
  (공통 필드만)

VIDEO_BALLOON_LINK (117) — VideoBalloonLinkEvent
  (공통 필드만)

VOD_ADCON (103) — VodAdconEvent
  (공통 필드만)

### SystemBaseEvent (시스템)

KEEP_ALIVE (0) — KeepAliveEvent
  (공통 필드만)

LOGIN (1) — LoginEvent
  String userId, String userFlag
  접근자: userLevel() -> UserLevel

JOIN_CHANNEL (2) — JoinChannelEvent
  String chatNo, String bjId, int maxSubBjCount, String familyNickname, String userFlag
  접근자: userLevel() -> UserLevel (인증 연결에서는 userFlag가 ENTER_INFO의 synAck로도 쓰임)

QUIT_CHANNEL (3) — QuitChannelEvent
  int quitType, int adminKickCount, String nickname, String bannedRoomBjId, String bannedRoomBjNickname
  접근자: quitStatus() -> ChatQuitStatus

CHAT_USER (4) — ChatUserEvent
  int type, List<ChatUserEntry> userList (수정 불가)
  ChatUserEntry(String id, String nickname, String flag), 접근자: level() -> UserLevel

SET_CHANNEL_NAME (6) — SetChannelNameEvent
  String channelName

SET_BJ_STAT (7) — SetBjStatEvent
  (공통 필드만)

ICE_MODE (19) — IceModeEvent
  int iceMode
  접근자: iceType(), iceFlags(), isIceFlagMode()

ICE_MODE_EX (21) — IceModeExEvent
  int iceMode, int freezeType, int balloonLimitCount, int subscriptionLimitCount
  접근자: iceType(), iceFlags(), isIceFlagMode(), freezeFlags()

GET_ICE_MODE_RELAY (22) — GetIceModeRelayEvent
  int iceMode, int freezeType
  접근자: iceType(), iceFlags(), isIceFlagMode(), freezeFlags()

SET_USER_FLAG (12) — SetUserFlagEvent
  String oldFlag, String userId, String userNickname, String newFlag
  접근자: oldLevel(), newLevel() -> UserLevel

SET_SUB_BJ (13) — SetSubBjEvent
  String userId, String flag, int hide, String nickname
  접근자: level() -> UserLevel

SET_NICKNAME (14) — SetNicknameEvent
  String userId, String newNickname, int changeType, String flag, String oldNickname
  접근자: level() -> UserLevel

SERVER_STAT (15) — ServerStatEvent
  String serverStat

NULL_16 (16) — Null16Event
  (공통 필드만)

CLUB_COLOR (17) — ClubColorEvent
  (공통 필드만)

APPEND_DATA (27) — AppendDataEvent
  String appendData

FREECAT_OWNER_JOIN (65) — FreecatOwnerJoinEvent
  String chatNo, String bjId, int maxSubBjCount, String familyNickname, String userFlag

SNS_MODE (32) — SnsModeEvent
  int snsMode

RELOAD_BURN_LEVEL (24) — ReloadBurnLevelEvent
  int burnLevel

EMOTICON_TICKET (110) — EmoticonTicketEvent
  int value

CHAT_BLOCK_MODE (51) — ChatBlockModeEvent
  (공통 필드만)

SET_BROAD_INFO (53) — SetBroadInfoEvent
  (공통 필드만)

BDM_ADD_BLACK_INFO (52) — BdmAddBlackInfoEvent
  (공통 필드만)

NOTIFY_MOBBROAD_PAUSE (75) — NotifyMobBroadPauseEvent
  int status

NOTIFY_VR (74) — NotifyVrEvent
  int action, String bjId, String vrId, String rtmp, String hls, int vrType

NOTI_GAME_RANKER (43) — NotiGameRankerEvent
  (공통 필드만)

CHUSER_EXTEND (127) — ChuserExtendEvent
  Map<String, Map<String, Integer>> userStatus (사용자 ID → "key=value&…" 필드를 정수로 읽은 맵. 바깥·안쪽 맵 모두 수정 불가)

DISCONNECTED (-3) — DisconnectedEvent
  int statusCode, String reason, boolean causedByError
  - statusCode: WebSocket 종료 코드. 오류로 끝났으면 -1, disconnect()/close()면 1000
  - causedByError: 연결 실패나 재시도 소진으로 끝났으면 true
  - 접근자: isClientInitiated() — `!causedByError && CLIENT_DISCONNECT_REASON.equals(reason)`
  - 상수: DisconnectedEvent.CLIENT_DISCONNECT_REASON = "Client disconnect"

RECONNECTING (-4) — ReconnectingEvent
  int attemptNumber, int maxAttempts, long delayMs

RECONNECTED (-5) — ReconnectedEvent
  int totalAttempts

RAW (-2) — RawEvent
  (공통 필드만, raw에 원시 패킷 전체 포함)

### ModerationBaseEvent (관리)

SET_DUMB (8) — SetDumbEvent
  String userId, String userInfo, int dumbTime, int dumbCount, String adminId, int adminType, String extraInfo, String userNickname

KICK (11) — KickEvent
  String userId, String userNickname, int kickType, String reason, String kickerNickname

BLIND_KICK (25) — BlindKickEvent
  String userId, String userNickname, int blindTime

BAN_WORD (54) — BanWordEvent
  String replaceWord, List<String> banWordList (빈 토큰 제외, 수정 불가. v0.14.0까지는 String[])

SEND_ADMIN_NOTICE (58) — SendAdminNoticeEvent
  String message

KICK_AND_CANCEL (76) — KickAndCancelEvent
  int status, String userId, String userNickname

KICK_USERLIST (77) — KickUserListEvent
  List<KickedUser> kickedUsers (수정 불가)
  KickedUser(String userId, String userNickname, String time, String orderUserId, String orderUserNickname, String orderUserFlag)

ADMIN_CHAT_USER (78) — AdminChatUserEvent
  String type, List<AdminChatUserEntry> users (수정 불가)
  AdminChatUserEntry(String id, String nickname, String flag), 접근자: level() -> UserLevel

CLI_DOBAE_INFO (79) — CliDobaeInfoEvent
  int dobaeInfo, String userId

KICK_MSG_STATE (90) — KickMsgStateEvent
  String chatNo, boolean isHideKickMessage

SET_ADMIN_FLAG (126) — SetAdminFlagEvent
  String flag
  접근자: level() -> UserLevel

ADMIN_CHUSER_EXTEND (128) — AdminChuserExtendEvent
  (공통 필드만)

### ItemBaseEvent (아이템)

OGQ_EMOTICON (109) — OGQEmoticonEvent
  String chatNo, String message, String groupId, String subId, String version, String userInfo, String color, String chatLang, String type
  접근자: senderId() (= userInfo, 발신자 ID), senderNickname() (= color, 발신자 닉네임). userInfo·color는 초기 구현의 이름이 남은 컴포넌트이므로 새 코드는 별칭을 씁니다.
  (필드가 6개 미만인 패킷은 버림. color·chatLang·type은 없으면 "")

SEND_QUICK_VIEW (45) — QuickViewEvent
  String senderId, String senderNickname, String receiverId, String receiverNickname, int itemType

BUY_GOODS (70) — BuyGoodsEvent
  int goodsType, String bjId, String buyerId, String buyerNickname, String goodsName, int goodsCount, int relay

BUY_GOODS_SUB (71) — BuyGoodsSubEvent
  int goodsType, String bjId, String buyerId, String buyerNickname, String goodsName, int goodsCount, int relay

PAID_ITEM (29) — PaidItemEvent
  int itemType, String bjId, String buyerId, String buyerNickname, String itemName, int itemCount

ITEM_DROPS (111) — ItemDropsEvent
  String bjId, String dropsName, String dropsMsg, String dropsImgUrl

ITEM_USING (47) — ItemUsingEvent
  String bjId, int itemType, int remainTime

FOLLOW_ITEM (91) — FollowItemEvent
  int chatNo, String recvId, String sendId, String sendNick, int type

FOLLOW_ITEM_EFFECT (93) — FollowItemEffectEvent
  String bjId, String sendId, String sendNick, int month, int chatNo

MISSION (121) — MissionEvent
  Map<String, Object> data

MISSION_SETTLE (125) — MissionSettleEvent
  Map<String, Object> data

AD_IN_BROAD_JSON (119) — AdInBroadJsonEvent
  Map<String, Object> data

BJ_STICKER_ITEM (36) — BjStickerItemEvent
  int type

BASEBALL_EVENT (28) — BaseballEventEvent
  String eventData

ITEM_STATUS (46) — ItemStatusEvent
  (공통 필드만)

ITEM_SELL_EFFECT (92) — ItemSellEffectEvent
  (공통 필드만)

UPDATE_TICKET (42) — UpdateTicketEvent
  (공통 필드만)

USE_QUICK_VIEW (48) — UseQuickViewEvent
  (공통 필드만)

### NotificationBaseEvent (알림)

NOTICE (10) — NoticeEvent
  String message

BJ_NOTICE (104) — BjNoticeEvent
  int show, String message

LIVE_CAPTION (122) — LiveCaptionEvent
  String caption

SLOW_MODE (23) — SlowModeEvent
  int autotime, int manualtime

NOTIFY_POLL (50) — NotifyPollEvent
  int status, String bjId, int no, int show

TRANSLATION (95) — TranslationEvent
  int idx, int mode, String message, int orgLanguage, int transLanguage

TRANSLATION_STATE (94) — TranslationStateEvent
  int state

### UnknownEvent

(eventType NONE_TYPE) — UnknownEvent
  int code, String originalMessage
  등록된 디코더가 없는 서비스 코드의 패킷에 MessageDispatcher가 만들어 NONE_TYPE 리스너에 전달합니다. 기본 팩토리는 서버 이벤트 92개에만 디코더를 등록하므로, ChatEvent.fromCode()가 모르는 코드의 패킷은 모두 이 이벤트가 됩니다.
  - code: 패킷 헤더에서 읽은 원래 서비스 코드
  - originalMessage: 수신한 패킷 전체(raw()와 같은 값)
  - eventType: 항상 NONE_TYPE
  - SystemBaseEvent가 아니라 BaseEvent를 직접 구현합니다. NONE_TYPE 리스너는 UnknownEvent나 BaseEvent로 받아야 하며, SystemBaseEvent로 받으면 캐스팅에 실패합니다.

## Fixture 검증 데이터 (30개 이벤트 합성 패킷)

`lib/src/test/java/.../decoder/SyntheticPackets.java`의 합성 패킷(이벤트 타입마다 하나, 30개)으로 디코딩을 검증한 필드 값입니다. ID·닉네임·메시지·채팅방 번호·URL은 모두 합성 placeholder이며 실방송 값이 아닙니다.

- 패킷 형식은 서버와 같습니다: ESC + 서비스 코드(4자리) + payload UTF-8 바이트 길이(6자리, 0 패딩) + "00" + payload(F로 시작하고 필드마다 F가 붙음). 필드 순서와 개수는 각 디코더가 읽는 위치를 따르고, 디코더가 읽지 않는 자리는 "0"으로 채웁니다.
- 디코더가 읽는 자리의 값은 같은 패킷의 다른 자리와 겹치지 않게 골랐고, 정수 필드는 "0"(채움 값이자 파싱 실패 시 기본값)을 피했습니다. 그래서 디코더가 위치를 잘못 읽으면 테스트가 실패합니다.
- FixtureDecoderDetailTest가 각 패킷을 MessageDispatcher로 디코딩해 모든 필드와 파생 접근자를 assertEquals로 비교하고, RawPacketFixtureTest가 헤더 형식과 RAW·기대 타입 이벤트가 하나씩 발행되는지 확인합니다. 패킷이 테스트 코드에 있으므로 두 테스트는 항상 실행됩니다(건너뛰지 않음).
- DataCollector(`./gradlew :lib:collectFixtures`, `--fixtures`)는 실방송 패킷을 `lib/src/test/resources/fixtures/*.bin`(저장소 미포함, .gitignore)에 저장하는 로컬 수집 도구일 뿐이며, 테스트는 이 파일을 읽지 않습니다. 새 패킷 형식을 확인하면 값을 합성 placeholder로 바꿔 SyntheticPackets에 옮겨 적습니다.

| 이벤트 | 합성 패킷의 필드 값 (디코딩 결과) |
|--------|------------------------------------|
| ADCON_EFFECT | chatNo=1000, bjId="bj1", senderId="user1", senderNickname="닉네임1", message="hello", message2="hello2", title="title1", urlImg="https://example.com/adcon/img1.png", urlDefault="https://example.com/adcon/default1.png", adconCount=200, fanOrder=5, isTopFan=1, isFanChief=2, isSubRoom=3 |
| BAN_WORD | 필드 "**", "금지어1,,금지어2" → replaceWord="**", banWordList=["금지어1", "금지어2"] (List<String>, 빈 토큰 제외) |
| BJ_NOTICE | show=1, message="공지1" (첫 필드와 세 번째 필드는 읽지 않음) |
| BJ_STICKER_ITEM | type=4 |
| CHAT_MESSAGE | message="hello", senderId="user1", type=5, chatLang=3, senderNickname="닉네임1", senderFlag="81952|32768" → senderLevel()=주 {FANCLUB, MOBILE, REALNAME} · 보조 {SPECIFY}, subscriptionMonth="-1", randomNicknameColor="#FF0000", randomNicknameColorDarkmode="#00FF00" |
| CHAT_USER | type=1, userList=[("viewer1", "닉네임1", "16|16384"), ("viewer2", "닉네임2", "81952|32768")] (id·nickname·flag 3필드 반복), level()=주 {GUEST} · 보조 {PC} / 주 {FANCLUB, MOBILE, REALNAME} · 보조 {SPECIFY} |
| CHUSER_EXTEND | 첫 필드는 읽지 않고 (사용자 ID, "key=value&…") 쌍 반복 → userStatus={"viewer1": {fw=1, afw=1}, "viewer2": {fw=3, afw=0}} |
| EMOTICON_TICKET | value=1 |
| FOLLOW_ITEM | chatNo=1000, recvId="bj1", sendId="user1", sendNick="닉네임1", type=111 |
| FOLLOW_ITEM_EFFECT | bjId="bj1", sendId="user1", sendNick="닉네임1", month=27, chatNo=1000 |
| ICE_MODE | iceMode=1 → iceType()=NORMAL, isIceFlagMode()=false, iceFlags()={} |
| ICE_MODE_EX | iceMode=1, freezeType=1008 → freezeFlags()={NORMAL2, FAN2, SUP2, TOP_FAN2, FOLLOWER2} (512 비트는 무시), balloonLimitCount=10, subscriptionLimitCount=3, iceType()=NORMAL |
| ITEM_DROPS | bjId="bj1", dropsName="상품1", dropsMsg="hello", dropsImgUrl="https://example.com/drops/item1.png" |
| JOIN_CHANNEL | chatNo="1000", bjId="bj1", maxSubBjCount=10, familyNickname="패밀리1", userFlag="16|16384" → userLevel()=주 {GUEST} · 보조 {PC} |
| KICK_MSG_STATE | chatNo="1000", isHideKickMessage=true ("1"이면 true) |
| LOGIN | userId="viewer1", userFlag="16|0" → userLevel()=주 {GUEST} (익명 연결이면 userId는 빈 문자열) |
| MISSION | data={type="CHALLENGE_NOTICE", mission_status="FAIL", title="미션1", key=1} |
| MISSION_SETTLE | data={chno=1000, list=[["user1", "닉네임1", 100]]} |
| OGQ_EMOTICON | chatNo="1000", message="hello", groupId="ogqgroup1", subId="3", version="1", userInfo="user1"(= senderId()), color="닉네임1"(= senderNickname()), chatLang="2", type="4" |
| OGQ_EMOTICON_GIFT | senderId="user1", senderNick="닉네임1", receivedId="bj1", receivedNick="닉네임2", ogqTitle="스티커1", ogqImageUrl="https://example.com/ogq/sticker1.png" |
| SEND_BALLOON | bjId="bj1", senderId="user1", senderNickname="닉네임1", count=100, fanOrder=2, fileName="balloon1", isDefault=true ("1"이면 true), isTopFan=3, ttsData="tts1" |
| SEND_QUICK_VIEW | senderId="user1", senderNickname="닉네임1", receiverId="viewer1", receiverNickname="닉네임2", itemType=101 |
| SEND_SUBSCRIPTION | senderId="user1", senderNickname="닉네임1", receiverId="viewer1", receiverNickname="닉네임2", subscriptionId="bj1", subscriptionNickname="닉네임3", itemType=11, itemCode="code1", isSubscription=1, subscriptionType="0", subscriptionPeriod="3", subscriptionRemain=30, subscriptionPaycount=2 |
| SET_BJ_STAT | 공통 필드만 (디코더가 필드를 읽지 않음) |
| SET_DUMB | userId="user1", userInfo="info1", dumbTime=30(초), dumbCount=1, adminId="bj1", adminType=2, extraInfo="extra1", userNickname="닉네임1" |
| SET_NICKNAME | userId="user1", newNickname="닉네임2", changeType=1, flag="65536|16384" → level()=주 {REALNAME} · 보조 {PC}, oldNickname="닉네임1" |
| SET_SUB_BJ | userId="user1", flag="4|16384" → level()=주 {BJ} · 보조 {PC}, hide=1, nickname="닉네임1" |
| SET_USER_FLAG | oldFlag="16|16384" → newFlag="48|16384", userId="user1", userNickname="닉네임1", oldLevel()=주 {GUEST} · 보조 {PC}, newLevel()=주 {GUEST, FANCLUB} · 보조 {PC} |
| TRANSLATION_STATE | state=1 |
| VIDEO_BALLOON | chatNo="1000", bjId="bj1", userId="user1", userNickname="닉네임1", balloonCount=50, fanOrder=3, isTopFan=4, relay="2", fileName="video1", isDefault=true, extraData="00112233445566778899aabbccddeeff" (32자리 16진수) |

### 코드표 및 플래그 해석

`senderFlag`, `userFlag`, `flag` 등은 "주|보조" 형식의 문자열로 전달되며, 파이프(`|`)로 구분된 두 정수는 서로 다른 비트 의미를 가집니다.

`com.github.getcurrentthread.soopapi.code` 패키지가 이 원시 값들을 타입으로 디코딩합니다. 원시 필드(String/int)는 그대로 유지하고, 이벤트 Record에 추가된 접근자가 **호출 시점에 지연 파싱**합니다(디코딩 경로 불변).

- `UserLevel.parse(flag)` → `UserLevel(Set<UserFlag> primary, Set<UserFlag2> secondary)`.
  - 두 집합은 생성 시 EnumSet으로 복사한 **수정 불가** 집합입니다(선언 순서 유지, 수정하면 UnsupportedOperationException).
  - 파싱 규칙: null/빈 문자열 → `UserLevel.EMPTY`, `|`가 없으면 전체를 주 그룹으로, 각 그룹은 부호 있는 표기(`"-2147483648"`)와 부호 없는 32비트 표기(`"2147483648"`)를 같은 마스크로 받음, 숫자가 아니거나 32비트 범위를 벗어난 쪽은 빈 집합. 예외를 던지지 않습니다.
  - 주 그룹 `UserFlag`: ADMIN=1, HIDDEN=2, BJ=4, DUMB=8, GUEST=16, FANCLUB=32, MANAGER=256, FEMALE=512, MOBILE=16384, TOPFAN=32768, REALNAME=65536, QUICKVIEW=1<<19, FOLLOWER=1<<28, NOTIVODBALLOON=1<<30, NOTITOPFAN=1<<31 …
  - 보조 그룹 `UserFlag2`: GLOBAL_PC=1, CLAN=2, TOPCLAN=4, GAMEGOD=16, ADMINCHAT=8192, PC=16384, SPECIFY=32768, HTML5=1<<17 …
  - 두 그룹은 비트값이 겹치므로(예: 16 = GUEST(주) vs GAMEGOD(보조)) 반드시 각자의 enum으로 분해합니다. 부호 비트(NOTITOPFAN=1<<31)는 `(mask & bit) == bit`로 안전하게 처리됩니다.
  - 접근자: `ChatMessageEvent.senderLevel()`, `ManagerChatEvent.senderLevel()`, `ChatUserEntry.level()`, `AdminChatUserEntry.level()`, `LoginEvent.userLevel()`, `JoinChannelEvent.userLevel()`, `SetUserFlagEvent.oldLevel()/newLevel()`, `SetAdminFlagEvent.level()`, `SetNicknameEvent.level()`, `SetSubBjEvent.level()`.
- 아이스(채팅 제한) 모드: `ChatIceType.fromCode(int)`(레거시 0~4: CLEAR/NORMAL/FAN/SUP/FAN_SUP) + `ChatIceType.isFlagMode(int)`(16 이상이면 v2) + `ChatIceType.Flag.fromMask(int)`(v2 비트: NORMAL2=16, FAN2=32, SUP2=64, TOP_FAN2=128, FOLLOWER2=256).
  - `Flag.fromMask()`는 CLEAR2(0)를 결과에서 빼고, 상수에 매핑되지 않은 비트는 조용히 무시합니다(예: `fromMask(1008)` = 16|32|64|128|256|512 → 512를 뺀 다섯 플래그).
  - 접근자: `IceModeEvent`/`IceModeExEvent`/`GetIceModeRelayEvent` 의 `iceType()`, `iceFlags()`, `isIceFlagMode()`.
  - `IceModeExEvent.freezeFlags()`, `GetIceModeRelayEvent.freezeFlags()`: `freezeType`을 v2 플래그로 분해합니다. 관측된 패킷에서 `iceMode`는 0/1 켜짐 값으로 오고 그룹 비트마스크는 `freezeType`에 실려 오므로(예: iceMode=1, freezeType=1008), 그룹 정보가 필요하면 이 메서드를 씁니다.
- 채널 퇴장 사유: `ChatQuitStatus.fromCode(int)` (0=CLOSED, 1=NORMAL, 2=KCIK, 3=DUMB, 4=OVERCHAT, 5=BLIND, 6=ADMKICK). 접근자: `QuitChannelEvent.quitStatus()`.

알 수 없는 코드는 센티넬(`UNKNOWN` / `UserLevel.EMPTY`)을 반환하며 예외를 던지지 않습니다.

### JSON 이벤트 (Map<String, Object>)

MISSION, MISSION_SETTLE, AD_IN_BROAD_JSON 이벤트는 `data` 필드에 JSON 파싱 결과를 담습니다. 세 디코더는 공통 베이스 JsonPayloadDecoder를 씁니다.

- `GsonUtil.fromJson(String)` 변환 규칙: 정수는 크기에 따라 `Integer` → `Long` → `BigInteger`(long 범위를 넘으면 정밀도 손실 없이 보존), 소수·지수 표기는 `Double`, 객체는 `LinkedHashMap`, 배열은 `List`
- 입력이 null이거나 JSON `null`이면 null 반환, 형식이 잘못됐거나 루트가 객체가 아니면(배열·원시값) `JsonParseException`
- 디코더는 null·파싱 실패를 이벤트 없이 버리고, 파싱 실패는 FINE 레벨로 기록합니다.

## 이벤트 시스템 내부

### EventEmitter 구현

파일: event/EventEmitter.java

- listeners: ConcurrentHashMap<ChatEvent, CopyOnWriteArrayList> — 사용자 리스너 (on/once)
- internalListeners: 같은 구조 — onInternal()/clearInternal()로 관리하는 내부용 목록. 현재 라이브러리 코드는 쓰지 않습니다(ENTER_INFO는 WebSocketManager가 JOIN 응답을 받은 수신 스레드에서 처리).
- emit() 순서: internalListeners 먼저, 그 다음 listeners. emit은 호출 스레드에서 그대로 실행되며, 라이브러리는 모든 emit을 클라이언트 lane에서 호출하므로 한 클라이언트의 리스너는 동시에 실행되지 않습니다.
- 에러 처리: 리스너 예외 catch → WARNING 로그 → errorHandler(EventEmitterException) 호출 → errorHandler 자체 예외도 catch(SEVERE 로그). 다른 리스너와 이후 이벤트 전달은 계속됩니다.
- hasListeners(event): 사용자·내부 목록 중 하나라도 비어 있지 않으면 true
- clear()/clear(event): 사용자 리스너만 제거

### once() 구현

- once(event, listener)는 등록마다 OnceListener(event, delegate, AtomicBoolean fired)로 감싸 listeners에 추가합니다.
- 호출되면 fired.compareAndSet(false, true)에 성공한 호출만 자신을 목록에서 제거한 뒤 원본을 실행합니다. 그래서 여러 스레드에서 동시에 emit되어도 최대 한 번만 호출됩니다.
- 같은 리스너를 여러 번(또는 여러 이벤트에) once() 등록하면 등록마다 독립적으로 동작합니다.
- off(event, listener)는 먼저 그 리스너 자체를 제거하고, 없으면 delegate가 그 리스너인 첫 OnceListener 하나를 제거합니다(호출 한 번에 등록 하나).
- 별도의 원본↔래퍼 맵은 없습니다. 이벤트가 오지 않으면 등록이 남으므로 필요하면 off()나 clear(event)로 정리합니다.

### Sealed Event 계층 상세

```java
public sealed interface BaseEvent
        permits ChatBaseEvent, DonationBaseEvent, SystemBaseEvent,
                ModerationBaseEvent, ItemBaseEvent, NotificationBaseEvent,
                UnknownEvent {
    ChatEvent eventType();
    String raw();
    long timestamp();
}
```

각 서브타입은 non-sealed 인터페이스로, 여러 Record가 implements 가능.

## 테스트

기본 빌드(`./gradlew :lib:build`, `./gradlew :lib:test`)는 네트워크를 쓰지 않는 테스트만 실행합니다. 연결 수명주기는 Mockito 없이 직접 만든 가짜 객체로 검증합니다. 디코더 테스트의 패킷은 테스트 코드 안의 합성 패킷(decoder/SyntheticPackets)이므로 수집한 fixture 파일 없이도 모두 실행되며, 기본 실행에서 건너뛰는 테스트는 없습니다.

### 테스트 클래스 (35개)

| 테스트 | 대상 | 유형 |
|--------|------|------|
| SOOPClientMultiConnectionTest | SOOPClient 다중 스트림: dedup, 글로벌 리스너 attach/detach, reconnect, 재시도 한도 전달, remove/close 뒤 재연결 차단 | 컴포넌트 |
| api/JsonFieldsTest | JSON 필드 null-safe 헬퍼, 객체가 아닌 본문은 본문 없이 실패(parseObject) | 단위 |
| api/SOOPAuthTest | 로그인 응답의 JSON null RESULT/REASON 처리, 파싱할 수 없는 Set-Cookie 값·응답 본문·비밀번호가 로그와 예외에 남지 않음 | 단위 |
| api/SOOPChannelTest | 방송국 중첩 JSON 파싱, station 누락 시 실패 | 단위 |
| api/SOOPLiveTest | CHDOMAIN 소문자화(기본 Locale 무관), RESULT -6→AdultBroadcastException(익명·인증·미인증 쿠키별 메시지), REASON 없는 실패의 RESULT 코드 표기, confirm_adult는 익명·미인증·인증 쿠키 모두 false(true를 보내면 실패), 로그인 Cookie 헤더는 인증 쿠키일 때만, 파싱할 수 없는 응답의 FTK·쿠키 값이 로그와 예외에 남지 않음 | 단위 |
| api/model/AuthCookieTest | toString() 자격 증명 마스킹 | 단위 |
| api/model/LiveDetailTest | toString() FTK 마스킹 | 단위 |
| client/SOOPChatClientConcurrencyTest | 동시 connectToChat()이 같은 future 반환 | 컴포넌트 |
| client/SOOPChatClientRealConnectionTest | 인기 방송 상위 10개(19금 제외)에 실제 접속해 모니터링, 입장한 스트림과 forceReconnect 뒤의 ready() 완료. 익명 조회가 실제로 19금으로 막히는 방송 하나에 익명 연결해 AdultBroadcastException·DISCONNECTED 1회·재시도 없음 확인(없으면 skipped). SOOP_TEST_ID·SOOP_TEST_PW(연령 인증된 테스트 계정)가 있으면 익명 조회가 19금으로 막히는 방송 하나를 로그인 쿠키로 detail() 조회하고 채팅에 연결해 ready() 완료·JOIN_CHANNEL·userId가 있는 LOGIN·RECONNECTING 0·disconnect() 뒤 DISCONNECTED 1회(클라이언트가 끊음) 확인, 채팅은 보내지 않고 로그 파일에 비밀번호·쿠키·FTK가 없는지도 확인(환경 변수가 없거나 그런 방송이 없으면 skipped, 방송은 로그인 전에 찾음). test-logs/normal.log는 INFO 미만을 이 라이브러리 로거의 것만 남김 | 통합 (@Tag) |
| client/SOOPChatClientSessionTest | 세션 수명주기: DISCONNECTED 한 번, forceReconnect, 연결 중 disconnect, close 뒤 차단. ready(): 세션 없음·close 뒤 실패, lane 밖 완료, 복구·forceReconnect를 지나 대기, 세션 종료 시 실패, 리스너 안에서 대기, 반복 호출이 연결에 쌓이지 않음 | 컴포넌트 |
| client/SOOPChatClientTest | 송신 검증 순서, 생성자 검증 (실서버 연결 메서드 1개는 @Tag) | 단위 + 통합 |
| code/ChatIceTypeTest | 아이스 모드 코드·v2 비트 | 단위 |
| code/ChatQuitStatusTest | 퇴장 사유 코드 | 단위 |
| code/DerivedAccessorTest | 이벤트 Record의 지연 접근자(senderLevel, level, freezeFlags 등) | 단위 |
| code/UserFlagTest | 주 그룹 비트 | 단위 |
| code/UserFlag2Test | 보조 그룹 비트 | 단위 |
| code/UserLevelTest | "주|보조" 파싱, 부호 없는 마스크, 수정 불가 집합 | 단위 |
| config/SOOPChatConfigTest | 채팅 설정 빌더 검증(0 타임아웃 거부, deprecated 설정) | 단위 |
| config/SOOPClientConfigTest | 전역 설정 빌더 검증 | 단위 |
| connection/SOOPConnectionTest | 방송 정보 조회를 주입해 WebSocket을 열기 전에 끝나는 연결의 ready() 실패: 조회 실패, 잘못된 채널 정보, 조회 중 close. 19금 조회 실패가 connect()·ready()·terminated()와 클라이언트 세션(DISCONNECTED 1회)까지 원인을 유지하고 재시도하지 않음 | 컴포넌트 |
| decoder/factory/DefaultMessageDecoderFactoryTest | 서버 이벤트 92개의 디코더 등록(등록 키가 정확히 서버 이벤트, NONE_TYPE 없음), eventType()==등록 키, 미지 코드→UnknownEvent(원래 코드) | 단위 |
| decoder/FixtureDecoderDetailTest | 합성 패킷 30종의 모든 필드 값과 파생 접근자 | 단위 |
| decoder/MessageDispatcherTest | 라우팅, RAW, 헤더 검증, 디코더 없는 코드→NONE_TYPE만, deactivate, lane 순서 | 컴포넌트 |
| decoder/RawPacketFixtureTest | 합성 패킷의 헤더 형식(길이 필드 = payload UTF-8 바이트 수)과 dispatch 결과(RAW + 기대 타입 이벤트 하나), 이벤트 타입마다 패킷 하나 | 단위 |
| decoder/message/ChatMessageDecoderTest | 채팅 메시지 디코딩 | 단위 |
| decoder/message/DecoderBoundsValidationTest | 짧은 패킷, JSON 디코더, OGQ·StationAdcon·BanWord 경계, 목록·맵 필드의 수정 불가·복사·null→빈 값 | 단위 |
| decoder/message/DirectChatDecoderTest | 귓속말 디코딩 | 단위 |
| event/EventEmitterTest | 구독/발행/에러 핸들러 | 단위 |
| event/EventEmitterOnceOffTest | once()/off() 동작, 동시 emit | 단위 |
| model/ChannelInfoTest | toString() FTK 마스킹 | 단위 |
| util/GsonUtilTest | JSON 변환(정수 타입, BigInteger, 비객체 루트) | 단위 |
| util/SOOPChatUtilsTest | 안전 파싱, UTF-8 길이, splitFields, parseServiceCode | 단위 |
| util/SerialExecutorTest | lane 순서, 거부 시 인라인 실행, whenPendingAtMost | 단위 |
| websocket/WebSocketListenerBufferTest | 프래그먼트 조립, slice 디코딩, JOIN 응답 감지(dispatch 전), detach, 백프레셔(첫 JOIN 응답 전에는 보류하지 않음) | 단위 |
| websocket/WebSocketManagerTest | 핸드셰이크, JOIN 재전송/기한, 송신 직렬화, 끊김 정책, 재시도 소진, 준비 게이트(ready()), ENTER_INFO 순서(ready() 대기자보다 먼저, JOIN 응답마다, 익명 연결은 보내지 않음) | 컴포넌트 |
| websocket/WebSocketPacketBuilderTest | 패킷 직렬화, 사용자 입력 검증 | 단위 |

테스트 보조 클래스(테스트 아님):
- websocket/FakeWebSocket — JDK처럼 미완료 송신 중 다음 송신이 오면 IllegalStateException("Send pending")으로 실패하고, JOIN 송신이 끝나면 JOIN 응답을 돌려주며, 서버 쪽 수신·닫힘·오류를 흉내 냄(WebSocketManager의 package-private Opener로 주입)
- connection/FakeChatConnection, connection/FakeConnectionFactory — 네트워크 없는 ChatConnection과 그 팩토리(만든 연결을 기억). establish()·drop()·fail()·serverClose()로 입장·끊김·실패·서버 종료와 ready() 게이트를 흉내 냄
- decoder/SyntheticPackets — 이벤트 타입별 합성 raw 패킷 30개(서버 형식, 모든 값은 placeholder). FixtureDecoderDetailTest·RawPacketFixtureTest가 사용
- api/StubHttpResponse — API 파싱 테스트용 고정 응답(헤더는 선택)
- api/LogCapture — 한 클래스의 로거 기록을 모든 레벨로 모으는 헬퍼. 자격 증명이 로그에 남지 않는지 확인할 때 씀
- DataCollector — 실방송 패킷 수집 도구(collectFixtures 태스크). 저장한 .bin은 로컬 분석용이며 테스트는 읽지 않음

### 테스트 실행

```bash
./gradlew :lib:test                                   # 네트워크 없는 테스트만 (@Tag("integration") 제외)
./gradlew :lib:build                                  # 위 테스트 + spotlessCheck 포함 빌드 (CI와 동일)
./gradlew :lib:test -PincludeTags=integration         # 통합 테스트만 (실서버 접속)
./gradlew :lib:test -PincludeTags=integration --tests '*RealConnectionTest*'

# 19금 로그인 테스트. 연령 인증된 테스트 계정이 있어야 돌고, 없으면 skipped
export SOOP_TEST_ID=<테스트 계정 ID>
read -rs SOOP_TEST_PW && export SOOP_TEST_PW   # 비밀번호가 셸 기록에 남지 않게 입력
./gradlew :lib:test -PincludeTags=integration --rerun --tests '*RealConnectionTest.testAdultBroadcastWithAgeVerifiedLogin'
```

- testAdultBroadcastWithAgeVerifiedLogin은 SOOP_TEST_ID·SOOP_TEST_PW가 둘 다 있고 비어 있지 않을 때만 돕니다(@EnabledIfEnvironmentVariable). 하나라도 없으면 JUnit이 skipped로 보고합니다. 익명 조회가 19금으로 막히는 방송이 지금 없을 때도 로그인하지 않고 skipped입니다.
- `--rerun`을 빼지 마세요. Gradle은 환경 변수를 test 태스크의 입력으로 보지 않으므로, 같은 명령을 환경 변수 없이 한 번 돌린 뒤에는 변수를 넣어도 `:lib:test UP-TO-DATE`로 테스트를 돌리지 않고 성공으로 끝납니다.
- 이 테스트는 읽기 전용입니다. 로그인하고 19금 방송을 조회·연결할 뿐 채팅·귓말은 보내지 않습니다. 계정 ID·비밀번호·쿠키·LOGIN의 userId·채팅 본문은 로그(lib/test-logs)와 실패 메시지에 남기지 않고 개수와 참·거짓만 남기며, 끝에 로그 파일에 비밀번호·쿠키·FTK가 없는지 확인합니다.

### 테스트 규약

- JUnit 5 (Jupiter, junit-bom 5.11.4). Mockito는 쓰지 않으며 가짜 객체는 직접 작성합니다.
- @Tag("integration")로 실서버 테스트 분리. 기본 test 태스크는 제외하고, `-PincludeTags=integration`(쉼표로 여러 태그)이면 지정한 태그만 실행
- 동시성 테스트: CountDownLatch, AtomicReference, AtomicInteger, 조건 대기(await) 헬퍼

## 빌드 시스템

### Gradle 설정 (lib/build.gradle)

- 플러그인: java-library, maven-publish, spotless(8.2.1)
- group: com.github.getCurrentThread, artifactId: soopapi
- version: Gradle 속성 `version`(gradle.properties 또는 `-Pversion=...`), 없으면 `0.0.0-SNAPSHOT`
- Java 25 toolchain (settings.gradle의 foojay resolver), sources/javadoc jar 생성
- 의존성: implementation Gson(gradle/libs.versions.toml, 2.10.1). 테스트는 JUnit 5 BOM + junit-platform-launcher (Mockito 없음)
- 인코딩: UTF-8
- Spotless: Google Java Format (AOSP variant), import 순서 java, javax, jakarta, org, com, 미사용 import 제거, 후행 공백 제거, 파일 끝 개행
- 포맷 게이트: `CI` 환경 변수가 없을 때(로컬)만 JavaCompile 전에 spotlessApply 자동 실행. CI에서는 코드를 고치지 않고 check에 포함된 spotlessCheck가 위반 시 빌드를 실패시킴
- test: 기본은 `integration` 태그 제외, `-PincludeTags`로 지정 태그만 실행
- collectFixtures (JavaExec): DataCollector `--fixtures`로 실방송에서 패킷 수집. 저장한 .bin은 로컬 분석용이며 테스트는 읽지 않음

### CI (GitHub Actions)

파일: .github/workflows/ci.yml

- 트리거: develop 브랜치 push/PR만
- 권한: `permissions: contents: read`
- 환경: ubuntu-latest, Oracle JDK 25, gradle/actions/setup-gradle
- 단계: checkout → setup-java → setup-gradle → `./gradlew :lib:build`(단위 테스트 + spotlessCheck) → `./gradlew :lib:publishToMavenLocal` 검증

릴리스 워크플로(.github/workflows/release.yml)는 아래 "버전 관리"를 참조하세요.

### JitPack 배포

파일: jitpack.yml

- openjdk25 설정 (sdk로 java 25.0.2-open 설치)
- `./gradlew :lib:publishToMavenLocal -xtest -xspotlessApply -xspotlessCheck`
- git 태그(`vX.Y.Z`)로 빌드

### 주요 Gradle 명령

```bash
./gradlew build                    # 컴파일, 테스트, 패키지
./gradlew :lib:build               # 라이브러리 모듈만 (CI와 동일)
./gradlew :lib:publishToMavenLocal # 로컬 Maven 배포
./gradlew spotlessApply            # 코드 포맷팅
./gradlew spotlessCheck            # 포맷 검사 (check에 포함)
./gradlew :lib:collectFixtures     # 실방송 패킷 수집 (로컬 분석용, 테스트와 무관)
```

## 기여 가이드

### 새 이벤트 추가 절차

1. ChatEvent enum에 새 코드 추가 (필요 시)
   - 파일: event/ChatEvent.java
   - 적절한 카테고리 주석 아래에 추가

2. event/model/ 에 Record 생성
   - 적절한 BaseEvent 서브타입 implements (ChatBaseEvent, DonationBaseEvent 등)
   - 반드시 eventType(), raw(), timestamp() 필드 포함
   - 코드표 값(플래그 등)은 원시 필드로 두고 지연 접근자를 추가
   - List·Map 컴포넌트는 compact 생성자에서 List.copyOf()/Map.copyOf()로 수정할 수 없는 복사본으로 바꾸고 null은 빈 값으로(모든 리스너가 같은 객체를 받음)

3. decoder/message/ 에 IMessageDecoder 구현 클래스 생성
   - MIN_PARTS로 최소 필드 수 검증, 부족하면 null 반환(예외 금지)
   - parts[] 인덱스로 필드 매핑
   - 선택적 필드는 parts.length > N 패턴 사용
   - JSON payload면 JsonPayloadDecoder를 상속해 create(data, raw)만 구현
   - 한 클래스가 여러 코드를 처리하면 ChocolateDecoder처럼 생성자로 태그를 받아 eventType()이 등록 키와 같게

4. decoder/factory/DefaultMessageDecoderFactory 에 Map.entry() 추가
   - DefaultMessageDecoderFactoryTest가 모든 서버 이벤트의 디코더 등록, 임의 입력에서 예외가 없는지, eventType()이 등록 키와 같은지 검사

5. 테스트 작성: 디코더 단위 테스트 (짧은 패킷 경계는 DecoderBoundsValidationTest). 실제 패킷 형식을 확인했으면 값을 합성 placeholder로 바꿔 decoder/SyntheticPackets에 패킷을 추가하고 FixtureDecoderDetailTest에 필드 검증을 추가

6. 문서 갱신: 이 문서의 이벤트 목록·필드 상세와 개수(서버 이벤트 92, ChatEvent 97, 디코더 등록 92, 디코더 구현 클래스 91)

### 새 API 엔드포인트 추가

1. api/ 패키지에 메서드 추가 (SOOPAuth, SOOPLive, SOOPChannel 중)
2. api/model/ 에 response record 생성 (자격 증명이 있으면 toString()에서 가림)
3. JSON 필드는 JsonFields로 읽기(키가 없거나 JSON null이면 기본값)
4. SOOPClient에 접근자 추가 (필요 시)
5. 테스트는 StubHttpResponse로 네트워크 없이 파싱 검증

### 코드 스타일

- Google Java Format (AOSP variant) — 로컬 빌드는 컴파일 전에 spotlessApply 자동 적용, CI는 spotlessCheck로 위반 시 실패
- import 순서: java, javax, jakarta, org, com
- 불필요한 import 자동 제거
- 후행 공백 제거, 파일 끝 개행

### 브랜치 전략

- develop: 주 개발 브랜치 (PR 대상, CI 대상)
- 릴리스: develop의 끝 커밋에 `vX.Y.Z` 태그를 push하거나 release 워크플로를 수동 실행. 워크플로가 버전 갱신을 그 커밋에 amend해 develop에 push하고 태그를 만듭니다.

## 성능 고려사항

### 메모리 최적화

- SHARED_DECODERS: SOOPConnection의 static final — 모든 연결에서 디코더 인스턴스 공유
- WebSocket용 HttpClient: SSLContext당 하나를 공유 (연결마다 만들지 않음)
- WebSocketListener: 조각나지 않은 프레임은 버퍼를 거치지 않음. textBuffer 기본 16KB, 4배(64KB) 초과 시 trimToSize(), binaryBuffer도 64KB 초과 시 새로 할당
- 바이너리 프레임: 배열에 접근할 수 있는(hasArray()) 버퍼는 backing array의 slice(arrayOffset()+position())를 복사 없이 바로 디코딩
- parseServiceCode(packet, 0, firstSep): 헤더 substring 없이 4자리 서비스 코드를 할당 없이 파싱
- splitFields(): 정규식 split 대신 indexOf 루프. 필드 수를 먼저 세어 배열을 한 번만 할당
- utf8ByteLength(): 바이트 배열 할당 없이 문자열 UTF-8 길이 계산
- PING 패킷은 상수로 한 번만 생성
- IODH Holder 패턴: lazy 초기화로 불필요한 인스턴스 생성 방지 (SSLContextProvider, ConnectionManager)
- RAW 이벤트: hasListeners() 체크 후 할당 (리스너 없으면 RawEvent 생성 안 함)
- hasListeners() 조기 반환: 리스너가 없으면 필드 분할·디코딩 자체를 스킵

### 동시성

- 메시지마다 가상 스레드를 만들던 방식 대신, 클라이언트별 직렬 lane(SerialExecutor)이 ConnectionManager의 공유 가상 스레드 풀 위에서 실행됩니다. 스트림 안에서는 순서가 보장되고 스트림끼리는 병렬로 진행됩니다. drain당 256개마다 양보합니다.
- 백프레셔: 소켓의 첫 JOIN 응답 이후 lane 대기 태스크가 10,000을 넘으면 WebSocket 수신 요청을 멈추고 1,000 이하에서 재개 — 느린 리스너 때문에 메모리가 무한히 늘지 않음. 첫 JOIN 응답 전에는 멈추지 않으므로 리스너가 lane에서 ready()를 기다려도 재연결 소켓이 JOIN 응답을 읽음
- ready()·reconnect()·송신 future는 lane 밖(대개 수신 스레드)에서 완료되므로 lane에서 기다려도 교착되지 않음. 인증 연결의 ENTER_INFO도 수신 스레드에서 준비 게이트보다 먼저 송신 체인에 들어감
- 스케줄러 스레드 1개(데몬)가 JOIN 재전송·핑·backoff를 모두 처리하며, 그 안에서 블로킹하지 않음(핑도 송신 체인에 넣기만 함)
- 송신 체인: 소켓마다 CompletableFuture 체인으로 송신을 직렬화(JDK는 미완료 텍스트 송신 하나만 허용)
- WebSocketManager: ReentrantLock 안에서는 상태만 바꾸고 WebSocket 호출·future 완료(준비 게이트 포함)·lane 제출은 lock 밖에서. current 소켓과 ready는 volatile이라 isConnected()는 lock 없이 읽음
- SOOPChatClient: ReentrantLock으로 세션 상태 보호
- ConcurrentHashMap + CopyOnWriteArrayList: lock-free 이벤트 발행

## 버전 관리

현재 버전은 상단 **핵심 정보**와 `gradle.properties`의 `version` 값을 참조하세요.

- `gradle.properties`의 `version`으로 관리 (lib/build.gradle이 Gradle 속성으로 읽음, `-Pversion`으로 덮어쓰기 가능, 없으면 `0.0.0-SNAPSHOT`)
- JitPack은 git 태그(`vX.Y.Z`)로 빌드

### 버전 업데이트 절차

릴리스는 `.github/workflows/release.yml`이 자동화합니다(`v*` 태그 push 또는 `workflow_dispatch`로 버전 입력 시 트리거, dispatch는 develop을 체크아웃).

1. VERSION 결정(태그명에서 `v` 제거 또는 입력값) 후 `MAJOR.MINOR.PATCH[-suffix]` 형식 검증. dispatch인데 같은 태그가 이미 있으면 실패
2. 릴리스 커밋이 develop의 끝(origin/develop)이 아니면 실패 — 과거 커밋에 태그를 달면 amend + push가 그 뒤의 develop 커밋을 지우기 때문
3. JDK 25 설정
4. 버전 일괄 갱신: README.md·llms.txt·llms-full.txt의 JitPack `implementation` 설치 줄(`com.github.getCurrentThread:soopapi:vX.Y.Z`), gradle.properties의 `version=` 줄, llms.txt·llms-full.txt의 `- 버전:` 줄. 각 파일을 갱신한 뒤 기대한 줄이 없으면 실패
5. `./gradlew :lib:build` — 태그될 내용 그대로 빌드·테스트
6. 변경을 직전 커밋에 amend하고 태그 생성(태그 push로 시작했으면 같은 태그를 새 커밋으로 다시 담). `git push --force-with-lease=refs/heads/develop:<원래 SHA>`로 develop을 갱신(그 사이 develop이 움직였으면 거부) 후 태그 push
7. GitHub Release 생성 (릴리스 노트 자동 생성)

이 문서의 `- 버전:` 줄과 `implementation` 줄 형식은 릴리스 자동화가 그대로 찾아 바꾸므로 형식을 바꾸지 않습니다.

## 면책 조항

이는 비공식 API이며 SOOP와 제휴되거나 승인되지 않았습니다. 사용에 따른 책임은 사용자에게 있습니다.
SOOP 플랫폼의 웹소켓 통신 방식이 변경되면 동작하지 않을 수 있습니다.