0.3.4 — cancel a request in flight with a std::stop_token

[yspbwx2010]

A request that has been sent cannot be abandoned. A caller that stops caring about the response (a user who pressed Esc, a deadline that passed elsewhere) can only leave the call running on a thread and wait for readTimeoutMs, with the connection held open and the server still producing the answer. The TLS handshake has no timeout at all, so a server that accepts the connection and never replies holds the call for good.

This adds an optional std::stop_token to send, send_stream and download_to_file. Stopping its source from another thread ends the call within about 50 ms and closes the connection. Released as 0.3.4: everything is added, nothing changes without a token, and every dependency written tinyhttps = "0.3.x" receives it.

HttpResponse response;
std::jthread worker([&](std::stop_token stop) { response = client.send(request, stop); });
// elsewhere:
worker.request_stop();

Design and plan: .agents/docs/design-cancel-stop-token.md, .agents/docs/exec-plan-0.3.4-cancel.md.

API

HttpResponse send(const HttpRequest&, std::stop_token stop = {});
HttpResponse send_stream(const HttpRequest&, SseCallbackFn, std::stop_token stop = {});
DownloadToFileResult download_to_file(const std::string& url, const std::filesystem::path&,
                                      DownloadProgressFn = nullptr,
                                      std::function<bool()> isCancelled = nullptr,
                                      std::stop_token stop = {});

HttpResponse::cancelled and DownloadToFileResult::cancelled say why the call ended, so nobody has to match text. Before the status line: statusCode 0, text Cancelled. After it: the server's status, bodyError / error cancelled. ok() does not look at cancelled, as it does not look at bodyComplete. A cancelled request is not retried and its redirect is not followed. isCancelled keeps working and sets cancelled too.

proxy_tunnel takes the token as a trailing default argument; Socket and TlsSocket gain set_stop, Socket gains stop_possible. A call by name compiles unchanged; a pointer to one of the three members needs the new parameter in its type.

How it works

Three invariants:

1. The token lives only on the socket at the bottom of a connection. Every wait ends there (Socket::wait_fd), so that is where it is set; TlsSocket::set_stop forwards to the session beneath it, which inside an https:// proxy's tunnel is where the waits are.
2. It lives only for one call. perform_exchange sets it; PooledConnection::keep() takes it off when the connection goes back to the pool, so nothing in the pool carries a token. A token stopped after its call returned (a std::jthread does that in its destructor) cannot reach the next call.
3. Without a token nothing changes. Every wait is the single poll it was, and bio_recv does not poll first.

With a token, waits are polls in slices of at most 50 ms with a check between them, the connect checks before each address, and bio_recv waits before recv so the handshake and the second half of a TLS record are covered. A stop wins over whatever error the failure would otherwise report. shutdown(fd) from the stopping thread and a wake-up pipe were considered and rejected (fd-reuse races, no pipe on Windows, unmeasured connect semantics on macOS/Windows/openkal); slicing uses only the poll already used on every platform.

Not covered: name resolution, a write blocked because the server is not reading, and the connect above openkal (synchronous there).

Found and fixed on the way

• A reused https:// proxy tunnel kept the first call's token. set_stop set only the outer session's own socket, which is unused inside a tunnel. Once that token was stopped, every wait on the tunnel failed at once, and the stale-connection retry sent a POST the target had already received a second time (reproduced: three requests at the target for two calls); a later call's own token never reached the tunnel. Fixed by invariants 1 and 2; covered directly, through http:// and through https:// proxies.
• TLS never worked above openkal on x86_64-windows-musl. mbedTLS seeds from /dev/urandom unless it recognises glibc, and that file does not exist there: every handshake failed with CTR_DRBG - The entropy source failed. Where the C library is musl (cfg(c-abi = "musl"), as for the socket interface), the generator is now seeded from musl's getentropy, which openkal-musl answers through openkal.random.
• libc++ 20 and 22 fail to link std::stop_source::request_stop() in a file that includes <thread> or <condition_variable> before import std; (an inline helper is never emitted); libstdc++ needs the opposite order. test_cancel.cpp chooses by _LIBCPP_VERSION; README tells users.

Tests

tests/test_cancel.cpp, 24 cases against the in-process TLS server, a listener that never speaks, and the proxy servers. Read timeout 30 s, so only the token can end them.

• Stopped while waiting for the head, between stream chunks, during the handshake, before the call, during connect; a timeout left alone without a stop.
• Stopped while an HTTP, https or SOCKS5 proxy has not answered, and during the handshake inside an https proxy's tunnel.
• Not retried, redirect not followed, cancelled connection not reused, 20 cancellations leak no descriptors.
• Reuse, ×{direct, http proxy, https proxy}: a stop after the call returned does not reach the next call (a POST arrives once, the connection is reused); the next call's own token reaches the reused connection.
• download_to_file: cancelled before the head (no file created), during the body, with a token already stopped, and by isCancelled.

Removing the forwarding in TlsSocket::set_stop fails exactly the two https-proxy reuse cases.

CI

job	runs
linux, [email protected] and [email protected]	every test, templates
macos-15 arm64, [email protected]	every test (new)
windows-2022, msvc and [email protected]	test_ca_store + test_framing, test_tls_verify, test_pool, test_proxy, test_cancel (new)
above openkal: x86_64-linux-gnu, x86_64-linux-musl, aarch64-linux-musl (qemu), x86_64-windows-musl (wine)	examples/openkal: parsers, a cancelled handshake against a local listener, one real HTTPS request

Above openkal on Windows there is no name resolution (openkal has no resolver interface; musl reads /etc/resolv.conf), so the HTTPS request there reports "no network"; the cancellation check needs none.