ARCHITECTURE.md — chaos-http 시스템 아키텍처

전체 구조 개요

chaos-http는 세 개의 독립적인 모듈로 구성됩니다.

┌─────────────────────────────────────────────────────────────────┐
│                      개발자 로컬 환경                             │
│                                                                  │
│  ┌──────────────┐     HTTP      ┌──────────────────────────────┐ │
│  │              │  :18080       │        chaos-proxy           │ │
│  │  Spring Boot │──────────────►│  (Netty 기반 리버스 프록시)   │ │
│  │  애플리케이션  │               │                              │ │
│  │              │               │  ┌──────────────────────┐   │ │
│  └──────────────┘               │  │    Rule Engine        │   │ │
│                                  │  │  ┌────────────────┐  │   │ │
│  ┌──────────────┐     HTTP      │  │  │ Latency Rule   │  │   │ │
│  │              │  :9090        │  │  │ Error Rule     │  │   │ │
│  │  웹 브라우저   │◄──────────────│  │  │ Timeout Rule   │  │   │ │
│  │  (Dashboard) │               │  │  │ Modify Rule    │  │   │ │
│  │              │               │  │  └────────────────┘  │   │ │
│  └──────────────┘               │  └──────────────────────┘   │ │
│                                  │              │               │ │
│                                  └──────────────┼───────────────┘ │
│                                                 │ 룰 통과 시         │
│                                                 ▼               │
│                                  ┌──────────────────────────┐   │
│                                  │     실제 외부 API          │   │
│                                  │  https://api.kakao.com   │   │
│                                  └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

모듈 상세 설명

1. chaos-proxy (핵심 엔진)

역할: HTTP 요청을 가로채 장애 룰을 적용한 뒤 실제 타겟으로 포워딩

기술 선택 이유

기술	선택 이유
Spring Boot 4	Auto-configuration, Actuator 통합, 생태계
Netty (via Reactor Netty)	논블로킹 I/O, 높은 동시 연결 처리, Spring WebFlux 기반
Spring WebFlux	리액티브 프록시 구현에 최적
WebClient	논블로킹 HTTP 클라이언트, 타임아웃 제어 용이

처리 흐름 (Request Pipeline)

전체 파이프라인은 CLAUDE.md 참조

인바운드 요청 (:18080)
  → 1. RequestLoggingFilter     (요청 기록)
  → 2. RuleMatchingFilter       (적용할 룰 탐색 + 조건 매칭)
  → 3. RateLimitFilter          (Rate Limit 확인)
  → 4. LatencyFilter            (지연 적용 - Mono.delay, 논블로킹)
  → 5. ErrorInjectionFilter     (에러 확률 판단 → 즉시 에러 응답 or 통과)
  → 6. RequestModifyFilter      (헤더/바디 변조)
  → 7. ProxyForwardFilter       (실제 타겟으로 포워딩 - WebClient)
  → 8. BandwidthThrottleFilter  (응답 대역폭 제한)
  → 9. TruncateFilter           (부분 응답 절단)
  → 10. ResponseModifyFilter    (응답 변조)
  → 11. ResponseLoggingFilter   (응답 기록)
→ 클라이언트에 응답 반환

2. Rule Engine

역할: 들어온 요청에 어떤 장애를 어떻게 적용할지 결정하는 핵심 로직

룰 매칭 알고리즘

요청: GET /api/user/123/profile

등록된 룰 순서대로 평가:
  Rule 1: path="/api/**"           → ✅ 매칭 (우선순위 100)
  Rule 2: path="/api/user/**"      → ✅ 매칭 (우선순위 90)
  Rule 3: path="/api/user/*/profile" → ✅ 매칭 (우선순위 80)

→ 가장 구체적인 Rule 3 적용 (경로 패턴이 가장 좁은 것 우선)
  만약 우선순위가 같다면 등록 순서대로 적용

룰 도메인 모델

전체 도메인 모델 상세는 CLAUDE.md 참조

핵심 필드: pathPattern (Ant-style), method, enabled, priority, 그리고 nullable한 장애 설정들(latency, error, timeout, responseModify, rateLimit, bandwidth, truncate, stateful)로 구성된 Java Record입니다.

3. Scenario System

역할: 여러 룰의 묶음을 파일로 저장/불러오기하여 팀 간 공유 가능하게 함

