60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
---
|
|
domain: protocol
|
|
last_rule_review_commit: 7ea0b484d2c5c73e85f4ef4b16cba20f25cb4b51
|
|
last_rule_updated_at: 2026-06-01
|
|
---
|
|
|
|
# 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, 메시지 타입 정식 원본
|
|
- `dart/lib/src/packets/message_common.pb*.dart` — Dart protobuf 생성 바인딩
|
|
- `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에 정의되지 않은 프레이밍 방식을 구현체에서 임의로 추가하지 않는다
|