proto-socket/agent-roadmap/milestones/high-performance-parallel-operations.md

고성능 병렬 운용 기준선과 최적화

목표

수신 큐와 처리 순서 보장 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 분석과 병목 우선순위 선정에 사용한다.

gateway 정책

• 기본값: default off. 현재 안정적으로 검증된 gateway는 TypeScript Communicator.onReceivedFrame opt-in frame-ingest 경로이며, 일반 TCP/WS transport read loop는 inline decode 경로를 기본으로 유지한다.
• default on 후보: 실제 TCP/WS 수신 경로에서 같은 payload/profile 기준 p95/p99 latency 또는 throughput이 반복 측정에서 유의미하게 개선되고, memory peak와 gateway backlog 비용이 안정성 hard gate를 해치지 않는 경우에만 후보로 둔다.
• adaptive 후보: payload가 크거나 frame ingest가 CPU-bound로 확인되는 조건에서만 별도 후보로 둔다. 해당 조건도 gateway-real-path 결과가 있어야 선언한다.
• fallback: 개선 폭이 불명확하거나 memory/backlog 비용이 크거나 close/cancel/drain 계측이 불충분하면 inline decode fallback을 기본으로 유지한다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 없음
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • 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을 기록했다.
• 완료 근거:
  • [bench-schema] agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh와 typescript/bench/stress.ts의 stress result row/table schema가 language, transport, payload bytes, client count, queue backlog, gateway backlog 필드를 기록하도록 확장되었다. 검증: cd typescript && npm run check, bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --profile gateway PASS, 결과 기록 agent-test/runs/20260602-112945-proto-socket-stress-quick.md.
  • [cross-baseline] run_stress.sh --profile cross가 Dart/Go/Kotlin/Python/TypeScript 서버/클라이언트 방향에서 TCP/WS와 concurrency 1/16/64/256 조합을 별도 실행하도록 정리되었다. 검증: agent-test/runs/20260602-194252-proto-socket-stress-quick-cross.md, agent-test/runs/20260602-200010-proto-socket-full-matrix.md, 완료 로그 agent-task/archive/2026/06/m-high-performance-parallel-operations/02+01_cross_baseline/complete.log.
  • [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full roundtrip/payload baseline이 required SKIP 없이 stability hard gate를 통과했다. 지연 사유였던 Kotlin TCP delayed-ACK/TCP_NODELAY 부재, Kotlin WS frame별 coroutine launch에 따른 FIFO 불안정, Go WS 기본 32KiB read limit, Kotlin server-side listener 설치 전 초기 frame 소비 race는 TcpClient.tcpNoDelay, Kotlin WS 단일 receive queue, Go WS SetReadLimit(MaxPacketSize), Kotlin stress server setup barrier로 제거했다. 검증: agent-test/runs/20260603-062724-proto-socket-stress-full.md PASS.
  • [payload-matrix] Dart, Go, Kotlin, Python, TypeScript stress harness가 quick 1KB/64KB와 full 1KB/64KB/1MB payload rows를 기록하고, Python WS 1MB 회귀를 통과하도록 정리되었다. 검증: agent-test/runs/20260602-205755-proto-socket-stress-full.md, agent-test/runs/20260602-205849-proto-socket-full-matrix.md, cd python && python3 -m pytest -q, git diff --check, 완료 로그 agent-task/archive/2026/06/m-high-performance-parallel-operations/03+01_payload_matrix/complete.log.
  • [gateway-threshold] gateway 기본 정책은 default off로 선언했다. 실제 TCP/WS 수신 경로에서 p95/p99 또는 throughput 개선이 반복 측정되고 memory/backlog 비용이 안정적일 때만 default on/adaptive 후보로 승격하며, 이득이 불명확하거나 cleanup 계측이 부족하면 inline decode fallback을 유지한다.
  • [burst-100k], [parallel-1k], [soak-load] Dart/Go/Kotlin/Python/TypeScript stress harness가 full load profile 축을 100k burst, 128/512/1024 clients, 30초/5분/30분 sustained 후보로 확장했다. 검증: agent-test/runs/20260602-232000-proto-socket-stress-full.md는 Dart/Go/Python TCP 축에서 hard gate 위반 0을 기록했고, TypeScript 512/1024 client 회귀는 agent-test/runs/20260603-015953-proto-socket-stress-full.md에서 0 violation PASS로 재확인되었다.
  • [slow-mix] Dart, Go, Kotlin, Python, TypeScript stress harness에 빠른/느린 handler 혼합 부하 profile이 추가되었다. 검증: agent-test/runs/20260603-035342-proto-socket-stress-quick.md는 Dart/Python/TypeScript TCP slow-mix PASS와 Go deferred를 기록했고, agent-test/runs/20260603-035352-proto-socket-stress-quick.md는 Kotlin TCP/WS deferred를 병목 후보로 기록했다.
  • [matrix] slow-mix 작업 후 전체 로컬 검증 매트릭스가 프로토콜 호환성과 크로스 언어 통신을 유지했다. 검증: agent-test/runs/20260603-035403-proto-socket-full-matrix.md PASS.
• 진행 근거:
  • [gateway-real-path] 실제 transport 수신 경로 benchmark는 큰 작업으로 분리해 agent-task/m-high-performance-parallel-operations/06_gateway_real_path/PLAN-cloud-G07.md에 구현 계획과 review stub을 만들었다.
  • [gateway-cleanup] gateway worker close/cancel/drain 계측은 gateway-real-path 완료 후 진행하는 큰 작업으로 분리해 agent-task/m-high-performance-parallel-operations/07+06_gateway_cleanup/PLAN-cloud-G06.md에 구현 계획과 review stub을 만들었다.
• 보강 필요: gateway 실제 transport 수신 경로 baseline, gateway cleanup 계측, Go/Kotlin slow-mix deferred 축, 언어별 병목 리포트와 regression gate가 남아 있다.
• 확인 필요: 없음