<!-- task=tls_crosstest plan=0 tag=TLS_CROSSTEST -->

# Code Review Reference - TLS_CROSSTEST

## 개요

date=2026-04-26
task=tls_crosstest, plan=0, tag=TLS_CROSSTEST

## 이 파일을 읽는 리뷰 에이전트에게

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료 후 반드시 아래 순서로 아카이브하세요.

1. `CODE_REVIEW.md` → `code_review_0.log` (N = 기존 code_review_*.log 수)
2. `PLAN.md` → `plan_0.log` (M = 기존 plan_*.log 수)
3. PASS인 경우 `complete.log` 작성 후 종료. WARN/FAIL인 경우 새 `PLAN.md` + `CODE_REVIEW.md` 스텁 작성.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [TLS_CROSSTEST-1] Dart 클라이언트 파일 — TLS 모드 추가 | [x] |
| [TLS_CROSSTEST-2] Go 클라이언트 파일 — TLS 모드 추가 | [x] |
| [TLS_CROSSTEST-3] Kotlin 클라이언트 파일 — TLS 모드 추가 | [x] |
| [TLS_CROSSTEST-4] Python 클라이언트 파일 — TLS 모드 추가 | [x] |
| [TLS_CROSSTEST-5] TypeScript 클라이언트 파일 — TLS 모드 추가 | [x] |
| [TLS_CROSSTEST-6] Dart orchestrator 3개 — TLS phase 추가 | [x] |
| [TLS_CROSSTEST-7] Go orchestrator 3개 — TLS phase 추가 | [x] |
| [TLS_CROSSTEST-8] Kotlin orchestrator 4개 — TLS TCP phase 추가 | [x] |
| [TLS_CROSSTEST-9] Python orchestrator 4개 — TLS phase 추가 | [x] |
| [TLS_CROSSTEST-10] TypeScript orchestrator 4개 — TLS phase 추가 | [x] |

## 계획 대비 변경 사항

- Kotlin server orchestrator는 최초 PLAN 일부에 WSS 항목이 섞여 있었으나, 배경/체크포인트의 "Kotlin WsServer TLS 미지원" 규칙에 맞춰 TLS TCP phase만 추가했다.
- Kotlin 클라이언트를 Gradle subprocess로 실행하는 orchestrator(`dart_kotlin`, `go_kotlin`, `python_kotlin`, `typescript_kotlin`)는 cold start가 20초를 넘을 수 있어 timeout을 60초로 늘렸다.
- Python crosstest 클라이언트는 TLS close가 완료 후 hang 되는 경우가 있어 검증 완료 후 `client.close()`를 1초 timeout으로 감쌌다.
- Kotlin server/Python client 조합에서 request listener 등록 전 request가 도착하는 race를 피하기 위해 Python crosstest 클라이언트에 연결 직후 50ms delay를 추가했다.
- `kotlin_python` WS phase는 같은 포트에서 `WsServer` 재시작이 timeout 되는 경우가 있어 `kotlin_typescript` 패턴처럼 하나의 WS 서버에서 send-push와 requests를 연속 실행하도록 맞췄다.

## 주요 설계 결정

- 각 server orchestrator는 자기 언어의 test cert fixture를 사용한다. 단 Go server orchestrator는 기존 `go_dart.go`와 동일하게 Go 패키지에 cert fixture가 없어 `dart/test/certs`를 사용한다.
- Kotlin server row는 WSS를 추가하지 않고 TLS TCP만 검증한다.
- 클라이언트 helper는 기존 TCP/WS 구조를 유지하고 `--cert`가 필요한 secure mode에서만 trust context/CA를 구성한다.

## 리뷰어를 위한 체크포인트

- **포트 충돌 없음**: 포트 배정표의 신규 TLS TCP / WSS 포트(볼드체)가 각 파일의 기존 TCP/WS 포트와 겹치지 않는지 확인.
- **인증서 경로 일관성**: 각 언어 orchestrator가 자신의 `test/certs/server.crt` + `server.key`를 사용하고, `--cert` 인수로 클라이언트에 전달하는지 확인.
- **클라이언트 `--mode` 확장**: 1-5번 클라이언트 파일 전체에서 `"tls"` / `"wss"` case가 기존 `"tcp"` / `"ws"` 구조와 동일한 패턴으로 추가됐는지 확인.
- **`buildClientTLS` / `buildClientSslContext` 헬퍼 복사 정확성**: Go 3개 클라이언트 파일과 Kotlin 4개 클라이언트 파일에 복사된 헬퍼가 기준 파일 (`dart_go_client/main.go`, `tls_support` TestHelpers.kt)과 일치하는지 확인.
- **TypeScript `typescript_kotlin` orchestrator**: WSS 없는 TLS TCP 2 phase만 포함됐는지 확인 (`typescript_kotlin_client.ts` 에 `wss` 케이스는 있어도 orchestrator에서 WSS phase를 호출하지 않음).
- **Push 메시지 검증 문자열**: 각 클라이언트 파일이 올바른 서버 언어명을 포함한 push 문자열을 검증하는지 확인 (예: `python_dart_client.dart` → `'push from python server'`).
- **의존 관계 순서**: 1단계(클라이언트 1-5) 완료 후 2단계(orchestrator 6-10)가 구현됐는지 확인.

## 검증 결과

아래 명령들은 2026-04-26에 실행했다. Gradle/Go가 필요한 조합은 로컬 SDK 경로를 환경 변수로 지정했다.

### TLS_CROSSTEST-1 중간 검증
```
$ cd dart && dart analyze crosstest/kotlin_dart_client.dart crosstest/python_dart_client.dart crosstest/typescript_dart_client.dart
No issues found!
```

