llms-full.txt

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

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

## 핵심 정보

- GitHub: https://github.com/getCurrentThread/soopapi
- 버전: v0.6.1
- 라이선스: MIT
- 언어: Java 25 이상 (--enable-preview 필요)
- 빌드: 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.5.0'
}
```

### --enable-preview 설정 (필수)

이 라이브러리는 JDK 25 Preview 기능(Stable Values, Structured Concurrency)을 사용합니다.
소비자 프로젝트에서도 컴파일 및 실행 시 아래 설정이 필요합니다.

```gradle
tasks.withType(JavaCompile) {
    options.compilerArgs.addAll(['--enable-preview'])
}
test {
    jvmArgs(['--enable-preview'])
}
```

## 빠른 시작

### 통합 클라이언트 (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 {
        SOOPClient client = new SOOPClient();

        // 방송 정보 조회
        LiveDetail detail = client.live().detail("streamerId").join();
        System.out.println("방송 제목: " + detail.title());

        // 채널 정보 조회
        StationInfo station = client.channel().station("streamerId").join();
        System.out.println("스테이션: " + station.stationName());

        // 채팅 연결 (이벤트 기반)
        SOOPChatClient chat = client.chat("streamerId");

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

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

        // connectToChat().join()은 연결이 해제될 때까지 블로킹됩니다
        chat.connectToChat().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());
});

client.connectAndAwait();
```

authCookie 없이 연결하면 익명 모드로 동작합니다. 채팅 수신은 가능하지만 sendChat() 호출 시 AuthenticationException이 발생합니다.

### 인증 + 채팅 전송

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

AuthCookie cookie = client.auth().signIn("userId", "password").join();

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());
});