시나리오 파일 구조

# scenarios/toss-payments.yml
metadata:
  name: "토스페이먼츠 장애 시뮬레이션"
  description: "결제 API 타임아웃 및 간헐적 실패 시나리오"
  author: "Max"
  version: "1.0.0"
  target: "https://api.tosspayments.com"

rules:
  - id: "payment-timeout"
    name: "결제 승인 타임아웃"
    path: "/v1/payments/confirm"
    method: POST
    enabled: false             # 기본 비활성화
    priority: 10
    timeout:
      after_ms: 30000          # 30초 타임아웃 (실제 카드사 타임아웃 시뮬레이션)

  - id: "payment-error"
    name: "간헐적 결제 실패"
    path: "/v1/payments/**"
    method: ALL
    enabled: false
    priority: 20
    error:
      rate: 0.1                # 10% 확률로 실패
      status_code: 500
      body: |
        {
          "code": "PAYMENT_FAILED",
          "message": "결제 처리 중 오류가 발생했습니다."
        }

  - id: "slow-webhook"
    name: "웹훅 지연"
    path: "/v1/webhooks"
    method: POST
    enabled: false
    priority: 30
    latency:
      range_ms: [2000, 8000]   # 2~8초 랜덤 지연

4. Dashboard (React SPA)

역할: 시나리오/룰의 CRUD 및 실시간 요청 로그 모니터링 웹 UI

기술 스택: React 19 + TypeScript + Vite

컴포넌트 구조

App
├── Header                    (타이틀 + 연결 상태)
├── RuleList                  (룰 목록 패널)
│   └── RuleCard              (룰 ON/OFF 토글, 삭제, 태그, 상세)
└── LogTable                  (실시간 요청 로그 테이블)

커스텀 Hooks

Hook	역할
`useRules`	룰 CRUD + toggle (REST API)
`useLogStream`	SSE 실시간 로그 스트림 (자동 재연결)
`useRuleStream`	SSE 룰 변경 이벤트

실시간 통신 방식

Dashboard (React)
    │
    │  SSE (Server-Sent Events)
    │  GET /api/v1/logs/stream
    │
    ▼
chaos-proxy (Spring WebFlux)
    │
    │  Flux<LogEntry> (논블로킹 스트림)
    │
    ▼
Sinks.Many<LogEntry> (인메모리 이벤트 버스)

SSE를 선택한 이유: 요청 로그는 서버→클라이언트 단방향 스트림이므로 WebSocket의 복잡성이 불필요합니다. SSE는 HTTP 기반이라 CORS, 인증 등 기존 Spring Security 설정을 그대로 재사용할 수 있습니다.

데이터 흐름 상세

요청 처리 시퀀스 다이어그램

Client App        chaos-proxy         Rule Engine       Target API
    │                  │                   │                 │
    │  GET /api/user   │                   │                 │
    │─────────────────►│                   │                 │
    │                  │  matchRules(req)  │                 │
    │                  │──────────────────►│                 │
    │                  │  [LatencyRule]    │                 │
    │                  │◄──────────────────│                 │
    │                  │                   │                 │
    │                  │  Mono.delay(3s)   │                 │
    │                  │◄─────────────────────────────────── │
    │                  │  (3초 대기)        │                 │
    │                  │                   │                 │
    │                  │                   │  GET /api/user  │
    │                  │─────────────────────────────────────►
    │                  │                   │                 │
    │                  │                   │    200 OK       │
    │                  │◄─────────────────────────────────────
    │                  │                   │                 │
    │  200 OK (3024ms) │                   │                 │
    │◄─────────────────│                   │                 │
    │                  │                   │                 │

에러 주입 분기 흐름

요청 도착
    │
    ▼
ErrorRule 적용 여부 확인
    │
    ├── 룰 없음 또는 비활성화
    │       │
    │       └──► 타겟으로 포워딩 (정상 흐름)
    │
    └── ErrorRule 활성화
            │
            ▼
        Math.random() < rule.rate ?
            │
            ├── YES (에러 주입)
            │       │
            │       └──► 설정된 status/body로 즉시 응답
            │            (타겟에 요청하지 않음)
            │
            └── NO (정상 처리)
                    │
                    └──► 타겟으로 포워딩

상태 관리

chaos-http는 인메모리 상태 관리를 기본으로 합니다. 재시작 시 파일에서 시나리오를 다시 로드합니다.