### TLS_CROSSTEST-2 중간 검증
```
$ cd go && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod \
  go build ./crosstest/kotlin_go_client ./crosstest/python_go_client ./crosstest/typescript_go_client
(exit 0)
```

### TLS_CROSSTEST-3 중간 검증
```
$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle \
  ./gradlew compileCrosstestKotlin
BUILD SUCCESSFUL
```

### TLS_CROSSTEST-4 중간 검증
```
$ python3 -m py_compile python/crosstest/dart_python_client.py \
  python/crosstest/go_python_client.py \
  python/crosstest/kotlin_python_client.py \
  python/crosstest/typescript_python_client.py
(exit 0)
```

### TLS_CROSSTEST-5 중간 검증
```
$ cd typescript && npx tsc --noEmit
(exit 0)
```

### TLS_CROSSTEST-6 중간 검증
```
$ cd dart && dart analyze crosstest/dart_kotlin.dart crosstest/dart_python.dart crosstest/dart_typescript.dart
No issues found!

$ cd dart && dart run crosstest/dart_python.dart
PASS all dart-server/python-client crosstests passed

$ cd dart && dart run crosstest/dart_typescript.dart
PASS all dart-server/typescript-client crosstests passed

$ cd dart && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 dart run crosstest/dart_kotlin.dart
PASS all dart-server/kotlin-client crosstests passed
```

### TLS_CROSSTEST-7 중간 검증
```
$ cd go && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod \
  go run ./crosstest/go_python.go
PASS all go-server/python-client crosstests passed

$ cd go && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod \
  go run ./crosstest/go_typescript.go
PASS all go-server/typescript-client crosstests passed

$ cd go && env PATH=/config/go-sdk/go/bin:$PATH JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod \
  go run ./crosstest/go_kotlin.go
PASS all go-server/kotlin-client crosstests passed
```

### TLS_CROSSTEST-8 중간 검증
```
$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinDartKt
PASS all kotlin-server/dart-client crosstests passed

$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinGoKt
PASS all kotlin-server/go-client crosstests passed

$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle PATH=/config/go-sdk/go/bin:$PATH \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinPythonKt
PASS all kotlin-server/python-client crosstests passed

$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinTypescriptKt
PASS all kotlin-server/typescript-client crosstests passed
```

### TLS_CROSSTEST-9 중간 검증
```
$ python3 -m py_compile python/crosstest/python_dart.py python/crosstest/python_go.py \
  python/crosstest/python_kotlin.py python/crosstest/python_typescript.py
(exit 0)

$ cd python && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod python3 -m crosstest.python_go
PASS all python-server/go-client crosstests passed

$ cd python && python3 -m crosstest.python_typescript
PASS all python-server/typescript-client crosstests passed

$ cd python && python3 -m crosstest.python_dart
PASS all python-server/dart-client crosstests passed

$ cd python && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 python3 -m crosstest.python_kotlin
PASS all python-server/kotlin-client crosstests passed
```

### TLS_CROSSTEST-10 중간 검증
```
$ cd typescript && npx tsc --noEmit
(exit 0)

$ cd typescript && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod node --import tsx crosstest/typescript_go.ts
PASS all typescript-server/go-client crosstests passed

$ cd typescript && node --import tsx crosstest/typescript_python.ts
PASS all typescript-server/python-client crosstests passed

$ cd typescript && node --import tsx crosstest/typescript_dart.ts
PASS all typescript-server/dart-client crosstests passed

$ cd typescript && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 node --import tsx crosstest/typescript_kotlin.ts
PASS all typescript-server/kotlin-client crosstests passed
```

### 최종 검증
```
$ cd dart && dart run crosstest/dart_kotlin.dart
PASS all dart-server/kotlin-client crosstests passed

$ cd dart && dart run crosstest/dart_python.dart
PASS all dart-server/python-client crosstests passed

$ cd dart && dart run crosstest/dart_typescript.dart
PASS all dart-server/typescript-client crosstests passed

$ cd go && env PATH=/config/go-sdk/go/bin:$PATH GOCACHE=/tmp/go-build GOMODCACHE=/tmp/go-mod \
  go run ./crosstest/go_kotlin.go && go run ./crosstest/go_python.go && go run ./crosstest/go_typescript.go
PASS all go-server/kotlin-client crosstests passed
PASS all go-server/python-client crosstests passed
PASS all go-server/typescript-client crosstests passed

$ cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinDartKt && \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinGoKt && \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinPythonKt && \
  ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinTypescriptKt
PASS all kotlin-server/dart-client crosstests passed
PASS all kotlin-server/go-client crosstests passed
PASS all kotlin-server/python-client crosstests passed
PASS all kotlin-server/typescript-client crosstests passed

$ cd python && python3 -m crosstest.python_dart && python3 -m crosstest.python_go && \
  python3 -m crosstest.python_kotlin && python3 -m crosstest.python_typescript
PASS all python-server/dart-client crosstests passed
PASS all python-server/go-client crosstests passed
PASS all python-server/kotlin-client crosstests passed
PASS all python-server/typescript-client crosstests passed

$ cd typescript && node --import tsx crosstest/typescript_dart.ts && \
  node --import tsx crosstest/typescript_go.ts && \
  node --import tsx crosstest/typescript_kotlin.ts && \
  node --import tsx crosstest/typescript_python.ts
PASS all typescript-server/dart-client crosstests passed
PASS all typescript-server/go-client crosstests passed
PASS all typescript-server/kotlin-client crosstests passed
PASS all typescript-server/python-client crosstests passed
```