---
domain: dart
last_rule_review_commit: 7ea0b484d2c5c73e85f4ef4b16cba20f25cb4b51
last_rule_updated_at: 2026-06-01
---

# dart

## 목적 / 책임

Proto Socket의 Dart/Flutter 구현체를 담당한다. Dart IO TCP/WS/WSS 클라이언트·서버, Flutter Web WebSocket 클라이언트, 공통 Communicator/BaseClient 로직, 하트비트 처리를 제공한다.

## 포함 경로

- `dart/lib/` — 공개 API 및 구현 (packets/ 제외)
- `dart/test/` — 동일 언어 단위/통합 테스트, browser WebSocket 테스트, WSS 테스트 인증서 fixture
- `dart/crosstest/` — 크로스 언어 테스트 (Dart.web, Go, Kotlin, Python, TypeScript와 연동). 오케스트레이터 또는 클라이언트 헬퍼
- `dart/pubspec.yaml` — 패키지 의존성
- `dart/analysis_options.yaml` — Dart 정적 분석 설정

## 제외 경로

- `dart/lib/src/packets/` — protocol 도메인의 Dart protobuf 생성 코드

## 주요 구성 요소

- `ProtobufClient` — Dart IO TCP 클라이언트 기반 클래스. web target에서는 TCP 미지원 stub
- `ProtobufServer` — Dart IO TCP 서버 기반 클래스. web target에서는 TCP 미지원 stub
- `WsProtobufClient` — 조건부 export로 Dart IO `dart:io` WebSocket과 Flutter Web `dart:html` WebSocket 클라이언트를 제공
- `WsProtobufServer` — Dart IO WS/WSS 서버 기반 클래스. web target에서는 서버 미지원 stub
- `BaseClient` / `Communicator` — 메시지 라우팅, 요청-응답 상관관계, 전송 공통 로직
- `HeartbeatMixin` — 하트비트 송수신 및 연결 종료 처리

## 유지할 패턴

- `dart pub get` 후 `dart test`로 테스트 실행
- browser WebSocket 테스트는 `dart test -p chrome test/browser_ws_*_test.dart` 형식을 사용한다
- crosstest는 상대방 언어 서버/클라이언트가 실행 중인 상태에서 수행하며, Dart.web은 browser client runtime으로만 취급한다
- conditional export 구조를 유지한다: TCP와 WebSocket server는 IO 전용, browser target은 WebSocket client만 제공한다
- Available 표시 조건: 동일 언어 테스트 + 크로스 언어 테스트 통과
- PacketBase의 `typeName`, `nonce`, `data`, `responseNonce` 의미는 PROTOCOL.md와 맞춘다

## 다른 도메인과의 경계

- **protocol**: proto 타입을 사용하지만, proto 파일과 생성된 packets 코드는 protocol 도메인
- **go/kotlin/python/typescript**: crosstest에서 상호 연동하지만, 각 구현체 내부 로직은 독립

## 금지 사항

- Dart 구현체에 Go/Kotlin 특화 로직을 추가하지 않는다
- Dart 구현체에 Python/TypeScript 특화 로직을 추가하지 않는다
- proto schema 변경 시 proto 도메인 규칙을 먼저 따른다