┌─────────────────────────────────┐
│         InMemoryRuleStore       │
│                                 │
│  ConcurrentHashMap<String,      │
│         ChaosRule>              │
│                                 │
│  - thread-safe 읽기/쓰기         │
│  - 재시작 시 scenario.yml 재로드  │
└─────────────────────────────────┘
         │ 변경 발생 시
         ▼
┌─────────────────────────────────┐
│      Sinks.Many<RuleEvent>      │
│  (SSE로 Dashboard에 실시간 푸시)  │
└─────────────────────────────────┘

설계 결정: 영구 저장(DB)은 의도적으로 제외했습니다. chaos-http는 로컬 개발 도구로, 단순성이 핵심 가치입니다. 시나리오 영구 저장은 YAML 파일로 충분합니다.

성능 고려사항

프록시 오버헤드 목표

상황	목표 추가 지연
룰 없음 (패스스루)	< 1ms
룰 매칭만 (지연 미적용)	< 2ms
지연 룰 적용	설정값 ± 10ms

메모리 관리

요청 로그는 링 버퍼(Circular Buffer) 로 관리합니다.

// 최근 10,000건만 인메모리 보관
private final Deque<RequestLog> logBuffer = 
    new ArrayDeque<>(MAX_LOG_SIZE);

// 초과 시 가장 오래된 것부터 제거
if (logBuffer.size() >= MAX_LOG_SIZE) {
    logBuffer.pollFirst();
}

보안 고려사항

로컬 전용 설계

chaos-http는 개발/테스트 환경 전용입니다.

기본값으로 localhost(127.0.0.1)에서만 접속 허용
프로덕션 환경 사용을 막는 경고 메시지 표시
CORS 기본 설정: localhost 오리진만 허용

# application.yml
chaos:
  security:
    allow-origins:
      - http://localhost:9090
      - http://127.0.0.1:9090
    warn-if-not-localhost: true  # 외부 IP 바인딩 시 경고

민감 정보 처리

요청 로그에서 민감한 헤더는 자동 마스킹됩니다.

chaos:
  logging:
    mask-headers:
      - Authorization
      - Cookie
      - X-Api-Key

AI 레이어 (선택적 옵션)

AI 기능은 핵심 프록시 엔진과 완전히 분리된 독립 레이어입니다. Spring AI 스타터 의존성을 추가하지 않으면 AI 코드는 전혀 실행되지 않습니다.

AI 레이어의 상세 구조, 프로바이더 설정, 프롬프트 엔지니어링은 AI_INTEGRATION.md 참조

핵심 설계 원칙:

Spring AI (ChatModel) 활용 — 프로바이더 전환 = application.yml 설정 변경만으로 완료
Spring AI의 자동 구성으로 인증, HTTP 호출, 직렬화를 프레임워크가 처리
AI 비활성화 시 AI API 엔드포인트는 503 반환 (핵심 프록시 기능에 영향 없음)
프롬프트 버전 관리, confidence 점수 + alternatives로 불확실성 표현

플러그인 시스템 (SPI)

Java SPI(Service Provider Interface)를 통해 커스텀 장애 필터를 확장할 수 있습니다.

ChaosFilter 인터페이스

public interface ChaosFilter {
    /** 플러그인 고유 이름 */
    String getName();

    /** 필터 체인 내 실행 순서 (낮을수록 먼저) */
    int getOrder();

    /** 이 룰에 대해 필터를 적용할지 여부 */
    boolean supports(ChaosRule rule);

    /** 장애 주입 로직 */
    Mono<ServerResponse> apply(ServerRequest request, ChaosRule rule,
                                ChaosFilterChain chain);
}

플러그인 등록 방법

1. 빌트인 (Spring Bean)

@Component
public class NthRequestFailFilter implements ChaosFilter {
    private final AtomicInteger counter = new AtomicInteger(0);

    @Override
    public Mono<ServerResponse> apply(ServerRequest request, ChaosRule rule,
                                       ChaosFilterChain chain) {
        int n = rule.getExtension("nthRequest.failFirst", Integer.class);
        if (counter.incrementAndGet() <= n) {
            return ServerResponse.status(500).bodyValue("nth-fail");
        }
        return chain.next(request, rule);
    }
}

2. 외부 JAR 플러그인

