diff --git a/PROMPT.md b/PROMPT.md new file mode 100644 index 0000000..228f62d --- /dev/null +++ b/PROMPT.md @@ -0,0 +1,140 @@ +# AIoT gRPC 고성능 통신 모듈 — 프로젝트 빠른 파악 + +> 이 프로젝트에 새로 투입된 당신을 위한 프롬프트입니다. +> AI 에이전트(Claude Code, Codex 등)에게 이 내용을 전달하면 프로젝트를 빠르게 이해하고 작업할 수 있습니다. + +--- + +## 프로젝트 한 줄 요약 + +**AI Agent와 IoT 디바이스 간 통신을 위해, TCP 기반 gRPC(HTTP/2)의 전송 계층을 QUIC(HTTP/3)으로 교체한 고성능 통신 모듈을 Go로 구현하고, 이를 활용한 엣지 게이트웨이 아키텍처를 설계·구현·성능 검증하는 연구 프로젝트.** + +--- + +## 핵심 정보 + +| 항목 | 내용 | +|------|------| +| **언어** | Go 1.22+ | +| **통신 프로토콜** | gRPC over HTTP/3 (QUIC) + Protocol Buffers v3 | +| **QUIC 라이브러리** | `github.com/quic-go/quic-go` | +| **비교 대상** | gRPC/HTTP3 vs gRPC/HTTP2 vs REST/HTTP2 vs REST/HTTP1.1 | +| **연구 범위** | 통신 모듈 구현 + 엣지 게이트웨이 + 6-way 정량 성능 비교 | +| **평가 시나리오** | ① IoT 데이터 전송 (수 KB~수 MB, 스트리밍) ② AI Agent RPC (수 KB, Unary, burst) | +| **네트워크 조건** | Ideal/LAN/WAN-Low/WAN-High/Lossy (tc로 시뮬레이션) | + +--- + +## 문서 구성 (읽는 순서) + +1. **`CLAUDE.md`** — 연구 방향, 동기, 목표, 평가 지표, 코드 정책. **모든 작업 시작 시 필독**. +2. **`IMPLEMENTATION.md`** — 디렉터리 구조, 네이밍, 워크플로우, Makefile, 코드 패턴. **코드 작성/수정 시 필독**. +3. **`BACKGROUND.md`** — 연구 배경 (AI Agent 트래픽 폭증, TCP 한계, QUIC 등장). **연구 동기 이해 시 참조**. +4. **`참고/SGS/README.md`** — 선행 연구 (스마트팜 해충 탐지, gRPC vs REST 비교). **차별성 파악 시 참조**. + +특별 디렉터리: +- **`docs/decisions/`** — 설계 결정 기록 (ADR). 중요한 설계 변경 전후 확인. +- **`docs/open-questions.md`** — 미해결 탐색 주제. 새 실험 기획 시 참조. +- **`src/`** — **다른 에이전트가 UI 프로그램 구현 중이므로 건드리지 말 것.** + +--- + +## 연구 동기 (왜 이 프로젝트인가) + +1. **AI Agent 격리 → 통신 폭증**: 보안을 위해 각 Agent를 컨테이너에 격리하면 IPC가 전부 네트워크 통신으로 전환되어 통신 건수가 폭증함 +2. **서브에이전트 아키텍처 → 통신 빈도 증가**: 컨텍스트 한계 극복을 위해 서브에이전트 + RAG 패턴이 표준화되면서 Agent 간/Agent-서비스 간 통신이 더 빈번해짐 +3. **24/7 가동 → 동시 트래픽 누적**: 사람이 쉴 때도 Agent는 일하므로 동시간 네트워크 사용량이 급증 + +→ TCP 기반 HTTP/2(gRPC)의 HoL Blocking, 연결 수립 비용, 연결 고정 문제가 병목이 됨 +→ QUIC(HTTP/3)이 0-RTT, 스트림 독립성, 연결 마이그레이션으로 이 문제들을 해결 가능 +→ **그러나 AIoT 환경에서의 gRPC over QUIC 실증 연구는 아직 부재함** — 이 gap을 메우는 것이 본 연구 + +--- + +## 제안 2가지 + +### 제안 ①: gRPC over QUIC 통신 모듈 +- QUIC의 0-RTT, HoL Blocking 해소, 연결 마이그레이션을 AIoT 환경에서 정량 검증 +- 6가지 시스템 간 latency(P50/P95/P99), throughput(RPS), connection overhead 비교 +- **성공 기준**: 각 측정값 최소 30회 반복, 95% 신뢰 구간 제시 + +### 제안 ②: gRPC 엣지 게이트웨이 아키텍처 +- 프로토콜 변환 (MQTT/CoAP → Protobuf) + 정적 룰 기반 서비스 라우팅 +- gRPC-QUIC 모듈을 사용해 백엔드와 통신 +- LLM 기반 동적 라우팅은 범위 밖 (정적 룰 한정) + +--- + +## 기술적 주의사항 + +### 가장 큰 리스크 +**quic-go의 `quic.Stream`과 `net.Conn` 인터페이스 호환성.** +- quic-go Stream은 `net.Conn`의 deadline 설정, LocalAddr/RemoteAddr, Close(반쪽 종료) 방식이 다름 +- 이 문제가 해결되지 않으면 QUIC 구현이 불가능함 → HTTP/2(gRPC-H2)만으로 게이트웨이 먼저 검증하고 QUIC은 별도 실험으로 분리 + +### 계층 분리 필수 +``` +Transport (QUIC/TCP) → Protocol (gRPC/HTTP) → Serialization (Protobuf/JSON) → Business Logic +``` +전송 계층은 인터페이스로 추상화하여 QUIC↔TCP 교체 가능하게 할 것. + +### 금지 사항 +- `gen/` 디렉터리 직접 수정 금지. `.proto` 수정 후 `make proto`로 재생성. +- `panic` 사용 금지 (초기화 코드 제외) +- 전역 변수 설정 금지. `config` 구조체 사용. +- 미사용 의존성 추가 금지. `go mod tidy` 후 커밋. +- **`src/` 디렉터리 수정 금지** (다른 에이전트가 UI 구현 중) + +--- + +## 자주 하는 작업 + +### 새 RPC 추가 +1. `proto/aiot/{module}/{service}.proto`에 정의 +2. `make proto` → `gen/` 생성 +3. `internal/server/`에 핸들러 구현 +4. 인터셉터(`internal/middleware/metrics.go`)로 latency 측정 자동화 +5. 단위 테스트 → 벤치마크 시나리오 추가 + +### 서버 실행 +```bash +go run ./cmd/server --transport=quic --port=50051 # gRPC over QUIC +go run ./cmd/server --transport=h2 --port=50052 # gRPC over HTTP/2 +go run ./cmd/rest-server # REST 비교군 +``` + +### 네트워크 조건 +```bash +sudo ./scripts/tc-setup.sh --delay 50ms --loss 1% --interface eth0 +sudo ./scripts/tc-reset.sh --interface eth0 +``` + +--- + +## 선행 연구(SGS) 대비 차별성 + +| 항목 | 선행 연구 | 본 연구 | +|------|----------|--------| +| 전송 계층 | HTTP/2 (TCP) | **HTTP/3 (QUIC) 추가** | +| 시나리오 | 스마트팜 단일 | **IoT + AI Agent RPC 이중** | +| 게이트웨이 | 개념 제시 | **구현·정량 검증** | +| 평가 지표 | 응답 시간, 전송량 | **+ 0-RTT, HoL 내성, 연결 마이그레이션** | +| 비교 시스템 | 3개 | **6개** | + +--- + +## 파일 상태 + +| 파일 | 목적 | 작성 완료 | +|------|------|----------| +| `CLAUDE.md` | 연구 방향·정책 | ✅ | +| `BACKGROUND.md` | 연구 배경 (발표 가능) | ✅ (1차 개선 완료) | +| `IMPLEMENTATION.md` | 구현 세부 사항 | ✅ | +| `FEEDBACK.md` | 문서 비평 | ✅ | +| `TASK_LIST.md` | 작업 리스트 | ✅ | +| `참고/SGS/README.md` | 선행 연구 | ✅ | + +## 추후 보강 예정 (부록 A 참조) +- 정량적 데이터 근거 (통신 빈도 추정치, 기존 연구 인용) +- AI Agent 트래픽 특성 구체화 (RPC 수, latency 요구사항) +- AI Agent + IoT 두 시나리오 연결 논리 강화 diff --git a/TASK_LIST.md b/TASK_LIST.md new file mode 100644 index 0000000..85f30e3 --- /dev/null +++ b/TASK_LIST.md @@ -0,0 +1,146 @@ +# 작업 리스트 (FEEDBACK.md 기반, 우선순위 순) + +> 다른 에이전트가 `src/` 디렉터리에서 UI 프로그램을 구현 중이므로 `src/`는 건드리지 않음. + +--- + +## P0 — 진행 전 반드시 해결 + +### 1. quic-go + gRPC transport interface 호환성 PoC 검증 + +- **리스크**: quic-go의 `quic.Stream`이 `net.Conn` 인터페이스를 완전히 충족하지 않을 가능성 +- **구체적 확인 사항**: + - `SetDeadline()`, `SetReadDeadline()`, `SetWriteDeadline()` 동작 여부 + - `LocalAddr()` / `RemoteAddr()` — quic-go Stream에서 Connection 정보를 가져오는 방법 + - `Close()`의 half-close 의미와 gRPC 예상 동작 차이 + - quic-go Stream을 gRPC transport에 주입하는 구체적 방법 +- **대비책**: 실패 시 HTTP/2(gRPC-H2)만으로 게이트웨이 검증을 먼저 수행하고, QUIC은 별도 실험으로 분리 +- **결과**: `docs/decisions/002-quic-grpc-compatibility-poc.md`에 기록 + +### 2. Novelty 재정의 및 문서 반영 + +- 문제: 「gRPC over QUIC 구현」만으로는 선행 연구 대비 차별성이 부족함 +- 해결 방안: + - 연구를 「**AIoT 도메인에서의 실증 연구(empirical study)**」로 포지셔닝 + - **무엇을 측정하고 증명할 것인가**를 전면에 내세움 + - (a) QUIC의 세 가지 특성(0-RTT, HoL Blocking 해소, 연결 마이그레이션)이 AIoT 환경에서 실제로 유의미한 성능 개선을 보이는가? + - (b) gRPC-QUIC 통신 모듈을 써서 엣지 게이트웨이를 구축할 때 기존 대비 measurable한 이점이 있는가? + - `CLAUDE.md`의 헤더(서문)와 2.0절(기여)을 수정 + - 선행 연구(SGS)와의 차별성 표(2.3절)를 더 구체화 + +--- + +## P1 — 구현 시작 전에 결정해야 할 사항 + +### 3. 게이트웨이 아키텍처 기여 재정의 + +- 현재: 「프로토콜 변환 + 정적 라우팅」만으로는 연구 기여로 부족 +- 해결 방안: + - **gRPC-QUIC 통합 자체**가 게이트웨이의 novelty임을 명시 + - 또는 게이트웨이의 구체적 설계 결정(예: gRPC stream을 IoT 프로토콜에 매핑하는 방식, edge/cloud 분기 로직의 구체적 설계)을 기여로 내세움 + - 게이트웨이의 정확한 아키텍처 다이어그램(데이터 흐름 포함)을 문서에 추가 +- **결정사항을 ADR로 기록**: `docs/decisions/003-gateway-architecture.md` + +### 4. MQTT/CoAP 변환 전략 정의 + +- 현재: 파일명만 있고 변환 전략 미정의 +- 결정 필요: + - MQTT message payload → Protobuf message 역직렬화? (가장 단순) + - MQTT topic 구조 → gRPC service/method에 매핑? (복잡함) + - MQTT connection → gRPC streaming session으로 변환? (가장 복잡) + - CoAP도 동일한 결정 필요 +- **권장**: P0 구현에는 MQTT만 포함하고, CoAP은 P1로 격하. MQTT는 payload 변환만 먼저 구현 +- **결과**: `docs/decisions/004-protocol-adapter-design.md`에 기록 + `IMPLEMENTATION.md`에 반영 + +### 5. 라우팅 데이터 모델 정의 + +- 현재: 「정적 룰 기반 라우팅」이라는 추상적 표현만 있음 +- 결정 필요: + - 라우팅 룰의 데이터 모델은? (입력 조건 → 대상 서비스) + - 설정 형식은? (YAML 파일 / 코드 내 map / DB 테이블) + - 런타임 변경 가능한가? (재시작 필요한가) +- **권장**: YAML 기반 단순 룰 테이블로 시작. 변경 시 재시작 필요 +- **결과**: `internal/gateway/route_table.go`의 데이터 구조 확정 + 예제 YAML 파일 추가 + +### 6. 실험 설계 강화 (CLAUDE.md 5절 수정) + +- Lossy 조건 다양화: + - 현재: 50ms + 1% loss + - 추가: 50ms + 3% loss, 100ms + 5% loss (P1) + - 최소 3%에서 QUIC과 HTTP/2의 차이가 유의미한지 확인 +- 통계적 유의성: + - 반복 횟수: count=5 → count=30 (특히 Lossy 환경) + - 신뢰 구간(95% CI) 계산 방법 명시 + - 이상치(outlier) 처리 정책 정의 +- AI Agent RPC 시나리오 KPI 조정: + - Payload Size는 이 시나리오에서 제외 (수 KB라서 직렬화 차이 미미) + - Connection Overhead / 0-RTT Resumption에 집중 +- 측정 인터셉터의 observer effect 문서화: + - 인터셉터 자체 overhead 측정 방법 추가 + - 모든 비교군에 동일 bias가 적용됨을 확인 + +### 7. 위험 관리 문서화 + +- 다음 위험 식별 및 대비책을 `CLAUDE.md`나 `docs/risks.md`에 명시: + +| 위험 | 영향 | 가능성 | 대비책 | +|------|------|--------|--------| +| quic-go + gRPC transport interface 불호환 | 프로젝트 전체 지연 | 중간 | HTTP/2만으로 게이트웨이 검증 후 QUIC 별도 실험 | +| Docker 내 tc(traffic control) 미작동 | 네트워크 조건 시뮬레이션 불가 | 낮음 | 호스트 레벨 tc 또는 네트워크 네임스페이스 분리 | +| MQTT/CoAP 어댑터 구현 범위 과다 | 게이트웨이 일정 지연 | 중간 | P1 격하 또는 MQTT만 먼저 검증 | +| Go 버전업에 따른 quic-go 호환성 이슈 | 빌드 실패 | 낮음 | go.mod에 quic-go 버전 고정 | + +--- + +## P2 — 구현과 병행 가능 + +### 8. BACKGROUND.md 전반 개선 + +- 1.3절 학원 관리 예시 → AI Agent 일반 아키텍처 다이어그램으로 교체 +- 2.2절 제목 「사람과 달리, ...」 → 「컨텍스트 메모리 한계에 따른 AI Agent 성능 저하 문제」 +- 3절 결론 강화 — 세 가지 추세 → gRPC over QUIC 연구 필요성으로의 논리적 연결 추가 +- Timeliness argument 추가: 「왜 지금 이 연구인가?」 섹션 신설 + +### 9. CLAUDE.md 세부 보강 + +- 1.4~2.1절: 세 가지 향후 연구 중 왜 HTTP/3을 선택했는지 근거 명시 +- 5.1절 비교 대상 표: REST-Cloud의 처리 위치 → 「엣지 → 클라우드 (원시 데이터)」로 통일 +- 1절 각 항목을 2-3문장 요약으로 축약 (상세는 BACKGROUND.md 참조) +- 6.4절: 측정 인터셉터 overhead 고려사항 추가 + +### 10. IMPLEMENTATION.md 보강 + +- 벤치마크 방식 역할 분담 명시: + - `benchmarks/scenarios/` (testing.B): 단일 프로세스 내 마이크로벤치마크 (직렬화 시간, 처리량) + - `cmd/benchmark-runner/`: 분산 end-to-end 측정 (P50/P95/P99 latency, RPS) + - Docker Compose 환경에서 benchmark-runner 실행 위치 +- `.golangci-lint.yaml` 추가 (errcheck, govet, staticcheck 등) +- 각 어댑터의 변환 전략을 protocol_adapter.go 인터페이스 정의 근처에 문서화 + +### 11. 문서 간 중복 제거 + +- BACKGROUND.md 2.1~2.3과 CLAUDE.md 1.1~1.3의 중복 제거 + - CLAUDE.md는 요약(각 2-3문장)으로 축소 + - BACKGROUND.md는 상세 논의로 유지 + +--- + +## 작업 진행 순서 요약 + +``` +Step 1 (P0): quic-go 호환성 PoC 검증 → docs/decisions/002 +Step 2 (P0): Novelty 재정의 → CLAUDE.md + docs/decisions/ 재작성 + │ +Step 3 (P1): 게이트웨이 기여 재정의 → docs/decisions/003 +Step 4 (P1): MQTT 변환 전략 결정 → docs/decisions/004 +Step 5 (P1): 라우팅 데이터 모델 정의 → route_table.go 설계 +Step 6 (P1): 실험 설계 강화 → CLAUDE.md 5절 수정 +Step 7 (P1): 위험 관리 문서화 → docs/risks.md + │ +Step 8 (P2): BACKGROUND.md 개선 +Step 9 (P2): CLAUDE.md 세부 보강 +Step 10 (P2): IMPLEMENTATION.md 보강 +Step 11 (P2): 문서 간 중복 제거 +``` + +> **주의**: `src/` 디렉터리는 다른 에이전트가 UI 프로그램을 구현 중이므로 수정하지 않음.