SSL/TLS Support  Copy Chapter
cpp-httplib supports multiple TLS backends through an abstraction layer:
| Backend | Define | Libraries | Notes |
| :------ | :----- | :-------- | :---- |
| OpenSSL | CPPHTTPLIB_OPENSSL_SUPPORT | libssl, libcrypto | 3.0 or later required |
| Mbed TLS | CPPHTTPLIB_MBEDTLS_SUPPORT | libmbedtls, libmbedx509, libmbedcrypto | 2.x and 3.x supported (auto-detected) |
| 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.

SSL Error Handling  Copy Section
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  Copy Section
You can set a custom verification callback using tls::VerifyCallback:

Peer Certificate Inspection  Copy Section
On the server side, you can inspect the client's peer certificate from a request handler:

Platform-specific Certificate Handling  Copy Section
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:

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  Copy Chapter

Post, Put, Patch, Delete and Options methods are also supported.
Bind a socket to multiple interfaces and any available port  Copy Section

Static File Server  Copy Section

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  Copy Section

Logging  Copy Section
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  Copy Section

Exception handler  Copy Section

The exception handler gets called if a user routing handler throws an error.

CAUTION
if you don't provide the catch (...) block for a rethrown exception pointer, an uncaught exception will end up causing the server crash. Be careful!
Pre routing handler  Copy Section

Post routing handler  Copy Section

Pre request handler  Copy Section

Response user data  Copy Section
res.user_data is a type-safe key-value store that lets pre-routing or pre-request handlers pass arbitrary data to route handlers.

Form data handling  Copy Section
#### URL-encoded form data ('application/x-www-form-urlencoded')

#### 'multipart/form-data' POST data

#### Filename Sanitization
file.filename in multipart uploads is an untrusted value from the client. Always sanitize before using it in file paths:

This function strips path separators (/, \), null bytes, leading/trailing whitespace, and rejects . and ... Returns an empty string if the filename is unsafe.
Receive content with a content receiver  Copy Section

Send content with the content provider  Copy Section

Without content length:

Chunked transfer encoding  Copy Section

With trailer:

Send file content  Copy Section

'Expect: 100-continue' handler  Copy Section
By default, the server sends a 100 Continue response for an Expect: 100-continue header.

Keep-Alive connection  Copy Section

Timeout  Copy Section

Set maximum payload length for reading a request body  Copy Section

NOTE
When the request body content type is 'www-form-urlencoded', the actual payload length shouldn't exceed CPPHTTPLIB_FORM_URL_ENCODED_PAYLOAD_MAX_LENGTH.
Server-Sent Events  Copy Section
Please see Server example and Client example.
Default thread pool support  Copy Section
ThreadPool is used as the default task queue, with dynamic scaling support. By default, it maintains a base thread count of 8 or std::thread::hardware_concurrency() - 1 (whichever is greater), and can scale up to 4x that count under load. You can change these with CPPHTTPLIB_THREAD_POOL_COUNT and CPPHTTPLIB_THREAD_POOL_MAX_COUNT.
When all threads are busy and a new task arrives, a temporary thread is spawned (up to the maximum). When a dynamic thread finishes its task and the queue is empty, or after an idle timeout, it exits automatically. The idle timeout defaults to 3 seconds, configurable via CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT.
If you want to set the thread counts at runtime:

#### Max queued requests
You can also provide an optional parameter to limit the maximum number
of pending requests, i.e. requests accept()ed by the listener but
still waiting to be serviced by worker threads.

Default limit is 0 (unlimited). Once the limit is reached, the listener
will shutdown the client connection.
Override the default thread pool with yours  Copy Section
You can supply your own thread pool implementation according to your need.

Client  Copy Chapter

TIP
Constructor with scheme-host-port string is now supported!

Error code  Copy Section
Here is the list of errors from Result::error().

Client Logging  Copy Section
#### Access Logging

#### Error Logging

GET with HTTP headers  Copy Section

or

or

POST  Copy Section

POST with parameters  Copy Section

or

POST with Multipart Form Data  Copy Section

To upload files from disk without loading them entirely into memory, use make_file_provider. The file is sent with chunked transfer encoding.

POST with a file body  Copy Section
To POST a file as a raw binary body with Content-Length, use make_file_body.

PUT  Copy Section

PATCH  Copy Section

DELETE  Copy Section

OPTIONS  Copy Section

Timeout  Copy Section

Receive content with a content receiver  Copy Section

Send content with a content provider  Copy Section

Chunked transfer encoding  Copy Section

With Progress Callback  Copy Section

!progress
Authentication  Copy Section

NOTE
OpenSSL is required for Digest Authentication.
Proxy server support  Copy Section

NOTE
OpenSSL is required for Digest Authentication.
Range  Copy Section

Keep-Alive connection  Copy Section

Redirect  Copy Section

Use a specific network interface  Copy Section
NOTE
This feature is not available on Windows, yet.

Automatic Path Encoding  Copy Section
The client automatically encodes special characters in URL paths by default:

- set_path_encode(bool on) - Controls automatic encoding of special characters in URL paths
  - true (default): Automatically encodes spaces, plus signs, newlines, and other special characters
  - false: Sends paths as-is without encoding (useful for pre-encoded URLs)
Performance Note for Local Connections  Copy Section
WARNING
On Windows systems with improperly configured IPv6 settings, using "localhost" as the hostname may cause significant connection delays (up to 2 seconds per request) due to DNS resolution issues. This affects both client and server operations. For better performance when connecting to local services, use "127.0.0.1" instead of "localhost".

> See: https://github.com/yhirose/cpp-httplib/issues/366#issuecomment-593004264

Payload Limit  Copy Chapter
The maximum payload body size is limited to 100MB by default for both server and client. You can change it with set_payload_max_length() or by defining CPPHTTPLIB_PAYLOAD_MAX_LENGTH at compile time. Setting it to 0 disables the limit entirely.
Compression  Copy Chapter
The server can apply compression to the following MIME type contents:
- all text types except text/event-stream
- image/svg+xml
- application/javascript
- application/json
- application/xml
- application/protobuf
- application/xhtml+xml
Zlib Support  Copy Section
'gzip' compression is available with CPPHTTPLIB_ZLIB_SUPPORT. libz should be linked.
Brotli Support  Copy Section
Brotli compression is available with CPPHTTPLIB_BROTLI_SUPPORT. Necessary libraries should be linked.
Please see https://github.com/google/brotli for more detail.
Zstd Support  Copy Section
Zstd compression is available with CPPHTTPLIB_ZSTD_SUPPORT. Necessary libraries should be linked.
Please see https://github.com/facebook/zstd for more detail.
Default Accept-Encoding value  value')" title="Copy section prompt for LLMs"> Copy Section
The default Accept-Encoding value contains all possible compression types. So, the following two examples are same.

If we don't want a response without compression, we have to set Accept-Encoding to an empty string. This behavior is similar to curl.

Compress request body on client  Copy Section

Compress response body on client  Copy Section

Unix Domain Socket Support
--------------------------
Unix Domain Socket support is available on Linux and macOS.

"my-socket.sock" can be a relative path or an absolute path. Your application must have the appropriate permissions for the path. You can also use an abstract socket address on Linux. To use an abstract socket address, prepend a null byte ('\x00') to the path.
This library automatically sets the Host header to "localhost" for Unix socket connections, similar to curl's behavior:

URI Encoding/Decoding Utilities
-------------------------------
cpp-httplib provides utility functions for URI encoding and decoding:

Functions  Copy Section
- encode_uri(const std::string &value) - Encodes a full URI, preserving reserved characters like ://, ?, &, =
- decode_uri(const std::string &value) - Decodes a URI-encoded string
- encode_uri_component(const std::string &value) - Encodes a URI component (query parameter, path segment), encoding all reserved characters
- decode_uri_component(const std::string &value) - Decodes a URI component
Use encode_uri() for full URLs and encode_uri_component() for individual query parameters or path segments.
Stream API  Copy Chapter
Process large responses without loading everything into memory.

All HTTP methods are supported: stream::Get, Post, Put, Patch, Delete, Head, Options.
See README-stream.md for more details.
SSE Client  Copy Chapter

See README-sse.md for more details.
WebSocket  Copy Chapter

SSL is also supported via wss:// scheme (e.g. WebSocketClient("wss://example.com/ws")). Subprotocol negotiation (Sec-WebSocket-Protocol) is supported via SubProtocolSelector callback.
Note: WebSocket connections occupy a thread for their entire lifetime (plus an additional thread per connection for heartbeat pings). This thread-per-connection model is intended for small- to mid-scale workloads; large numbers of simultaneous WebSocket connections are outside the design target of this library. If you expect many concurrent WebSocket clients, configure a dynamic thread pool (svr.new_task_queue = [] { return new ThreadPool(8, 64); };) and measure carefully.
WebSocket extensions are not supported. permessage-deflate and other RFC 6455 extensions are not implemented. If a client proposes them via Sec-WebSocket-Extensions, the server silently declines them in its handshake response.
Unresponsive-peer detection. Heartbeat pings also serve as a liveness probe when set_websocket_max_missed_pongs(n) is set: if the client sends n consecutive pings without receiving a pong, it will close the connection. Disabled by default (0).
See README-websocket.md for more details.
Socket Option Utility  Copy Chapter
set_socket_opt is a convenience wrapper around setsockopt for setting integer socket options:

TIP
For most use cases, prefer set_tcp_nodelay(true) or set_socket_options(callback) on the Server/Client instead of calling set_socket_opt directly.
Split httplib.h into .h and .cc  Copy Chapter

Dockerfile for Static HTTP Server  Copy Chapter
Dockerfile for static HTTP server is available. Port number of this HTTP server is 80, and it serves static files from /html directory in the container.

From Docker Hub

NOTE
----
Regular Expression Stack Overflow  Copy Section
CAUTION
When using complex regex patterns in route handlers, be aware that certain patterns may cause stack overflow during pattern matching. This is a known issue with std::regex implementations and affects the dispatch_request() method.

>