H2 Server

리눅스 환경에서 Modern C++(C++17)을 활용하여 개발한 epoll, mmap, NGHTTP2, OpenSSL 기반의 고성능 http/2 서버

게시 2025/10/23 업데이트 2025/11/30

Structure of http/2 server

By Hyeonsu Choe

22 분읽는 시간

H2 Server

구분	내용
플랫폼	Linux
개발 도구 및 사용 언어	g++ 11.4.0, C++, Socket(epoll), nghttp2 v1.60.0, OpenSSL v3.0.2
개발 기간	2025년 3월 ~ 2025년 10월
저장소	바로 가기

1. 개요

h2-server는 Modern C++(C++17) 기반의 고성능 HTTP/2 서버 이다.
Linux에서 epoll(Edge-Triggered) 로 비동기 통신을 처리하고, nghttp2 + OpenSSL 을 통해 HTTP/2의 요청/응답을 처리한다.
또한 H2C(평문) 모드와 mmap 기반 파일 캐시를 지원하여 저지연 업/다운로드 기능을 제공한다.
프로그램은 내부적으로 eventfd 기반의 worker 구조로써 acceptor와 worker로 나뉘어져 동작하며
acceptor에서 worker로의 작업 요청은 load balancer에 의해 분산 되어 SPSC(Single Producer Single Consumer) 구조의 lock-free 큐를 통해 전달 된다.

1.1. 빌드

1.1.1. 소스 코드 빌드

  
# (예) 빌드
cd src
make

# (예) 정리
cd src
make clean

1.1.2. 도커로 빌드

프로젝트를 도커 이미지로 빌드하려면 프로젝트 루트(최상위 디렉터리) 를 다음과 같이 빌드 컨텍스트 위치로 지정해야 한다.
(docker_build/와 src/가 함께 위치한 상위 경로)

  
docker build -t h2-server -f ./docker_build/Dockerfile .

1.2. 실행

1.2.1. 빌드 후 직접 실행

  
# TLS (기본값 포트 443)
cd src
./h2server --port 443 --key ./cert/server.key --cert ./cert/server.crt --threads 4

# H2C (평문)
cd src
./h2server --port 8080 --h2c --threads 4

1.2.2. 도커로 실행

도커로 실행할 때는 환경 변수로 기본 동작을 제어 한다.

환경 변수	설명
`RUN_MODE`	실행 모드: `h2`(TLS) 또는 `h2c`(평문)
`PORT`	서버 리스닝 포트 (예: `443`, `8080`)
`THREADS`	워커 스레드 수

1) 단일 컨테이너 실행

TLS(H2) 예시

  
docker run -d --name h2server -e RUN_MODE=h2 -e PORT=443 -e THREADS=4 -p 443:443  h2-server

평문(H2C) 예시

  
docker run -d --name h2server-h2c -e RUN_MODE=h2c -e PORT=8080 -e THREADS=4   -p 8080:8080   h2-server

2) `docker compose`로 실행

docker_build/docker-compose.yml 예시:

  
  h2_server:
    image: h2-server
    environment:
      - RUN_MODE=h2
      - PORT=443
      - THREADS=4
    ports:
      - 0.0.0.0:443:443
      - :::443:443

실행:

cd docker_build
docker-compose up -d

H2C로 실행하려면 위 compose 파일에서 RUN_MODE: "h2c", PORT: "8080", ports: ["8080:8080"] 로 변경 하면 된다.

1.3 핸들러 사용법

등록

  
server.add_handler(GET,  "/files/{file_name}", downloader);
server.add_handler(POST, "/files",            uploader);

Request API

함수	설명
`reply_ok()`	바디 없이 `:status=200` 응답 전송
`reply_ok_with_file()`	`FileContext`를 data source로 연결해 파일 응답
`reply_404()`	간단한 404 HTML 바디와 함께 `:status=404` 전송

