Atomic HTTP

고성능 HTTP 서버 라이브러리 - Arena 메모리 관리와 Zero-copy 기술을 활용한 최적화된 HTTP 서버

🚀 주요 기능

• Arena 메모리 관리: 효율적인 메모리 할당과 관리
• Zero-copy 기술: 메모리 복사 없는 파일 서빙
• 멀티파트 지원: 고성능 파일 업로드 처리
• 비동기 처리: Tokio 기반 비동기 I/O
• SSE 스트리밍: into_sse()로 Server-Sent Events 전송
• 타입 안전성: Rust의 타입 시스템 활용

📦 설치

[dependencies]
atomic_http = { version = "0.15.1", features = ["arena"] }

ℹ️ 프로덕션 배포 전 SECURITY.md 의 권장 설정 (max_body_size, header_read_deadline_ms, TLS) 을 적용하세요.

🛠️ 기능별 Features

• arena: Arena 메모리 관리 (기본 활성화)
• router: Radix trie 기반 라우터 (마이그레이션 가이드)
• websocket: WebSocket 업그레이드 지원
• connection_pool: Keep-alive 연결 풀링
• response_file: 파일 응답 지원
• env: 환경변수 설정 지원
• debug: 디버그 출력 활성화

🧪 테스트 실행 가이드

📋 새로운 통합 테스트 (추천)

1. 완전 통합 테스트

서버와 클라이언트를 자동으로 시작하고 종합적인 테스트 실행

# Arena + Zero-copy 모드
cargo run --example integrated_test --features arena

# 표준 모드
cargo run --example integrated_test

2. 성능 비교 벤치마크

Arena 서버와 표준 서버의 성능을 직접 비교

# Arena vs 표준 서버 성능 비교
cargo run --example comparative_benchmark --features arena

# 릴리즈 모드로 정확한 성능 측정
cargo run --release --example comparative_benchmark --features arena

3. 멀티파트 테스트

파일 업로드와 멀티파트 폼 데이터 처리 테스트

# Arena 멀티파트 테스트
cargo run --example integrated_multipart_test --features arena

# 표준 멀티파트 테스트  
cargo run --example integrated_multipart_test

🔧 간단한 테스트

0. 문제 해결용 디버그 테스트

# Arena 서버 디버그
cargo run --example debug_test --features arena -- 9999

# 표준 서버 디버그
cargo run --example debug_test -- 9999

1. 간단한 벤치마크 테스트 (추천)

# Arena 간단 벤치마크
cargo run --example simple_benchmark_test --features arena -- 9998

# 표준 간단 벤치마크  
cargo run --example simple_benchmark_test -- 9998

2. 기본 서버 테스트

# Arena 서버
cargo run --example simple_server_test --features arena -- 9080

# 표준 서버
cargo run --example simple_server_test -- 9081

2. 간단한 성능 테스트

# Arena 성능 테스트
cargo run --example simple_performance_test --features arena

# 표준 성능 테스트
cargo run --example simple_performance_test

📊 벤치마크

Criterion을 사용한 마이크로 벤치마크:

cargo bench

🔍 기존 테스트들 (레거시)

필요시 개별 기능 테스트:

# 기존 서버 테스트
cargo run --example server --features arena

# 부하 테스트 클라이언트 (별도 실행)
cargo run --example load_test_client -- -n 1000 -c 50

# 파일 서빙 테스트
cargo run --example file_serving_test --features arena,response_file

# 제로카피 테스트
cargo run --example zero_copy_test --features arena

📈 성능 특징

Arena 서버의 장점

• ✅ 제로카피: 메모리 복사 없음
• ✅ 낮은 메모리 사용량: 원본 데이터만 유지
• ✅ 빠른 파싱: String 생성 없이 바이트 직접 접근
• ✅ 예측 가능한 성능: GC 압박 없음
• ✅ 대용량 파일 최적화: 메모리 효율적

표준 서버 특징

• 📝 안정적이고 검증된 방식
• 📝 메모리 복사와 String 할당 포함
• 📝 상대적으로 높은 메모리 사용량

💡 사용 예제

기본 서버 설정

use atomic_http::*;
use http::StatusCode;

#[tokio::main]
async fn main() -> Result<(), SendableError> {
    let mut server = Server::new("127.0.0.1:8080").await?;
    
    loop {
        let accept = server.accept().await?;
        
        tokio::spawn(async move {
            let (request, mut response) = accept.parse_request_arena_writer().await?;
            
            // JSON 파싱 (Zero-copy)
            let data: MyData = request.get_json_arena()?;
            
            // 응답 생성 (Arena 할당)
            let result = serde_json::json!({
                "status": "success",
                "data": data
            });
            response.body_mut().set_arena_json(&result)?;
            *response.status_mut() = StatusCode::OK;
            
            response.responser_arena().await?;
            
            Ok::<(), SendableError>(())
        });
    }
}

멀티파트 파일 업로드

