<!-- task=m-inbound-queue-ordering/05_go_gateway plan=1 tag=REVIEW_API -->

# Go Worker Gateway Follow-up 계획

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

이 계획은 `code_review_cloud_G08_0.log`의 Required 이슈만 해결한다. 구현 후 `CODE_REVIEW-cloud-G08.md`의 구현 에이전트 소유 섹션에 실제 변경 내용과 검증 stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 최종 판정, 로그화, `complete.log`, archive 이동은 code-review 전용이다.

## 배경

초기 구현은 `Communicator.OnReceivedFrame`과 worker gateway 자체는 추가했지만, 실제 TCP/WS read loop는 여전히 raw `PacketBase` bytes를 직접 `proto.Unmarshal`하고 `OnReceivedData`로 전달한다. 그 결과 `EnableInboundGateway`를 호출해도 실연결 수신 경로는 gateway를 우회한다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active `CODE_REVIEW-cloud-G08.md`의 `사용자 리뷰 요청` 섹션에 결정 필요 항목과 실행한 명령 출력을 기록한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `go-gateway`: Go goroutine worker pool gateway 후보를 적용한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-task/m-inbound-queue-ordering/05_go_gateway/plan_cloud_G08_0.log`
- `agent-task/m-inbound-queue-ordering/05_go_gateway/code_review_cloud_G08_0.log`
- `go/communicator.go`
- `go/inbound_gateway.go`
- `go/tcp_client.go`
- `go/ws_client.go`
- `go/test/communicator_test.go`

### 테스트 환경 규칙

- Go 변경 필수 검증은 `cd go && go test -count=1 ./...`.
- concurrency/gateway 보완이므로 `cd go && go test -race ./...`를 포함한다.
- 최종 검증은 전체 matrix `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`.

### 범위 결정 근거

- Go transport read path와 gateway tests만 다룬다.
- proto schema, wire format, pending/listener/request/write queue 소유 모델은 변경하지 않는다.
- parse 실패 시 기존 TCP/WS disconnect reason이 사라지지 않게 한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: 실제 transport read loop와 gateway worker pool 연결, parse error semantics, race 검증이 포함된다.

## 구현 체크리스트

- [ ] TCP/WS read loop가 gateway 부착 시 raw frame을 gateway 경로로 전달하고, gateway 미부착 시 기존 inline decode 동작을 유지한다.
- [ ] raw frame decode 실패 시 기존 TCP/WS parse error disconnect semantics가 유지되도록 error 처리 경계를 보완한다.
- [ ] 실제 TCP 또는 WS read path에서 `EnableInboundGateway`가 dispatch 순서를 보존하는 테스트를 추가한다.
- [ ] gateway read path 테스트가 `OnReceivedFrame` 직접 호출만으로 통과하지 않고 transport read loop 연결 누락을 잡을 수 있게 구성한다.
- [ ] 중간 검증으로 `cd go && go test -count=1 ./... && go test -race ./...`를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행하고 결과 기록 파일을 남긴다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_API-1] 실제 transport read path gateway 연결

#### 문제

- `TcpClient.readLoop`와 `WsClient.readLoop`가 gateway 부착 여부와 무관하게 직접 protobuf decode 후 `OnReceivedData`를 호출한다.
- 따라서 gateway는 단위 helper 경로에서만 동작하고 실제 TCP/WS 연결에서는 적용되지 않는다.

#### 해결 방법

- raw frame 처리용 communicator API를 정리해 gateway가 있으면 worker pool로 보내고, 없으면 inline decode 후 coordinator로 전달한다.
- read loop가 이 raw frame API를 호출하도록 연결한다.
- 기존 read loop의 parse error disconnect reason은 보존한다. 필요하면 raw frame API가 error를 반환하도록 바꾸거나, read loop에서 inline decode와 gateway decode 경계를 명확히 분리한다.

#### 수정 파일 및 체크리스트

- [ ] `go/communicator.go`
- [ ] `go/inbound_gateway.go`
- [ ] `go/tcp_client.go`
- [ ] `go/ws_client.go`
- [ ] `go/test/communicator_test.go`
- [ ] 필요 시 `go/inbound_gateway_test.go`

#### 테스트 작성

- `net.Pipe` 또는 기존 테스트 helper를 사용해 실제 `TcpClient.readLoop`에 raw PacketBase frame을 넣고, `EnableInboundGateway` 부착 후 listener dispatch 순서가 입력 순서와 일치하는지 확인한다.
- 필요하면 WS read path도 동일 방식으로 검증한다. 최소 하나의 실제 transport read loop는 반드시 포함한다.
- malformed frame이 들어왔을 때 기존 parse error disconnect 동작이 유지되는지 확인한다.

#### 중간 검증

```bash
cd go && go test -count=1 ./... && go test -race ./...
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `go/communicator.go` | REVIEW_API-1 |
| `go/inbound_gateway.go` | REVIEW_API-1 |
| `go/tcp_client.go` | REVIEW_API-1 |
| `go/ws_client.go` | REVIEW_API-1 |
| `go/test/communicator_test.go` | REVIEW_API-1 |
| `go/inbound_gateway_test.go` | REVIEW_API-1 |

## 최종 검증

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

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