chat.connectToChat();
chat.sendChat("Hello!").join();
```

### 연결 상태 이벤트

```java
client.on(ChatEvent.DISCONNECTED, (DisconnectedEvent e) -> {
    System.out.println("연결 해제: code=" + e.statusCode()
            + ", reason=" + e.reason()
            + ", error=" + e.causedByError());
});

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() + "회 시도)");
});
```

### 에러 핸들링

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

## API 레퍼런스

### SOOPClient (파사드)

통합 진입점. AutoCloseable 구현.

- SOOPClient() - 기본 설정으로 생성
- SOOPClient(SOOPClientConfig config) - 커스텀 설정
- auth() -> SOOPAuth - 인증 API
- live() -> SOOPLive - 방송 정보 API
- channel() -> SOOPChannel - 채널 정보 API
- chat(String streamerId) -> SOOPChatClient - 스트리머 ID로 채팅 클라이언트 생성
- chat(SOOPChatConfig config) -> SOOPChatClient - 커스텀 설정으로 채팅 클라이언트 생성
- close() - 모든 리소스 해제

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

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

이벤트 관리:
- <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> - 비동기 연결 (연결 해제 시 완료)
- connectAndAwait() - 블로킹 연결
- disconnect() - 연결 해제
- reconnect() -> CompletableFuture<Void> - 수동 재연결
- isConnected() -> boolean
- getConnectionStatus() -> CompletableFuture<ConnectionStatus>

채팅:
- sendChat(String message) -> CompletableFuture<Void> - 채팅 전송 (인증 필요)

기타:
- getBid() -> String
- getEventEmitter() -> EventEmitter

### SOOPChatConfig.Builder (설정)

| 메서드 | 타입 | 기본값 | 설명 |
|--------|------|--------|------|
| bid(String) | String | (필수) | 방송인 ID |
| bno(String) | String | null (자동 해석) | 방송 번호 |
| authCookie(AuthCookie) | AuthCookie | null (익명 모드) | 인증 쿠키 |
| connectionTimeout(Duration) | Duration | 30초 | 연결 타임아웃 |
| maxRetryAttempts(int) | int | 5 | 최대 재시도 횟수 |
| pingIntervalSeconds(long) | long | 60 | 핑 전송 간격(초) |
| initialPacketDelayMs(long) | long | 1000 | 초기 패킷 대기(ms) |
| sslContext(SSLContext) | SSLContext | null | 커스텀 SSL 컨텍스트 |

### SOOPAuth (인증)

- signIn(String userId, String password) -> CompletableFuture<AuthCookie>

AuthCookie record 필드: userId, success, rawResponse, authTicket, abroadChk, abroadVod, bbsTicket, rdb, userTicket, au, au3rd, ausa, ausb
- isAuthenticated() -> boolean

### SOOPLive (방송 정보)

- getBno(String streamerId) -> CompletableFuture<String>
- detail(String streamerId) -> CompletableFuture<LiveDetail>
- detail(String streamerId, String bno) -> CompletableFuture<LiveDetail>
- detail(String streamerId, String bno, AuthCookie authCookie) -> CompletableFuture<LiveDetail>

LiveDetail record 필드: bjId, bno, title, chatDomain, chatNo, ftk, chatPort, result, bps, geoCC, geoRC, acptLang, svcLang

### SOOPChannel (채널 정보)

- station(String streamerId) -> CompletableFuture<StationInfo>

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

## 이벤트 시스템

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

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

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

### EventEmitter

- on(ChatEvent, EventListener) - 이벤트 구독
- once(ChatEvent, EventListener) - 일회성 구독
- off(ChatEvent, EventListener) - 구독 해제
- setErrorHandler(Consumer<EventEmitterException>) - 에러 핸들러 설정
- clear() - 모든 리스너 제거
- clear(ChatEvent) - 특정 이벤트의 리스너 제거
- hasListeners(ChatEvent) -> boolean

## connectToChat() 동작 방식

v0.5.0부터 connectToChat()이 반환하는 CompletableFuture는 연결이 해제될 때 완료됩니다.

| 메서드 | 동작 |
|--------|------|
| connectToChat() | 연결 해제 시 완료되는 CompletableFuture<Void> 반환 |
| connectToChat().join() | 연결이 해제될 때까지 현재 스레드를 블로킹 |
| connectAndAwait() | connectToChat().join()의 편의 메서드 (블로킹) |

## 에러 처리

### 예외 계층

SOOPChatException (RuntimeException)
├── AuthenticationException - 로그인 실패, 미인증 sendChat()
├── ConnectionException - WebSocket/HTTP 연결 실패
└── EventEmitterException - 이벤트 리스너 예외 래핑

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

---

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

### 패키지 구조

```
lib/src/main/java/com/github/getcurrentthread/soopapi/
├── SOOPClient.java                          # 파사드 진입점
├── api/                                     # HTTP API 통신
│   ├── SOOPAuth.java                        #   로그인/인증
│   ├── SOOPLive.java                        #   방송 정보 API
│   ├── SOOPChannel.java                     #   채널 정보 API
│   ├── SOOPHttpClient.java                  #   공유 HTTP 클라이언트
│   └── model/                               #   데이터 모델 (AuthCookie, LiveDetail, StationInfo)
├── client/                                  # 사용자 대면 클라이언트
│   └── SOOPChatClient.java                  #   이벤트 구독 + 연결 관리
├── config/                                  # 설정
│   ├── SOOPChatConfig.java                  #   채팅 연결 설정 (Builder)
│   └── SOOPClientConfig.java                #   전역 클라이언트 설정 (Builder)
├── connection/                              # WebSocket 연결 관리
│   ├── ConnectionManager.java               #   싱글톤 연결 매니저
│   └── SOOPConnection.java                  #   채널별 연결 핸들러
├── decoder/                                 # 메시지 파싱/디스패치
│   ├── MessageDispatcher.java               #   메시지 라우팅
│   ├── message/                             #   개별 디코더 (87개)
│   │   ├── IMessageDecoder.java             #     디코더 인터페이스
│   │   ├── ChatMessageDecoder.java          #     채팅 메시지 디코더 (대표 예시)
│   │   └── ...                              #     SendBalloonDecoder, ChocolateDecoder 등
│   └── factory/                             #   디코더 팩토리
│       ├── MessageDecoderFactory.java        #     팩토리 인터페이스
│       └── DefaultMessageDecoderFactory.java #     87개 디코더 등록
├── event/                                   # 이벤트 시스템
│   ├── ChatEvent.java                       #   93개 이벤트 열거형
│   ├── EventEmitter.java                    #   Pub/Sub 이벤트 버스
│   ├── EventListener.java                   #   리스너 함수형 인터페이스
│   └── model/                               #   이벤트 Record 타입 (104개)
│       ├── BaseEvent.java                   #     sealed 루트 인터페이스
│       ├── ChatBaseEvent.java               #     채팅 카테고리
│       ├── DonationBaseEvent.java           #     후원 카테고리
│       ├── SystemBaseEvent.java             #     시스템 카테고리
│       ├── ModerationBaseEvent.java         #     관리 카테고리
│       ├── ItemBaseEvent.java               #     아이템 카테고리
│       ├── NotificationBaseEvent.java       #     알림 카테고리
│       └── UnknownEvent.java                #     미지의 이벤트
├── exception/                               # 예외
│   ├── SOOPChatException.java               #   기본 예외 (RuntimeException)
│   ├── AuthenticationException.java
│   ├── ConnectionException.java
│   └── EventEmitterException.java
├── model/                                   # 도메인 모델
│   ├── ChannelInfo.java                     #   WebSocket 엔드포인트 정보
│   └── ConnectionStatus.java                #   연결 상태 스냅샷
├── constant/                                # 프로토콜 상수
│   └── SOOPConstants.java                   #   패킷 구분자, ESC 헤더
├── util/                                    # 유틸리티
│   ├── SOOPChatUtils.java                   #   파싱, UTF-8, 예외 언래핑
│   ├── GsonUtil.java                        #   JSON 직렬화
│   └── SSLContextProvider.java              #   SSL/TLS 컨텍스트
└── websocket/                               # WebSocket 계층
    ├── WebSocketManager.java                #   연결/재연결/핑 관리
    ├── WebSocketListener.java               #   수신 메시지 처리
    └── WebSocketPacketBuilder.java          #   패킷 직렬화
