Compression

Burl can advertise the content codings it accepts and transparently decode a compressed response body, so gzip, deflate, br, and zstd responses arrive already decompressed. Decoding depends on the relevant Boost.Http service being installed in the system context.

Installing the Decode Services

Decoding is provided by Boost.Http and must be registered in the system context once at startup, before any clients are constructed.

The decoder services are provided by the Boost::http_brotli, Boost::http_zlib, and Boost::http_zstd libraries. Each library is available only when Boost.Http is built with the corresponding compression library. Link the libraries for the compression formats you use, and guard the installation calls with the feature macros they define. This keeps the program portable across builds that do not include all compression libraries.

// Install the available decoder services.
[[maybe_unused]] auto& ctx = capy::get_system_context();

#ifdef BOOST_HTTP_HAS_BROTLI
http::brotli::install_decode_service(ctx);
#endif

#ifdef BOOST_HTTP_HAS_ZLIB
http::zlib::install_inflate_service(ctx);
#endif

#ifdef BOOST_HTTP_HAS_ZSTD
http::zstd::install_decompress_service(ctx);
#endif

Burl does not link against any compression library directly. Instead, it looks up the corresponding decoder services at run time.

How It Works

With a service installed and the corresponding setting enabled, the client adds that coding to the Accept-Encoding request header and decodes a response encoded with it.

burl::client::config cfg;
cfg.gzip    = true;
cfg.deflate = true;
cfg.brotli  = false;   // do not advertise or decode br
cfg.zstd    = false;   // do not advertise or decode zstd

burl::client client(co_await capy::this_coro::executor, tls_ctx, cfg);

A coding whose decode service is not installed when the client is constructed is disabled regardless of the setting, since the client cannot honor what it advertises.

The decoding is transparent: the body you read through any of the body functions is the decoded content, and response::content_length and the Content-Length header reflect the encoded size as sent on the wire.

Opting Out for a Request

A request that sets its own Accept-Encoding header is left alone: the client neither adds codings to it nor decodes the response. This is the way to control encoding for a single request:

auto [ec, r] = co_await client.get("https://example.com/data")
    .header(http::field::accept_encoding, "identity")
    .send();

Next Steps

Edit this Page