---
domain: protocol
last_rule_review_commit: 34692aec1891b5042867daf29479e478861954ed
last_rule_updated_at: 2026-05-21
---

# protocol

## 목적 / 책임

와이어 포맷 명세와 proto 정의, 언어별 packet 바인딩/코덱을 관리한다. PacketBase 프레이밍, 타입 라우팅, 요청-응답 상관관계, 하트비트의 공식 계약을 정의한다.

## 포함 경로

- `proto/` — 언어 옵션 없는 proto 정식 원본
- `dart/lib/src/packets/` — Dart protobuf 생성 코드
- `go/packets/` — Go용 proto 복사본 (go_package 옵션만 추가)
- `kotlin/src/main/proto/` — Kotlin용 proto 복사본 (Java 패키지 옵션만 추가)
- `python/proto_socket/packets/` — Python proto 복사본 및 protobuf 바인딩
- `typescript/src/packets/` — TypeScript packet 타입 및 바이너리 코덱
- `PROTOCOL.md` — 공식 와이어 포맷 명세
- `VERSIONING.md` — 프로토콜/패키지 버전 정책

## 제외 경로

- `dart/lib/src/` (packets/ 외) — Dart 구현체 로직 (dart 도메인)
- `go/*.go` (packets/ 외) — Go 구현체 로직 (go 도메인)
- `kotlin/src/main/kotlin/`, `kotlin/src/test/`, `kotlin/crosstest/` — Kotlin 구현체 로직 (kotlin 도메인)
- `python/proto_socket/` (packets/ 외), `python/test/`, `python/crosstest/` — Python 구현체 로직
- `typescript/src/` (packets/ 외), `typescript/test/`, `typescript/crosstest/` — TypeScript 구현체 로직

## 주요 구성 요소

- `proto/message_common.proto` — PacketBase, 메시지 타입 정식 원본
- `go/packets/message_common.proto` — Go 언어 옵션이 붙은 proto 복사본
- `kotlin/src/main/proto/message_common.proto` — Kotlin/Java 언어 옵션이 붙은 proto 복사본
- `python/proto_socket/packets/message_common.proto` — Python 패키지의 proto 복사본
- `typescript/src/packets/message_common_pb.ts` — TypeScript packet 타입 및 수동 바이너리 코덱
- `PacketBase` — 모든 패킷의 공통 래퍼 (`typeName`, `nonce`, `data`, `responseNonce`)
- `HeartBeat` / `TestData` — 내장 하트비트 및 크로스 테스트용 메시지

## 유지할 패턴

- proto 원본은 `proto/message_common.proto`에서만 편집
- Go/Kotlin proto는 언어별 옵션만 추가. 메시지 스키마는 건드리지 않는다
- Python proto 복사본은 정식 원본과 메시지 스키마를 맞춘다
- TypeScript packet 코덱은 `PacketBase`, `HeartBeat`, `TestData`의 필드 번호와 wire type을 PROTOCOL.md/proto와 맞춘다
- 변경 후 반드시 `tools/generate_proto.sh` + `tools/check_proto_sync.sh` 실행. 현재 스크립트는 Dart/Go 바인딩 생성과 Go/Kotlin proto 동기화 검증을 수행한다

## 다른 도메인과의 경계

- **dart/go/kotlin/python/typescript**: 구현체가 proto 타입을 사용하지만, 타입 정의·packet 바인딩·코덱 자체는 protocol 도메인
- **tools**: proto 생성/검증 스크립트는 tools 도메인. proto 파일 자체는 protocol 도메인

## 금지 사항

- proto 파일을 Go/Kotlin 복사본에서 직접 편집하지 않는다 (메시지 스키마 변경은 `proto/message_common.proto`에서만)
- Python proto 복사본 또는 TypeScript packet 코덱에서 메시지 스키마를 단독 변경하지 않는다
- PROTOCOL.md에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다