```

### 핵심 컴포넌트 관계

```
SOOPClient (파사드)
├── SOOPAuth ─── SOOPHttpClient
├── SOOPLive ─── SOOPHttpClient
├── SOOPChannel ─ SOOPHttpClient
└── SOOPChatClient
    └── ConnectionManager (싱글톤)
        └── SOOPConnection (채널당 1개)
            ├── WebSocketManager ─── WebSocketListener
            └── MessageDispatcher ─── IMessageDecoder[]
                                      └── EventEmitter ─── 사용자 리스너
```

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

```
WebSocket.onText()
    → WebSocketListener.onText(): textBuffer에 프래그먼트 조립
    → last=true → MessageDispatcher.dispatchMessage()
    → Virtual Thread에서 실행:
        1. RAW 리스너 확인 → RawEvent 발행 (있을 때만)
        2. F_CHAR로 첫 구분자 찾기 → 헤더 추출
        3. parseServiceCode() → ChatEvent.fromCode()
        4. hasListeners() 확인 (없으면 조기 반환)
        5. IMessageDecoder.decode(parts[], raw) → BaseEvent
        6. EventEmitter.emit(chatEvent, event)
            → internalListeners 먼저 호출
            → listeners 호출
```

## 내부 구조 상세

### ConnectionManager (싱글톤)

파일: connection/ConnectionManager.java

- StableValue<ConnectionManager>를 사용한 lazy 싱글톤 패턴
- messageProcessorPool: Executors.newVirtualThreadPerTaskExecutor() — 메시지당 Virtual Thread 생성
- sharedScheduler: ScheduledThreadPool(1, daemon) — 핑/재연결 스케줄링
- connections: ConcurrentHashMap<String, SOOPConnection> — BID별 연결 관리
- JVM shutdown hook으로 모든 연결 정리
- shutdown(): StructuredTaskScope로 모든 연결 병렬 종료

### SOOPConnection (채널별 연결)

파일: connection/SOOPConnection.java

- SHARED_DECODERS: static final Map — 모든 연결에서 디코더 인스턴스 공유 (메모리 최적화)
- connect() 흐름:
  1. getBno() → BNO가 없으면 API로 조회
  2. soopLive.detail(bid, bno) → LiveDetail 획득
  3. toChannelInfo() → ChannelInfo(CHATNO, FTK, CHPT, CHDOMAIN 등) 변환
  4. CHPT/CHDOMAIN 유효성 검증
  5. webSocketManager.connect(channelInfo)
- registerEnterInfoHandler(): 인증 연결 시 JOIN_CHANNEL 이벤트의 userFlag(synAck)를 ENTER_INFO 패킷으로 전송
- ReentrantLock으로 연결 상태 보호

### WebSocketManager

파일: websocket/WebSocketManager.java

- WsState record: (connected, ws, ping) — AtomicReference로 원자적 상태 관리
- connect(): buildWebSocketUri() → httpClient.newWebSocketBuilder() → sendInitialPackets() → startPingScheduler()
- 재연결: scheduleRetry() — 지수 백오프 (2s, 4s, 8s, ... 최대 30s)
- RECONNECTING 이벤트 발행 (시도 전) → RECONNECTED 이벤트 발행 (성공 시)
- Ping: pingIntervalSeconds 간격으로 핑 패킷 전송, 실패 시 자동 재연결

### WebSocketListener

파일: websocket/WebSocketListener.java

- onText(): StringBuilder textBuffer로 프래그먼트 조립
- last=true일 때 MessageDispatcher.dispatchMessage() 호출
- 버퍼 관리: 기본 16KB, 4배(64KB) 초과 시 trimToSize()
- onClose()/onError(): DISCONNECTED 이벤트 발행

## WebSocket 프로토콜

### 패킷 구조

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

ESC     = \u001b\t (2바이트: ESC + TAB)
command = 4자리 문자열 서비스 코드
length  = UTF-8 바이트 길이, 6자리 0-패딩
suffix  = "00" (고정)
payload = F(\u000c) 구분자로 필드 분리
```