예시

  
int downloader(Request& request) {
    StreamData* stream_data = request.stream_data;
    const std::string& rel_path = request.rel_path;

    if (rel_path.empty()) {
        return request.reply_404();
    }
    auto file = load_file_from_filecache(rel_path);
    if (!file) {
        return request.reply_404();
    }

    stream_data->file_ctx.data = file->get_data();
    stream_data->file_ctx.size = file->get_data_len();
    return request.reply_ok_with_file();
}

2. 자료 구조 (Data Structure Overview)

2.1. 주요 자료 구조

1) StreamData — 스트림 레벨 컨텍스트

  
class StreamData {
public:
    uint32_t stream_id;
    METHOD method;
    std::string request_path;
    FileContext file_ctx;
    std::unique_ptr<MultipartFormParser> mime_parser;
    std::vector<uint8_t> upload_file_buffer;
};

2) SessionData — 세션(소켓) 레벨 컨텍스트

  
class SessionData {
public:
    const Router* router;
    std::list<std::unique_ptr<StreamData>> streams;
    nghttp2_session* session;
    std::vector<uint8_t> output_buffer;
    std::vector<uint8_t> input_buffer;
    uint32_t events;
    SessionState state;
    SSL* ssl;
};

3) Server — accept/분배 + 워커 관리

  
class Server {
private:
    Router router;
    std::vector<Worker> workers;
    std::vector<std::thread> threads;
    LoadBalancer load_balancer;
    int epfd, server_sock;
    struct sockaddr_in addr;
};

4) Worker — 이벤트 루프 & nghttp2/TLS I/O

  
class Worker {
private:
    const Router* router;
    std::function<bool(uint32_t)> check_rd_hup;
    std::function<void(int, std::shared_ptr<SessionData>)> update_events;
    std::function<IOResult(int, std::shared_ptr<SessionData>)> fill_input_buffer;
    std::function<IOResult(int, std::shared_ptr<SessionData>)> flush_output_buffer;

    std::mutex m;
    int signal_fd, epfd;
    bool use_tls;
    SSL_CTX* ssl_ctx;

    std::queue<int> socket_queue;
    std::unordered_map<int, std::shared_ptr<SessionData>> session_map;
};

5) Router — 정적/파라미터 경로 트리

  
class RouterNode {
public:
    std::unordered_map<std::string, std::unique_ptr<RouterNode>> static_children;
    std::unique_ptr<RouterNode> param_child;      // 같은 레벨에서 파라미터 노드는 1개 제한
    std::string param_child_name;                 // ex) "{id}" -> "id"
    std::array<Handler, METHOD_MAX> handlers;     // GET/POST 등
};

class Router {
private:
    RouterNode root_node;
};

6) File Cache — mmap 기반 zero-copy 지향

  
class FileContext {
public:
    size_t size;
    int offset;
    const char* data;
};

class MappedFile {
public:
    void*  data;     // mmap 주소
    size_t data_len;
};

3. 모듈 구조 (Module Architecture)

아래는 모듈 간 주요 데이터 플로우이다.

3.1. Server

--threads 개수만큼 Worker 생성 및 초기화
accept된 클라이언트 소켓을 LoadBalancer를 이용하여 각 Worker 큐에 분배
(eventfd를 통해 워커를 깨워 즉시 처리)

3.1.1. LoadBalancer

다음은 Server 내에 위치하여 입력되는 client 연결 요청을 받아 각 Worker로 분배하는 로드 밸런서이다.

로드 밸런서는 입력된 요청을 받아 해시 연산을 통해 Indirect Table을 참조하여 요청을 전달 할 Worker Queue의 번호를 얻는다.
이때의 Worker Queue는 SPSC(Single Producer Single Consumer) 구조의 lock-free Queue 로써,
그 Worker Queue에 여유가 있는 경우 그대로 요청을 전달 한다.
그러나 만약 선택된 Worker Queue 가 full인 경우, 다른 여유가 있는 Worker Queue를 Round Robin 스케쥴링을 통해 찾아 작업을 요청한다.