plugins/
└── my-custom-filter-1.0.jar
    └── META-INF/services/net.chimaek.chaosproxy.plugin.ChaosFilter

chaos-http 시작 시 plugins/ 디렉토리의 JAR을 자동 스캔하여 로드합니다.

빌트인 플러그인 목록

플러그인	설명
`NthRequestFailFilter`	N번째 요청까지만 실패 → 이후 성공 (Retry 테스트)
`CronScheduleFilter`	cron 표현식 기반 시간대별 활성화
`CorrelationIdFilter`	특정 트레이스 ID를 가진 요청만 장애 주입
`GradualDegradationFilter`	시간에 따라 에러율 점진적 증가 (0% → 100%)
`JitterFilter`	응답 시간에 랜덤 지터 추가 (네트워크 불안정 시뮬레이션)

트래픽 녹화 & 재생

프록시를 통과하는 실제 트래픽을 캡처하고 시나리오로 변환할 수 있습니다.

┌──────────┐     요청     ┌──────────────┐     포워딩     ┌──────────┐
│ Client   │────────────►│  chaos-proxy  │──────────────►│ Target   │
│ App      │◄────────────│  (녹화 모드)   │◄──────────────│ API      │
└──────────┘     응답     └──────┬───────┘     응답       └──────────┘
                                │
                                │ 요청+응답 쌍 기록
                                ▼
                         ┌──────────────┐
                         │ RecordStore  │
                         │ (인메모리)    │
                         └──────┬───────┘
                                │ 내보내기
                                ▼
                    ┌─────────────────────┐
                    │  scenario.yml       │
                    │  또는 HAR 파일       │
                    └─────────────────────┘

확장 아키텍처 (향후)

Kubernetes 사이드카 모드

┌─── Pod ──────────────────────────────────┐
│                                          │
│  ┌───────────┐     ┌──────────────────┐ │
│  │ App       │────►│ chaos-http       │──────► External API
│  │ Container │     │ (sidecar)        │ │
│  └───────────┘     └──────────────────┘ │
│                            │             │
│                     ConfigMap/CRD        │
└──────────────────────────────────────────┘

분산 카오스 조율

┌─────────────────────────┐
│   Central Dashboard     │
│   (중앙 관리 콘솔)       │
└──────────┬──────────────┘
           │ Redis pub/sub
    ┌──────┼──────────┐
    ▼      ▼          ▼
┌──────┐ ┌──────┐ ┌──────┐
│Proxy │ │Proxy │ │Proxy │
│ #1   │ │ #2   │ │ #3   │
└──────┘ └──────┘ └──────┘

여러 chaos-http 인스턴스 간 룰을 동기화하여 마이크로서비스 호출 체인 전체에 걸친 장애 시나리오를 실행할 수 있습니다.

실험 오케스트레이션 (Experiment Orchestration)

단순 룰 적용을 넘어, 시간 순서에 따른 장애 시퀀스를 자동 실행하는 오케스트레이션 엔진입니다.

실험 흐름

┌─────────────────────────────────────────────────────────────┐
│                    ExperimentExecutor                        │
│                                                             │
│  1. Steady-State 검증 (사전 조건 확인)                        │
│     └─ 타겟 API 헬스체크, 에러율 < 1% 확인                    │
│                                                             │
│  2. 장애 시퀀스 실행                                          │
│     ├─ Step 1: 지연 500ms 적용 → 30초 유지                   │
│     ├─ Step 2: 에러율 10%로 증가 → 60초 유지                  │
│     └─ Step 3: 타임아웃 5s 적용 → 30초 유지                   │
│                                                             │
│  3. Steady-State 재검증 (사후 조건 확인)                      │
│     └─ 에러율 복원 확인, 응답시간 정상화 확인                   │
│                                                             │
│  4. 결과 리포트 생성                                          │
└─────────────────────────────────────────────────────────────┘

실험 정의 (YAML)

experiment:
  name: "결제 API 복원력 테스트"
  timeout: 300s           # 전체 실험 제한 시간
  dry-run: false          # true면 실제 적용 없이 검증만

  steady-state:
    - type: health-check
      target: "/v1/payments/health"
      expect: 200
    - type: error-rate
      threshold: "< 1%"

  steps:
    - name: "지연 주입"
      rule: { path: "/v1/payments/**", latency: { fixedMs: 500 } }
      duration: 30s
    - name: "에러 주입"
      rule: { path: "/v1/payments/**", error: { rate: 0.1, statusCode: 500 } }
      duration: 60s

  rollback: auto           # 실패 시 자동 롤백