### 명령 코드 (WebSocketPacketBuilder)

| 코드 | 상수 | 용도 |
|------|------|------|
| 0000 | CMD_PING | 연결 유지 핑 |
| 0001 | CMD_CONNECT | 초기 연결 핸드셰이크 |
| 0002 | CMD_JOIN | 채팅 채널 입장 |
| 0005 | CMD_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 패킷 (CMD_CONNECT=0001):
   - 익명: F×3 + "16" + F
   - 인증: F + AuthTicket + F×2 + "16" + F

2. 대기 (initialPacketDelayMs, 기본 1000ms)

3. Join 패킷 (CMD_JOIN=0002):
   - 익명: F + CHATNO + F×5
   - 인증: F + CHATNO + F + FTK + F + "0" + F + log{...}pwd{...}auth_info{NULL}pver{2}access_system{html5} + F

4. [인증 시] EnterInfo 패킷 (CMD_ENTER_INFO=0012):
   - JOIN_CHANNEL 응답의 userFlag(synAck) 수신 후 전송
   - F + synAck + F + "0" + F

### Ping 메커니즘

- pingIntervalSeconds (기본 60초) 간격으로 CMD_PING 패킷 전송
- 전송 실패 시 자동 재연결 시도

## 디코더 시스템

### IMessageDecoder 인터페이스

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

### DefaultMessageDecoderFactory

