# yhirose/cpp-httplib architecture

> Architecture diagram of the GitHub repository yhirose/cpp-httplib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yhirose/cpp-httplib
- Repository: https://github.com/yhirose/cpp-httplib

## Overview

##### Project Type and Purpose
- This is an open-source, header-only C++11 library (cpp-httplib) that provides both HTTP/HTTPS client and server functionality via a single `httplib.h` file.
- It’s not a monolithic application but a reusable toolkit that application developers include in their code.

##### File Structure Analysis
- Core Library
- `httplib.h` – the single-file header containing the entire public API and implementation when included.
- `split.py` – helper to split the header into `.h`/`.cc` for projects that prefer separate compilation.
- Build & Packaging
- `CMakeLists.txt`, `meson.build`, `Makefile` scripts – support CMake, Meson and plain‐Make builds.
- `cmake/httplibConfig.cmake.in`, `FindBrotli.cmake` – custom CMake helpers for packaging and optional dependencies.
- `Dockerfile`, `docker-compose.yml` – build a static HTTP server image serving `/html`.
- Examples & Benchmarks
- `example/` – dozens of client and server usage examples (plain HTTP, HTTPS, SSE, uploads, proxies).
- `benchmark/` – performance comparisons against other header-only libraries (cpp-httplib v18/v19, crow).
- Testing & CI
- `test/` – unit tests (Google Test), fuzz tests (libFuzzer, ClusterFuzz), integration tests (proxy, files, SSL).
- `.github/workflows/` – GitHub Actions pipelines for testing, ABI diffs, and fuzzing.

##### Components
A. Core Library Component
- “cpp-httplib Core” (httplib.h) subdivided into:
- Server module (blocking sockets, thread pool, routing, static file server)
- Client module (HTTP/HTTPS requests, headers, streaming, multipart, proxies)
- Optional extensions (SSL/OpenSSL, zlib, Brotli, UDS) toggled via macros.
B. External Dependencies
- OS networking (BSD sockets / Winsock)
- OpenSSL (`libssl`, `libcrypto`)
- zlib (`libz`), Brotli library
C. Build & Test Infrastructure
- Build systems (CMake, Meson, Make)
- Python split script
- Docker build for static server
- CI pipelines (GitHub Actions) orchestrating builds, tests, fuzzing
D. Consumer Applications & Examples
- Example binaries (`hello`, `server`, `client`, `ssecli`, etc.)
- Docker static server container
- Benchmarks invoking both examples and core library

##### Relationships and Interactions
- Core Library → OS Sockets (blocking I/O)
- Core Library → External Libraries (OpenSSL, zlib, Brotli)
- Build & CI → Core Library & Tests (compilation/test automation pipelines)
- Docker image → Core Library (static server entrypoint uses core’s Server API)
- Benchmarks → Core Library and competitor libraries

