yhirose / 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** file in your code! Learn more in the official documentation (built with 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. > [!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 • Server-Sent Events • WebSocket Simple examples Server Client SSL/TLS Support cpp-httplib supports multiple TLS backends through an abstraction layer: | Backend | Define | Libraries | Notes | | :------ | :----- | :-------- | :---- | | OpenSSL | | , | 3.0 or later required | | Mbed TLS | | , , | 2.x and 3.x supported (auto-detected) | | wolfSSL | | | 5.x supported; must build with | > [!NOTE] > **Mbed TLS / wolfSSL limitation:** and only reflect CA certificates loaded via . Certificates loaded through or system certificates ( ) are not enumerable. SSL Error Handling When SSL operations fail, cpp-httplib provides detailed error information through and : • - Returns the TLS-level error code (e.g., for OpenSSL) • - Returns the backend-specific error code (e.g., for OpenSSL/wolfSSL, return value for Mbed TLS) Custom Certificate Verification You can set a custom verification callback using : Peer Certificate Inspection On the server side, you can inspect the client's peer certificate from a request handler: 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 and with ) | | | Windows | Verifies certs via CryptoAPI ( / ) with revocation checking | | On Windows, verification can also be disabled at runtime: > [!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 , , , and methods are also supported. Bind a socket to multiple interfaces and any available port Static File Server 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 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: Pre-compression Logging You can also set a pre-compression logger to capture request/response data before compression is applied: The pre-compression logger is only called when compression would be applied. For responses without compression, only the access logger is called. Error Logging Error loggers capture failed requests and connection issues. Unlike access loggers, error loggers only receive the Error and Request information, as errors typically occur before a meaningful Response can be generated. Error handler Exception handler The exception handler gets called if a user routing handler throws an error. > [!CAUTION] > if you don't provide the block for a rethrown exception pointer, an uncaught exception will end up causing the server crash. Be careful! Pre routing handler Post routing handler Pre request handler Response user data is a that lets pre-routing or pre-request handlers pass arbitrary data to route handlers. mirrors the C++17 API. On C++17 and later it is an alias for ; on C++11/14 a compatible implementation is provided. Form data handling URL-encoded form data ('application/x-www-form-urlencoded') 'multipart/form-data' POST data Filename Sanitization in multipart uploads is an untrusted value from the…