// Arena 멀티파트 처리
match request.get_multi_part_arena()? {
    Some(form) => {
        // 텍스트 필드 접근
        for i in 0..form.text_fields.len() {
            let name = form.get_text_field_name(i);
            let value = form.get_text_field_value(i);
        }
        
        // 파일 처리
        for part in &form.parts {
            let filename = part.get_file_name();
            let file_data = part.get_body(); // Zero-copy 접근
            
            // 파일 저장
            tokio::fs::write(filename?, file_data).await?;
        }
    }
    None => {
        // JSON 또는 다른 형식 처리
    }
}

Server-Sent Events (SSE)

응답은 보통 content-length와 함께 한 번에 전송되지만, into_sse()는 소켓의 write half를 넘겨받아 헤더를 한 번 보내고 이후 프레임을 원하는 만큼 전송합니다. (Response<Writer>, Response<ArenaWriter> 모두 지원)

use atomic_http::*;
use std::time::Duration;

async fn stream(response: http::Response<ArenaWriter>) -> Result<(), SendableError> {
    // 추가 헤더(Set-Cookie, CORS 등)는 into_sse() 전에 response.headers_mut()로 설정
    let mut sse = response.into_sse().await?;

    sse.send_event("token", "안녕").await?;                       // event: token
    sse.send(&SseEvent::data("여러 줄\n데이터").id("42")).await?;  // 줄바꿈은 data: 줄로 분리

    // 느린 작업 동안 15초마다 주석 프레임을 보내 연결 유지
    let answer = sse
        .keepalive_while(Duration::from_secs(15), slow_work())
        .await?;
    sse.send_event("done", &answer).await?;

    sse.finish().await // FIN 전송
}

• 상태 코드는 항상 200 OK이고, 스트림은 connection: close로 소켓이 닫히면 끝납니다 (chunked 미사용).
• 오류 응답은 responser / responser_arena로 보내세요.
• 전송 실패가 클라이언트 이탈인지 is_disconnect(&err)로 확인할 수 있습니다.
• 예제: cargo run --example sse_test 후 curl -N http://127.0.0.1:8080/events

바이너리 응답 (오디오, 이미지 등)

set_arena_bytes()는 UTF-8이 아닌 바이트도 그대로 본문으로 보냅니다. content-length는 자동으로 붙고, content-type은 직접 지정하세요.

use atomic_http::*;
use http::{header, HeaderValue, StatusCode};

async fn audio(mut response: http::Response<ArenaWriter>, wav: Vec<u8>) -> Result<(), SendableError> {
    *response.status_mut() = StatusCode::OK;
    response.headers_mut().insert(header::CONTENT_TYPE, HeaderValue::from_static("audio/wav"));
    response.body_mut().set_arena_bytes(&wav)?;
    response.responser_arena().await
}

🔧 환경 설정

환경변수를 통한 서버 설정 (env 피쳐 활성화 시):

export NO_DELAY=true
export READ_TIMEOUT_MILLISECONDS=5000
export READ_BUFFER_SIZE=8192
export ROOT_PATH="/var/www"
export ZERO_COPY_THRESHOLD=1048576
export ENABLE_FILE_CACHE=true
# 0.14+ 보안 옵션 (DoS / slowloris 방어)
export MAX_BODY_SIZE=10485760           # 본문 cap (bytes); 미설정 시 무제한
export HEADER_READ_DEADLINE_MS=5000     # 헤더 전체 수신 deadline

🏗️ 개발 및 기여

요구사항

• Rust 1.77 이상
• Tokio 런타임

컴파일

# 기본 빌드
cargo build

# Arena + Zero-copy 모든 기능
cargo build --features arena,response_file,env

# 릴리즈 빌드  
cargo build --release --features arena

테스트

# 단위 테스트
cargo test

# 통합 테스트
cargo run --example integrated_test --features arena

# 성능 벤치마크
cargo bench

📄 라이선스

Apache License 2.0

🤝 기여

이슈와 풀 리퀘스트를 환영합니다. 주요 변경사항은 먼저 이슈를 열어 논의해 주세요.

📞 지원

• GitHub Issues: 프로젝트 이슈
• 문서: docs.rs

---

추천 테스트 순서:

1. cargo run --example debug_test --features arena - 기본 동작 확인
2. cargo run --example simple_benchmark_test --features arena - 간단한 벤치마크
3. cargo run --example integrated_test --features arena - 전체 기능 확인
4. cargo run --example comparative_benchmark --features arena - 성능 비교
5. cargo bench - 마이크로 벤치마크

각 테스트는 서버와 클라이언트를 자동으로 관리하므로 별도 설정이 필요하지 않습니다.

🚨 문제 해결

벤치마크 실패 문제

만약 comparative_benchmark에서 요청이 실패한다면:

1. 기본 테스트부터 실행:

   cargo run --example debug_test --features arena

2. 간단한 벤치마크 실행:

   cargo run --example simple_benchmark_test --features arena

3. 포트 충돌 확인:

   # 다른 포트 사용
   cargo run --example simple_benchmark_test --features arena -- 8888

일반적인 문제들

• 컴파일 오류: cargo clean && cargo build --features arena
• 연결 실패: 방화벽이나 포트 사용 중인지 확인
• 성능 측정: --release 모드로 실행

로그 확인

각 테스트는 상세한 로그를 출력하므로 실패 지점을 쉽게 파악할 수 있습니다.