update roadmap: add high-performance-parallel-operations milestone and update inbound-queue-ordering

This commit is contained in:
toki 2026-06-02 19:44:42 +09:00
parent 041a7b529b
commit 255c585bc1
4 changed files with 134 additions and 17 deletions

View file

@ -28,7 +28,8 @@ Proto Socket은 여러 언어와 플랫폼에서 일관되게 동작하는 얇
### 안정화와 유지
- [안정화 기준선](milestones/stability-baseline.md) - 상태: 완료; 목표: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단과 유지 기준을 정리한다.
- [수신 큐와 처리 순서 보장](milestones/inbound-queue-ordering.md) - 상태: [진행중]; 목표: 현재 5개 언어 구현에 per-connection 수신 큐와 언어별 worker gateway 후보를 도입해 수신 처리 순서, 자동 응답 출력 순서, thread-safe한 공유 상태 접근, 대량 처리 성능 개선 가능성을 보장한다.
- [수신 큐와 처리 순서 보장](milestones/inbound-queue-ordering.md) - 상태: [검토중]; 목표: 현재 5개 언어 구현에 per-connection 수신 큐와 언어별 worker gateway 후보를 도입해 수신 처리 순서, 자동 응답 출력 순서, thread-safe한 공유 상태 접근, 대량 처리 성능 개선 가능성을 보장한다.
- [고성능 병렬 운용 기준선과 최적화](milestones/high-performance-parallel-operations.md) - 상태: [계획]; 목표: 현재 5개 언어 구현의 병렬 운용 성능을 언어별/transport별로 측정하고 gateway, queue, worker, serialization 병목을 최적화한다.
### 남은 native platform 포팅

View file

@ -2,10 +2,14 @@
## 활성 Milestone
- [진행중] 수신 큐와 처리 순서 보장
- [검토중] 수신 큐와 처리 순서 보장
- 단계: 안정화와 유지
- 경로: `agent-roadmap/milestones/inbound-queue-ordering.md`
- [계획] 고성능 병렬 운용 기준선과 최적화
- 단계: 안정화와 유지
- 경로: `agent-roadmap/milestones/high-performance-parallel-operations.md`
## 선택 규칙
- 이 문서는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.

View file