이때, 선택된 Worker Queue의 번호는 hash 연산을 통해 접근된 indirect_table의 entry에 갱신 된다.
그리고 이후 이 entry에 접근하는 요청은 새롭게 선택된 Worker Queue로 전달 되게 된다.

만약, Round Robin 스케쥴링을 통해 Worker Queue 들을 한 바퀴 순회 하였음에도 여유 있는 Worker Queue를 발견하지 못하는 경우에는 해당 요청은 버려진다.

새롭게 생성된 클라이언트 소켓에 대해 modular 연산을 수행하여 indirect_table의 인덱스 값으로 변환
indirect_table의 엔트리에 있는 Worker Queue 번호를 획득
- 최초 indirect_table에는 Worker Queue의 번호가 순서대로 반복 입력 되어 있다.
Worker Queue 가 full이 아니라면, 해당 worker queue로 클라이언트 소켓을 전달한다.
- 만약 Worker Queue 가 full 인 경우, Round Robin 스케쥴링을 통해 여분의 Worker Queue 를 찿는다.
  - 이것은 일종의 fallover 동작으로 볼 수 있다.
  - 여분의 Worker Queue 발견 시 방금 접근 했던 indirect_table의 엔트리에 Queue 번호 값을 갱신한다.
  - 새롭게 선택된 Worker Queue에 클라이언트 소켓을 전달 한다.
- 만약 여력이 있는 Worker Queue 를 발견하지 못한 경우 생성된 소켓을 close 한다.

3.2. Worker

큐로 전달받은 소켓을 epoll에 등록하고, TLS 핸드셰이크(옵션) → nghttp2 세션을 초기화
이벤트 처리:
- handle_read: fill_input_buffer → feed_input_buffer(nghttp2_session_mem_recv2) → 콜백 체인
- handle_write: fill_output_buffer(nghttp2_session_mem_send2) → flush_output_buffer
- check_rd_hup: FIN(RDHUP) 감지 시 안전 종료

3.2.1. worker 내 buffer 처리와 nghttp2 callback 함수들의 호출 flow

3.2.2. 주요 함수 호출 체인

| 함수명 | 의미 | 트리거 | | :—————————- | :——————- | :——————————- | | fill_input_buffer | 소켓을 통해 수신된 데이터들을 읽어 수신 버퍼에 저장 | 수신 소켓에서 이벤트 발생 시 | |feed_input_buffer| 채워진 수신 buffer 내 내용을 nghttp2 세션 데이터로 feed 할 준비| 더이상 소켓에서 수신할 데이터가 없는 경우 | | nghttp2_session_mem_recv2 | 채워진 buffer 내 데이터들을 nghttp2 라이브러리로 feed | 수신 버퍼에 데이터가 존재하는 경우 | | nghttp2_submit_response2 | 전송할 응답 프레임을 전송 대기큐로 큐잉, data_prd 존재 시 DATA 프레임 생성 | 응답 메시지 전송을 위해 직접 호출 | | nghttp2_session_mem_send2 | 전송 대기 큐 내 응답 프레임을 전송 할 수 있게 직렬화 화여 포인터 반환 | 응답할 수 있는 데이터 존재 시 | |fill_ouput_buffer|포인터가 가리키는 직렬화된 데이터를 출력 버퍼로 복사|| | flush_output_buffer | 출력 버퍼 내 데이터를 소켓을 통해 전송 | 직접 호출 |

3.2.3 .주요 nghttp2 콜백 함수들

함수명	의미	트리거
`on_begin_headers_callback`	헤더 블록 수신 시작	`mem_recv2()` 중
`on_header_callback`	헤더 name/value 수신	헤더 수신 때마다 반복
`on_data_chunk_recv_callback`	DATA 바디 청크 수신	DATA 프레임 수신 중 반복
`on_frame_recv_callback`	프레임 수신 완료	요청 완료 시 Router→Handler 호출
`on_stream_close_callback`	스트림 종료	스트림 close 요청 수신 시

3.2.2 TLS(SSL_CTX)