파일: decoder/factory/DefaultMessageDecoderFactory.java

87개 디코더를 Map.ofEntries()로 등록. static final로 선언되어 모든 SOOPConnection에서 공유.

### 디코더 구현 패턴 (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로 최소 필드 수 검증
2. parts[] 인덱스로 필드 매핑
3. SOOPChatUtils.safeParseInt()로 안전한 정수 파싱
4. 선택적 필드: parts.length > N ? parts[N] : ""
5. 공통 3개 필드 항상 포함: ChatEvent, raw, timestamp

### MessageDispatcher 처리 흐름

파일: decoder/MessageDispatcher.java

1. null/빈 메시지 무시
2. Virtual Thread에서 비동기 실행:
   a. RAW 리스너 확인 → 있으면 RawEvent 발행 (없으면 할당 스킵)
   b. F_CHAR로 첫 구분자 인덱스 찾기 → 없으면 반환
   c. 헤더 추출 → parseServiceCode() → ChatEvent.fromCode()
   d. hasListeners(chatEvent) 확인 → 없으면 조기 반환 (디코딩 스킵)
   e. 디코더 조회 → 없으면 UnknownEvent 생성
   f. decoder.decode(parts, raw) → 결과가 null이면 무시
   g. eventEmitter.emit(chatEvent, event)

## 전체 이벤트 목록

### 기본 연결 (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 | 알 수 없는 타입 |

## 이벤트 시스템 내부

### EventEmitter 구현

파일: event/EventEmitter.java

- listeners: ConcurrentHashMap<ChatEvent, CopyOnWriteArrayList> — 사용자 리스너
- internalListeners: 같은 구조 — 내부 전용 (registerEnterInfoHandler 등)
- onceWrappers: ConcurrentHashMap<원본리스너, 래퍼리스너> — once() 추적
- emit() 순서: internalListeners 먼저, 그 다음 listeners
- 에러 처리: 리스너 예외 catch → errorHandler 호출 → errorHandler 자체 예외도 catch

### once() 구현

래퍼 패턴: 실행 시 off(event, this) 호출 후 원본 리스너 실행.
onceWrappers 맵으로 원본↔래퍼 매핑 추적 (off() 시 래퍼도 제거 가능).

### 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 가능.

## 테스트

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

| 테스트 | 대상 | 유형 |
|--------|------|------|
| SOOPChatClientTest | 채팅 클라이언트 | 컴포넌트 |
| SOOPChatClientConcurrencyTest | 동시성 동작 | 컴포넌트 |
| SOOPChatClientRealConnectionTest | 실제 연결 | 통합 (@Tag) |
| SOOPClientConfigTest | 설정 빌더 검증 | 단위 |
| ChatMessageDecoderTest | 메시지 디코딩 | 단위 |
| DecoderBoundsValidationTest | 배열 범위 검증 | 단위 |
| MessageDispatcherTest | 메시지 라우팅 | 컴포넌트 |
| EventEmitterTest | 이벤트 구독/발행 | 컴포넌트 |
| EventEmitterOnceOffTest | once() 메모리 정리 | 컴포넌트 |
| GsonUtilTest | JSON 직렬화 | 단위 |
| SOOPChatUtilsTest | 유틸리티 파싱 | 단위 |
| WebSocketListenerBufferTest | 텍스트 버퍼 | 단위 |
| WebSocketPacketBuilderTest | 패킷 직렬화 | 단위 |

### 테스트 실행

```bash
./gradlew :lib:test                    # 단위 + 컴포넌트 (통합 제외)
./gradlew :lib:test -PincludeTags=integration  # 통합 포함
```

### 테스트 규약

- JUnit 5 (Jupiter) + Mockito 5.14.2
- @Tag("integration")로 통합 테스트 분리 (CI에서 기본 제외)
- 동시성 테스트: CountDownLatch, AtomicReference, AtomicInteger
- --enable-preview JVM 인수 필수

