From 5e2cb0b5c32236a4354ed71e26ebdb6808184978 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 15 Jun 2026 14:40:05 +0900 Subject: [PATCH] Update README.md --- README.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8de4023..1393c22 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,27 @@ Protocol Buffers 직렬화, TCP 4바이트 빅엔디안 길이 프리픽스 프 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을 재생성하며, 전체 검증 매트릭스가 통과해야 한다. ### 런타임 포트와 테스트 포트 @@ -58,15 +79,15 @@ WebSocket/WSS transport에서는 각 binary frame이 TCP length header 없이 `P ## 구현체 -| 언어 | 상태 | 경로 | 사용처 | -|------|------|------|--------| -| Dart | 사용 가능 | [dart/](dart/) | Flutter, Dart server | -| Kotlin | 사용 가능 | [kotlin/](kotlin/) | Android, JVM | -| Go | 사용 가능 | [go/](go/) | Server, tooling, scripting | -| TypeScript | 사용 가능 | [typescript/](typescript/) | Browser, Node.js | -| Python | 사용 가능 | [python/](python/) | Server, tooling, scripting | -| C# | 계획 / 보류 | `csharp/` | Unity, .NET | -| Swift | 계획 / 보류 | `swift/` | iOS, macOS | +| 언어　　　 | 상태　　　　| 경로　　　　　　　　　　　 | 사용처　　　　　　　　　　 | +| ------------| -------------| ----------------------------| ----------------------------| +| Dart　　　 | 사용 가능　 | [dart/](dart/)　　　　　　 | Flutter, Dart server　　　 | +| Kotlin　　 | 사용 가능　 | [kotlin/](kotlin/)　　　　 | Android, JVM　　　　　　　 | +| Go　　　　 | 사용 가능　 | [go/](go/)　　　　　　　　 | Server, tooling, scripting | +| TypeScript | 사용 가능　 | [typescript/](typescript/) | Browser, Node.js　　　　　 | +| Python　　 | 사용 가능　 | [python/](python/)　　　　 | Server, tooling, scripting | +| C#　　　　 | 계획 / 보류 | `csharp/`　　　　　　　　　| Unity, .NET　　　　　　　　| +| 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/)의 템플릿에서 시작한다. 동일 언어 테스트와 크로스 언어 테스트가 통과한 뒤에만 구현 상태를 사용 가능으로 표시한다. @@ -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, 동일 언어 테스트, 사용 가능 구현의 크로스 언어 검증을 실행한다. | +| 성능/안정성 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/.md` | 같은 host/runtime/profile의 이전 기록과 throughput/p99 회귀 후보를 비교한다. | | Proto schema sync 확인 | `tools/check_proto_sync.sh` | 언어별 proto copy가 허용된 언어 옵션을 제외하고 `proto/message_common.proto`와 일치하는지 확인한다. | | 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 확인 |