chaos-http

코드 한 줄 수정 없이 외부 API 장애를 시뮬레이션하는 개발자용 카오스 프록시

빠른 시작 · 핵심 기능 · 시나리오 예제 · REST API · 문서 · 기여하기

---

왜 chaos-http인가?

개발 중 가장 테스트하기 어려운 시나리오는 "외부 API가 죽었을 때 내 서비스는 어떻게 반응하는가" 입니다.

기존 방법	문제점
Thread.sleep() 삽입	테스트 후 반드시 롤백. 실수로 배포될 위험
WireMock	JSON/XML 설정 작성 필요. 학습 비용 높음
Toxiproxy	TCP 레벨만 가능. HTTP 헤더/바디 변조 불가. Web UI 없음
외부 API 강제 종료	불가능하거나 다른 팀원에게 영향

chaos-http는 리버스 프록시로 동작하며, 웹 대시보드에서 지연/에러/타임아웃을 실시간 주입합니다. 애플리케이션 코드는 한 줄도 수정할 필요 없습니다.

┌──────────────┐     ┌───────────────┐     ┌──────────────────┐
│  내 서비스    │ ──> │  chaos-http   │ ──> │  외부 API        │
│              │     │  :18080       │     │  api.kakao.com   │
│  localhost   │ <── │  지연/에러 주입 │ <── │                  │
└──────────────┘     └───────────────┘     └──────────────────┘
                           │
                     ┌─────┴─────┐
                     │ Dashboard │
                     │  :9090    │
                     └───────────┘

---

🚀 빠른 시작

Docker (권장)

# 카카오 API를 타겟으로 시작
docker run -p 18080:18080 -p 9090:9090 \
  ghcr.io/chimaek/chaos-http:latest \
  --chaos.proxy.target-url=https://api.kakao.com

# 앱에서 호출 주소만 변경
# Before: https://api.kakao.com/v2/user/me
# After:  http://localhost:18080/v2/user/me

# 웹 대시보드
open http://localhost:9090

Docker Compose

# 환경 변수로 타겟 지정
CHAOS_TARGET_URL=https://api.tosspayments.com \
  docker compose -f docker/docker-compose.yml up

JAR 직접 실행

cd chaos-proxy
./gradlew bootJar
java -jar build/libs/chaos-proxy-0.0.1-SNAPSHOT.jar \
  --chaos.proxy.target-url=https://httpbin.org

첫 장애 주입 (30초 안에!)

# 1. GET /get 요청에 100% 503 에러 주입
curl -X POST http://localhost:18080/api/v1/rules \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "첫 번째 장애",
    "pathPattern": "/get",
    "method": "GET",
    "enabled": true,
    "error": { "rate": 1.0, "statusCode": 503, "body": "{\"error\": \"chaos!\"}" }
  }'

# 2. 프록시를 통해 요청 → 503 에러 확인
curl http://localhost:18080/get

# 3. 대시보드에서 토글 OFF
open http://localhost:9090

---

✨ 핵심 기능

지연 주입

# 3초 고정 지연
curl -X POST http://localhost:18080/api/v1/rules \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "느린 API",
    "pathPattern": "/v2/user/**",
    "method": "GET",
    "latency": { "fixedMs": 3000 }
  }'

에러 주입

# 30% 확률로 500 에러
curl -X POST http://localhost:18080/api/v1/rules \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "간헐적 실패",
    "pathPattern": "/api/**",
    "error": { "rate": 0.3, "statusCode": 500, "body": "{\"error\": \"chaos injected\"}" }
  }'

타임아웃 시뮬레이션

# 5초 후 연결 강제 종료
curl -X POST http://localhost:18080/api/v1/rules \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "타임아웃",
    "pathPattern": "/v1/payments/confirm",
    "method": "POST",
    "timeout": { "afterMs": 5000 }
  }'

YAML 시나리오

미리 정의된 시나리오 파일로 한 번에 여러 룰을 로드할 수 있습니다.

# 번들된 예제 시나리오 로드
curl -X POST http://localhost:18080/api/v1/scenarios/load \
  -H 'Content-Type: application/json' \
  -d '{"filename": "toss-payments.yml"}'

실시간 대시보드 & SSE 로그 스트림

# 실시간 요청 로그 스트림 (Server-Sent Events)
curl -N http://localhost:18080/api/v1/logs/stream

# 룰 변경 실시간 알림
curl -N http://localhost:18080/api/v1/rules/stream

룰 토글

# 대시보드에서 원클릭 또는 API로 ON/OFF
curl -X PATCH http://localhost:18080/api/v1/rules/{id}/toggle

---

📋 시나리오 예제

scenarios/ 디렉토리에 바로 사용 가능한 예제가 포함되어 있습니다.

httpbin-demo.yml — 기본 데모

