cpp-httplib

# cpp-httplib A C++11 single-file header-only cross platform HTTP/HTTPS library.
It's extremely easy to set up. Just include the **[httplib.h](https://raw.githubusercontent.com/yhirose/cpp-httplib/refs/heads/master/httplib.h)** file in your code! Learn more in the [official documentation](https://yhirose.github.io/cpp-httplib/) (built with [docs-gen](https://github.com/yhirose/docs-gen)). > [!IMPORTANT] > This library uses 'blocking' socket I/O. If you are looking for a library with 'non-blocking' socket I/O, this is not the one that you want. Only **HTTP/1.1** is supported — HTTP/2 and HTTP/3 are not implemented. > [!WARNING] > 32-bit platforms are **NOT supported**. Use at your own risk. The library may compile on 32-bit targets, but no security review has been conducted for 32-bit environments. Integer truncation and other 32-bit-specific issues may exist. **Security reports that only affect 32-bit platforms will be closed without action.** The maintainer does not have access to 32-bit environments for testing or fixing issues. CI includes basic compile checks only, not functional or security testing. ## Main Features - HTTP Server/Client - SSL/TLS support (OpenSSL, MbedTLS, wolfSSL) - [Stream API](README-stream.md) - [Server-Sent Events](README-sse.md) - [WebSocket](README-websocket.md) ## Simple examples ### Server ```c++ #define CPPHTTPLIB_OPENSSL_SUPPORT #include "path/to/httplib.h" // HTTP httplib::Server svr; // HTTPS httplib::SSLServer svr; svr.Get("/hi", [](const httplib::Request &, httplib::Response &res) { res.set_content("Hello World!", "text/plain"); }); svr.listen("0.0.0.0", 8080); ``` ### Client ```c++ #define CPPHTTPLIB_OPENSSL_SUPPORT #include "path/to/httplib.h" // HTTP httplib::Client cli("http://yhirose.github.io"); // HTTPS httplib::Client cli("https://yhirose.github.io"); if (auto res = cli.Get("/hi")) { res->status; res->body; } ``` ## SSL/TLS Support cpp-httplib supports multiple TLS backends through an abstraction layer: | Backend | Define | Libraries | Notes | | :------ | :----- | :-------- | :---- | | OpenSSL | `CPPHTTPLIB_OPENSSL_SUPPORT` | `libssl`, `libcrypto` | [3.0 or later](https://www.openssl.org/policies/releasestrat.html) required | | Mbed TLS | `CPPHTTPLIB_MBEDTLS_SUPPORT` | `libmbedtls`, `libmbedx509`, `libmbedcrypto` | 2.x, 3.x, and 4.x supported (auto-detected); 4.x renames `libmbedcrypto` to `libtfpsacrypto` | | wolfSSL | `CPPHTTPLIB_WOLFSSL_SUPPORT` | `libwolfssl` | 5.x supported; must build with `--enable-opensslall` | > [!NOTE] > **Mbed TLS / wolfSSL limitation:** `get_ca_certs()` and `get_ca_names()` only reflect CA certificates loaded via `load_ca_cert_store()`. Certificates loaded through `set_ca_cert_path()` or system certificates (`load_system_certs`) are not enumerable. > [!NOTE] > **BoringSSL (best-effort):** BoringSSL builds under `CPPHTTPLIB_OPENSSL_SUPPORT` and is exercised by CI against current upstream. Because BoringSSL does not guarantee API stability, support is best-effort — breakage may occasionally land. Two known behavioral differences vs OpenSSL: (1) BoringSSL's public headers require C++14 or later, so consumers must compile accordingly; (2) hostname verification is SAN-only per RFC 6125 §6.4.4 (no CN fallback). ``` … ``` ### SSL Error Handling When SSL operations fail, cpp-httplib provides detailed error information through `ssl_error()` and `ssl_backend_error()`: - `ssl_error()` - Returns the TLS-level error code (e.g., `SSL_ERROR_SSL` for OpenSSL) - `ssl_backend_error()` - Returns the backend-specific error code (e.g., `ERR_get_error()` for OpenSSL/wolfSSL, return value for Mbed TLS) ``` … ``` ### Custom Certificate Verification You can set a custom verification callback using `tls::VerifyCallback`: ``` … ``` ### Mutual TLS (mTLS) Regular TLS only verifies the server certificate. With mTLS, the client also presents a certificate that the server verifies. ```c++ // Server: pass a CA to verify client certificates against httplib::SSLServer svr("./cert.pem", "./key.pem", "./client-ca-cert.pem"); // Client: present a certificate httplib::SSLClient cli("api.example.com", 443, "./client-cert.pem", "./client-key.pem"); ``` Both `SSLServer` and `SSLClient` also accept an in-memory `PemMemory` struct instead of file paths — handy when certs come from an environment variable or a secrets manager: ``` … ``` `httplib::ws::WebSocketClient` has the same `PemMemory` constructor for `wss://` connections. See [README-websocket.md](README-websocket.md) for details. ### Peer Certificate Inspection On the server side, you can inspect the client's peer certificate from a request handler: ```c++ httplib::SSLServer svr("./cert.pem", "./key.pem", "./client-ca-cert.pem"); svr.Get("/", [](const httplib::Request &req, httplib::Response &res) { auto cert = req.peer_cert(); if (cert) { std::cout << "Client CN: " << cert.subject_cn() << std::endl; std::cout << "Serial: " << cert.serial() << std::endl; } auto sni = req.sni(); std::cout << "SNI: " << sni << std::endl; }); ``` ### Platform-specific Certificate Handling cpp-httplib automatically integrates with the OS certificate store on macOS and Windows. This works with all TLS backends. | Platform | Behavior | Disable (compile time) | | :------- | :------- | :--------------------- | | macOS | Loads system certs from Keychain (link `CoreFoundation` and `Security` with `-framework`). Requires Apple Clang; GCC is not supported for this feature. | `CPPHTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES` | | Windows | Verifies certs via CryptoAPI (`CertGetCertificateChain` / `CertVerifyCertificateChainPolicy`) with revocation checking | `CPPHTTPLIB_DISABLE_WINDOWS_AUTOMATIC_ROOT_CERTIFICATES_UPDATE` | On Windows, verification can also be disabled at runtime: ```c++ cli.enable_windows_certificate_verification(false); ``` > [!NOTE] > When using SSL, it seems impossible to avoid SIGPIPE in all cases, since on some operating systems, SIGPIPE can only be suppressed on a per-message basis, but there is no way to make the OpenSSL library do so for its internal communications. If your program needs to avoid being terminated on SIGPIPE, the only fully general way might be to set up a signal handler for SIGPIPE to handle or ignore it yourself. ## Server ``` … ``` `Post`, `Put`, `Patch`, `Delete` and `Options` methods are also supported. ### Custom HTTP methods Methods outside the built-in set are rejected with `400 Bad Request` unless a handler is registered for them with `CustomRoute`. This covers the WebDAV methods of RFC 4918, `SUBSCRIBE` and friends from UPnP, and any other extension method. ``` … ``` Patterns work exactly as they do for `Get` and the other methods, so regular expressions and path parameters are both available. Note the following: * The method name must be a valid HTTP method token (RFC 9110) and must be registered before `listen()` is called. * `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` and `PRI` cannot be registered this way. Use the dedicated methods above instead. * A rejected registration makes `is_valid()` return `false`, and `listen()` then fails rather than starting a server with a route that would never fire. * Static file serving and WebSocket upgrades remain `GET`/`HEAD` only. * `Allow` and the WebDAV `DAV:` header are not generated automatically. Register an `Options` handler if clients need them. ### Bind a socket to multiple interfaces and any available port ```cpp int port = svr.bind_to_any_port("0.0.0.0"); svr.listen_after_bind(); ``` ### Static File Server ```cpp // Mount / to ./www directory auto ret = svr.set_mount_point("/", "./www"); if (!ret) { // The specified base directory doesn't exist... } // Mount /public to ./www directory ret = svr.set_mount_point("/public", "./www"); // Mount /public to ./www1 and ./www2 directories ret = svr.set_mount_point("/public", "./www1"); // 1st order to search ret = svr.set_mount_point("/public", "./www2"); // 2nd order to search // Remove mount / ret = svr.remove_mount_point("/"); // Remove mount /public ret = svr.remove_mount_point("/public"); ``` ```cpp // User defined file extension and MIME type mappings svr.set_file_extension_and_mimetype_mapping("cc", "text/x-c"); svr.set_file_extension_and_mimetype_mapping("cpp", "text/x-c"); svr.set_file_extension_and_mimetype_mapping("hh", "text/x-h"); ``` The following are built-in mappings: | Extension | MIME Type | Extension | MIME Type | | :--------- | :-------------------------- | :--------- | :-------------------------- | | css | text/css | mpga | audio/mpeg | | csv | text/csv | weba | audio/webm | | txt | text/plain | wav | audio/wave | | vtt | text/vtt | otf | font/otf | | html, htm | text/html | ttf | font/ttf | | apng | image/apng | woff | font/woff | | avif | image/avif | woff2 | font/woff2 | | bmp | image/bmp | 7z | application/x-7z-compressed | | gif | image/gif | atom | application/atom+xml | | png | image/png | pdf | application/pdf | | svg | image/svg+xml | mjs, js | text/javascript | | webp | image/webp | json | application/json | | ico | image/x-icon | rss | application/rss+xml | | tif | image/tiff | tar | application/x-tar | | tiff | image/tiff | xhtml, xht | application/xhtml+xml | | jpeg, jpg | image/jpeg | xslt | application/xslt+xml | | mp4 | video/mp4 | xml | application/xml | | mpeg | video/mpeg | gz | application/gzip | | webm | video/webm | zip | application/zip | | mp3 | audio/mp3 | wasm | application/wasm | > [!WARNING] > These static file server methods are not thread-safe. > [!NOTE] > On POSIX systems, the static file server rejects requests that resolve (via symlinks) to a path outside the mounted base directory. Ensure that the served directory has appropriate permissions, as managing access to the served directory is the application developer's responsibility. ### File request handler ```cpp // The handler is called right before the response is sent to a client svr.set_file_request_handler([](const Request &req, Response &res) { ... }); ``` ### Logging cpp-httplib provides separate logging capabilities for access logs and error logs, similar to web servers like Nginx and Apache. #### Access Logging Access loggers capture successful HTTP requests and responses: ```cpp svr.set_logger([](const httplib::Request& req, const httplib::Response& res) { std::cout << req.method << " " << req.path << " -> " << res.status << std::endl; }); ``` #### Pre-compression Logging You can also set a pre-compression logger to capture request/response data before compression is applied: ```cpp svr.set_pre_compression_logger([](const httplib::Request& req, const httplib::Response& res) { // Log before compression - res.body contains uncompressed content // Content-Encoding header is not yet set your_pre_compression_logger(req, res); }); ``` The pre-compression logger is only called when compression would be applied. For responses without compression, only the access logger is called. For a static file response (