## 빌드 시스템

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

- 플러그인: java-library, maven-publish, spotless(8.2.1)
- Java 25 toolchain
- 컴파일러: --enable-preview, -Xlint:-preview
- 인코딩: UTF-8
- Spotless: Google Java Format (AOSP variant)
- import 순서: java, javax, jakarta, org, com
- JavaCompile 시 spotlessApply 자동 실행

### CI (GitHub Actions)

파일: .github/workflows/ci.yml

- 트리거: push/PR to develop, main
- 환경: ubuntu-latest, Oracle JDK 25
- 단계: checkout → setup-jdk → setup-gradle → build → publishToMavenLocal 검증

### JitPack 배포

파일: jitpack.yml

- openjdk25 설정
- publishToMavenLocal -xtest -xspotlessApply

### 주요 Gradle 명령

```bash
./gradlew build                    # 컴파일, 테스트, 패키지
./gradlew :lib:build               # 라이브러리 모듈만
./gradlew :lib:publishToMavenLocal # 로컬 Maven 배포
./gradlew spotlessApply            # 코드 포맷팅
```

## 기여 가이드

### 새 이벤트 추가 절차

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

2. event/model/ 에 Record 생성
   - 적절한 BaseEvent 서브타입 implements (ChatBaseEvent, DonationBaseEvent 등)
   - 반드시 eventType(), raw(), timestamp() 필드 포함

3. decoder/message/ 에 IMessageDecoder 구현 클래스 생성
   - MIN_PARTS로 최소 필드 수 검증
   - parts[] 인덱스로 필드 매핑
   - 선택적 필드는 parts.length > N 패턴 사용

4. decoder/factory/DefaultMessageDecoderFactory 에 Map.entry() 추가

5. 테스트 작성: 디코더 단위 테스트

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

1. api/ 패키지에 메서드 추가 (SOOPAuth, SOOPLive, SOOPChannel 중)
2. api/model/ 에 response record 생성
3. SOOPClient에 접근자 추가 (필요 시)

### 코드 스타일

- Google Java Format (AOSP variant) — Spotless 자동 적용
- import 순서: java, javax, jakarta, org, com
- 불필요한 import 자동 제거
- 후행 공백 제거, 파일 끝 개행

### 브랜치 전략

- develop: 주 개발 브랜치 (PR 대상)
- main: 릴리스 브랜치

## 성능 고려사항

### 메모리 최적화

- SHARED_DECODERS: SOOPConnection의 static final — 모든 연결에서 디코더 인스턴스 공유
- WebSocketListener textBuffer: 기본 16KB, 4배(64KB) 초과 시 trimToSize()
- StableValue: lazy 초기화로 불필요한 인스턴스 생성 방지
- utf8ByteLength(): 바이트 배열 할당 없이 문자열 UTF-8 길이 계산
- RAW 이벤트: hasListeners() 체크 후 할당 (리스너 없으면 RawEvent 생성 안 함)
- hasListeners() 조기 반환: 리스너 없으면 디코딩 자체를 스킵

### 동시성

- Virtual Thread per task executor (messageProcessorPool)
- ConcurrentHashMap + CopyOnWriteArrayList: lock-free 이벤트 발행
- AtomicReference<WsState>: WebSocket 상태 원자적 관리
- ReentrantLock: 연결 상태 보호 (connect/disconnect/reconnect)

### Java 25 Preview 기능

- StableValue: ConnectionManager 싱글톤, ChatEvent code-to-enum 맵
- StructuredTaskScope: ConnectionManager.shutdown()에서 병렬 종료

## 버전 관리

현재 버전: 0.5.0

- gradle.properties에서 version=0.5.0 관리
- JitPack에서 git 태그(v0.5.0)로 빌드

### 버전 업데이트 절차

1. gradle.properties의 version 값 변경
2. README.md의 JitPack 의존성 버전 업데이트

## 면책 조항

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