yhirose
bef278e0d2
Samples that did not compile or run as shown: - res.user_data.get<T>() inside a generic lambda needs the `template` keyword; use explicit parameter types (tour 09, cookbook s15). - listen() on a Unix domain socket fails with port 0 (tour 09, s22). - "*.dev.local" is not a NO_PROXY pattern (c16). - ssl_backend_error() holds a verify result, not an ERR_get_error() value, after a verification failure; decode each with the matching OpenSSL function (c18). - The content provider's `length` is everything that remains, so the sample read the whole file in one call (s05). Statements corrected: - Client keep-alive is off by default; c14 is rewritten around set_keep_alive(true). - Mounted files are looked up before GET handlers (tour 04, s04). - Params keep insertion order, and to_string(Error::Connection) reads "Could not establish connection" (tour 02). - A chunked provider ends with sink.done(), and post_routing_handler runs before the response is sent (tour 09). - Timeouts surface as Error::Read; Error::Timeout comes from the stream API (c17). The max timeout cuts off the wait for the response only (c13). The progress callback needs Content-Length (c11). - Encoding selection follows q-values, then Brotli, gzip, Zstd (s08), and the client compresses with the first of those it was built with (c15). - stop() cuts a provider-driven response short (s19); a rejected content_reader already gets 400 or 413 (s07); user_data values must be copyable (s12); Client accepts a client certificate too (t04); on_message() is the fallback for every unhandled event and 204/403/404 end reconnection (e04); the pong timeout takes two to three intervals and ends a waiting read() (w02). In the LLM app tutorial, an uncaught exception does not crash the server, so say what it does instead. Drop the server and client timeout settings whose stated purpose, covering inference and download time, they do not serve: those timeouts bound a single socket wait. Update the llama.cpp server layout in chapter 7.
3.8 KiB
title, order, status
| title | order | status |
|---|---|---|
| S08. Return a Compressed Response | 27 | draft |
cpp-httplib automatically compresses response bodies when the client indicates support via Accept-Encoding. The handler doesn't need to do anything special. Supported encodings are gzip, Brotli, and Zstd.
Build-time setup
To enable compression, define the relevant macros before including httplib.h:
#define CPPHTTPLIB_ZLIB_SUPPORT // gzip
#define CPPHTTPLIB_BROTLI_SUPPORT // brotli
#define CPPHTTPLIB_ZSTD_SUPPORT // zstd
#include <httplib.h>
You'll also need to link zlib, brotli, and zstd respectively. Enable only what you need.
Usage
svr.Get("/api/data", [](const httplib::Request &req, httplib::Response &res) {
std::string body = build_large_response();
res.set_content(body, "application/json");
});
That's it. If the client sent Accept-Encoding: gzip, cpp-httplib compresses the response with gzip automatically. Content-Encoding: gzip and Vary: Accept-Encoding are added for you.
Encoding priority
When the client accepts multiple encodings, cpp-httplib picks the one with the highest q-value in Accept-Encoding. On a tie the order is Brotli → gzip → Zstd (among those enabled at build time).
Streaming responses are compressed too
Streaming responses via set_chunked_content_provider() get the same automatic compression.
svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
res.set_chunked_content_provider(
"text/plain",
[](size_t offset, httplib::DataSink &sink) {
// ...
});
});
Static files need to be opted in
Files served as they are, through set_mount_point() or Response::set_file_content(), are not compressed by default. Turn it on with:
svr.set_static_file_compression(true);
Only files within a size range are compressed, and both ends of it can be moved:
svr.set_static_file_compression_min_length(512);
svr.set_static_file_compression_max_length(1024 * 1024);
The lower bound defaults to 1400 bytes. A response that already fits in a single 1500-byte MTU is not delivered any faster for being smaller, and a file of a few bytes comes back larger than it went in, because gzip's header and trailer outweigh what deflate saves.
The upper bound defaults to 4MB and exists for a different reason: the file is compressed on every request, and the compressed bytes stay in memory until the response has been written, so the peak cost scales with the number of requests in flight. It bounds what a single request can cost, and says nothing about how well large files compress, so raising it is reasonable when the files are known and the traffic is not.
Either bound takes 0 to turn it off, and each has a compile-time default (CPPHTTPLIB_STATIC_FILE_COMPRESSION_MIN_LENGTH, CPPHTTPLIB_STATIC_FILE_COMPRESSION_MAX_LENGTH).
A compressed response keeps its Content-Length, so HEAD reports the same size a GET would. Two details to know: Range requests are answered from the uncompressed representation, and the ETag carries the coding it belongs to, as in W/"...-gzip".
Content providers registered with set_content_provider() are not covered. Running one through a compressor holds each write back until the internal buffer fills, which stalls providers that build their body a piece at a time. To compress a generated body, use set_chunked_content_provider().
Note: The size range covers static files only. A body passed to
set_content()is compressed whenever the client accepts it and the MIME type is compressible, however small it is, so a response of a few bytes ends up larger than it started. Decide in the handler if you want to avoid that.
For the client-side counterpart, see C15. Enable compression.