toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.md

Browse source
This commit is contained in:
toki 2026-06-15 14:40:05 +09:00
parent 3bc131c269
commit 5e2cb0b5c3
1 changed files with 32 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
README.md
View file

@ -18,6 +18,27 @@ Protocol Buffers 직렬화, TCP 4바이트 빅엔디안 길이 프리픽스 프
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
``` ```
### 검증 스냅샷
다른 프로젝트나 에이전트가 도입 여부를 빠르게 판단할 때는 아래 값을 현재 공개 snapshot으로 본다. 절대 throughput/latency는 local host와 runtime 상태에 의존하므로, 회귀 판단은 같은 host/runtime/profile에서 생성한 결과끼리 비교한다.
| 항목 | 최신 근거 | 결과 | 해석 |
|------|-----------|------|------|
| 기능 호환성 | [20260615-020431-proto-socket-full-matrix.md](agent-test/runs/20260615-020431-proto-socket-full-matrix.md), ref `3bc131c` | PASS | proto sync, 동일 언어 테스트, 20개 native cross-language 방향, Dart.web/Dart.web(WSS) client coverage가 모두 통과했다. |
| 성능/안정성 baseline 후보 | [20260614-123328-proto-socket-performance-full.md](agent-test/runs/20260614-123328-proto-socket-performance-full.md), ref `29ea189` | PASS | same-language, cross-language, TypeScript gateway 성능/안정성 측정이 모두 통과했다. baseline 비교가 없어 regression 판정은 `SKIPPED`다. |
| 안정성 hard gate | performance full 378 rows | PASS | timeout, nonce mismatch, response type mismatch, FIFO violation, pending leak가 모두 0이다. |
성능 full 기록의 대표 수치는 다음과 같다.
| 축 | 대표 결과 |
|----|-----------|
| 30분 sustained | Dart TCP 40k rps, TypeScript TCP 33k rps, Kotlin TCP 27k rps, Go TCP 15.6k rps, Python TCP 12.2k rps 수준 |
| 1024 clients 병렬 | Go TCP 209k rps/p99 133ms, Kotlin TCP 70k rps/p99 219ms, TypeScript TCP 47k rps/p99 76ms |
| 1MB payload | Python TCP 463 rps/p99 17ms, Go TCP 415 rps/p99 20ms, Kotlin TCP 351 rps/p99 46ms |
| TypeScript gateway | in-process gateway는 TCP/WS p99 1.7-3.2ms 수준, `worker_threads` gateway는 p99 190-203ms 수준이라 저지연 기본값으로 보지 않는다. |
도입 판단은 "얇은 protocol-first 소켓 프레임워크로 충분히 실용적"으로 둔다. 다만 Kotlin WebSocket과 Python high-concurrency row는 다른 구현보다 tail latency가 크므로, 초저지연/초고동시성 제품에서는 해당 언어와 transport 조합을 별도로 재측정한다. 최신 기능 ref에서 성능 회귀 없음까지 확정하려면 `run_performance.sh --full --baseline <이전 performance record>`로 같은 환경 비교를 수행한다.
프로토콜 또는 공개 API 변경은 호환성 작업으로 다룬다. 관련 문서를 갱신하고, 필요한 경우 protobuf binding을 재생성하며, 전체 검증 매트릭스가 통과해야 한다. 프로토콜 또는 공개 API 변경은 호환성 작업으로 다룬다. 관련 문서를 갱신하고, 필요한 경우 protobuf binding을 재생성하며, 전체 검증 매트릭스가 통과해야 한다.
### 런타임 포트와 테스트 포트 ### 런타임 포트와 테스트 포트
@ -58,15 +79,15 @@ WebSocket/WSS transport에서는 각 binary frame이 TCP length header 없이 `P
## 구현체 ## 구현체
| 언어 | 상태 | 경로 | 사용처 | | 언어　　　 | 상태　　　　| 경로　　　　　　　　　　　 | 사용처　　　　　　　　　　 |
|------|------|------|--------| | ------------| -------------| ----------------------------| ----------------------------|
| Dart | 사용 가능 | [dart/](dart/) | Flutter, Dart server | | Dart　　　 | 사용 가능　 | [dart/](dart/)　　　　　　 | Flutter, Dart server　　　 |
| Kotlin | 사용 가능 | [kotlin/](kotlin/) | Android, JVM | | Kotlin　　 | 사용 가능　 | [kotlin/](kotlin/)　　　　 | Android, JVM　　　　　　　 |
| Go | 사용 가능 | [go/](go/) | Server, tooling, scripting | | Go　　　　 | 사용 가능　 | [go/](go/)　　　　　　　　 | Server, tooling, scripting |
| TypeScript | 사용 가능 | [typescript/](typescript/) | Browser, Node.js | | TypeScript | 사용 가능　 | [typescript/](typescript/) | Browser, Node.js　　　　　 |
| Python | 사용 가능 | [python/](python/) | Server, tooling, scripting | | Python　　 | 사용 가능　 | [python/](python/)　　　　 | Server, tooling, scripting |
| C# | 계획 / 보류 | `csharp/` | Unity, .NET | | C#　　　　 | 계획 / 보류 | `csharp/`　　　　　　　　　| Unity, .NET　　　　　　　　|
| Swift | 계획 / 보류 | `swift/` | iOS, macOS | | Swift　　　| 계획 / 보류 | `swift/`　　　　　　　　　 | iOS, macOS　　　　　　　　 |
새 언어 구현은 [PORTING_GUIDE.md](PORTING_GUIDE.md)와 [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/)의 템플릿에서 시작한다. 동일 언어 테스트와 크로스 언어 테스트가 통과한 뒤에만 구현 상태를 사용 가능으로 표시한다. 새 언어 구현은 [PORTING_GUIDE.md](PORTING_GUIDE.md)와 [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/)의 템플릿에서 시작한다. 동일 언어 테스트와 크로스 언어 테스트가 통과한 뒤에만 구현 상태를 사용 가능으로 표시한다.
@ -79,6 +100,8 @@ WebSocket/WSS transport에서는 각 binary frame이 TCP length header 없이 `P
| 목적 | 명령 | 비고 | | 목적 | 명령 | 비고 |
|------|------|------| |------|------|------|
| 전체 로컬 검증 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | proto sync, 동일 언어 테스트, 사용 가능 구현의 크로스 언어 검증을 실행한다. | | 전체 로컬 검증 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | proto sync, 동일 언어 테스트, 사용 가능 구현의 크로스 언어 검증을 실행한다. |
| 성능/안정성 full 측정 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --full` | same-language, cross-language, TypeScript gateway 성능과 stability hard gate를 측정한다. |
| 성능 baseline 비교 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick --baseline agent-test/runs/<baseline-record>.md` | 같은 host/runtime/profile의 이전 기록과 throughput/p99 회귀 후보를 비교한다. |
| Proto schema sync 확인 | `tools/check_proto_sync.sh` | 언어별 proto copy가 허용된 언어 옵션을 제외하고 `proto/message_common.proto`와 일치하는지 확인한다. | | Proto schema sync 확인 | `tools/check_proto_sync.sh` | 언어별 proto copy가 허용된 언어 옵션을 제외하고 `proto/message_common.proto`와 일치하는지 확인한다. |
| Protobuf binding 재생성 | `tools/generate_proto.sh` | canonical proto schema를 바꾼 뒤 실행한다. | | Protobuf binding 재생성 | `tools/generate_proto.sh` | canonical proto schema를 바꾼 뒤 실행한다. |
| Dart 테스트 | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO 테스트와 web import compile 확인 | | Dart 테스트 | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO 테스트와 web import compile 확인 |