proto-socket/agent-ops/rules/project/domain/kotlin/rules.md

domain	last_rule_review_commit	last_rule_updated_at
kotlin	7ea0b484d2	2026-06-01

kotlin

목적 / 책임

Proto Socket의 Kotlin/Android 구현체를 담당한다. JVM/Android 대상 TCP/WS/WSS 클라이언트·서버, 공통 Communicator/BaseClient 로직, 하트비트 처리를 제공한다.

포함 경로

• kotlin/src/main/kotlin/ — 구현 소스
• kotlin/src/test/ — 동일 언어 테스트 및 테스트 리소스
• kotlin/crosstest/ — 크로스 언어 테스트 (Dart.io, Dart.web, Go, Python, TypeScript와 연동). 오케스트레이터 또는 클라이언트 헬퍼
• kotlin/build.gradle.kts, kotlin/settings.gradle.kts — Gradle 빌드 설정
• kotlin/gradle/, kotlin/gradlew, kotlin/gradlew.bat — Gradle wrapper

제외 경로

• kotlin/src/main/proto/ — protocol 도메인의 Kotlin proto 복사본
• kotlin/build/, kotlin/.gradle/, kotlin/.kotlin/ — 빌드 산출물 및 로컬 캐시

주요 구성 요소

• Transport / ParserMap — 전송 추상화와 타입명 기반 파서 등록
• Communicator — 메시지 라우팅 및 요청-응답 상관관계 공통 로직
• BaseClient — 하트비트와 연결 종료 공통 처리
• TcpClient / TcpServer — TCP 클라이언트/서버
• WsClient / WsServer — OkHttp/Java-WebSocket 기반 WS/WSS 클라이언트·서버
• HeartbeatTimer — 하트비트 타이머 처리

유지할 패턴

• ./gradlew test로 테스트 실행
• ./gradlew run -PmainClass=...으로 crosstest 실행
• Dart.web 크로스 테스트는 Kotlin WS/WSS 서버가 Dart browser test를 실행하는 구조다
• PacketBase의 typeName, nonce, data, responseNonce 의미는 PROTOCOL.md와 맞춘다

다른 도메인과의 경계

• protocol: proto 타입을 사용하지만, kotlin/src/main/proto/의 스키마 복사본은 protocol 도메인
• dart/go/python/typescript: crosstest에서 상호 연동. Dart.web은 browser client runtime으로만 연동

금지 사항

• Kotlin proto 복사본에서 메시지 스키마를 변경하지 않는다
• Kotlin 구현체에 특정 상대 언어 전용 동작을 추가하지 않는다