룰	설명
demo-latency	GET /get 요청 3초 지연
demo-error	POST /post 요청 50% 500 에러
demo-timeout	/delay/** 5초 타임아웃

toss-payments.yml — 토스페이먼츠 장애

룰	설명
toss-payment-timeout	결제 승인 30초 타임아웃
toss-payment-error	결제 API 10% 실패
toss-webhook-delay	웹훅 2~8초 랜덤 지연
toss-card-timeout	카드사 응답 5초 지연

kakao-api.yml — 카카오 API 장애

룰	설명
kakao-profile-latency	프로필 조회 3초 지연
kakao-login-error	토큰 발급 30% 실패
kakao-total-outage	전체 API 503 장애

모든 시나리오의 룰은 기본 enabled: false입니다. 대시보드나 API로 원하는 룰만 활성화하세요.

---

📡 REST API

메서드	엔드포인트	설명
GET	/api/v1/rules	전체 룰 목록
POST	/api/v1/rules	룰 생성
GET	/api/v1/rules/{id}	룰 상세 조회
PUT	/api/v1/rules/{id}	룰 수정
DELETE	/api/v1/rules/{id}	룰 삭제
PATCH	/api/v1/rules/{id}/toggle	룰 ON/OFF 토글
GET	/api/v1/rules/stream	룰 변경 SSE 스트림
GET	/api/v1/logs	요청 로그 목록
GET	/api/v1/logs/stream	실시간 로그 SSE 스트림
GET	/api/v1/scenarios	시나리오 파일 목록
POST	/api/v1/scenarios/load	시나리오 로드
POST	/api/v1/scenarios/save	시나리오 저장
GET	/api/v1/config	런타임 설정 조회
GET	/api/v1/health	상태 확인

전체 API 명세: docs/API.md

---

경쟁 도구 비교

기능	Toxiproxy	WireMock	Chaos Monkey	chaos-http
Web UI 대시보드	-	-	-	O
HTTP 헤더/바디 변조	- (TCP)	O	-	O
경로 기반 룰	-	O	-	O
YAML 시나리오 공유	-	JSON	-	O
실시간 ON/OFF 토글	API만	-	API만	UI+API
코드 변경 필요	-	설정	O	-

핵심 차별점: Toxiproxy의 "프록시 방식(코드 무수정)"과 WireMock의 "HTTP 레벨 제어"를 결합하고, 실시간 Web UI를 추가했습니다.

---

아키텍처

요청 → RuleEngine(룰 매칭) → LatencyFilter(지연) → ErrorFilter(에러)
     → ProxyForward(타겟 포워딩) → ResponseModify(응답 변조) → 응답

컴포넌트	역할
ProxyHandler	프록시 파이프라인 오케스트레이션
RuleEngine	경로+메서드 기반 룰 매칭 (Ant-style)
RuleStore	인메모리 룰 저장소 (ConcurrentHashMap)
ScenarioLoader	YAML 시나리오 로드/저장
RequestLogStore	요청 로그 링 버퍼 + SSE 스트림
RuleEventPublisher	룰 변경 이벤트 SSE 멀티캐스트

상세 아키텍처: docs/ARCHITECTURE.md

---

기술 스택

영역	기술
런타임	Java 25 (Virtual Threads)
백엔드	Spring Boot 4.0 + WebFlux + Reactor Netty
프론트엔드	React 19 + TypeScript + Vite
실시간 통신	SSE (Server-Sent Events)
빌드	Gradle 8.x
테스트	JUnit 5 + WireMock + AssertJ
컨테이너	Docker (eclipse-temurin:25-jre-alpine)
AI (선택)	Spring AI 2.0 (Anthropic, OpenAI, Ollama)

---

포트

포트	용도
18080	프록시 (앱이 이 포트로 요청)
9090	웹 대시보드
9091	Spring Actuator (Health, Metrics)

---

개발

# 빌드
cd chaos-proxy && ./gradlew build

# 개발 서버 실행
./gradlew bootRun --args='--chaos.proxy.target-url=https://httpbin.org'

# 테스트만 실행
./gradlew test

개발 가이드: docs/DEVELOPMENT.md

---

📖 문서

문서	내용
ARCHITECTURE.md	시스템 아키텍처, 데이터 흐름
API.md	REST API 전체 명세 + cURL 예시
DEVELOPMENT.md	개발 환경 설정, 코드 예시
AI_INTEGRATION.md	AI 프로바이더 설정 (선택적)
ROADMAP.md	개발 로드맵

---

🤝 기여하기

기여를 환영합니다! CONTRIBUTING.md를 읽고 시작하세요.

현재 가장 도움이 필요한 부분:

1. 예제 시나리오 추가 — 실무 외부 API 장애 시나리오
2. 테스트 작성 — 엣지 케이스, 통합 테스트
3. 문서 번역 — 영어 README, API 문서

---

라이선스

MIT License — 자유롭게 사용, 수정, 배포하세요.