toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
proto-socket/agent-task/m-inbound-queue-ordering/03+02_gateway_contract/PLAN-cloud-G06.md
toki a9480c5afb feat: implement inbound queue ordering across all language implementations 
- Add gateway contract for inbound queue ordering (03+02_gateway_contract)
- Update receive thread model across Dart, Go, Kotlin, Python, TypeScript
- Implement queue ordering logic in BaseClient and Communicator
- Add comprehensive tests for queue ordering in all languages
- Update documentation (PORTING_GUIDE, PROTOCOL, README)
- Archive task completion logs for completed subtasks
2026-06-02 05:36:52 +09:00

7.1 KiB
Raw Blame History

Worker Gateway 계약 계획

이 파일을 읽는 구현 에이전트에게

이 계획은 구현 에이전트가 읽고 실행한다. 구현 후 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션에 실제 변경 내용, 검증 명령, stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 사용자 결정, 사용자 소유 환경, scope 충돌로 막히면 review stub의 사용자 리뷰 요청 섹션을 채우고 중단한다. complete.log 작성, archive 이동, 최종 판정은 code-review 전용이다.

배경

Milestone은 대량 raw packet 처리와 decode/전처리를 worker gateway 후보로 분리하되, stateful dispatch는 receive coordinator가 소유해야 한다. gateway-contract는 실제 worker 구현 전에 gateway가 어떤 일을 할 수 없고, 어떤 순서 복원 책임을 coordinator에 남겨야 하는지 문서와 테스트 anchor로 고정한다.

사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active CODE_REVIEW-cloud-G06.md의 사용자 리뷰 요청 섹션에 결정 필요 항목과 실행한 명령 출력을 기록한다. code-review가 정당성을 검토하고 실제 USER_REVIEW.md 작성 여부를 판단한다.

Roadmap Targets

  • Milestone: agent-roadmap/milestones/inbound-queue-ordering.md
  • Task ids:
    • gateway-contract: worker gateway 계약을 문서화한다.
  • Completion mode: check-on-pass

분석 결과

읽은 파일

  • agent-roadmap/milestones/inbound-queue-ordering.md
  • agent-test/local/rules.md
  • agent-test/local/proto-socket-full-matrix.md
  • PROTOCOL.md
  • PORTING_GUIDE.md
  • dart/lib/src/communicator.dart
  • go/communicator.go
  • kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt
  • python/proto_socket/communicator.py
  • typescript/src/communicator.ts
  • typescript/test/communicator.test.ts

테스트 환경 규칙

  • test_env: local
  • 적용 규칙: agent-test/local/rules.md, agent-test/local/proto-socket-full-matrix.md
  • gateway 계약은 protocol/API 수준의 concurrency 경계이므로 최종 검증은 full matrix다.

테스트 커버리지 공백

  • gateway on/off나 seq reorder 테스트는 아직 없다.
  • TypeScript에는 write queue 포화 테스트가 있으나 gateway가 stateful dispatch를 소유하지 않는다는 테스트는 없다.
  • 이 subtask는 gateway 구현을 만들지 않고, receive coordinator가 seq reorder와 dispatch를 소유한다는 계약 및 future-test anchor를 추가한다.

심볼 참조

  • rename/remove 없음.
  • 현재 gateway 관련 symbol 없음. 새 API를 만들지 않는 것이 기본이다.

분할 판단

  • 이 subtask는 02+01_receive_thread_model 완료 뒤 수행한다. receive coordinator가 없으면 gateway 경계가 추상 문서에 머물기 때문이다.
  • 실제 gateway 구현은 Milestone의 [gateway] Epic으로 남긴다.

범위 결정 근거

  • Dart isolate, Go worker pool, Kotlin dispatcher, Python process pool, TypeScript worker_threads/Web Worker 구현은 하지 않는다.
  • packet schema와 transport framing은 변경하지 않는다.
  • 테스트는 gateway 구현을 요구하지 않는 coordinator ownership/seq ordering anchor 위주로 둔다.

빌드 등급

  • build: cloud-G06, review: cloud-G06
  • 이유: 문서와 테스트 anchor 중심이지만 향후 worker 병렬화의 concurrency 경계를 고정한다.

구현 체크리스트

  • PORTING_GUIDE.md에 worker gateway 계약을 추가한다. gateway는 raw bytes/decode/순수 전처리만 수행하고 listener/request handler/pending map/write queue를 소유하지 않는다고 명시한다.
  • PROTOCOL.md 또는 PORTING_GUIDE.md에 seq 기반 reorder와 coordinator 단독 dispatch 책임을 명시한다. wire field 추가가 아니라 내부 구현 sequence임을 분명히 한다.
  • receive coordinator 테스트에 gateway 결과가 out-of-order로 도착해도 dispatch/response enqueue가 입력 seq 순서를 따른다는 future-proof hook 또는 fake gateway 테스트를 추가한다.
  • 최종 검증으로 bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all을 실행한다.
  • CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

[API-1] Gateway Boundary Contract

문제

  • agent-roadmap/milestones/inbound-queue-ordering.md는 gateway 후보를 상세히 적지만, public guide에는 gateway가 stateful dispatch를 소유하면 안 된다는 기준이 없다.
  • 현재 communicator들은 stateful routing과 pending response matching을 직접 갖고 있다. 예: go/communicator.go:255, python/proto_socket/communicator.py:198, typescript/src/communicator.ts:258.

해결 방법

PORTING_GUIDE.md에 Worker gateway boundary 섹션을 추가한다.

Before:

PORTING_GUIDE.md:14
### 반드시 유지해야 하는 구조

After:

### Worker gateway boundary

- Gateway input/output carries an internal `seq` assigned by the read side.
- Gateway may parse raw bytes or perform pure preprocessing only.
- The receive coordinator owns reorder-by-seq, pending response matching, listener dispatch, request handler execution, and automatic response enqueue.

테스트는 실제 worker 구현 없이 fake gateway/reorder helper를 통해 coordinator가 seq 순서를 보존하는 anchor를 둔다. 구현체가 아직 gateway를 지원하지 않는 언어는 gateway off fallback에서도 같은 coordinator path를 사용해야 한다.

수정 파일 및 체크리스트

  • PORTING_GUIDE.md
  • 필요 시 PROTOCOL.md에 internal seq가 wire format이 아니라 구현 내부 값임을 짧게 명시
  • 각 언어 coordinator 테스트 파일 중 02+01_receive_thread_model에서 만든 fake inbound/gateway hook 위치

테스트 작성

테스트를 작성한다. 언어별 receive coordinator가 fake decoded result를 seq=2, seq=1 순서로 받아도 listener/request response enqueue는 1, 2 순서로 발생하는지 확인한다. gateway API가 아직 없는 언어는 private test hook 또는 helper를 사용하고 public API를 만들지 않는다.

중간 검증

rg --sort path -n "gateway|seq|receive coordinator|stateful dispatch|pending response" PROTOCOL.md PORTING_GUIDE.md dart/test go/test kotlin/src/test python/test typescript/test

기대 결과: 문서와 테스트에 gateway 경계와 seq 순서 anchor가 검색된다.

수정 파일 요약

파일 항목
PORTING_GUIDE.md API-1
PROTOCOL.md API-1
언어별 coordinator 테스트 파일 API-1

최종 검증

bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all

기대 결과: exit code 0, matrix 결과 파일의 최종 결과값 PASS.

모든 코드 변경 완료 후 반드시 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.