From 2e565db65b1956c56ca866de0a20cad0cd395eea Mon Sep 17 00:00:00 2001 From: Godopu Date: Thu, 7 May 2026 01:32:31 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=ED=94=84=EB=A1=9C=EC=A0=9D=ED=8A=B8=20?= =?UTF-8?q?README=20=EC=B6=94=EA=B0=80=20(=EB=A3=A8=ED=8A=B8=20+=20src/)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 두 README의 역할을 분리한다: - README.md (루트): 프로젝트 1페이지 overview - 핵심 기여, 비교 대상, 워크로드 시나리오, KPI 요약 - 네트워크 제어 단계 (Phase 1 tc · Phase 2 mininet) - 문서 안내 표 (CLAUDE.md / IMPLEMENTATION.md / BACKGROUND.md / SGS) - 구현 코드 실행은 src/README.md로 위임 - src/README.md: 구현 코드 가이드 - Phase 0~6 진행 상태 체크리스트 - 사전 요구사항 (Go 1.22+, UTF-8 터미널, tc) - 빌드/실행 (go run ./cmd/benchcli) - src/ 디렉터리 구조와 각 파일 역할 - UI 사용법 (화면 흐름·키 바인딩·파라미터 범위) - mock 시뮬레이터 가정과 실측 전환 경로 - 트러블슈팅 (한글·색상·폰트 등) Co-Authored-By: Claude Opus 4.7 --- README.md | 91 +++++++++++++++++++++++++ src/README.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 275 insertions(+) create mode 100644 README.md create mode 100644 src/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bbdaa9f --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# AIoT gRPC 고성능 통신 모듈 + +> AI Agent 및 AIoT 환경에서 고성능·경량 서비스 간 통신을 위한 **gRPC over HTTP/3 (QUIC) 통신 모듈**과 **엣지 게이트웨이** 설계·구현·성능 검증 연구 프로젝트. + +## 핵심 기여 + +1. **HTTP/3 (QUIC) 전송 계층을 채택한 gRPC 통신 모듈**을 AIoT 환경에서 실증 +2. 위 모듈을 활용해 AI Agent 통신과 IoT 프로토콜을 통합 처리하는 **엣지 게이트웨이 아키텍처** 제안 + +## 비교 대상 시스템 + +| ID | 전송 | 직렬화 | 비고 | +|----|------|--------|------| +| `rest-h2` | HTTP/2 (TCP+TLS) | JSON | 베이스라인 | +| `grpc-h2` | HTTP/2 (TCP+TLS) | Protobuf | 선행 연구 (SGS) 확인 | +| `grpc-h3` | HTTP/3 (QUIC+TLS1.3) | Protobuf | **본 연구 제안** | + +## 워크로드 시나리오 + +| 이름 | 메시지 크기 | 횟수 | 의도 | +|------|-----------|------|------| +| **Small-Many** | 1 KB | 10,000회 / 디바이스 | AI Agent RPC 패턴 | +| **Large-Few** | 1 MB | 50회 / 디바이스 | IoT 이미지 전송 (해충 탐지 ROI) | + +## 측정 지표 (KPI) + +- Latency P50 / P95 / P99 +- Throughput (RPS) +- 데이터 전송량 (Payload Size) +- 성공률 (패킷 손실 환경 내구성) +- 연결 수립 시간 (Connection Overhead) +- 0-RTT Resumption · HoL Blocking 내성 (Phase 2) + +## 네트워크 제어 단계 + +| 단계 | 도구 | 범위 | +|-----|------|------| +| **Phase 1 (현재 계획)** | Linux `tc netem` | 단일 NIC 구간의 지연·손실·대역폭 제어 | +| **Phase 2 (예정)** | Mininet | SDN 스위치 기반 다중 홉 토폴로지, 다중 디바이스 동시 시뮬레이션 | + +## 프로젝트 구조 + +``` +. +├── README.md # (본 파일) 프로젝트 개요 — 연구 목적·비교 대상·KPI +├── CLAUDE.md # 연구 방향·동기·목표·평가 지표·코드 정책 +├── IMPLEMENTATION.md # 디렉터리 구조·네이밍·워크플로우·코드 패턴 +├── BACKGROUND.md # 연구 수행 배경 (AI Agent 시대의 통신 인프라 변화) +├── 참고/ +│ └── SGS/ # 선행 연구 (스마트팜 해충 탐지, gRPC vs REST/HTTP-2) +└── src/ # 구현 코드 — 빌드/실행/UI 가이드는 src/README.md + └── README.md +``` + +## 구현 코드 실행 + +구현 디렉터리(`src/`)는 자체 README와 빌드 가이드를 제공한다. + +→ **[`src/README.md`](src/README.md)** 에서 다음을 확인할 수 있다: +- 사전 요구사항 (Go 버전, 터미널 환경) +- Terminal UI 데모 빌드 및 실행 방법 +- UI 화면 흐름·키 바인딩·조절 가능한 파라미터 +- 디렉터리 구조 (`cmd/`, `internal/ui/`) +- mock 시뮬레이터의 가정과 실측 전환 경로 +- Phase별 구현 진행 상태 + +## 진행 상태 (연구 단계) + +- [x] 연구 방향 문서화 (`CLAUDE.md`, `BACKGROUND.md`) +- [x] 구현 가이드 분리 (`IMPLEMENTATION.md`) +- [x] 테스트베드 계획 수립 +- [x] Phase 0 — Terminal UI 데모 (자세한 사항: `src/README.md`) +- [ ] Phase 1 — Proto + gRPC/REST 서버, tc 통합, 벤치마크 러너 +- [ ] Phase 2 — gRPC over QUIC 전송 계층 + Mininet 환경 + +## 문서 안내 + +작업 종류에 따라 참조할 문서: + +| 상황 | 우선 참조 | +|------|----------| +| 프로젝트 개요·연구 목적 | 본 README | +| 연구 방향·동기·평가 지표 | [`CLAUDE.md`](CLAUDE.md) | +| 디렉터리·네이밍·코드 패턴·작업 분담 | [`IMPLEMENTATION.md`](IMPLEMENTATION.md) | +| 연구 시작의 구조적 배경 (발표 자료 추출 가능) | [`BACKGROUND.md`](BACKGROUND.md) | +| 선행 연구 | [`참고/SGS/README.md`](참고/SGS/README.md) | +| **빌드·실행·UI 사용법** | [`src/README.md`](src/README.md) | + +## 라이선스 / 안내 + +본 프로젝트는 연구 목적의 프로토타입입니다. 프로덕션 환경의 안정성·보안·가용성을 보장하지 않습니다. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..c9a7f54 --- /dev/null +++ b/src/README.md @@ -0,0 +1,184 @@ +# `src/` — 구현 코드 + +본 디렉터리는 **AIoT gRPC 고성능 통신 모듈** 프로젝트의 구현 코드 루트다. +프로젝트 전체 개요·연구 목적·비교 대상은 [상위 디렉터리의 `README.md`](../README.md)를, 연구 방향과 평가 지표는 [`../CLAUDE.md`](../CLAUDE.md)를 참고한다. + +--- + +## 1. 현재 구현 단계 + +현재 빌드는 **Phase 0 — Terminal UI 데모**다. 실제 gRPC/REST 서버나 `tc` 연동 없이, 파라미터에 반응하는 시뮬레이션 값으로 최종 목표 화면을 가시화한다. + +| Phase | 상태 | 내용 | +|------|------|------| +| **0. Demo UI** | ✅ 완료 | Bubble Tea 기반 TUI · mock 시뮬레이터 | +| 1. Proto + gRPC 서버/클라이언트 | ☐ | `proto/`, `cmd/server`, `cmd/client` | +| 2. REST 비교군 | ☐ | `cmd/rest-server`, `internal/client/rest_client.go` | +| 3. gRPC over QUIC 전송 계층 | ☐ | `internal/transport/quic_*.go` | +| 4. tc 스크립트 + 벤치마크 러너 | ☐ | `scripts/tc-*.sh`, `cmd/benchmark-runner` | +| 5. UI ↔ 실측 데이터 연결 | ☐ | `internal/ui/simulator.go` 교체 | +| 6. Mininet 토폴로지 | ☐ | Phase 2 평가 환경 | + +--- + +## 2. 사전 요구사항 + +- **Go 1.22+** (현재 빌드는 1.26에서 검증됨) +- 256색 / UTF-8 지원 터미널 +- (Linux, Phase 1+) `iproute2` 패키지의 `tc` 명령 + +```bash +go version # 1.22 이상 확인 +``` + +--- + +## 3. 빌드 및 실행 + +### 3.1. Terminal UI 데모 + +```bash +# 본 src/ 디렉터리에서 +go mod tidy # 최초 1회 의존성 다운로드 +go run ./cmd/benchcli # 즉시 실행 + +# 또는 바이너리 빌드 +go build -o ../bin/benchcli ./cmd/benchcli +../bin/benchcli +``` + +### 3.2. 검증 + +```bash +go vet ./... # 정적 분석 +go build ./... # 전체 컴파일 +go test ./... # (테스트 추가 후) 단위·통합 테스트 +``` + +--- + +## 4. 디렉터리 구조 (src/) + +``` +src/ +├── go.mod # 모듈명: aiot-grpc-bench, Go 1.22 +├── go.sum +│ +├── cmd/ +│ └── benchcli/ +│ └── main.go # Terminal UI 진입점 +│ +└── internal/ + └── ui/ # Bubble Tea + Lipgloss 기반 TUI + ├── app.go # Model + Update + View dispatcher + ├── types.go # Config / Result / RunState 정의 + ├── styles.go # Lipgloss 색상·스타일 + ├── components.go # progressBar / sparkline / slider / formatBytes + ├── simulator.go # ★ mock 시뮬레이터 (Phase 5에서 교체 예정) + ├── screen_menu.go # 메인 메뉴 + ├── screen_config.go # 시나리오·네트워크·시스템 설정 + ├── screen_running.go # 실시간 진행 화면 + ├── screen_results.go # 비교 차트 화면 + └── screen_about.go # 테스트베드 정보 +``` + +향후 Phase 1 이후 추가될 디렉터리는 [`../IMPLEMENTATION.md`](../IMPLEMENTATION.md) 1절(프로젝트 구조)을 따른다(`proto/`, `gen/`, `internal/transport/`, `internal/server/`, `internal/gateway/` 등). + +--- + +## 5. UI 사용법 + +### 5.1. 화면 흐름 + +``` +[메인 메뉴] + │ + ├─ 새 실험 시작 ─→ [Config] ─→ [Running] ─→ [Results] + │ │ + │ └─ r: 같은 조건 재실행 + │ └─ n: 새 실험 + │ + └─ 테스트베드 정보 ─→ [About] +``` + +### 5.2. 키 바인딩 + +| 키 | 동작 | +|----|------| +| `↑/↓` `j/k` | 항목 이동 | +| `←/→` `h/l` | 파라미터 값 조정 | +| `Space` | 비교 시스템 선택 토글 | +| `Enter` | 선택 / 실험 시작 | +| `r` | (결과 화면) 같은 조건으로 재실행 | +| `n` | (결과 화면) 새 실험 시작 | +| `Esc` | 한 단계 뒤로 / 진행 중단 | +| `q` `Ctrl+C` | 종료 | + +### 5.3. 조절 가능한 파라미터 + +| 파라미터 | 범위 | 단위/단계 | +|---------|-----|----------| +| 시나리오 | Small-Many / Large-Few | 토글 | +| 링크 지연 (편도) | 0 – 500 | ms (10ms 단위) | +| 패킷 손실율 | 0.0 – 5.0 | % (0.5% 단위) | +| 대역폭 | 1, 5, 10, 25, 50, 100, 250, 500, 1000 | Mbps (이산) | +| 디바이스 수 | 1 – 100 | 1/5/10 단위 (값 크기에 따라) | +| 비교 시스템 | rest-h2 / grpc-h2 / grpc-h3 | 개별 토글 | + +--- + +## 6. 의존성 + +``` +github.com/charmbracelet/bubbletea v1.2.4 # TUI 프레임워크 +github.com/charmbracelet/lipgloss v1.0.0 # 스타일링 +``` + +간접 의존성은 `go.mod`의 `// indirect` 블록 참고. + +--- + +## 7. mock 시뮬레이터의 가정 + +`internal/ui/simulator.go`는 실제 측정 없이 파라미터에 반응하여 그럴듯한 추세를 만든다. 시뮬레이션이 가정한 추세는 다음과 같다. + +| 가정 | 코드 위치 | +|------|----------| +| HTTP/3 (QUIC)은 패킷 손실 환경에서 HoL Blocking 해소로 처리량/latency 안정성 우위 | `simSpeed`, `mockLatency` | +| gRPC (Protobuf)는 REST (JSON) 대비 페이로드 ~30% 절감 | `step` 함수의 bytes 계산 | +| QUIC 연결 수립은 0/1-RTT (≈0.5×RTT), TCP+TLS는 ≈1.5×RTT | `mockConnectionTime` | +| Large-Few 시나리오는 대역폭 영향 지배적 | `mockLatency`의 bandwidth 항 | +| 디바이스 수 증가 시 병렬성으로 처리량 비례 증가 | `simSpeed`의 `parFactor` | + +> ⚠ **이 수치는 모두 시뮬레이션이다.** 실제 gRPC/QUIC 구현이 같은 추세를 보일지는 Phase 1 이후의 실측으로 검증한다. 시뮬레이터 가중치는 발표·논의를 위한 예시이며, 실측을 대신하지 않는다. + +--- + +## 8. 다음 단계 + +### 8.1. UI 측면 +- 결과 export (JSON / CSV) 기능 추가 +- 시나리오 저장/불러오기 (프리셋) +- 비교 결과를 동시에 여러 개 누적 보기 (네트워크 조건 매트릭스 sweep) + +### 8.2. 백엔드 연결 (Phase 1+) +1. `proto/aiot/inference/inference.proto` 정의 및 `make proto`로 코드 생성 +2. `cmd/server`에 gRPC InferenceService 구현 (HTTP/2) +3. `cmd/rest-server`에 동일 시나리오의 REST 엔드포인트 구현 +4. `cmd/benchmark-runner`에서 두 서버 호출하는 부하 생성기 구현 +5. `internal/ui/simulator.go`의 `step()` 함수를 실측 데이터 수집기로 교체 +6. `scripts/tc-setup.sh`를 UI에서 자동 호출하도록 통합 + +자세한 구현 패턴은 [`../IMPLEMENTATION.md`](../IMPLEMENTATION.md) 4절(코드 패턴)과 7절(자주 수행하는 작업 시나리오)을 참고한다. + +--- + +## 9. 트러블슈팅 + +| 증상 | 원인 / 해결 | +|------|-----------| +| 한글이 깨져 보임 | 터미널 로케일을 UTF-8로 설정 (`export LANG=ko_KR.UTF-8`) | +| 색상이 단조로움 | `TERM` 환경변수가 256색을 지원하는지 확인 (`echo $TERM` → `xterm-256color` 등) | +| `go: module ... not found` | `cd src && go mod tidy` 재실행 | +| sparkline/막대가 깨짐 | 터미널 폰트가 Block Element(`▓░█▁▂▃▄▅▆▇`)를 지원하는지 확인 (Nerd Font 권장) | +| 화면이 잘림 | 최소 터미널 크기 약 100×40 권장 |