3.3 KiB
3.3 KiB
| domain | last_rule_review_commit | last_rule_updated_at |
|---|---|---|
| protocol | 34692aec18 |
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에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다