cpp-httplib — Header-Only C++ HTTP/HTTPS Server and Client Library

Introduction

cpp-httplib is a cross-platform, header-only C++ library that makes building HTTP/HTTPS servers and clients as simple as including a single file. It targets developers who need straightforward HTTP functionality without pulling in heavyweight frameworks or complex build dependencies.

What cpp-httplib Does

• Creates HTTP/HTTPS servers with route handlers using lambda callbacks and path pattern matching
• Provides an HTTP client for making GET, POST, PUT, DELETE, and other standard requests
• Supports SSL/TLS via OpenSSL, MbedTLS, or wolfSSL backends for encrypted connections
• Handles multipart form data, file uploads, and chunked transfer encoding automatically
• Includes built-in WebSocket support and Server-Sent Events (SSE) for real-time communication

Architecture Overview

The library is contained entirely in a single header file (httplib.h). It uses blocking socket I/O with a thread-per-connection model managed by an internal thread pool. Request routing is handled through a pattern-matching system that maps URL paths to user-defined handlers. TLS support is compiled in conditionally based on preprocessor definitions, keeping the library lightweight when encryption is not needed.

Self-Hosting & Configuration

• Include httplib.h in your project — no build system integration required
• Define CPPHTTPLIB_OPENSSL_SUPPORT and link OpenSSL for HTTPS support
• Define CPPHTTPLIB_ZLIB_SUPPORT to enable gzip compression on responses
• Thread pool size is configurable via svr.new_task_queue for tuning concurrency
• Supports both IPv4 and IPv6 binding with configurable listen backlog

Key Features

• True single-header design with zero mandatory dependencies
• Built-in support for gzip, Brotli, and Zstandard response compression
• Stream API for handling large file downloads without buffering entire responses in memory
• Regex-based URL routing with path parameter capture
• Cross-platform compatibility across Linux, macOS, and Windows (MSVC, GCC, Clang)

Comparison with Similar Tools

• Crow — also header-only but uses async I/O; cpp-httplib is simpler with blocking sockets
• Drogon — full async framework with ORM and WebSocket; cpp-httplib is lighter and easier to embed
• Boost.Beast — lower-level HTTP/WebSocket on Boost.Asio; cpp-httplib abstracts away all networking details
• Pistache — REST-focused with async design; cpp-httplib covers more protocols with less setup
• cpr — client-only wrapper around libcurl; cpp-httplib provides both server and client

FAQ

Q: Is cpp-httplib suitable for high-concurrency production servers? A: It uses blocking I/O and a thread pool, so it works well for moderate concurrency. For tens of thousands of simultaneous connections, consider an async framework.

Q: How do I enable HTTPS? A: Define CPPHTTPLIB_OPENSSL_SUPPORT, link OpenSSL, and use httplib::SSLServer with your certificate and key paths.

Q: Does it support HTTP/2? A: No. cpp-httplib implements HTTP/1.1 only. Use a reverse proxy like Nginx for HTTP/2 termination.

Q: Can I serve static files? A: Yes. Use svr.set_mount_point("/", "/path/to/www") to serve a directory of static files.

Sources

• https://github.com/yhirose/cpp-httplib
• https://github.com/yhirose/cpp-httplib#readme