281 lines
8.6 KiB
Text
281 lines
8.6 KiB
Text
<!-- task=proto_restructure plan=0 tag=PROTO_MOVE -->
|
|
|
|
# Proto 루트 디렉터리 독립화
|
|
|
|
## 이 파일을 읽는 구현 에이전트에게
|
|
|
|
각 항목의 체크리스트를 완료하면서 `[ ]`를 `[x]`로 표시하라.
|
|
중간 검증 명령은 해당 항목 구현 직후 실행하고, 출력을 `CODE_REVIEW.md`의 검증 결과 섹션에 붙여넣어라.
|
|
최종 검증도 마찬가지로 실행 후 출력을 기록하라.
|
|
계획과 다르게 구현한 부분은 이유와 함께 `CODE_REVIEW.md`의 "계획 대비 변경 사항"에 기록하라.
|
|
|
|
⚠️ **이 태스크는 모든 언어의 빌드 경로를 변경한다. 각 검증을 반드시 실행한 후 다음 단계로 넘어가라.**
|
|
|
|
---
|
|
|
|
## 배경
|
|
|
|
현재 proto canonical source가 `dart/lib/src/packets/message_common.proto`에 위치한다.
|
|
Dart는 5개 언어 구현체 중 하나이지만 동시에 스펙 원본의 저장소 역할을 하고 있어,
|
|
새 기여자에게 "proto = Dart 전용"으로 오해될 수 있다.
|
|
`proto/message_common.proto` 루트 디렉터리로 이동하면:
|
|
|
|
- proto가 특정 언어 종속성 없이 독립 소스임이 명확해진다
|
|
- 새 언어 포팅 시 proto 위치가 자명해진다
|
|
- `check_proto_sync.sh`의 "canonical Dart proto"라는 명칭이 사라진다
|
|
|
|
## 언어별 proto 현황
|
|
|
|
| 언어 | 현재 위치 | 방식 | 변경 여부 |
|
|
|------|----------|------|---------|
|
|
| Dart | `dart/lib/src/packets/message_common.proto` (canonical) | `protoc --dart_out` (generate_proto.sh) | 제거 후 생성 경로 변경 |
|
|
| Go | `go/packets/message_common.proto` (go_package 옵션 포함 복사본) | `protoc --go_out` (generate_proto.sh) | 유지 (언어 옵션 필요), sync 비교 대상 변경 |
|
|
| Kotlin | `kotlin/src/main/proto/message_common.proto` (java 옵션 포함 복사본) | Gradle protobuf 플러그인 | 유지 (언어 옵션 필요), sync 비교 대상 변경 |
|
|
| TypeScript | `typescript/src/packets/message_common_pb.ts` (생성 결과물만, .proto 없음) | `protoc-gen-es` 수동 실행 | 영향 없음 |
|
|
| Python | `python/toki_socket/packets/message_common_pb2.py` (생성 결과물만, .proto 없음) | `protoc --python_out` 수동 실행 | 영향 없음 |
|
|
|
|
## 의존 관계 및 구현 순서
|
|
|
|
```
|
|
[PROTO_MOVE-1] proto/ 생성 + generate_proto.sh 수정
|
|
→ [PROTO_MOVE-2] check_proto_sync.sh canonical 경로 변경
|
|
→ [PROTO_MOVE-3] PROTOCOL.md 업데이트
|
|
→ [PROTO_MOVE-4] dart/lib/src/packets/message_common.proto 제거
|
|
```
|
|
|
|
---
|
|
|
|
### [PROTO_MOVE-1] `proto/` 디렉터리 생성 및 generate_proto.sh 수정
|
|
|
|
**문제**
|
|
|
|
`tools/generate_proto.sh`가 Dart canonical에서 직접 생성한다.
|
|
|
|
```bash
|
|
# 현재
|
|
cd "$repo_root/dart"
|
|
protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto
|
|
|
|
cd "$repo_root/go"
|
|
protoc --go_out=. --go_opt=paths=source_relative packets/message_common.proto
|
|
```
|
|
|
|
**해결 방법**
|
|
|
|
1. `proto/message_common.proto` 생성: `dart/lib/src/packets/message_common.proto`에서 언어 옵션 없이 그대로 복사 (현재 Dart canonical에는 언어 옵션이 없으므로 내용 동일).
|
|
2. `generate_proto.sh`의 Dart 생성 경로를 `proto/`에서 `dart/lib/src/packets/`로 출력하도록 변경.
|
|
3. Go 생성은 Go copy(`go/packets/message_common.proto`)에서 그대로 진행 (go_package 옵션 보존 필요).
|
|
|
|
Before (`generate_proto.sh` Dart 섹션):
|
|
```bash
|
|
(
|
|
cd "$repo_root/dart"
|
|
protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto
|
|
)
|
|
```
|
|
|
|
After:
|
|
```bash
|
|
(
|
|
protoc \
|
|
--proto_path="$repo_root/proto" \
|
|
--dart_out="$repo_root/dart/lib/src/packets" \
|
|
message_common.proto
|
|
)
|
|
```
|
|
|
|
Go 섹션은 변경 없음 (Go는 자체 복사본에서 생성).
|
|
|
|
**수정 파일 및 체크리스트**
|
|
|
|
- [x] `proto/message_common.proto` 생성 (dart canonical과 동일 내용)
|
|
- [x] `tools/generate_proto.sh` — Dart 생성 섹션 경로 변경
|
|
|
|
**테스트 없음** — generate_proto.sh 실행으로 검증
|
|
|
|
**중간 검증**
|
|
|
|
```bash
|
|
# protoc가 있는 환경에서 실행
|
|
tools/generate_proto.sh
|
|
# 오류 없이 완료
|
|
|
|
# 생성 결과가 기존과 동일한지 확인
|
|
cd dart && dart analyze
|
|
# No issues found
|
|
```
|
|
|
|
---
|
|
|
|
### [PROTO_MOVE-2] `check_proto_sync.sh` canonical 경로 변경
|
|
|
|
**문제**
|
|
|
|
`tools/check_proto_sync.sh`의 canonical이 `dart_proto` 변수로 Dart 경로를 가리킨다.
|
|
|
|
```bash
|
|
dart_proto="$repo_root/dart/lib/src/packets/message_common.proto"
|
|
```
|
|
|
|
**해결 방법**
|
|
|
|
변수명과 경로를 `proto/` 기준으로 변경한다.
|
|
|
|
Before:
|
|
```bash
|
|
dart_proto="$repo_root/dart/lib/src/packets/message_common.proto"
|
|
go_proto="$repo_root/go/packets/message_common.proto"
|
|
kotlin_proto="$repo_root/kotlin/src/main/proto/message_common.proto"
|
|
|
|
if [[ ! -f "$dart_proto" ]]; then
|
|
echo "Missing canonical Dart proto: $dart_proto" >&2
|
|
exit 1
|
|
fi
|
|
# ...
|
|
normalize_proto "$dart_proto" >"$tmp_dir/dart.proto"
|
|
normalize_proto "$go_proto" >"$tmp_dir/go.proto"
|
|
# ...
|
|
if ! cmp -s "$tmp_dir/dart.proto" "$tmp_dir/go.proto"; then
|
|
echo "Proto schema mismatch: go/packets/message_common.proto must match the Dart canonical proto ..."
|
|
# ...
|
|
```
|
|
|
|
After:
|
|
```bash
|
|
canonical_proto="$repo_root/proto/message_common.proto"
|
|
go_proto="$repo_root/go/packets/message_common.proto"
|
|
kotlin_proto="$repo_root/kotlin/src/main/proto/message_common.proto"
|
|
|
|
if [[ ! -f "$canonical_proto" ]]; then
|
|
echo "Missing canonical proto: $canonical_proto" >&2
|
|
exit 1
|
|
fi
|
|
# ...
|
|
normalize_proto "$canonical_proto" >"$tmp_dir/canonical.proto"
|
|
normalize_proto "$go_proto" >"$tmp_dir/go.proto"
|
|
# ...
|
|
if ! cmp -s "$tmp_dir/canonical.proto" "$tmp_dir/go.proto"; then
|
|
echo "Proto schema mismatch: go/packets/message_common.proto must match proto/message_common.proto ..."
|
|
# ...
|
|
```
|
|
|
|
**수정 파일 및 체크리스트**
|
|
|
|
- [x] `tools/check_proto_sync.sh` — `dart_proto` → `canonical_proto`, 경로를 `proto/message_common.proto`로 변경
|
|
- [x] `tools/check_proto_sync.sh` — 오류 메시지에서 "Dart canonical" 문구 제거
|
|
- [x] `tools/check_proto_sync.sh` — normalize 비교 대상 변수명 일관성 수정
|
|
|
|
**중간 검증**
|
|
|
|
```bash
|
|
tools/check_proto_sync.sh
|
|
# Proto schemas are in sync.
|
|
```
|
|
|
|
---
|
|
|
|
### [PROTO_MOVE-3] `PROTOCOL.md` Proto Source 섹션 업데이트
|
|
|
|
**문제**
|
|
|
|
`PROTOCOL.md` 하단 "Proto Source" 섹션이 Dart 경로를 canonical로 명시한다.
|
|
|
|
```markdown
|
|
`dart/lib/src/packets/message_common.proto` is the canonical packet definition.
|
|
All language implementations must keep the same message schema and generate bindings from it.
|
|
```
|
|
|
|
**해결 방법**
|
|
|
|
```markdown
|
|
`proto/message_common.proto` is the canonical packet definition.
|
|
All language implementations generate bindings from it.
|
|
Language-specific generation options (go_package, java_package, etc.) are kept in each
|
|
language's own proto copy under `go/packets/` and `kotlin/src/main/proto/`.
|
|
```
|
|
|
|
**수정 파일 및 체크리스트**
|
|
|
|
- [x] `PROTOCOL.md` — "Proto Source" 섹션 경로 및 설명 업데이트
|
|
|
|
**테스트 없음** — 문서 전용
|
|
|
|
**중간 검증**
|
|
|
|
```bash
|
|
grep "canonical" PROTOCOL.md
|
|
# proto/message_common.proto 언급
|
|
grep "dart/lib/src/packets/message_common.proto" PROTOCOL.md
|
|
# 출력 없음이 정상
|
|
```
|
|
|
|
---
|
|
|
|
### [PROTO_MOVE-4] `dart/lib/src/packets/message_common.proto` 제거
|
|
|
|
**문제**
|
|
|
|
PROTO_MOVE-1~3 완료 후 `dart/lib/src/packets/message_common.proto`는 더 이상 canonical이 아니다.
|
|
그러나 여전히 파일로 남아 혼란을 줄 수 있다.
|
|
|
|
**해결 방법**
|
|
|
|
파일을 삭제한다. Dart 생성 결과물인 `.pb.dart` 파일들은 유지한다.
|
|
|
|
**수정 파일 및 체크리스트**
|
|
|
|
- [x] `dart/lib/src/packets/message_common.proto` 삭제
|
|
- [x] `dart analyze` — proto 파일 제거 후 여전히 No issues인지 확인
|
|
|
|
**중간 검증**
|
|
|
|
```bash
|
|
ls dart/lib/src/packets/
|
|
# message_common.pb.dart, message_common.pbenum.dart 등 생성 결과물만 존재
|
|
# message_common.proto 없음
|
|
|
|
cd dart && dart analyze
|
|
# No issues found
|
|
cd dart && dart test
|
|
# 전체 PASS
|
|
```
|
|
|
|
---
|
|
|
|
## 수정 파일 요약
|
|
|
|
| 파일 | 항목 |
|
|
|------|------|
|
|
| `proto/message_common.proto` (신규) | PROTO_MOVE-1 |
|
|
| `tools/generate_proto.sh` | PROTO_MOVE-1 |
|
|
| `tools/check_proto_sync.sh` | PROTO_MOVE-2 |
|
|
| `PROTOCOL.md` | PROTO_MOVE-3 |
|
|
| `dart/lib/src/packets/message_common.proto` (삭제) | PROTO_MOVE-4 |
|
|
|
|
## 최종 검증
|
|
|
|
```bash
|
|
# proto sync 도구 검증
|
|
tools/check_proto_sync.sh
|
|
# Proto schemas are in sync.
|
|
|
|
# Dart
|
|
cd dart && dart analyze
|
|
# No issues found
|
|
cd dart && dart test
|
|
# 전체 PASS
|
|
|
|
# Go
|
|
cd go && go build ./...
|
|
# 빌드 성공
|
|
|
|
# Kotlin
|
|
cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle ./gradlew build
|
|
# BUILD SUCCESSFUL
|
|
|
|
# proto/ 파일 확인
|
|
ls proto/
|
|
# message_common.proto 존재
|
|
ls dart/lib/src/packets/
|
|
# *.pb.dart만 존재, message_common.proto 없음
|
|
```
|