toki
bdcebdeb56
- Add inbound_gateway.dart, inbound_gateway_io.dart, inbound_gateway_web.dart - Update communicator.dart and proto_socket.dart for inbound queue support - Update browser_ws_import_compile.dart and communicator_test.dart - Archive Dart gateway task (04_dart_gateway) - Create plan and code review docs for go/kotlin/python/typescript gateways - Update roadmap files (ROADMAP.md, current.md, inbound-queue-ordering.md)
111 lines
4.1 KiB
Markdown
111 lines
4.1 KiB
Markdown
<!-- task=m-inbound-queue-ordering/07_python_gateway plan=0 tag=API -->
|
|
|
|
# Python Worker Gateway 구현 계획
|
|
|
|
## 이 파일을 읽는 구현 에이전트에게
|
|
|
|
구현 후 `CODE_REVIEW-cloud-G08.md`의 구현 에이전트 소유 섹션에 실제 변경 내용과 검증 stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 최종화는 code-review 전용이다.
|
|
|
|
## 배경
|
|
|
|
`python-gateway`는 Python에서 CPU-bound decode는 process worker 후보로, 경량 전처리는 asyncio worker 후보로 분리하는 작업이다. 현재 Python은 `asyncio.Queue` receive task와 fake gateway reorder test만 있고 실제 gateway on/off 후보가 없다.
|
|
|
|
## 사용자 리뷰 요청 흐름
|
|
|
|
구현 중 user-only blocker가 있으면 active review stub의 `사용자 리뷰 요청` 섹션을 채운다.
|
|
|
|
## Roadmap Targets
|
|
|
|
- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
|
|
- Task ids:
|
|
- `python-gateway`: Python process/asyncio worker gateway 후보를 적용한다.
|
|
- Completion mode: check-on-pass
|
|
|
|
## 분석 결과
|
|
|
|
### 읽은 파일
|
|
|
|
- `agent-roadmap/current.md`
|
|
- `agent-roadmap/milestones/inbound-queue-ordering.md`
|
|
- `agent-test/local/rules.md`
|
|
- `agent-test/local/python-smoke.md`
|
|
- `agent-test/local/proto-socket-full-matrix.md`
|
|
- `python/proto_socket/communicator.py`
|
|
- `python/test/test_communicator.py`
|
|
|
|
### 테스트 환경 규칙
|
|
|
|
- Python 변경 필수 검증: `cd python && python3 -m pytest -q`.
|
|
- 최종 검증: 전체 matrix.
|
|
|
|
### 테스트 커버리지 공백
|
|
|
|
- 실제 gateway on/off, out-of-order worker completion, close/cancel, small packet fallback 검증이 없다.
|
|
|
|
### 심볼 참조
|
|
|
|
- renamed/removed symbol: none.
|
|
|
|
### 분할 판단
|
|
|
|
- `07_python_gateway`는 독립 언어 task이며 dependency 없음.
|
|
|
|
### 범위 결정 근거
|
|
|
|
- Python communicator/gateway와 tests만 수정한다. 외부 dependency 추가는 피하고 standard library `asyncio`/`concurrent.futures`를 우선한다.
|
|
|
|
### 빌드 등급
|
|
|
|
- build/review: `cloud-G08`. 이유: process/async worker와 close/cancel/order 경계가 있다.
|
|
|
|
## 구현 체크리스트
|
|
|
|
- [ ] Python gateway input/output에 내부 `seq`를 포함하고 asyncio worker 또는 process worker 후보를 추가한다.
|
|
- [ ] gateway는 decode/전처리만 수행하고 pending/listener/request/write queue 상태를 소유하지 않는다.
|
|
- [ ] 작은 packet에서는 gateway off fallback이 기존 receive coordinator path를 사용하도록 한다.
|
|
- [ ] Python tests에 out-of-order worker completion, fallback, close/cancel 순서 검증을 추가한다.
|
|
- [ ] 중간 검증으로 `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`을 실행한다.
|
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
|
|
|
### [API-1] Python gateway worker candidate
|
|
|
|
#### 문제
|
|
|
|
- `python/proto_socket/communicator.py`에는 실제 gateway 후보가 없다.
|
|
|
|
#### 해결 방법
|
|
|
|
- asyncio worker path와 CPU-bound process worker 후보를 표준 라이브러리로 구성한다.
|
|
- 결과 collector가 `seq` 순서로 기존 `enqueue_inbound`/coordinator path에 넘긴다.
|
|
|
|
#### 수정 파일 및 체크리스트
|
|
|
|
- [ ] `python/proto_socket/communicator.py`
|
|
- [ ] `python/test/test_communicator.py`
|
|
|
|
#### 테스트 작성
|
|
|
|
- out-of-order worker result가 `[1,2]`로 dispatch되는지 검증한다.
|
|
- gateway off fallback이 기존 테스트와 동일 path를 사용하는지 검증한다.
|
|
|
|
#### 중간 검증
|
|
|
|
```bash
|
|
cd python && python3 -m pytest -q test/test_communicator.py
|
|
```
|
|
|
|
## 수정 파일 요약
|
|
|
|
| 파일 | 항목 |
|
|
|------|------|
|
|
| `python/proto_socket/communicator.py` | API-1 |
|
|
| `python/test/test_communicator.py` | API-1 |
|
|
|
|
## 최종 검증
|
|
|
|
```bash
|
|
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
|
|
```
|
|
|
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|