@ -0,0 +1,103 @@
# 고성능 병렬 운용 기준선과 최적화
## 목표
`수신 큐와 처리 순서 보장` Milestone에서 확보한 FIFO, nonce matching, close cleanup 안정성을 바탕으로 Dart, Go, Kotlin, Python, TypeScript 구현이 실제 고성능 병렬 운용에서 어느 정도까지 안전하고 빠르게 동작하는지 측정하고 최적화한다. 단순 PASS/FAIL 안정성 검증을 넘어, 언어별 TCP/WS 경로, payload 크기, connection 수, sustained load, gateway on/off 조건에서 병목을 식별하고 기본 정책을 정한다.
이 Milestone의 결과는 package registry 릴리즈나 외부 CI/CD 연결이 아니라, Git ref/tag 기반 소비자가 참고할 수 있는 로컬 성능 기준선과 최적화 근거다.
## 단계
안정화와 유지
## 상태
[계획]
## 구현 잠금
- 상태: 해제
- 결정 필요: 없음
## 범위
- Dart, Go, Kotlin, Python, TypeScript의 same-language TCP/WS 성능 기준선을 모두 확보한다.
- 지원 가능한 크로스 언어 request-response 경로에서 병렬 운용 안정성과 주요 성능 지표를 측정한다.
- concurrency, client connection 수, payload size, burst size, sustained duration을 축으로 하는 stress/benchmark matrix를 만든다.
- gateway on/off가 실제 transport 수신 경로에서 이득인지 언어별로 판단하고, 이득이 불명확하거나 손해인 경우 안전한 fallback/default-off 정책을 명확히 한다.
- queue depth, pending request 수, gateway backlog, memory peak/growth, close cleanup을 직접 계측한다.
- 병목이 확인된 언어/경로는 queue/channel/lock/worker/serialization 비용을 우선순위에 따라 최적화한다.
- 결과는 local baseline으로 저장하고, 안정성 hard gate와 성능 regression gate를 분리한다.
## 기능
### Epic: [bench-matrix] 언어별 benchmark matrix
모든 지원 언어가 같은 축의 benchmark/stress 결과를 남기도록 진입점과 결과 schema를 정렬한다.
- [ ] [bench-schema] stress/benchmark 결과 schema를 공통화한다. 검증: 결과 파일이 언어, transport, payload size, concurrency, client count, throughput, p50/p95/p99 latency, timeout, nonce mismatch, type mismatch, FIFO violation, pending leak, queue/gateway backlog, peak memory를 기록한다.
- [ ] [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full baseline을 추가한다. 검증: 각 언어별 full run이 결과 파일을 남기고 stability hard gate를 통과한다.
- [ ] [cross-baseline] 지원 가능한 크로스 언어 request-response 병렬 baseline을 추가한다. 검증: 서버 가능한 5개 구현과 클라이언트 가능한 구현 조합에서 concurrency 1/16/64/256 기준의 nonce/FIFO 독립성이 유지된다.
- [ ] [payload-matrix] payload size matrix를 추가한다. 검증: 1KB, 64KB, 1MB payload에서 latency, throughput, memory peak, gateway backlog가 기록된다.
### Epic: [load-profile] 운영형 부하 기준선
짧은 smoke가 아니라 병렬 운용에서 재현 가능한 부하 프로파일을 만든다.
- [ ] [burst-100k] burst inbound 기준선을 10k에서 100k message/request까지 확장한다. 검증: 입력 순서, dispatch 순서, pending cleanup, queue drain 결과가 기록되고 hard gate 위반이 0이다.
- [ ] [parallel-1k] 다중 connection 기준선을 16 clients에서 128/512/1024 clients 후보까지 확장한다. 검증: connection별 FIFO와 nonce matching이 독립적으로 유지되고, 한 connection의 지연/포화가 다른 connection의 pending map을 오염시키지 않는다.
- [ ] [soak-load] sustained load를 30초에서 5분 smoke, 30분 full 후보로 확장한다. 검증: p95/p99 latency trend, throughput trend, memory growth, queue/pending/gateway backlog trend가 결과 파일에 기록된다.
- [ ] [slow-mix] 빠른 handler와 느린 handler가 섞인 혼합 부하를 추가한다. 검증: 느린 handler가 같은 connection FIFO를 계약대로 지연시키되 다른 connection의 nonce/FIFO 상태를 오염시키지 않는다.
### Epic: [gateway-policy] gateway 성능 정책
worker gateway가 실제 성능 이득을 주는 조건과 fallback 조건을 수치로 정한다.
- [ ] [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway on/off baseline을 추가한다. 검증: in-process `onReceivedFrame`뿐 아니라 실제 transport frame ingest에서 gateway 사용 여부별 throughput, p95/p99, memory, backlog가 기록된다.
- [ ] [gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: payload/traffic 조건별로 default on, default off, adaptive candidate 중 하나가 문서화되고, 이득이 불명확하면 fallback을 기본으로 둔다.
- [ ] [gateway-cleanup] gateway worker close/cancel/drain 계측을 추가한다. 검증: close 후 worker, queue, pending 상태가 비어 있고 repeated run에서 memory growth가 누적되지 않는다.
### Epic: [optimize] 병목 최적화
측정 결과를 근거로 병목을 줄이고 regression gate를 만든다.
- [ ] [hotspot-report] 언어별 병목 리포트를 작성한다. 검증: queue/channel/lock/serialization/worker/transport write path 중 주요 병목 후보와 근거가 결과 파일 또는 작업 문서에 남는다.
- [ ] [targeted-opt] 측정으로 확인된 상위 병목을 우선 최적화한다. 검증: 최적화 전후 같은 local profile에서 stability hard gate를 유지하고, 대상 metric이 개선되거나 fallback 정책이 명확해진다.
- [ ] [regression-gate] 성능 regression gate를 추가한다. 검증: 같은 환경의 이전 baseline 대비 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화가 발생하면 WARN/FAIL 후보로 표시하되, 환경 차이는 별도 baseline으로 분리할 수 있다.
- [ ] [matrix] 전체 로컬 검증 매트릭스를 실행해 최적화 후에도 프로토콜 호환성과 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과.
## 성능 기준선
- 안정성 hard gate: timeout 0, nonce mismatch 0, response type mismatch 0, connection별 FIFO violation 0, close 후 pending/queue/gateway backlog leak 0.
- local full baseline 최소 축: concurrency 1/16/64/256, burst 10k/100k, sustained 5분 smoke와 30분 full 후보, parallel clients 16/128/512/1024 후보, payload 1KB/64KB/1MB.
- 초기 성능 기대선: same-language TCP 기준 concurrency 256에서 p99 100ms 이하, sustained 5분 smoke에서 unexpected timeout 0, memory growth가 안정 구간 진입 후 선형 증가하지 않을 것.
- regression gate: 같은 환경과 같은 profile에서 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화를 WARN/FAIL 후보로 본다.
- gateway 정책 기준: gateway on이 같은 payload/profile에서 p95/p99 또는 throughput을 유의미하게 개선하지 못하거나 memory/backlog 비용이 크면 default off 또는 adaptive fallback을 기본으로 둔다.
- 절대 throughput 수치는 hardware/runtime 의존 baseline으로 저장하고, release gate보다 regression 분석과 병목 우선순위 선정에 사용한다.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
## 범위 제외
- wire format, proto schema, nonce 의미를 변경하지 않는다.
- package registry 릴리즈, 외부 CI/CD runner 연결을 시작하지 않는다.
- C# 또는 Swift 포팅을 시작하지 않는다.
- 애플리케이션 레벨 priority queue, routing key, room/session semantics를 추가하지 않는다.
- 절대 성능 수치를 모든 환경의 고정 합격선으로 선언하지 않는다.
## 작업 컨텍스트
- 관련 경로: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`, `typescript/bench/stress.ts`, `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`
- 선행 작업: 수신 큐와 처리 순서 보장
- 후속 작업: 릴리즈 준비 또는 사용처별 성능 요구가 생길 때 package/runtime 정책 정리
- 현재 근거: `agent-test/runs/20260602-095911-proto-socket-stress-full.md`는 TypeScript same-language local baseline으로 roundtrip, burst, sustained, parallel, gateway profile에서 stability violations 0을 기록했다.
- 보강 필요: 현재 stress baseline은 TypeScript 중심이고 gateway profile은 실제 TCP/WS transport 수신 경로가 아니라 `onReceivedFrame` opt-in 경로 중심이다. 고성능 병렬 운용 근거로 쓰려면 언어별/transport별 full baseline과 장시간/대규모 connection 계측이 필요하다.
- 확인 필요: 없음

View file

@ -10,7 +10,7 @@
## 상태
[진행중]
[검토중]
## 구현 잠금
@ -61,25 +61,25 @@
수신 큐 도입이 프로토콜 호환성과 기존 송신 직렬화 보장을 깨지 않는지 확인한다.
- [ ] [unit-order] 모든 지원 언어에 순서 보장 테스트를 추가한다. 검증: 연속 수신된 일반 메시지와 request 메시지가 등록 순서대로 listener/handler에 전달된다.
- [ ] [slow-handler] 모든 지원 언어에 느린 request handler 테스트를 추가한다. 검증: 먼저 받은 요청의 응답이 먼저 송신 큐에 들어가며, 뒤 요청이 앞 요청을 추월하지 않는다.
- [ ] [queue-close] 모든 지원 언어에 큐 포화와 연결 종료 테스트를 추가한다. 검증: inbound queue가 꽉 찼을 때 backpressure가 적용되고, close 시 queued item과 pending request가 일관되게 취소된다.
- [ ] [rt-bench] 빠른 request-response 왕복 메시징 벤치마크를 추가한다. 검증: 지원 언어의 same-language TCP/WS 경로에서 순차와 동시 `sendRequest` 부하를 측정하고, concurrency 1/16/64/256 기준의 throughput, p50/p95/p99 latency, timeout/error count, nonce mismatch count를 기록한다. 기준선은 각 실행에서 nonce mismatch 0, response type mismatch 0, unexpected timeout 0이며, 절대 성능 수치는 환경 의존 baseline으로 저장한다.
- [ ] [burst-stress] burst inbound traffic 스트레스 테스트를 추가한다. 검증: 1k/10k 이상 연속 inbound message와 request burst에서 listener/handler dispatch 순서가 입력 순서와 일치하고, queue full 구간에서 backpressure 또는 disconnect 정책이 계약대로 동작하며, 처리 완료 후 queue/pending 상태가 비어 있다.
- [ ] [sustained-load] 지속 부하 테스트 기준선을 추가한다. 검증: 최소 30초 이상 configurable sustained request-response 부하를 실행해 처리량, p95/p99 latency, peak memory 또는 runtime별 관측 가능한 메모리 지표를 기록하고, 테스트 종료 후 close/drain/cancel cleanup이 완료된다.
- [ ] [parallel-clients] 다중 connection 병렬 스트레스 테스트를 추가한다. 검증: 여러 client connection이 동시에 request-response를 수행할 때 connection별 FIFO와 nonce 매칭이 독립적으로 유지되고, 한 connection의 느린 handler나 queue 포화가 다른 connection의 pending response 상태를 오염시키지 않는다.
- [ ] [gateway-bench] 언어별 worker gateway 성능 기준을 검증한다. 검증: 큰 payload 또는 burst traffic에서 gateway on/off 비교 결과를 기록하고, 이득이 불명확한 언어/환경은 안전한 fallback을 기본으로 둔다.
- [ ] [matrix] 전체 로컬 검증 매트릭스를 실행해 변경 후에도 동일 언어 및 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과.
- [x] [unit-order] 모든 지원 언어에 순서 보장 테스트를 추가한다. 검증: 연속 수신된 일반 메시지와 request 메시지가 등록 순서대로 listener/handler에 전달된다.
- [x] [slow-handler] 모든 지원 언어에 느린 request handler 테스트를 추가한다. 검증: 먼저 받은 요청의 응답이 먼저 송신 큐에 들어가며, 뒤 요청이 앞 요청을 추월하지 않는다.
- [x] [queue-close] 모든 지원 언어에 큐 포화와 연결 종료 테스트를 추가한다. 검증: inbound queue가 꽉 찼을 때 backpressure가 적용되고, close 시 queued item과 pending request가 일관되게 취소된다.
- [x] [rt-bench] 빠른 request-response 왕복 메시징 벤치마크를 추가한다. 검증: 지원 언어의 same-language TCP/WS 경로에서 순차와 동시 `sendRequest` 부하를 측정하고, concurrency 1/16/64/256 기준의 throughput, p50/p95/p99 latency, timeout/error count, nonce mismatch count를 기록한다. 기준선은 각 실행에서 nonce mismatch 0, response type mismatch 0, unexpected timeout 0이며, 절대 성능 수치는 환경 의존 baseline으로 저장한다.
- [x] [burst-stress] burst inbound traffic 스트레스 테스트를 추가한다. 검증: 1k/10k 이상 연속 inbound message와 request burst에서 listener/handler dispatch 순서가 입력 순서와 일치하고, queue full 구간에서 backpressure 또는 disconnect 정책이 계약대로 동작하며, 처리 완료 후 queue/pending 상태가 비어 있다.
- [x] [sustained-load] 지속 부하 테스트 기준선을 추가한다. 검증: 최소 30초 이상 configurable sustained request-response 부하를 실행해 처리량, p95/p99 latency, peak memory 또는 runtime별 관측 가능한 메모리 지표를 기록하고, 테스트 종료 후 close/drain/cancel cleanup이 완료된다.
- [x] [parallel-clients] 다중 connection 병렬 스트레스 테스트를 추가한다. 검증: 여러 client connection이 동시에 request-response를 수행할 때 connection별 FIFO와 nonce 매칭이 독립적으로 유지되고, 한 connection의 느린 handler나 queue 포화가 다른 connection의 pending response 상태를 오염시키지 않는다.
- [x] [gateway-bench] 언어별 worker gateway 성능 기준을 검증한다. 검증: 큰 payload 또는 burst traffic에서 gateway on/off 비교 결과를 기록하고, 이득이 불명확한 언어/환경은 안전한 fallback을 기본으로 둔다.
- [x] [matrix] 전체 로컬 검증 매트릭스를 실행해 변경 후에도 동일 언어 및 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과.
## 완료 리뷰
- 상태: 없음
- 요청일: 없음
- 완료 근거: contract, impl, gateway Epic은 완료되었으나 verify Epic과 고속 병렬 스트레스 기준선은 아직 완료 전이다.
- 상태: 요청됨
- 요청일: 2026-06-02
- 완료 근거: contract, impl, gateway Epic 완료 근거에 더해 `09_verify_ordering``10+09_stress_baseline` 완료 로그가 PASS로 정리되어 verify Epic과 스트레스 기준선까지 완료 후보가 되었다.
- 리뷰 필요:
- [ ] 사용자가 완료 결과를 확인했다
- [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음
- 리뷰 코멘트: 모든 기능 Task와 명시 검증이 완료 근거와 함께 충족된 것으로 보여 `[검토중]`으로 전환했다. 사용자 최종 확인과 archive 승인이 남아 있다.
## 범위 제외
@ -96,7 +96,7 @@
- Dart isolate 후보: `../dart-app-core/lib/platform/isolate_manager.dart`의 장기 실행 isolate + `SendPort`/`ReceivePort` 이벤트 패턴은 참고하되, `dart:io`/앱 전역 system 초기화/범용 broadcast 구조는 복사하지 않는다. proto-socket에는 IO 전용 상시 worker gateway와 web fallback/stub을 둔다. gateway는 isolate spawn 비용을 반복하지 않고 `seq`가 붙은 raw bytes를 받아 병렬화 가능한 순수 작업을 처리한다. user listener/request handler, `pendingRequests`, transport/write queue는 isolate로 옮기지 않고 main isolate의 receive worker에서 순서와 상태 일관성을 유지한다.
- 언어별 gateway 후보: Go는 goroutine worker pool, Kotlin은 coroutine worker pool/dispatcher, Python은 process worker 또는 asyncio fallback, TypeScript는 Node `worker_threads`/browser Web Worker를 후보로 둔다. 모든 gateway 결과는 `seq`로 reorder된 뒤 coordinator가 dispatch하며, gateway는 수신 큐와 thread-safe 상태 소유 모델을 대체하지 않는다.
- 선행 작업: 안정화 기준선에서 확인된 현재 5개 언어 구현
- 후속 작업: 다음 작업 지점은 verify Epic의 순서/느린 핸들러/큐 종료 검증과 고속 병렬 스트레스 기준선 계획이다.
- 후속 작업: 사용자 최종 완료 확인과 archive 승인 대기. 고성능 병렬 운용 성능 보강은 `agent-roadmap/milestones/high-performance-parallel-operations.md`로 분리한다.
- 완료 근거:
- [recv-contract] `agent-task/archive/2026/06/m-inbound-queue-ordering/01_contract_docs/complete.log` PASS. 검증: `agent-test/runs/20260601-105247-proto-socket-full-matrix.md`.
- [thread-model] `agent-task/archive/2026/06/m-inbound-queue-ordering/02+01_receive_thread_model/complete.log` PASS. 검증: `agent-test/runs/20260601-201443-proto-socket-full-matrix.md`.
@ -111,4 +111,13 @@
- [kotlin-gateway] `agent-task/archive/2026/06/m-inbound-queue-ordering/06_kotlin_gateway/complete.log` PASS. 검증: `agent-test/runs/20260602-041819-proto-socket-full-matrix.md`.
- [python-gateway] `agent-task/archive/2026/06/m-inbound-queue-ordering/07_python_gateway/complete.log` PASS. 검증: `cd python && python3 -m pytest -q test/test_communicator.py`, `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`, `git diff --check`.
- [typescript-gateway] `agent-task/archive/2026/06/m-inbound-queue-ordering/08_typescript_gateway/complete.log` PASS. 검증: `agent-test/runs/20260602-074418-proto-socket-full-matrix.md`.
- [unit-order] `agent-task/archive/2026/06/m-inbound-queue-ordering/09_verify_ordering/complete.log` PASS. 검증: `agent-test/runs/20260602-093257-proto-socket-full-matrix.md`, focused communicator suites PASS.
- [slow-handler] `agent-task/archive/2026/06/m-inbound-queue-ordering/09_verify_ordering/complete.log` PASS. 검증: Dart 21 tests, Go full suite, Kotlin `CommunicatorTest`, Python 20 passed, TypeScript 24 passed.
- [queue-close] `agent-task/archive/2026/06/m-inbound-queue-ordering/09_verify_ordering/complete.log` PASS. 검증: queue full backpressure, graceful close drain, pending cleanup focused suites PASS.
- [rt-bench] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `run_stress.sh --quick`, `SUMMARY|status=PASS|mode=quick|profiles=roundtrip,burst,sustained,parallel,gateway|rows=9|stability_violations=0`.
- [burst-stress] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `run_stress.sh --quick --profile roundtrip,burst,sustained,parallel`, `stability_violations=0`.
- [sustained-load] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `run_stress.sh --quick --profile roundtrip,burst,sustained,parallel`, sustained profile included.
- [parallel-clients] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `run_stress.sh --quick --profile roundtrip,burst,sustained,parallel`, parallel profile included.
- [gateway-bench] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `run_stress.sh --quick`, gateway profile included.
- [matrix] `agent-task/archive/2026/06/m-inbound-queue-ordering/10+09_stress_baseline/complete.log` PASS. 검증: `agent-test/runs/20260602-102155-proto-socket-full-matrix.md`.
- 확인 필요: 없음