ALPN 협상에서 h2만 수락(미지원 시 종료)
TLS 미사용(H2C) 모드에서는 ALPN 협상 생략

3.3 Router

다음 4개 경로가 등록되면 트리는 다음과 같은 형태로 구성된다.

POST /files/images/{file_name} : handler_b
GET  /files/docs/{file_name}   : handler_c
POST /users/{user_num}         : handler_d
GET  /files/images/{file_name} : handler_a

정적 경로 우선 → 없으면 파라미터 경로 탐색
핸들러는 프로그램 구동 시에만 등록(런타임엔 읽기 전용)

3.4 File Cache

디스크 병목 완화 목적의 mmap 캐시
주의: 동일 파일에 대한 동시 쓰기 시 경쟁/일관성 문제가 발생할 수 있으므로 운영 시 동기화 정책이 필요하다.

3.5 Multipart Form Parser

업로드 요청 처리: multipart/form-data → 파일 추출
플로우: boundary 파싱 → filename 추출 → temp 쓰기 → 종료 시 rename
temp 파일명: h2_tmp_<thread_id>_<count>

3.6 Config Option

Flag	Type / Default	Description
`-p, --port <NUM>`	integer / `443`	리스닝 포트
`-k, --key <PATH>`	path / `./cert/server.key`	TLS 개인키(PEM). `--h2c`면 불필요
`-c, --cert <PATH>`	path / `./cert/server.crt`	TLS 인증서(PEM). `--h2c`면 불필요
`-n, --threads <NUM>`	integer / `1`	워커 스레드 수
`--h2c`	flag	HTTP/2 cleartext 모드
`-h, --help`	flag	도움말 출력

4. 성능 측정 (Benchmark)

4.1 개선 단계별 성능 변화

Prototype → mmap(파일 캐시) 적용 → TLS(https) 적용 → Router 적용 → socket port reuse 멀티스레딩 구조 적용 → acceptor/worker 멀티스레딩 구조 적용 -> Load Balancer 적

주: mmap 도입 전 -c1000 -m100에서는 FD 제한(기본 1024)으로 성공률이 0.1%에 불과.
동일 이슈는 libevent-server, nghttpd(≥8 threads)에서도 관측되어 ulimit -n 상향으로 대응.

1) h2load -c100 -m10

Server	QPS	P99 Latency (ms)	P90 Latency (ms)	P50 Latency (ms)	CPU Usage (%)	Mem Usage (MB)
Prototype	122060.232	10.674	8.9248	8.0674	98.412	7.451171875
with MMAP (h2c)	224543.5	3.7808	2.9148	2.4816	89.632	20.30703125
with MMAP + TLS	190543.634	6.327	4.626	3.074	92.728	15.84726563
Router (TLS)	175203.934	7.3868	5.8176	4.7424	98.974	15.94824219
Router (h2c)	199643.8	0.006327	0.004626	0.003074	92.728	0.015475845
LoadBalancer (TLS)	173702.098	7.306	5.9562	5.0248	99.208	18.12
LoadBalancer (h2c)	192895.766	6.7044	5.5092	4.5218	99.078	9.565039063

2) h2load -c1000 -m100

Server	QPS	P99 Latency (ms)	P90 Latency (ms)	P50 Latency (ms)	CPU Usage (%)	Mem Usage (MB)
Prototype	108745.666	968.666	891.9512	740.1804	85.978	76.84316406
with MMAP (h2c)	361051.334	290.2608	276.253	270.2988	99.236	84.17207031
with MMAP + TLS	340922.308	324.6172	290.5728	277.5948	99.892	125.9441406
Router (TLS)	218128.414	505.9948	473.1074	458.968	99.81	140.4175781
Router (h2c)	226110.666	486.169	453.9088	448.7806	99.536	98.51445313
Load Balancer (TLS)	205574.332	547.7828	508.3812	486.7182	99.942	141.19
Load Balancer (h2c)	221886.068	514.821	474.6454	445.1006	99.938	96.4296875