##### Architectural Patterns & Design Principles
- Header-only design for zero-dependency inclusion
- Compile-time feature flags (`#define CPPHTTPLIB_OPENSSL_SUPPORT`, etc.)
- Blocking I/O with a default thread pool (TaskQueue abstraction)
- Extensibility hooks (custom ThreadPool, file handlers, routing middleware)
- Single responsibility: routing, concurrency, SSL, compression each modularized

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        OS["OS Networking (BSD Sockets/Winsock)"]:::external
        OpenSSL["OpenSSL (libssl, libcrypto)"]:::external
        Zlib["zlib (libz)"]:::external
        Brotli["Brotli Library"]:::external
    end

    %% Core Library
    subgraph "cpp-httplib Core" 
        direction TB
        httplib_h["httplib.h"]:::core
        split_py["split.py"]:::core
        subgraph "Modules"
            direction TB
            Server["Server Module"]:::core
            Client["Client Module"]:::core
            Extensions["Optional Extensions"]:::core
        end
    end

    %% Build & CI Infrastructure
    subgraph "Build & CI Infrastructure"
        direction TB
        subgraph "Build Systems"
            CMake["CMakeLists.txt"]:::infra
            Meson["meson.build / meson_options.txt"]:::infra
            Make["Makefile"]:::infra
        end
        split_py_ci["split.py"]:::infra
        subgraph "Docker Packaging"
            Dockerfile["Dockerfile"]:::infra
            Compose["docker-compose.yml"]:::infra
            HTML["docker/html/index.html"]:::infra
            DockerMain["docker/main.cc"]:::infra
            HelloDocker["example/Dockerfile.hello"]:::infra
        end
        subgraph "CI Pipelines"
            GH_Test[".github/workflows/test.yaml"]:::infra
            GH_ABI[".github/workflows/abidiff.yaml"]:::infra
            GH_CIFuzz[".github/workflows/cifuzz.yaml"]:::infra
        end
    end

    %% Consumer Applications & Tests
    subgraph "Examples / Benchmarks / Tests"
        direction TB
        subgraph "Examples"
            Hello["hello.cc"]:::consumer
            ServerEx["server.cc"]:::consumer
            ClientEx["client.cc"]:::consumer
            SSECli["ssecli.cc"]:::consumer
            SSESvc["ssesvr.cc"]:::consumer
            Upload["upload.cc"]:::consumer
            ExMake["example/Makefile"]:::consumer
        end
        subgraph "Benchmarks"
            BM_Make["benchmark/Makefile"]:::consumer
            BM_v18["cpp-httplib-v18"]:::consumer
            BM_v19["cpp-httplib-v19"]:::consumer
            BM_master["cpp-httplib-master"]:::consumer
            BM_crow["crow benchmark"]:::consumer
        end
        subgraph "Tests & Fuzzing"
            UT1["test/test.cc"]:::consumer
            UT2["test/test_proxy.cc"]:::consumer
            TCM["test/CMakeLists.txt"]:::consumer
            TMK["test/Makefile"]:::consumer
            FuzzDir["test/fuzzing"]:::consumer
            Certs["test/ca-bundle.crt & configs"]:::consumer
        end
    end

    %% Relationships
    Hello -->|"#include httplib.h"| httplib_h
    ServerEx -->|"#include httplib.h"| httplib_h
    ClientEx -->|"#include httplib.h"| httplib_h
    SSECli -->|"#include httplib.h"| httplib_h
    SSESvc -->|"#include httplib.h"| httplib_h
    Upload -->|"#include httplib.h"| httplib_h

    BM_Make -->|"builds and runs"| httplib_h
    BM_v18 -->|"bibliography compare"| httplib_h
    BM_v19 -->|"bibliography compare"| httplib_h
    BM_master -->|"bibliography compare"| httplib_h
    BM_crow -->|"competitor"| httplib_h

    UT1 -->|"unit test on"| httplib_h
    UT2 -->|"unit test on"| httplib_h
    FuzzDir -->|"fuzz test on"| httplib_h

    CMake -->|"build configuration"| httplib_h
    Meson -->|"build configuration"| httplib_h
    Make -->|"build configuration"| httplib_h
    split_py_ci -->|"splits header"| httplib_h

    GH_Test -->|"run tests on"| httplib_h
    GH_ABI -->|"ABI diff on"| httplib_h
    GH_CIFuzz -->|"fuzz on"| httplib_h

    Dockerfile -->|"builds image using"| DockerMain
    DockerMain -->|"uses Server API from"| httplib_h
    Compose -->|"orchestrates image"| Dockerfile
    HTML -->|"served by static server"| DockerMain

    %% Core to External
    httplib_h -->|"uses blocking I/O"| OS
    httplib_h -->|"optional SSL"| OpenSSL
    httplib_h -->|"optional compression"| Zlib
    httplib_h -->|"optional compression"| Brotli
    Server -->|"implements routing & static files"| OS
    Client -->|"HTTP/HTTPS requests"| OS

    %% Click events
    click httplib_h "https://github.com/yhirose/cpp-httplib/blob/master//httplib.h"
    click split_py "https://github.com/yhirose/cpp-httplib/blob/master//split.py"
    click CMake "https://github.com/yhirose/cpp-httplib/blob/master//CMakeLists.txt"
    click Meson "https://github.com/yhirose/cpp-httplib/blob/master//meson.build"
    click Meson "https://github.com/yhirose/cpp-httplib/blob/master//meson_options.txt"
    click Make "https://github.com/yhirose/cpp-httplib/tree/master//Makefile"
    click Dockerfile "https://github.com/yhirose/cpp-httplib/tree/master//Dockerfile"
    click Compose "https://github.com/yhirose/cpp-httplib/blob/master//docker-compose.yml"
    click HTML "https://github.com/yhirose/cpp-httplib/blob/master//docker/html/index.html"
    click DockerMain "https://github.com/yhirose/cpp-httplib/blob/master//docker/main.cc"
    click HelloDocker "https://github.com/yhirose/cpp-httplib/blob/master//example/Dockerfile.hello"
    click Hello "https://github.com/yhirose/cpp-httplib/blob/master//example/hello.cc"
    click ServerEx "https://github.com/yhirose/cpp-httplib/blob/master//example/server.cc"
    click ClientEx "https://github.com/yhirose/cpp-httplib/blob/master//example/client.cc"
    click SSECli "https://github.com/yhirose/cpp-httplib/blob/master//example/ssecli.cc"
    click SSESvc "https://github.com/yhirose/cpp-httplib/blob/master//example/ssesvr.cc"
    click Upload "https://github.com/yhirose/cpp-httplib/blob/master//example/upload.cc"
    click ExMake "https://github.com/yhirose/cpp-httplib/tree/master//example/Makefile"
    click BM_Make "https://github.com/yhirose/cpp-httplib/tree/master//benchmark/Makefile"
    click BM_v18 "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/cpp-httplib-v18/httplib.h"
    click BM_v18 "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/cpp-httplib-v18/main.cpp"
    click BM_v19 "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/cpp-httplib-v19/httplib.h"
    click BM_v19 "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/cpp-httplib-v19/main.cpp"
    click BM_master "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/cpp-httplib/main.cpp"
    click BM_crow "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/crow/crow_all.h"
    click BM_crow "https://github.com/yhirose/cpp-httplib/blob/master//benchmark/crow/main.cpp"
    click UT1 "https://github.com/yhirose/cpp-httplib/blob/master//test/test.cc"
    click UT2 "https://github.com/yhirose/cpp-httplib/blob/master//test/test_proxy.cc"
    click TCM "https://github.com/yhirose/cpp-httplib/blob/master//test/CMakeLists.txt"
    click TMK "https://github.com/yhirose/cpp-httplib/tree/master//test/Makefile"
    click FuzzDir "https://github.com/yhirose/cpp-httplib/blob/master//test/fuzzing/server_fuzzer.cc"
    click FuzzDir "https://github.com/yhirose/cpp-httplib/blob/master//test/fuzzing/standalone_fuzz_target_runner.cpp"
    click FuzzDir "https://github.com/yhirose/cpp-httplib/tree/master//test/fuzzing/Makefile"
    click FuzzDir "https://github.com/yhirose/cpp-httplib/blob/master//test/fuzzing/CMakeLists.txt"
    click FuzzDir "https://github.com/yhirose/cpp-httplib/tree/master//test/fuzzing/corpus"
    click Certs "https://github.com/yhirose/cpp-httplib/blob/master//test/ca-bundle.crt"
    click Certs "https://github.com/yhirose/cpp-httplib/blob/master//test/gen-certs.sh"
    click Certs "https://github.com/yhirose/cpp-httplib/blob/master//test/test.conf"
    click Certs "https://github.com/yhirose/cpp-httplib/blob/master//test/test.rootCA.conf"
    click GH_Test "https://github.com/yhirose/cpp-httplib/blob/master//.github/workflows/test.yaml"
    click GH_ABI "https://github.com/yhirose/cpp-httplib/blob/master//.github/workflows/abidiff.yaml"
    click GH_CIFuzz "https://github.com/yhirose/cpp-httplib/blob/master//.github/workflows/cifuzz.yaml"

    %% Styles
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef external fill:#ffcdd2,stroke:#b71c1c,color:#b71c1c;
    classDef infra fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef consumer fill:#ffe0b2,stroke:#e65100,color:#e65100;
```
