mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-09-02 14:53:46 +00:00
139f30e0f1
* Drop the claim that small bodies skip compression There is no size threshold anywhere in the compression path. encoding_type() gates on the content type and Accept-Encoding only, and apply_ranges() compresses whatever body it is given, so a two-byte text/plain response comes back gzipped at 22 bytes. Say what actually happens and leave the decision to the handler. * Compress static file responses behind an opt-in (Fix #2545) apply_ranges() runs the compressor inside the branch it takes when res.body is non-empty. A response served from a file leaves res.body empty and sets content_length_, so it took the other branch, which writes Content-Length and returns; encoding_type() was computed before the split and never consulted on that side. The same bytes handed to set_content() came back gzipped, which left set_mount_point() and Response::set_file_content() as the one path that missed out. Add Server::set_static_file_compression(), off by default so nothing about an existing server changes. When it is on, the file-backed provider is run through the compressor into res.body ahead of the rest of apply_ranges(), so the response is framed the way set_content() already frames one: it keeps its Content-Length, and HEAD still reports the size a GET would return. Ranges are answered from the identity representation, since RFC 9110 applies Range after content coding and slicing a compressed body would mean compressing the whole file first. The ETag carries the coding it belongs to, so a client that cached the compressed form revalidates against its own validator rather than the identity one. Both the ETag and the body take their coding from static_file_encoding(), so the two cannot disagree. Providers registered with set_content_provider() are left alone. zlib buffers until its window fills, so running one through a compressor would hold back writes that a caller expects to reach the peer as they are produced. The compressed bytes stay in memory until the response has been written, so the peak cost scales with requests in flight. set_static_file_compression_max_length() bounds it, defaulting to 4MB. * Add a minimum size for static file compression Compressing a file that already fits in a single 1500-byte MTU does not get it to the client any sooner, and a file of a few bytes comes back larger than it went in once gzip's header and trailer are added. Every other server draws this line: nginx's gzip_min_length, Caddy's minimum_length, IIS's minFileSizeForComp, CloudFront's 1000-byte floor. The note this replaces told callers to decide in the handler. A response served through set_mount_point() has no handler to decide in, so the floor has to live in the server. It defaults to 1400 bytes, the size that fits inside one MTU with room for headers. set_static_file_compression_min_length() moves it, and CPPHTTPLIB_STATIC_FILE_COMPRESSION_MIN_LENGTH sets the default at compile time. The empty-file case keeps its own early-out so that a zero floor still cannot turn an empty body into a 20-byte gzip stream. The two bounds now read as a pair, so the documentation says what each one is for: the lower bound is about what is worth compressing, the upper bound about what one request is allowed to cost. Every file under test/www except 1MB.txt is below the default floor, so the tests that need a small file compressed lower it explicitly.
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
---
|
|
title: "S08. Return a Compressed Response"
|
|
order: 27
|
|
status: "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`:
|
|
|
|
```cpp
|
|
#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
|
|
|
|
```cpp
|
|
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 in this order (among those enabled at build time): Brotli → Zstd → gzip. Your code doesn't need to care — you always get the most efficient option available.
|
|
|
|
## Streaming responses are compressed too
|
|
|
|
Streaming responses via `set_chunked_content_provider()` get the same automatic compression.
|
|
|
|
```cpp
|
|
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:
|
|
|
|
```cpp
|
|
svr.set_static_file_compression(true);
|
|
```
|
|
|
|
Only files within a size range are compressed, and both ends of it can be moved:
|
|
|
|
```cpp
|
|
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](../c15-compression).
|