안전장치 (Safety Mechanisms)

카오스 엔지니어링에서 가장 중요한 것은 통제된 실험입니다. 장애 주입이 예상 범위를 벗어나지 않도록 다중 안전장치를 제공합니다.

안전장치 아키텍처

┌───────────────────────────────────────────────┐
│              Safety Layer                      │
│                                                │
│  ┌─────────────┐  ┌──────────────────────────┐│
│  │ Kill Switch │  │ Auto-Rollback            ││
│  │ (긴급 중지)  │  │ (에러율 임계치 초과 시     ││
│  │ POST /safety│  │  자동으로 모든 룰 비활성화) ││
│  │ /kill-switch│  │                          ││
│  └──────┬──────┘  └────────────┬─────────────┘│
│         │                      │               │
│         ▼                      ▼               │
│  ┌─────────────────────────────────────────┐  │
│  │         InMemoryRuleStore               │  │
│  │  모든 룰 enabled=false 즉시 전환         │  │
│  └─────────────────────────────────────────┘  │
│                                                │
│  ┌──────────────────┐  ┌────────────────────┐ │
│  │ Experiment       │  │ Dry-Run Mode       │ │
│  │ Timeout          │  │ (실제 적용 없이     │ │
│  │ (실험 제한 시간   │  │  영향 범위만 표시)   │ │
│  │  초과 시 자동 중지)│  │                    │ │
│  └──────────────────┘  └────────────────────┘ │
└───────────────────────────────────────────────┘

안전장치	설명	트리거
Kill Switch	모든 룰을 즉시 비활성화 (1 API 호출)	수동 (대시보드 버튼/API)
Auto-Rollback	에러율이 설정 임계치를 초과하면 자동 복원	자동 (메트릭 기반)
Experiment Timeout	실험이 최대 시간을 초과하면 자동 중지	자동 (타이머)
Dry-Run Mode	장애를 실제로 적용하지 않고 영향 범위만 표시	수동 (설정)
Steady-State 검증	실험 전후 시스템 상태를 비교하여 안전 확인	자동 (실험 흐름)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ARCHITECTURE.md — chaos-http 시스템 아키텍처

전체 구조 개요

모듈 상세 설명

1. chaos-proxy (핵심 엔진)

2. Rule Engine

3. Scenario System

4. Dashboard (React SPA)

데이터 흐름 상세

요청 처리 시퀀스 다이어그램

에러 주입 분기 흐름

상태 관리

성능 고려사항

프록시 오버헤드 목표

메모리 관리

보안 고려사항

로컬 전용 설계

민감 정보 처리

AI 레이어 (선택적 옵션)

플러그인 시스템 (SPI)

ChaosFilter 인터페이스

플러그인 등록 방법

빌트인 플러그인 목록

트래픽 녹화 & 재생

확장 아키텍처 (향후)

Kubernetes 사이드카 모드

분산 카오스 조율

실험 오케스트레이션 (Experiment Orchestration)

실험 흐름

실험 정의 (YAML)

안전장치 (Safety Mechanisms)

안전장치 아키텍처

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

ARCHITECTURE.md — chaos-http 시스템 아키텍처

전체 구조 개요

모듈 상세 설명

1. chaos-proxy (핵심 엔진)

2. Rule Engine

3. Scenario System

4. Dashboard (React SPA)

데이터 흐름 상세

요청 처리 시퀀스 다이어그램

에러 주입 분기 흐름

상태 관리

성능 고려사항

프록시 오버헤드 목표

메모리 관리

보안 고려사항

로컬 전용 설계

민감 정보 처리

AI 레이어 (선택적 옵션)

플러그인 시스템 (SPI)

ChaosFilter 인터페이스

플러그인 등록 방법

빌트인 플러그인 목록

트래픽 녹화 & 재생

확장 아키텍처 (향후)

Kubernetes 사이드카 모드

분산 카오스 조율

실험 오케스트레이션 (Experiment Orchestration)

실험 흐름

실험 정의 (YAML)

안전장치 (Safety Mechanisms)

안전장치 아키텍처