From 8ad75679702aae37b0f33bbd5a4989fe39eaf044 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 14:22:38 +0100 Subject: [PATCH 1/5] Add the request executor and the client that drives it The queue state machine from D25: retry with exponential back-off, timeouts, the concurrency cap, and the caller-pumped Update() contract. Update() does a frame's worth of work - poll, retry, promote, deliver - and returns false only when nothing is in flight and nothing is queued, which is what lets a loop-less program exit. The retry policy is the part that bites, so it lives in one place: - 5xx, 429 and a transport failure are retried; any other 4xx is not. - Retry-After is obeyed exactly when the server sends one. - A non-idempotent request whose response was LOST is never retried (R25). A POST that timed out may have succeeded, and retrying it can double-grant. A 5xx on a POST is still retried, because the server told us it failed - only a lost response is ambiguous. Time is read through an internal core::Clock so tests advance it by hand and nothing sleeps. It is deliberately not a Config seam: nobody has asked to supply time, and a seam with no consumer is a seam nobody maintains. Two bugs found by the tests, both fixed here: - A dead transport only failed IN-FLIGHT requests, so a queued request with no transport sat in the queue for ever and Update() returned true for ever. That is a hang, which is worse than an error. Update() now checks for a transport first and fails everything with Transport. - That failure reported Cancelled, which is the wrong code: the request did not fail because anyone cancelled it, it failed because there is no way to send it. The two tests T10 could not write, both here: - A real round trip through the real CurlHttpTransport against a loopback server, asserting the request line, headers and body that actually arrived on the wire, and the response the SDK decoded. Verified against curl 8.22.0, not just compiled. Also covers a refused connection (status 0) and a 302 (reported as-is, not followed). - A transport-injection test proving Config::transport is consulted rather than the default being hard-wired. It was a declared field that nothing read. Both were verified by sabotage: removing CURLOPT_HTTPHEADER fails three assertions in the round-trip test, and ignoring Config::transport fails three in the injection test. Neither passes vacuously. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CMakeLists.txt | 2 + README.md | 53 ++++ include/lootlocker/client.h | 78 +++++ src/core/client.cpp | 123 ++++++++ src/core/clock.h | 43 +++ src/core/executor.cpp | 471 +++++++++++++++++++++++++++++ src/core/executor.h | 159 ++++++++++ tests/CMakeLists.txt | 25 ++ tests/loopback_server.h | 377 +++++++++++++++++++++++ tests/test_executor.cpp | 569 +++++++++++++++++++++++++++++++++++ tests/test_transport_e2e.cpp | 316 +++++++++++++++++++ 11 files changed, 2216 insertions(+) create mode 100644 include/lootlocker/client.h create mode 100644 src/core/client.cpp create mode 100644 src/core/clock.h create mode 100644 src/core/executor.cpp create mode 100644 src/core/executor.h create mode 100644 tests/loopback_server.h create mode 100644 tests/test_executor.cpp create mode 100644 tests/test_transport_e2e.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 585b4ea..00549c6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -139,6 +139,8 @@ add_library(lootlocker_core STATIC src/core/text.cpp src/core/config_obfuscation.cpp src/core/header_map.cpp + src/core/executor.cpp + src/core/client.cpp ) # The curl transport is only compiled when curl was found AND the option is on. Both diff --git a/README.md b/README.md index 837711d..ce85d4c 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,59 @@ Only what you name is compiled and linked. To declare a subset of modules withou `-DLOOTLOCKER_MODULE_ONLY="auth;broadcasts"` — quoted, because an unquoted `;` ends the `cmake` command on a POSIX shell. +## Driving it + +Constructing a `Client` starts no thread and opens no socket. Requests move only when +someone calls `Update()`, which does a frame's worth of work and returns `false` when +nothing is in flight and nothing is queued: + +```cpp +lootlocker::Config cfg; +cfg.domain_key = "1g9glch3"; +cfg.game_key = "prod_1c52468fc6e8420c955e3b6c303ea8cc"; +cfg.game_version = "1.2.1"; + +lootlocker::Client ll(cfg); + +// In your loop, once per frame: +ll.Update(); +``` + +`Update()` polls in-flight transfers, applies the retry policy, promotes queued requests +under the concurrency cap, and delivers callbacks — all in one call, on the calling thread. +A `while (ll.Update())` loop therefore terminates once the last callback has fired, which is +what lets a program with no host loop exit. + +A bad config does not throw and does not crash. `Client::ConfigError()` reports it, and the +client is inert: `Update()` returns `false` and nothing is ever sent. + +### The queue's policy + +`QueueConfig` is public and per-client, because a slow platform or a tight memory budget +needs different numbers: + +| Field | Default | What it does | +| --- | --- | --- | +| `max_retries` | 5 | Retries after the first attempt | +| `initial_backoff_ms` | 50 | First delay; doubles each retry | +| `backoff_factor` | 2 | Multiplier per retry | +| `max_in_flight` | 50 | Concurrent transfers | +| `max_queue_size` | 5000 | Queued requests before the queue is "full" | +| `choke_warning_threshold` | 500 | When to warn that the queue is backing up | +| `request_timeout_seconds` | 300 | Whole-request budget | +| `deny_when_backed_up` | true | Reject on a full queue instead of stalling | + +The retry policy, which is the part that bites: + +- **Retried:** 5xx, 429, and a transport failure (no response at all). +- **Not retried:** any other 4xx. A 400 will be a 400 again. +- **`Retry-After` is obeyed exactly** when the server sends one, instead of guessing. +- **A non-idempotent request whose response was lost is never retried.** A POST that timed + out may have succeeded, and retrying it can double-grant. A 5xx on a POST *is* retried, + because the server told us it failed. This is set per request with + `PendingRequest::idempotent`, which defaults to `true` — every write must opt out + deliberately. + ## The transport The SDK never calls the network directly. Everything goes through `IHttpTransport`, and the diff --git a/include/lootlocker/client.h b/include/lootlocker/client.h new file mode 100644 index 0000000..32896a2 --- /dev/null +++ b/include/lootlocker/client.h @@ -0,0 +1,78 @@ +#pragma once + +// The client (D5, D20). The only object an adopter owns. +// +// It is not a singleton, it starts no thread, and it exposes no feature methods: modules +// are namespaces of free functions that take it (D19). Constructing one starts nothing; +// requests move only when someone calls `Update()`. + +#include +#include + +#include + +namespace lootlocker { + +class Client; + +namespace core { +class Executor; + +// The internal access point a module uses to reach the queue. +// +// Declared here rather than in a `src/` header because a module target has to be able to +// name it, and a module may include `core`'s internals (D18). An adopter cannot use it: +// `src/` is not on their include path, so the definition is unreachable even though the +// declaration is visible. +// +// This is the seam `core::Send()` is built on (T13). It is not test +// scaffolding. +Executor& GetExecutor(Client& client); +} // namespace core + +class Client { +public: + // Validates the config and throws nothing: a bad config is reported through + // `ConfigError()`, because a constructor cannot return a `Result` and the SDK does not + // throw (D7). + // + // A client with an invalid config is inert: `Update()` returns false, every request is + // rejected with `InvalidConfig`, and nothing is sent. That is deliberate - a game that + // ships a bad config gets a clear error in its log rather than a crash at startup. + explicit Client(const Config& config); + ~Client(); + + Client(const Client&) = delete; // one owner, no copies + Client& operator=(const Client&) = delete; + + // Drives the queue. Returns false when nothing is in flight and nothing is queued. + // + // Does a frame's worth of work, not one item: it polls, retries, promotes and delivers + // in one call. Callbacks fire here, on the calling thread (D5). + bool Update(); + + // The config the client was built with, after validation. + const Config& GetConfig() const; + + // Empty when the config was usable. Set when it was not, and the client is inert. + const Error& ConfigError() const; + + // Replaces the transport. The client observes it through a `weak_ptr`, so the adopter + // keeps ownership and a transport that dies is detected rather than dereferenced. + void SetTransport(std::weak_ptr transport); + + // The transport in use, for a test or a wrapper that needs to inspect it. Empty when + // the client has none, which happens when curl was not built in and nothing was + // injected. + std::weak_ptr GetTransport() const; + +private: + // The correct form: the function is declared in `core` above, so the friend + // declaration names it qualified rather than declaring a new one in this scope. + friend core::Executor& core::GetExecutor(Client& client); + + struct Impl; + std::unique_ptr m_impl; +}; + +} // namespace lootlocker diff --git a/src/core/client.cpp b/src/core/client.cpp new file mode 100644 index 0000000..b2db27f --- /dev/null +++ b/src/core/client.cpp @@ -0,0 +1,123 @@ +#include + +#include +#include +#include + +#include "clock.h" +#include "executor.h" + +#include + +namespace lootlocker { + +struct Client::Impl { + Config config; + Error config_error; + + // The default logger, owned here because `Config::logger` is a `weak_ptr` and the + // default has to live somewhere. Constructed lazily: a client that never logs should + // not pay for it. + std::shared_ptr owned_logger; + + // The default transport, owned here for the same reason. Empty when curl was not built + // in, which is a supported configuration: the adopter injects their own. + std::shared_ptr owned_transport; + + core::SteadyClock clock; + std::unique_ptr executor; +}; + +namespace { + +// The logger the client will use: the injected one if it is alive, otherwise the default. +std::weak_ptr ResolveLogger(const Config& config, std::shared_ptr& owned) +{ + if (std::shared_ptr injected = config.logger.lock()) { + return injected; + } + if (!owned) { + owned = std::make_shared(config.log_level); + } + return owned; +} + +} // namespace + +Client::Client(const Config& config) : m_impl(new Impl()) +{ + m_impl->config = config; + m_impl->config_error = ValidateConfig(config); + + // A bad config leaves the client inert rather than half-built. The executor is still + // constructed so `Update()` and `Submit` behave predictably, but nothing is ever sent + // because every submission is rejected. + std::weak_ptr logger = ResolveLogger(config, m_impl->owned_logger); + + if (!m_impl->config_error.Ok()) { + if (std::shared_ptr sink = logger.lock()) { + sink->Log(LogLevel::Error, "invalid configuration: " + m_impl->config_error.message); + } + } + + // The transport: the injected one wins, otherwise the libcurl default when it was + // built. `Config::transport` is a `weak_ptr`, so an injected transport that has already + // died falls through to the default rather than leaving the client with nothing. + std::shared_ptr transport = config.transport.lock(); + if (!transport) { +#if defined(LOOTLOCKER_HAVE_CURL) + m_impl->owned_transport = std::make_shared(); + transport = m_impl->owned_transport; +#else + if (std::shared_ptr sink = logger.lock()) { + sink->Log(LogLevel::Warning, + "no transport: libcurl was not built in and none was injected, so no " + "request can be sent"); + } +#endif + } + + m_impl->executor.reset( + new core::Executor(config.queue, transport, m_impl->clock, logger)); +} + +Client::~Client() = default; + +bool Client::Update() +{ + if (!m_impl->config_error.Ok()) { + return false; + } + return m_impl->executor->Update(); +} + +const Config& Client::GetConfig() const +{ + return m_impl->config; +} + +const Error& Client::ConfigError() const +{ + return m_impl->config_error; +} + +void Client::SetTransport(std::weak_ptr transport) +{ + m_impl->executor->SetTransport(std::move(transport)); +} + +std::weak_ptr Client::GetTransport() const +{ + return m_impl->executor->GetTransport(); +} + +namespace core { + +Executor& GetExecutor(Client& client) +{ + return *client.m_impl->executor; +} + +} // namespace core + +} // namespace lootlocker diff --git a/src/core/clock.h b/src/core/clock.h new file mode 100644 index 0000000..9aaec08 --- /dev/null +++ b/src/core/clock.h @@ -0,0 +1,43 @@ +#pragma once + +// The clock seam (D25, R26). Internal: `lootlocker::core::` is not on an adopter's include +// path (D18). +// +// The executor needs time for two things: back-off delays and request timeouts. Both are +// behaviour a test has to observe, and observing them against a wall clock means sleeping, +// which makes a suite slow and flaky. So time is read through this interface and a test +// advances a fake instead. +// +// This is deliberately NOT a `Config` seam. The four public seams exist because an adopter +// has to dock to their own ecosystem (challenge #5); nobody has asked to supply time, and +// `steady_clock` is monotonic on every platform we target. A seam with no consumer is a +// seam nobody maintains (D18). If a host with a fixed-timestep loop ever needs to drive +// time, that is a decision to take then. + +#include +#include + +namespace lootlocker { +namespace core { + +class Clock { +public: + virtual ~Clock() = default; + + // Monotonic milliseconds. Never wall-clock: a system clock adjustment must not make a + // back-off fire early or a timeout fire late. + virtual std::int64_t NowMs() = 0; +}; + +class SteadyClock : public Clock { +public: + std::int64_t NowMs() override + { + return std::chrono::duration_cast( + std::chrono::steady_clock::now().time_since_epoch()) + .count(); + } +}; + +} // namespace core +} // namespace lootlocker diff --git a/src/core/executor.cpp b/src/core/executor.cpp new file mode 100644 index 0000000..bcc6be6 --- /dev/null +++ b/src/core/executor.cpp @@ -0,0 +1,471 @@ +#include "executor.h" + +#include +#include + +namespace lootlocker { +namespace core { + +namespace { + +Error MakeError(ErrorCode code, const std::string& message, int status_code = 0) +{ + Error e; + e.code = code; + e.status_code = status_code; + e.message = message; + return e; +} + +// Whether a finished attempt may be retried at all, before the attempt budget is +// considered. This is the policy from D25, in one place. +bool IsRetryableStatus(int status_code) +{ + // 0 means no response arrived: a transport failure, which is retryable in principle. + if (status_code == 0) { + return true; + } + // 429 is the server asking us to come back later. + if (status_code == 429) { + return true; + } + // 5xx is the server failing, which may be transient. + if (status_code >= 500 && status_code <= 599) { + return true; + } + // Everything else, including every other 4xx, will be the same answer again. A 400 + // will be a 400 again. + return false; +} + +} // namespace + +Executor::Executor(const QueueConfig& config, std::weak_ptr transport, + Clock& clock, std::weak_ptr logger) + : m_config(config), m_transport(std::move(transport)), m_clock(clock), + m_logger(std::move(logger)) +{ +} + +Executor::~Executor() +{ + Abandon(); +} + +void Executor::SetTransport(std::weak_ptr transport) +{ + m_transport = std::move(transport); +} + +std::weak_ptr Executor::GetTransport() const +{ + return m_transport; +} + +std::size_t Executor::QueuedCount() const +{ + std::size_t queued = 0; + for (const auto& entry : m_entries) { + if (!entry.second.in_flight) { + ++queued; + } + } + return queued; +} + +std::size_t Executor::InFlightCount() const +{ + std::size_t in_flight = 0; + for (const auto& entry : m_entries) { + if (entry.second.in_flight) { + ++in_flight; + } + } + return in_flight; +} + +std::int64_t Executor::TimeoutMs() const +{ + return static_cast(m_config.request_timeout_seconds) * 1000; +} + +std::int64_t Executor::BackoffMs(int attempts, const Completion& completion) const +{ + // A server that told us when to come back is obeyed exactly. Guessing at a back-off + // when the server has stated the answer is how a client gets itself rate limited + // harder. + if (completion.error.retry_after_seconds > 0) { + return static_cast(completion.error.retry_after_seconds) * 1000; + } + + // initial * factor^(attempts-1), capped so a long retry chain cannot overflow into a + // negative delay. The cap is a day, which is far beyond any sane back-off and exists + // only to keep the arithmetic total. + std::int64_t delay = m_config.initial_backoff_ms; + for (int i = 1; i < attempts; ++i) { + delay *= m_config.backoff_factor; + if (delay > 86400000) { + return 86400000; + } + } + return delay; +} + +std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done) +{ + const std::int64_t now = m_clock.NowMs(); + + // The queue is full. `deny_when_backed_up` decides whether that is an error or a wait: + // a game that would rather stall than drop a request leaves it false and the request + // simply waits its turn. + if (m_config.deny_when_backed_up + && static_cast(QueuedCount()) >= m_config.max_queue_size) { + if (on_done) { + Completion completion; + completion.error = MakeError(ErrorCode::QueueFull, + "the request queue is full; the request was not sent"); + m_rejected.push_back( + [handler = std::move(on_done), completion]() { handler(completion); }); + } + return 0; + } + + Entry entry; + entry.id = m_next_id++; + entry.request = std::move(request); + entry.on_done = std::move(on_done); + entry.ready_at_ms = now; + + const std::uint64_t id = entry.id; + m_entries.emplace(id, std::move(entry)); + return id; +} + +void Executor::DrainRejected() +{ + if (m_rejected.empty()) { + return; + } + // Moved out first: a handler is allowed to submit another request, which would + // otherwise mutate the vector we are iterating. + std::vector> rejected; + rejected.swap(m_rejected); + for (auto& handler : rejected) { + handler(); + } +} + +void Executor::Deliver(std::vector& handlers, + std::vector& completions) +{ + for (std::size_t i = 0; i < handlers.size(); ++i) { + if (handlers[i]) { + handlers[i](completions[i]); + } + } +} + +void Executor::LogAttempt(const Entry& entry, const Completion& completion, + std::int64_t duration_ms) +{ + std::shared_ptr logger = m_logger.lock(); + if (!logger) { + return; + } + + log::HttpEntry http; + http.method = entry.request.method; + http.url = entry.request.url; + http.request_body = entry.request.body; + http.response_body = completion.body; + http.status_code = completion.status_code; + http.duration_ms = duration_ms; + http.attempt = entry.attempts; + + std::string trace_id; + if (completion.headers.Get("LL-Trace-Id", trace_id)) { + http.trace_id = trace_id; + } + + // Through `LogExchange`, never `LogHttp` directly: that is the only path that + // obfuscates both bodies first (D26, R28). + log::LogExchange(*logger, http); +} + +void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64_t now, + std::vector& out_handlers, + std::vector& out_completions) +{ + const auto it = m_entries.find(id); + if (it == m_entries.end()) { + return; + } + Entry& entry = it->second; + + // --- Classify the outcome --------------------------------------------------------- + + if (completion.status_code == 0) { + completion.error = MakeError(ErrorCode::Transport, + "no response arrived: the transport failed"); + } else if (completion.status_code == 429) { + completion.error = MakeError(ErrorCode::RateLimited, "the server rate limited us", + completion.status_code); + } else if (completion.status_code >= 400) { + completion.error = MakeError(ErrorCode::Http, "the server returned an error status", + completion.status_code); + } + + // A `Retry-After` header is the server's own instruction, so it is read before the + // retry decision rather than after. + std::string retry_after; + if (completion.headers.Get("Retry-After", retry_after)) { + int seconds = 0; + for (const char c : retry_after) { + if (c < '0' || c > '9') { + seconds = 0; + break; + } + seconds = seconds * 10 + (c - '0'); + } + completion.error.retry_after_seconds = seconds; + } + + // --- Retry or deliver ------------------------------------------------------------- + + const bool retryable = IsRetryableStatus(completion.status_code); + + // R25: a non-idempotent request whose response was lost is never retried. A POST that + // timed out may have succeeded, and retrying it can double-grant. This is checked + // before the attempt budget because it is a correctness rule, not a policy knob. + const bool lost_response = completion.status_code == 0; + const bool may_retry = retryable && !(lost_response && !entry.request.idempotent); + + if (may_retry && entry.attempts <= m_config.max_retries) { + entry.in_flight = false; + entry.transfer = 0; + entry.ready_at_ms = now + BackoffMs(entry.attempts, completion); + return; + } + + // Delivered. The entry is erased before the handler runs, so a handler that submits a + // new request cannot invalidate the map under us. + CompletionHandler handler = std::move(entry.on_done); + m_entries.erase(it); + + out_handlers.push_back(std::move(handler)); + out_completions.push_back(std::move(completion)); +} + +bool Executor::Update() +{ + DrainRejected(); + + const std::int64_t now = m_clock.NowMs(); + + std::vector handlers; + std::vector completions; + + // --- Phase 0: is there a transport at all? ---------------------------------------- + // + // A dead transport is not a retryable condition: there is nothing to retry with, so + // every queued and in-flight request would sit in the queue forever and `Update()` + // would keep returning true. That is a hang, and a hang is worse than an error. + // + // This is the case the `weak_ptr` seam exists to make detectable (D3): the adopter's + // transport died, so the SDK notices and fails the requests instead of dereferencing + // freed memory or spinning. + std::shared_ptr transport = m_transport.lock(); + if (!transport) { + if (!m_entries.empty()) { + if (std::shared_ptr logger = m_logger.lock()) { + logger->Log(LogLevel::Error, + "no transport is available; queued and in-flight requests are " + "being failed"); + } + FailAll("no transport is available"); + } + return false; + } + + // --- Phase 1: poll what is in flight ---------------------------------------------- + // + // Collected first, then processed, because `FinishOrRetry` erases from `m_entries` and + // a handler may submit. Iterating the map while either happens is the bug this + // two-step exists to avoid. + std::vector finished; + std::vector timed_out; + + for (auto& pair : m_entries) { + Entry& entry = pair.second; + if (!entry.in_flight) { + continue; + } + + // The timeout is checked before the poll, so a transfer that never reports + // completion is still bounded. A transport that ignores `Cancel` cannot hold a + // request forever. + if (now - entry.started_at_ms >= TimeoutMs()) { + timed_out.push_back(entry.id); + continue; + } + + IHttpTransport::Response response; + if (transport->Poll(entry.transfer, response)) { + finished.push_back(entry.id); + } + } + + // --- Phase 2: collect completions ------------------------------------------------- + + for (const std::uint64_t id : finished) { + const auto it = m_entries.find(id); + if (it == m_entries.end()) { + continue; + } + Entry& entry = it->second; + + IHttpTransport::Response response; + transport->Poll(entry.transfer, response); + transport->Cancel(entry.transfer); + + Completion completion; + completion.status_code = response.status_code; + completion.headers = std::move(response.headers); + completion.body = std::move(response.body); + completion.attempts = entry.attempts; + + LogAttempt(entry, completion, now - entry.started_at_ms); + FinishOrRetry(id, std::move(completion), now, handlers, completions); + } + + for (const std::uint64_t id : timed_out) { + const auto it = m_entries.find(id); + if (it == m_entries.end()) { + continue; + } + Entry& entry = it->second; + + if (entry.transfer != 0) { + transport->Cancel(entry.transfer); + } + + Completion completion; + completion.status_code = 0; + completion.attempts = entry.attempts; + completion.error = MakeError(ErrorCode::Transport, "the request timed out"); + + LogAttempt(entry, completion, now - entry.started_at_ms); + FinishOrRetry(id, std::move(completion), now, handlers, completions); + } + + // --- Phase 3: promote what is ready ----------------------------------------------- + // + // After polling, so a slot freed by a completion in this same `Update()` is used in + // this same `Update()`. That is what makes one call drain a frame's worth of work + // rather than one item. + + { + std::vector ready; + for (const auto& pair : m_entries) { + const Entry& entry = pair.second; + if (!entry.in_flight && entry.ready_at_ms <= now) { + ready.push_back(entry.id); + } + } + // Id order, so the queue is FIFO among requests that are equally ready. + std::sort(ready.begin(), ready.end()); + + for (const std::uint64_t id : ready) { + if (static_cast(InFlightCount()) >= m_config.max_in_flight) { + break; + } + + const auto it = m_entries.find(id); + if (it == m_entries.end()) { + continue; + } + Entry& entry = it->second; + + IHttpTransport::Request request; + request.method = entry.request.method; + request.url = entry.request.url; + request.headers = entry.request.headers; + request.body = entry.request.body; + request.timeout_seconds = m_config.request_timeout_seconds; + + ++entry.attempts; + entry.started_at_ms = now; + + const IHttpTransport::TransferId transfer = transport->Start(request); + if (transfer == 0) { + // The transport refused to start. Treated as a transport failure rather + // than a request that is still running, so the retry policy decides. + Completion completion; + completion.status_code = 0; + completion.attempts = entry.attempts; + completion.error = MakeError(ErrorCode::Transport, + "the transport could not start the request"); + FinishOrRetry(id, std::move(completion), now, handlers, completions); + continue; + } + + entry.transfer = transfer; + entry.in_flight = true; + } + } + + // --- Phase 4: deliver ------------------------------------------------------------- + // + // Last, so every handler sees a queue that has already been advanced. A handler that + // submits a request gets it started on the next `Update()`, not recursively inside + // this one. + + Deliver(handlers, completions); + + return !m_entries.empty() || !m_rejected.empty(); +} + +void Executor::FailAll(const std::string& reason) +{ + std::vector handlers; + std::vector completions; + + for (auto& pair : m_entries) { + Entry& entry = pair.second; + if (entry.on_done) { + Completion completion; + completion.status_code = 0; + completion.attempts = entry.attempts; + // `Transport`, not `Cancelled`: the request did not fail because anyone + // cancelled it, it failed because there is no way to send it. An adopter + // branching on the code needs to tell "I cancelled this" from "the SDK could + // not send this". + completion.error = MakeError(ErrorCode::Transport, reason); + handlers.push_back(std::move(entry.on_done)); + completions.push_back(std::move(completion)); + } + } + m_entries.clear(); + + Deliver(handlers, completions); +} + +void Executor::Abandon() +{ + std::shared_ptr transport = m_transport.lock(); + if (transport) { + for (auto& pair : m_entries) { + if (pair.second.in_flight && pair.second.transfer != 0) { + transport->Cancel(pair.second.transfer); + } + } + } + + // Handlers are dropped, not invoked. This runs from the destructor, where calling back + // into a half-destroyed client is worse than silence. + m_entries.clear(); + m_rejected.clear(); +} + +} // namespace core +} // namespace lootlocker diff --git a/src/core/executor.h b/src/core/executor.h new file mode 100644 index 0000000..d095738 --- /dev/null +++ b/src/core/executor.h @@ -0,0 +1,159 @@ +#pragma once + +// The request executor (D25). Internal: `lootlocker::core::` is not on an adopter's include +// path (D18). +// +// This is the queue state machine. It owns three things the transport does not: retry with +// back-off, timeouts, and the concurrency cap. It is driven entirely by `Update()`, which +// does a frame's worth of work and never waits on the network (D5). +// +// The rate limiter (T11a) is deliberately NOT here yet. It is a separate concern with its +// own clock arithmetic, and folding it in now would mean writing the queue twice. + +#include +#include +#include +#include +#include + +#include "clock.h" + +#include +#include +#include +#include +#include +#include +#include + +namespace lootlocker { +namespace core { + +// One request, as the executor sees it. +// +// Deliberately not `IHttpTransport::Request`: the transport's shape is the wire contract, +// and this carries the policy the transport has no business knowing about. +struct PendingRequest { + std::string method; + std::string url; + HeaderMap headers; + std::string body; + + // Whether a lost response may be retried (R25). + // + // A GET that timed out did not change anything, so retrying is free. A POST that timed + // out may have succeeded, and retrying it can double-grant. The default is `true` + // because most of the surface is reads; every write must set it to `false` + // deliberately, which is the right way round for a safety flag. + bool idempotent = true; +}; + +// The outcome of one request, delivered exactly once. +struct Completion { + // 0 when no response arrived, which is how a transport failure is told apart from a + // 4xx (D23). + int status_code = 0; + HeaderMap headers; + std::string body; + + // `code` is `None` on success. On failure it is the coarse kind, and `status_code` + // carries the HTTP status when there was one. + Error error; + + // How many attempts were made in total, 1-based. A caller that sees 3 knows the + // request was retried twice. + int attempts = 1; +}; + +using CompletionHandler = std::function; + +class Executor { +public: + Executor(const QueueConfig& config, std::weak_ptr transport, Clock& clock, + std::weak_ptr logger); + ~Executor(); + + Executor(const Executor&) = delete; + Executor& operator=(const Executor&) = delete; + + // Queues a request and returns its id. Never invokes the handler synchronously: the + // contract is that callbacks fire on the thread that calls `Update()` (D5), so a + // rejected request is delivered on the next `Update()` too. + // + // Returns 0 when the request was rejected outright, which happens only when the queue + // is full and `deny_when_backed_up` is set. The handler still runs, with `QueueFull`. + std::uint64_t Submit(PendingRequest request, CompletionHandler on_done); + + // A frame's worth of work. Returns false when nothing is queued and nothing is in + // flight, which is what lets a loop-less program terminate. + bool Update(); + + // Replaces the transport. The executor holds a `weak_ptr` and locks it per use, so a + // transport that dies mid-flight is detected rather than dereferenced. + void SetTransport(std::weak_ptr transport); + + // The transport in use. Empty when the client has none, which happens when curl was + // not built in and nothing was injected. + std::weak_ptr GetTransport() const; + + std::size_t QueuedCount() const; + std::size_t InFlightCount() const; + + // Cancels every in-flight transfer and drops the queue without invoking handlers. + // Called from the destructor, where invoking a handler would be a callback into a + // half-destroyed client. + void Abandon(); + +private: + struct Entry { + std::uint64_t id = 0; + PendingRequest request; + CompletionHandler on_done; + + // Attempts started so far, 1-based once the first one begins. + int attempts = 0; + + // Not before this time. Set on submit and on every retry. + std::int64_t ready_at_ms = 0; + + std::int64_t started_at_ms = 0; + IHttpTransport::TransferId transfer = 0; + bool in_flight = false; + }; + + // Decide whether a finished attempt is retried or delivered, and either requeue it or + // move its handler into the delivery lists. Shared by the poll path and the + // start-failure path so the policy exists in exactly one place. + void FinishOrRetry(std::uint64_t id, Completion completion, std::int64_t now, + std::vector& out_handlers, + std::vector& out_completions); + + void Deliver(std::vector& handlers, std::vector& completions); + + void DrainRejected(); + + void FailAll(const std::string& reason); + + void LogAttempt(const Entry& entry, const Completion& completion, std::int64_t duration_ms); + + std::int64_t TimeoutMs() const; + std::int64_t BackoffMs(int attempts, const Completion& completion) const; + + QueueConfig m_config; + std::weak_ptr m_transport; + Clock& m_clock; + std::weak_ptr m_logger; + + std::uint64_t m_next_id = 1; + std::map m_entries; + + // Handlers for requests rejected at submit time. Bounded by how many the caller + // submits while the queue is full, and drained on the next `Update()`. + // + // `void()` rather than `CompletionHandler`: the completion is already decided, so + // there is nothing left to pass. + std::vector> m_rejected; +}; + +} // namespace core +} // namespace lootlocker diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index d6c997b..50d51ff 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -44,6 +44,31 @@ add_executable(test_log test_log.cpp) target_link_libraries(test_log PRIVATE LootLocker::core lootlocker_compile_options) add_test(NAME log COMMAND test_log) +# The executor's state machine. Driven by a fake clock and the public fake transport, so +# nothing sleeps and every timing assertion is exact. +# +# `src/core` is on the include path because the executor is internal (D18): an adopter +# cannot reach it, and a test that exercises it has to reach in deliberately. +add_executable(test_executor test_executor.cpp) +target_link_libraries(test_executor PRIVATE LootLocker::core lootlocker_compile_options) +target_include_directories(test_executor PRIVATE ${CMAKE_SOURCE_DIR}/src/core) +add_test(NAME executor COMMAND test_executor) + +# The end-to-end transport test (T11, owner 2026-11-13): a real round trip through the real +# curl transport against a loopback server, plus the proof that `Config::transport` is +# actually consulted. +# +# The loopback server needs the platform socket library, which is why this target links +# ws2_32 on Windows. The curl half is compiled only when curl was built in; the injection +# half always runs. +add_executable(test_transport_e2e test_transport_e2e.cpp) +target_link_libraries(test_transport_e2e PRIVATE LootLocker::core lootlocker_compile_options) +target_include_directories(test_transport_e2e PRIVATE ${CMAKE_SOURCE_DIR}/src/core) +if(WIN32) + target_link_libraries(test_transport_e2e PRIVATE ws2_32) +endif() +add_test(NAME transport_e2e COMMAND test_transport_e2e) + # Tier 2 (D14): a tiny consumer that links only one module, proving the target graph and # the headers work from outside the library. It deliberately does NOT link broadcasts. # diff --git a/tests/loopback_server.h b/tests/loopback_server.h new file mode 100644 index 0000000..068cb9f --- /dev/null +++ b/tests/loopback_server.h @@ -0,0 +1,377 @@ +// A minimal loopback HTTP server for the end-to-end transport test (T11). +// +// Deliberately hand-rolled on sockets rather than a library: the point of the test is to +// prove the SDK's real transport works against a real socket, and pulling in a server +// framework would add a dependency to the test suite for one file. It speaks just enough +// HTTP/1.1 for the SDK's own requests: one request per connection, `Content-Length` bodies, +// `Connection: close`. +// +// It runs on its own thread and records what it received, so the test can assert on the +// request line, headers and body that actually arrived on the wire - which is the whole +// reason this exists. Asserting on what the SDK *thinks* it sent would prove nothing. + +#pragma once + +#include +#include +#include +#include +#include +#include + +#if defined(_WIN32) +# ifndef WIN32_LEAN_AND_MEAN +# define WIN32_LEAN_AND_MEAN +# endif +# ifndef NOMINMAX +# define NOMINMAX +# endif +# include +# include +# pragma comment(lib, "ws2_32.lib") +#else +# include +# include +# include +# include +#endif + +namespace testing { + +// One request as it arrived on the wire. +struct ReceivedRequest { + std::string method; + std::string target; // path plus query, exactly as sent + std::string version; + + // Header lines in the order they arrived, name and value split on the first colon and + // trimmed. Kept as a vector rather than a map so the test can assert on order and on + // duplicates, which a map would hide. + std::vector> headers; + + std::string body; + + // Case-insensitive header lookup. Empty when absent. + std::string Header(const std::string& name) const + { + for (const auto& header : headers) { + if (header.first.size() != name.size()) { + continue; + } + bool same = true; + for (std::size_t i = 0; i < name.size(); ++i) { + const char a = header.first[i]; + const char b = name[i]; + const char la = (a >= 'A' && a <= 'Z') ? static_cast(a - 'A' + 'a') : a; + const char lb = (b >= 'A' && b <= 'Z') ? static_cast(b - 'A' + 'a') : b; + if (la != lb) { + same = false; + break; + } + } + if (same) { + return header.second; + } + } + return std::string(); + } +}; + +// A canned response, one per request, in order. The last one repeats if more requests +// arrive than were scripted. +struct ScriptedResponse { + int status_code = 200; + std::string reason = "OK"; + std::string content_type = "application/json"; + std::string body; + + // Extra headers, e.g. `Retry-After`. + std::vector> headers; +}; + +class LoopbackServer { +public: + LoopbackServer() = default; + ~LoopbackServer() { Stop(); } + + LoopbackServer(const LoopbackServer&) = delete; + LoopbackServer& operator=(const LoopbackServer&) = delete; + + // Binds to 127.0.0.1 on an ephemeral port and starts accepting. Returns false when the + // socket could not be created, which the test reports rather than silently passing. + bool Start() + { +#if defined(_WIN32) + WSADATA data; + if (WSAStartup(MAKEWORD(2, 2), &data) != 0) { + return false; + } + m_wsa_started = true; +#endif + + m_listen = static_cast(::socket(AF_INET, SOCK_STREAM, 0)); + if (m_listen < 0) { + return false; + } + + // SO_REUSEADDR so a rerun in the same process does not fail on a lingering socket. + int yes = 1; + ::setsockopt(static_cast(m_listen), SOL_SOCKET, SO_REUSEADDR, + reinterpret_cast(&yes), sizeof(yes)); + + sockaddr_in address{}; + address.sin_family = AF_INET; + address.sin_addr.s_addr = ::htonl(INADDR_LOOPBACK); + address.sin_port = 0; // ephemeral + + if (::bind(static_cast(m_listen), reinterpret_cast(&address), + sizeof(address)) != 0) { + CloseListen(); + return false; + } + + // Read back the port the OS chose. + sockaddr_in bound{}; +#if defined(_WIN32) + int length = sizeof(bound); +#else + socklen_t length = sizeof(bound); +#endif + if (::getsockname(static_cast(m_listen), reinterpret_cast(&bound), + &length) != 0) { + CloseListen(); + return false; + } + m_port = ::ntohs(bound.sin_port); + + if (::listen(static_cast(m_listen), 8) != 0) { + CloseListen(); + return false; + } + + m_running = true; + m_thread = std::thread([this]() { Run(); }); + return true; + } + + void Stop() + { + if (!m_running.exchange(false)) { + return; + } + + // Closing the listening socket unblocks `accept` on every platform we target. + CloseListen(); + + if (m_thread.joinable()) { + m_thread.join(); + } + +#if defined(_WIN32) + if (m_wsa_started) { + WSACleanup(); + m_wsa_started = false; + } +#endif + } + + // The base URL to hand the SDK, e.g. "http://127.0.0.1:54321". + std::string BaseUrl() const + { + return "http://127.0.0.1:" + std::to_string(m_port); + } + + int Port() const { return m_port; } + + // Queue the responses to serve, in order. + void Script(std::vector responses) + { + std::lock_guard lock(m_mutex); + m_script = std::move(responses); + } + + // What arrived, in order. + std::vector Received() const + { + std::lock_guard lock(m_mutex); + return m_received; + } + + std::size_t ReceivedCount() const + { + std::lock_guard lock(m_mutex); + return m_received.size(); + } + +private: + void CloseListen() + { + if (m_listen >= 0) { +#if defined(_WIN32) + ::closesocket(static_cast(m_listen)); +#else + ::close(static_cast(m_listen)); +#endif + m_listen = -1; + } + } + + void Run() + { + while (m_running.load()) { + const std::intptr_t client = + static_cast(::accept(static_cast(m_listen), nullptr, nullptr)); + if (client < 0) { + // Either we are shutting down or the accept failed; both mean stop. + break; + } + + HandleOne(client); + +#if defined(_WIN32) + ::closesocket(static_cast(client)); +#else + ::close(static_cast(client)); +#endif + } + } + + // Read until the header terminator, then read exactly Content-Length bytes. + static bool ReadRequest(std::intptr_t client, ReceivedRequest& out) + { + std::string buffer; + char chunk[4096]; + + std::size_t header_end = std::string::npos; + while (header_end == std::string::npos) { + const int got = ::recv(static_cast(client), chunk, sizeof(chunk), 0); + if (got <= 0) { + return false; + } + buffer.append(chunk, static_cast(got)); + header_end = buffer.find("\r\n\r\n"); + } + + const std::string head = buffer.substr(0, header_end); + std::string body = buffer.substr(header_end + 4); + + // Request line. + const std::size_t first_line_end = head.find("\r\n"); + const std::string request_line = + first_line_end == std::string::npos ? head : head.substr(0, first_line_end); + + const std::size_t sp1 = request_line.find(' '); + const std::size_t sp2 = + sp1 == std::string::npos ? std::string::npos : request_line.find(' ', sp1 + 1); + if (sp1 == std::string::npos || sp2 == std::string::npos) { + return false; + } + out.method = request_line.substr(0, sp1); + out.target = request_line.substr(sp1 + 1, sp2 - sp1 - 1); + out.version = request_line.substr(sp2 + 1); + + // Headers. + std::size_t pos = first_line_end == std::string::npos ? head.size() : first_line_end + 2; + while (pos < head.size()) { + const std::size_t line_end = head.find("\r\n", pos); + const std::string line = + line_end == std::string::npos ? head.substr(pos) : head.substr(pos, line_end - pos); + const std::size_t colon = line.find(':'); + if (colon != std::string::npos) { + std::string name = line.substr(0, colon); + std::string value = line.substr(colon + 1); + std::size_t begin = 0; + while (begin < value.size() && (value[begin] == ' ' || value[begin] == '\t')) { + ++begin; + } + std::size_t end = value.size(); + while (end > begin && (value[end - 1] == '\r' || value[end - 1] == '\n')) { + --end; + } + out.headers.emplace_back(name, value.substr(begin, end - begin)); + } + if (line_end == std::string::npos) { + break; + } + pos = line_end + 2; + } + + // Body, by Content-Length. A request with no body has none. + std::size_t expected = 0; + const std::string length = out.Header("Content-Length"); + if (!length.empty()) { + for (const char c : length) { + if (c < '0' || c > '9') { + break; + } + expected = expected * 10 + static_cast(c - '0'); + } + } + + while (body.size() < expected) { + const int got = ::recv(static_cast(client), chunk, sizeof(chunk), 0); + if (got <= 0) { + break; + } + body.append(chunk, static_cast(got)); + } + + out.body = body.substr(0, expected); + return true; + } + + void HandleOne(std::intptr_t client) + { + ReceivedRequest request; + if (!ReadRequest(client, request)) { + return; + } + + ScriptedResponse response; + { + std::lock_guard lock(m_mutex); + const std::size_t index = m_received.size(); + m_received.push_back(request); + if (!m_script.empty()) { + response = m_script[index < m_script.size() ? index : m_script.size() - 1]; + } + } + + std::string out = "HTTP/1.1 " + std::to_string(response.status_code) + " " + + response.reason + "\r\n"; + if (!response.content_type.empty()) { + out += "Content-Type: " + response.content_type + "\r\n"; + } + out += "Content-Length: " + std::to_string(response.body.size()) + "\r\n"; + for (const auto& header : response.headers) { + out += header.first + ": " + header.second + "\r\n"; + } + // One request per connection, so the client never has to guess where the response + // ends. + out += "Connection: close\r\n\r\n"; + out += response.body; + + std::size_t sent = 0; + while (sent < out.size()) { + const int wrote = ::send(static_cast(client), out.data() + sent, + static_cast(out.size() - sent), 0); + if (wrote <= 0) { + return; + } + sent += static_cast(wrote); + } + } + + std::intptr_t m_listen = -1; + int m_port = 0; + bool m_wsa_started = false; + + std::atomic m_running{false}; + std::thread m_thread; + + mutable std::mutex m_mutex; + std::vector m_script; + std::vector m_received; +}; + +} // namespace testing diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp new file mode 100644 index 0000000..388aa6d --- /dev/null +++ b/tests/test_executor.cpp @@ -0,0 +1,569 @@ +// The request executor's state machine (T11). +// +// Driven by a fake clock and the public `FakeHttpTransport`, so nothing here sleeps and +// every timing assertion is exact. The end-to-end proof that the real transport works is +// in `test_transport_e2e.cpp`; this file is about the queue's own behaviour. + +#include +#include + +#include "clock.h" +#include "executor.h" +#include "test_harness.h" + +#include +#include +#include +#include + +using namespace lootlocker; +using namespace lootlocker::core; + +namespace { + +// A clock the test advances by hand. Time never moves on its own, so a back-off either +// fires exactly when it should or the test fails. +class FakeClock : public Clock { +public: + std::int64_t NowMs() override { return m_now; } + void Advance(std::int64_t ms) { m_now += ms; } + +private: + std::int64_t m_now = 1000; // non-zero, so "not set" is distinguishable +}; + +// A logger that records what it was given, so the obfuscation path can be asserted on. +class RecordingLogger : public Logger { +public: + void Log(LogLevel level, const std::string& message) override + { + levels.push_back(level); + messages.push_back(message); + } + + void LogHttp(const log::HttpEntry& entry) override { entries.push_back(entry); } + + std::vector levels; + std::vector messages; + std::vector entries; +}; + +QueueConfig DefaultQueue() +{ + QueueConfig config; + config.max_retries = 5; + config.backoff_factor = 2; + config.initial_backoff_ms = 50; + config.max_in_flight = 50; + config.max_queue_size = 5000; + config.request_timeout_seconds = 300; + return config; +} + +PendingRequest Get(const std::string& url) +{ + PendingRequest request; + request.method = "GET"; + request.url = url; + return request; +} + +PendingRequest Post(const std::string& url) +{ + PendingRequest request; + request.method = "POST"; + request.url = url; + request.body = "{}"; + request.idempotent = false; // a write: never retried when the response is lost + return request; +} + +// A harness that owns the pieces in the right order, so the executor's reference to the +// clock stays valid. +struct Fixture { + explicit Fixture(QueueConfig config = DefaultQueue()) + : transport(std::make_shared()), logger(std::make_shared()) + { + executor.reset(new Executor(config, transport, clock, logger)); + } + + std::shared_ptr transport; + std::shared_ptr logger; + FakeClock clock; + std::unique_ptr executor; +}; + +// --- Update() drains a frame's worth of work ------------------------------------------- + +void TestOneUpdateDrainsSeveralCompletions() +{ + Fixture f; + + int delivered = 0; + std::vector ids; + for (int i = 0; i < 3; ++i) { + ids.push_back(f.executor->Submit(Get("https://example.test/a"), + [&delivered](const Completion&) { ++delivered; })); + } + + CHECK_EQ_INT(static_cast(ids.size()), 3); + CHECK(ids[0] != 0 && ids[1] != 0 && ids[2] != 0); + + // One Update starts all three, because max_in_flight is 50. + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 3); + + // Complete all three, then a single Update must deliver all three. This is the + // "frame's worth of work, not one item" contract (D5). + for (const std::uint64_t id : ids) { + f.transport->Complete(id, 200, "{}"); + } + + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 3); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 0); + CHECK_EQ_INT(static_cast(f.executor->QueuedCount()), 0); +} + +// --- Update() returns false exactly when there is nothing left ------------------------- + +void TestUpdateReturnsFalseOnlyWhenEmpty() +{ + Fixture f; + + // Nothing submitted: nothing to do. + CHECK(!f.executor->Update()); + + bool delivered = false; + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), + [&delivered](const Completion&) { delivered = true; }); + CHECK(id != 0); + + // Queued, so there is work. + CHECK(f.executor->Update()); + CHECK(!delivered); + + f.transport->Complete(id, 200, "{}"); + + // The call that delivers the last completion also reports that nothing is left. A + // `while (Update())` loop therefore terminates after the callback has fired, which is + // what lets a loop-less program exit. + CHECK(!f.executor->Update()); + CHECK(delivered); +} + +// --- Retry policy ---------------------------------------------------------------------- + +void TestServerErrorRetriesWithExponentialBackoff() +{ + Fixture f; + + int delivered = 0; + Completion last; + f.executor->Submit(Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + // Attempt 1. + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + f.transport->Complete(f.transport->Order().back(), 500, "boom"); + + // The 500 is retryable, so it is requeued with a 50 ms delay rather than delivered. + CHECK(f.executor->Update()); + CHECK_EQ_INT(delivered, 0); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // Not yet: 49 ms is not enough. + f.clock.Advance(49); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // 50 ms is. Attempt 2. + f.clock.Advance(1); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); + + // Attempt 2 fails too, so the delay doubles to 100 ms. + f.transport->Complete(f.transport->Order().back(), 500, "boom"); + CHECK(f.executor->Update()); + f.clock.Advance(99); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); + f.clock.Advance(1); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); + + // Attempt 3 succeeds, so it is delivered with the attempt count. + f.transport->Complete(f.transport->Order().back(), 200, "{\"ok\":true}"); + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.Ok()); + CHECK_EQ_INT(last.status_code, 200); + CHECK_EQ_INT(last.attempts, 3); + CHECK_EQ(last.body, std::string("{\"ok\":true}")); +} + +void TestClientErrorDoesNotRetry() +{ + Fixture f; + + int delivered = 0; + Completion last; + const std::uint64_t id = f.executor->Submit( + Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK(f.executor->Update()); + f.transport->Complete(id, 400, "{\"error\":\"bad\"}"); + + // A 400 will be a 400 again, so it is delivered on the first Update after it arrives. + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 1); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + CHECK(last.error.code == ErrorCode::Http); + CHECK_EQ_INT(last.status_code, 400); + CHECK_EQ_INT(last.attempts, 1); + + // The body survives on the failure, which is what makes a 400 diagnosable (D7, D23). + CHECK_EQ(last.body, std::string("{\"error\":\"bad\"}")); +} + +void TestRetryAfterIsHonoured() +{ + Fixture f; + + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(f.executor->Update()); + + IHttpTransport::Response response; + response.status_code = 429; + response.body = "{}"; + response.headers.Set("Retry-After", "7"); + f.transport->Complete(id, response); + + CHECK(f.executor->Update()); + + // The server said 7 seconds, so the back-off is 7000 ms, not the 50 ms default. + f.clock.Advance(6999); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + f.clock.Advance(1); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +void TestRetriesStopAtTheBudget() +{ + QueueConfig config = DefaultQueue(); + config.max_retries = 2; // 1 initial attempt + 2 retries = 3 total + Fixture f(config); + + int delivered = 0; + Completion last; + f.executor->Submit(Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + // Two full retry cycles: each starts an attempt, fails it, and requeues. + for (int attempt = 0; attempt < 2; ++attempt) { + CHECK(f.executor->Update()); + f.transport->Complete(f.transport->Order().back(), 503, "unavailable"); + CHECK(f.executor->Update()); + CHECK_EQ_INT(delivered, 0); + f.clock.Advance(1000); + } + + // The third attempt is the last the budget allows, so its failure is delivered rather + // than requeued. + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); + f.transport->Complete(f.transport->Order().back(), 503, "unavailable"); + CHECK(!f.executor->Update()); + + CHECK_EQ_INT(delivered, 1); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); + CHECK(last.error.code == ErrorCode::Http); + CHECK_EQ_INT(last.attempts, 3); +} + +// --- R25: never retry a non-idempotent request whose response was lost ----------------- + +void TestTimedOutPostIsNotRetried() +{ + Fixture f; + + int delivered = 0; + Completion last; + f.executor->Submit(Post("https://example.test/grant"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // The response never arrives. A POST that timed out may have succeeded, and retrying + // it can double-grant, so it is delivered as a failure instead. + f.clock.Advance(300 * 1000); + CHECK(!f.executor->Update()); + + CHECK_EQ_INT(delivered, 1); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + CHECK(last.error.code == ErrorCode::Transport); + CHECK_EQ_INT(last.status_code, 0); +} + +void TestTimedOutGetIsRetried() +{ + Fixture f; + + int delivered = 0; + f.executor->Submit(Get("https://example.test/broadcasts"), [&](const Completion& c) { + ++delivered; + (void)c; + }); + + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // A GET changed nothing, so a lost response is free to retry. + f.clock.Advance(300 * 1000); + CHECK(f.executor->Update()); + CHECK_EQ_INT(delivered, 0); + + f.clock.Advance(50); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +void TestServerErrorOnPostIsStillRetried() +{ + Fixture f; + + int delivered = 0; + const std::uint64_t id = f.executor->Submit(Post("https://example.test/grant"), + [&](const Completion&) { ++delivered; }); + + CHECK(f.executor->Update()); + + // A 500 is a *received* response: the server told us it failed, so the request did not + // take effect and retrying is safe even for a POST. Only a lost response is ambiguous. + f.transport->Complete(id, 500, "boom"); + CHECK(f.executor->Update()); + CHECK_EQ_INT(delivered, 0); + + f.clock.Advance(50); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +// --- The concurrency cap and the queue cap --------------------------------------------- + +void TestConcurrencyCapIsRespected() +{ + QueueConfig config = DefaultQueue(); + config.max_in_flight = 2; + Fixture f(config); + + for (int i = 0; i < 5; ++i) { + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + } + + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 2); + CHECK_EQ_INT(static_cast(f.executor->QueuedCount()), 3); + + // A slot freed in this Update is used in this same Update, which is what makes one + // call drain a frame rather than one item. + const auto order = f.transport->Order(); + f.transport->Complete(order[0], 200, "{}"); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); +} + +void TestFullQueueRejectsAndReportsOnNextUpdate() +{ + QueueConfig config = DefaultQueue(); + config.max_queue_size = 1; + config.deny_when_backed_up = true; + Fixture f(config); + + const std::uint64_t first = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(first != 0); + + int rejected = 0; + Completion rejection; + const std::uint64_t second = f.executor->Submit( + Get("https://example.test/b"), [&](const Completion& c) { + ++rejected; + rejection = c; + }); + + // Rejected outright, and the id says so. + CHECK_EQ_INT(static_cast(second), 0); + + // The handler is not called synchronously: callbacks fire from Update() (D5). + CHECK_EQ_INT(rejected, 0); + + CHECK(f.executor->Update()); + CHECK_EQ_INT(rejected, 1); + CHECK(rejection.error.code == ErrorCode::QueueFull); +} + +void TestBackedUpQueueWaitsWhenDenyIsOff() +{ + QueueConfig config = DefaultQueue(); + config.max_queue_size = 1; + config.deny_when_backed_up = false; + Fixture f(config); + + const std::uint64_t first = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + const std::uint64_t second = + f.executor->Submit(Get("https://example.test/b"), [](const Completion&) {}); + + // Both accepted: the adopter chose to stall rather than drop. + CHECK(first != 0); + CHECK(second != 0); +} + +// --- The transport seam ---------------------------------------------------------------- + +void TestDeadTransportFailsInFlightRequests() +{ + Fixture f; + + int delivered = 0; + Completion last; + f.executor->Submit(Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 1); + + // The adopter's transport dies while a request is in flight. This is the case the + // `weak_ptr` seam exists to make detectable: the executor must notice and fail the + // request rather than dereference freed memory. + f.transport.reset(); + + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.code == ErrorCode::Transport); + + // And it said so, rather than failing silently. + bool logged = false; + for (const std::string& message : f.logger->messages) { + if (message.find("no transport is available") != std::string::npos) { + logged = true; + } + } + CHECK(logged); +} + +void TestSetTransportReplacesTheSeam() +{ + Fixture f; + + auto replacement = std::make_shared(); + f.executor->SetTransport(replacement); + + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(f.executor->Update()); + + // The new transport received it, and the old one did not. + CHECK_EQ_INT(static_cast(replacement->StartCount()), 1); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 0); +} + +// --- Logging --------------------------------------------------------------------------- + +void TestEachAttemptIsLoggedAndObfuscated() +{ + Fixture f; + + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(f.executor->Update()); + + IHttpTransport::Response response; + response.status_code = 200; + response.body = "{\"session_token\":\"abcdef1234567890\"}"; + response.headers.Set("LL-Trace-Id", "trace-42"); + f.transport->Complete(id, response); + + CHECK(!f.executor->Update()); + + CHECK_EQ_INT(static_cast(f.logger->entries.size()), 1); + const log::HttpEntry& entry = f.logger->entries[0]; + CHECK_EQ(entry.method, std::string("GET")); + CHECK_EQ(entry.url, std::string("https://example.test/a")); + CHECK_EQ_INT(entry.status_code, 200); + CHECK_EQ_INT(entry.attempt, 1); + CHECK_EQ(entry.trace_id, std::string("trace-42")); + + // The token must not appear in the logged body. Asserting on the exact masked form + // rather than on "the secret is absent", because an absent-secret assertion passes + // when the body is empty for the wrong reason. + CHECK(entry.response_body.find("abcdef1234567890") == std::string::npos); + CHECK(entry.response_body.find("abc") != std::string::npos); +} + +void TestAbandonCancelsInFlightWithoutCallingBack() +{ + Fixture f; + + int delivered = 0; + f.executor->Submit(Get("https://example.test/a"), + [&](const Completion&) { ++delivered; }); + CHECK(f.executor->Update()); + + const auto order = f.transport->Order(); + CHECK_EQ_INT(static_cast(order.size()), 1); + + f.executor->Abandon(); + + // The transfer was cancelled, and the handler was not invoked: this runs from a + // destructor, where calling back into a half-destroyed client is worse than silence. + CHECK(f.transport->WasCancelled(order[0])); + CHECK_EQ_INT(delivered, 0); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 0); +} + +} // namespace + +int main() +{ + TestOneUpdateDrainsSeveralCompletions(); + TestUpdateReturnsFalseOnlyWhenEmpty(); + TestServerErrorRetriesWithExponentialBackoff(); + TestClientErrorDoesNotRetry(); + TestRetryAfterIsHonoured(); + TestRetriesStopAtTheBudget(); + TestTimedOutPostIsNotRetried(); + TestTimedOutGetIsRetried(); + TestServerErrorOnPostIsStillRetried(); + TestConcurrencyCapIsRespected(); + TestFullQueueRejectsAndReportsOnNextUpdate(); + TestBackedUpQueueWaitsWhenDenyIsOff(); + TestDeadTransportFailsInFlightRequests(); + TestSetTransportReplacesTheSeam(); + TestEachAttemptIsLoggedAndObfuscated(); + TestAbandonCancelsInFlightWithoutCallingBack(); + + return testing::Report(); +} diff --git a/tests/test_transport_e2e.cpp b/tests/test_transport_e2e.cpp new file mode 100644 index 0000000..cd55388 --- /dev/null +++ b/tests/test_transport_e2e.cpp @@ -0,0 +1,316 @@ +// The end-to-end transport test (T11, owner 2026-11-13). +// +// T10 shipped a transport that compiled but had never sent a request. This file is what +// closes that: a real `CurlHttpTransport` talking to a real socket, with the server +// asserting on what actually arrived on the wire and the SDK asserting on what it decoded. +// +// Two things are proven here that nothing else proves: +// 1. The curl adapter works, rather than merely compiles. +// 2. `Config::transport` is actually consulted, rather than the default being hard-wired. +// +// The second test does not need curl, so it runs even in a build without it. The first is +// skipped with a printed reason when curl was not built in, because a test that silently +// passes when the thing under test is absent is worse than no test. + +#include +#include +#include +#include +#include + +#include "executor.h" +#include "loopback_server.h" +#include "test_harness.h" + +#include +#include +#include + +using namespace lootlocker; + +namespace { + +Config MakeConfig(const std::string& base_url) +{ + Config config; + config.domain_key = "1g9glch3"; + config.game_key = "prod_1c52468fc6e8420c955e3b6c303ea8cc"; + config.game_version = "1.2.1"; + config.base_url = base_url; + config.log_level = LogLevel::NoLogging; + return config; +} + +// --- 1. A real round trip through the real transport ----------------------------------- + +#if defined(LOOTLOCKER_HAVE_CURL) + +void TestRealRoundTripThroughCurl() +{ + testing::LoopbackServer server; + if (!server.Start()) { + // A failure to bind is a real failure, not a skip: the test cannot prove anything + // without a socket, and silently passing would hide that. + CHECK(false); + return; + } + + testing::ScriptedResponse response; + response.status_code = 200; + response.body = "{\"broadcasts\":[{\"id\":\"b1\",\"message\":\"hello\"}]}"; + server.Script({response}); + + auto transport = std::make_shared(); + + IHttpTransport::Request request; + request.method = "POST"; + request.url = server.BaseUrl() + "/game/broadcasts/v1?limit=10"; + request.headers.Set("Content-Type", "application/json"); + request.headers.Set("x-session-token", "session-abc"); + request.headers.Set("LL-Request-Id", "42"); + request.body = "{\"limit\":10}"; + request.timeout_seconds = 10; + + const IHttpTransport::TransferId id = transport->Start(request); + CHECK(id != 0); + + // Poll until it finishes. The transport is pollable, so this is the real contract: no + // blocking call, and the loop is bounded so a hang fails the test instead of hanging + // CI. + IHttpTransport::Response received; + bool done = false; + for (int i = 0; i < 2000 && !done; ++i) { + done = transport->Poll(id, received); + if (!done) { + std::this_thread::sleep_for(std::chrono::milliseconds(5)); + } + } + CHECK(done); + transport->Cancel(id); + + // --- What the server actually received -------------------------------------------- + + const std::vector requests = server.Received(); + CHECK_EQ_INT(static_cast(requests.size()), 1); + if (requests.empty()) { + server.Stop(); + return; + } + const testing::ReceivedRequest& wire = requests[0]; + + // The request line: method, path and query exactly as the SDK built them. + CHECK_EQ(wire.method, std::string("POST")); + CHECK_EQ(wire.target, std::string("/game/broadcasts/v1?limit=10")); + + // The headers the SDK set, as they arrived. This is the assertion that would have + // caught a header being dropped or renamed by the adapter. + CHECK_EQ(wire.Header("Content-Type"), std::string("application/json")); + CHECK_EQ(wire.Header("x-session-token"), std::string("session-abc")); + CHECK_EQ(wire.Header("LL-Request-Id"), std::string("42")); + + // The body, byte for byte. + CHECK_EQ(wire.body, std::string("{\"limit\":10}")); + + // --- What the SDK received -------------------------------------------------------- + + CHECK_EQ_INT(received.status_code, 200); + CHECK_EQ(received.body, std::string("{\"broadcasts\":[{\"id\":\"b1\",\"message\":\"hello\"}]}")); + + // Response headers are parsed into the map, which is what the executor reads + // `Retry-After` and `LL-Trace-Id` from. + std::string content_type; + CHECK(received.headers.Get("Content-Type", content_type)); + CHECK_EQ(content_type, std::string("application/json")); + + server.Stop(); +} + +void TestRealTransportReportsATransportFailure() +{ + // Nothing is listening on this port, so the connection is refused. The transport must + // report that as "no response" (status 0) rather than inventing a status, because the + // executor's retry policy branches on exactly that (D23). + auto transport = std::make_shared(); + + IHttpTransport::Request request; + request.method = "GET"; + request.url = "http://127.0.0.1:1/nothing-here"; + request.timeout_seconds = 5; + + const IHttpTransport::TransferId id = transport->Start(request); + CHECK(id != 0); + + IHttpTransport::Response received; + bool done = false; + for (int i = 0; i < 2000 && !done; ++i) { + done = transport->Poll(id, received); + if (!done) { + std::this_thread::sleep_for(std::chrono::milliseconds(5)); + } + } + CHECK(done); + transport->Cancel(id); + + CHECK_EQ_INT(received.status_code, 0); +} + +void TestRealTransportDoesNotFollowRedirects() +{ + // A redirect must not be followed, because curl replays the caller's headers to the + // target and the SDK sends `x-session-token` (D3). The transport reports the 302 + // itself, and the caller decides. + testing::LoopbackServer server; + if (!server.Start()) { + CHECK(false); + return; + } + + testing::ScriptedResponse redirect; + redirect.status_code = 302; + redirect.reason = "Found"; + redirect.content_type.clear(); + redirect.headers.emplace_back("Location", "http://127.0.0.1:1/elsewhere"); + server.Script({redirect}); + + auto transport = std::make_shared(); + + IHttpTransport::Request request; + request.method = "GET"; + request.url = server.BaseUrl() + "/game/broadcasts/v1"; + request.headers.Set("x-session-token", "session-abc"); + request.timeout_seconds = 5; + + const IHttpTransport::TransferId id = transport->Start(request); + IHttpTransport::Response received; + bool done = false; + for (int i = 0; i < 2000 && !done; ++i) { + done = transport->Poll(id, received); + if (!done) { + std::this_thread::sleep_for(std::chrono::milliseconds(5)); + } + } + CHECK(done); + transport->Cancel(id); + + // The 302 is reported as-is, and only one request reached the server: the redirect was + // not followed, so the token was never replayed anywhere. + CHECK_EQ_INT(received.status_code, 302); + CHECK_EQ_INT(static_cast(server.ReceivedCount()), 1); + + server.Stop(); +} + +#endif // LOOTLOCKER_HAVE_CURL + +// --- 2. The transport seam is actually consulted --------------------------------------- + +void TestInjectedTransportIsUsedByTheClient() +{ + // The point of this test: `Config::transport` was a declared field that nothing read. + // If the client hard-wired the default, this fake would never see the request and the + // test would fail. + auto fake = std::make_shared(); + + Config config = MakeConfig("http://127.0.0.1:1"); + config.transport = fake; + + Client client(config); + CHECK(client.ConfigError().Ok()); + + // The client reports the injected transport, not a default. + CHECK(!client.GetTransport().expired()); + CHECK(client.GetTransport().lock() == fake); + + int delivered = 0; + core::Completion last; + core::PendingRequest request; + request.method = "GET"; + request.url = "http://127.0.0.1:1/game/broadcasts/v1"; + + core::GetExecutor(client).Submit(request, [&](const core::Completion& completion) { + ++delivered; + last = completion; + }); + + CHECK(client.Update()); + + // The fake received it, which is the whole assertion. + CHECK_EQ_INT(static_cast(fake->StartCount()), 1); + const auto order = fake->Order(); + CHECK_EQ_INT(static_cast(order.size()), 1); + if (!order.empty()) { + const IHttpTransport::Request* sent = fake->FindRequest(order[0]); + CHECK(sent != nullptr); + if (sent != nullptr) { + CHECK_EQ(sent->method, std::string("GET")); + CHECK_EQ(sent->url, std::string("http://127.0.0.1:1/game/broadcasts/v1")); + } + } + + // Complete it through the fake and confirm the result reaches the caller, so the whole + // path is exercised rather than just the start. + fake->Complete(order[0], 200, "{\"broadcasts\":[]}"); + CHECK(!client.Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.Ok()); + CHECK_EQ(last.body, std::string("{\"broadcasts\":[]}")); +} + +void TestSetTransportReplacesTheInjectedOne() +{ + auto first = std::make_shared(); + auto second = std::make_shared(); + + Config config = MakeConfig("http://127.0.0.1:1"); + config.transport = first; + + Client client(config); + client.SetTransport(second); + + CHECK(client.GetTransport().lock() == second); + + core::PendingRequest request; + request.method = "GET"; + request.url = "http://127.0.0.1:1/x"; + core::GetExecutor(client).Submit(request, [](const core::Completion&) {}); + CHECK(client.Update()); + + CHECK_EQ_INT(static_cast(second->StartCount()), 1); + CHECK_EQ_INT(static_cast(first->StartCount()), 0); +} + +void TestInvalidConfigMakesTheClientInert() +{ + Config config; + // No domain_key, no game key, no version. + auto fake = std::make_shared(); + config.transport = fake; + + Client client(config); + + CHECK(!client.ConfigError().Ok()); + CHECK(client.ConfigError().code == ErrorCode::InvalidConfig); + + // Inert: Update reports nothing to do and nothing is ever sent. + CHECK(!client.Update()); + CHECK_EQ_INT(static_cast(fake->StartCount()), 0); +} + +} // namespace + +int main() +{ + TestInjectedTransportIsUsedByTheClient(); + TestSetTransportReplacesTheInjectedOne(); + TestInvalidConfigMakesTheClientInert(); + +#if defined(LOOTLOCKER_HAVE_CURL) + TestRealRoundTripThroughCurl(); + TestRealTransportReportsATransportFailure(); + TestRealTransportDoesNotFollowRedirects(); +#else + std::printf("skipping the curl round-trip tests: libcurl was not built in\n"); +#endif + + return testing::Report(); +} From 76e67d3c753da16a3ca98918ee40e7988b552519 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 14:28:17 +0100 Subject: [PATCH 2/5] Fix the loopback server for macOS and clang Two portability bugs, both caught by CI rather than by me: - htonl and ntohs are MACROS on macOS (__DARWIN_OSSwapInt32), so ::htonl(...) expands to ::__DARWIN_OSSwapInt32(...) and cannot be qualified. Dropped the ::. This is the kind of thing that only shows up on the platform you are not building on. - m_wsa_started is Windows-only, so clang warned about an unused private field. Guarded on _WIN32 rather than left alone: a warning in the test suite is a warning someone eventually silences by deleting the field. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/loopback_server.h | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/tests/loopback_server.h b/tests/loopback_server.h index 068cb9f..829d08b 100644 --- a/tests/loopback_server.h +++ b/tests/loopback_server.h @@ -121,7 +121,9 @@ class LoopbackServer { sockaddr_in address{}; address.sin_family = AF_INET; - address.sin_addr.s_addr = ::htonl(INADDR_LOOPBACK); + // Not `::htonl`: on macOS these are macros (`__DARWIN_OSSwapInt32`), and a macro + // expansion cannot be qualified with `::`. + address.sin_addr.s_addr = htonl(INADDR_LOOPBACK); address.sin_port = 0; // ephemeral if (::bind(static_cast(m_listen), reinterpret_cast(&address), @@ -142,7 +144,7 @@ class LoopbackServer { CloseListen(); return false; } - m_port = ::ntohs(bound.sin_port); + m_port = ntohs(bound.sin_port); if (::listen(static_cast(m_listen), 8) != 0) { CloseListen(); @@ -363,8 +365,14 @@ class LoopbackServer { } std::intptr_t m_listen = -1; - int m_port = 0; - bool m_wsa_started = false; + int m_port = 0; + + // Windows-only: WSAStartup has to be paired with WSACleanup. Guarded rather than left + // unguarded because clang warns about an unused private field, and a warning in the + // test suite is a warning someone will eventually silence by deleting the field. +#if defined(_WIN32) + bool m_wsa_started = false; +#endif std::atomic m_running{false}; std::thread m_thread; From 86a80318340ffbad9ae9ace1467fedcf28469f5e Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 14:40:05 +0100 Subject: [PATCH 3/5] Wake the loopback server's accept on Linux The Linux CI job sat in the test step for twenty minutes. The cause is in the test server, not the SDK: on Linux, closing a listening socket does NOT unblock a thread already blocked in accept(), so Stop() hung on join() for ever. Windows and macOS do unblock it, which is exactly why only one of the three targets hung. shutdown() before close() makes the pending accept return, which is the portable way to wake it. Also added a 120 s CTest timeout to the two new suites. A hang should fail the job in two minutes, not block CI until someone notices - which is what happened here. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/CMakeLists.txt | 6 ++++++ tests/loopback_server.h | 15 ++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 50d51ff..9093c9b 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -69,6 +69,12 @@ if(WIN32) endif() add_test(NAME transport_e2e COMMAND test_transport_e2e) +# A timeout on every test, so a hang fails the job instead of blocking CI until someone +# notices. This is not hypothetical: the loopback server's `Stop()` hung on Linux because +# closing a listening socket does not unblock `accept()` there, and the job sat in the test +# step for twenty minutes before anyone could see why. +set_tests_properties(transport_e2e executor PROPERTIES TIMEOUT 120) + # Tier 2 (D14): a tiny consumer that links only one module, proving the target graph and # the headers work from outside the library. It deliberately does NOT link broadcasts. # diff --git a/tests/loopback_server.h b/tests/loopback_server.h index 829d08b..7c0032e 100644 --- a/tests/loopback_server.h +++ b/tests/loopback_server.h @@ -162,7 +162,20 @@ class LoopbackServer { return; } - // Closing the listening socket unblocks `accept` on every platform we target. + // `shutdown` before `close`, and this is not belt-and-braces: on Linux, closing a + // listening socket does NOT unblock a thread already blocked in `accept()`, so + // `join()` below would hang for ever. Windows and macOS do unblock it, which is + // exactly why this only showed up on one of the three CI targets. + // + // `shutdown` on a listening socket makes the pending `accept` return, which is the + // portable way to wake it. + if (m_listen >= 0) { +#if defined(_WIN32) + ::shutdown(static_cast(m_listen), SD_BOTH); +#else + ::shutdown(static_cast(m_listen), SHUT_RDWR); +#endif + } CloseListen(); if (m_thread.joinable()) { From 391447fe972a2deb631fa3fa95f29ac5721b56d2 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Tue, 17 Nov 2026 09:51:18 +0100 Subject: [PATCH 4/5] Fix eight review findings in the executor and the loopback server All eight were real. The two that mattered most: - Poll was called TWICE per Update for a finished transfer: once to detect completion, then again to collect the response. The interface documents "called once per Update()", and a transport is entitled to consume its completion on the first poll - so the second poll would lose the response and report an empty result. The response is now kept from the first poll. Sabotaging this fix breaks six assertions across three tests. - SetTransport replaced the transport under in-flight entries, which hold only a transfer id. That id means nothing to a different transport, so the next Update would poll and cancel it on the new one and the old transfer would never be cancelled. Now refused while anything is in flight, returning false and logging why; the caller drains first, because only the caller knows whether waiting is acceptable. The rest: - Back-off overflowed signed int64 on the multiply before the cap was checked, which is undefined behaviour rather than a late clamp. The cap is now checked before multiplying. - Retry-After was accumulated in a signed int from server-controlled input, so a large header overflowed. Parsed into a checked 64-bit accumulator and clamped. - Retry-After: 0 is a valid instruction to retry immediately, but the > 0 check treated it as absent and applied the exponential back-off instead. Error now carries retry_after_present so "the server said zero" is distinguishable from "there was no header". - An invalid config made Update() return early, so a handler submitted through core::GetExecutor was stranded for ever. The executor now carries the config error and rejects through the normal path, so the handler runs on the next Update. - The loopback server's Stop() closed the listening socket while Run() was blocked in accept() on it: a data race, and not a portable wake-up. Replaced with a self-connection, which is portable and removes the race. - test_transport_e2e now links Threads::Threads, because the loopback server runs on its own thread and pthreads is not folded into libc everywhere. Five new tests cover the new behaviour, and the Retry-After: 0 fix was verified by sabotage as well. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- include/lootlocker/client.h | 6 +- include/lootlocker/result.h | 7 +- src/core/client.cpp | 15 ++-- src/core/executor.cpp | 138 +++++++++++++++++++++++++------- src/core/executor.h | 23 +++++- tests/CMakeLists.txt | 7 ++ tests/loopback_server.h | 60 ++++++++++---- tests/test_executor.cpp | 151 ++++++++++++++++++++++++++++++++++- tests/test_transport_e2e.cpp | 22 ++++- 9 files changed, 371 insertions(+), 58 deletions(-) diff --git a/include/lootlocker/client.h b/include/lootlocker/client.h index 32896a2..3257730 100644 --- a/include/lootlocker/client.h +++ b/include/lootlocker/client.h @@ -59,7 +59,11 @@ class Client { // Replaces the transport. The client observes it through a `weak_ptr`, so the adopter // keeps ownership and a transport that dies is detected rather than dereferenced. - void SetTransport(std::weak_ptr transport); + // + // Returns false when the replacement was refused because requests are still in flight. + // An in-flight transfer id is meaningful only to the transport that issued it, so + // swapping underneath would strand the old transfer. Drain first, then replace. + bool SetTransport(std::weak_ptr transport); // The transport in use, for a test or a wrapper that needs to inspect it. Empty when // the client has none, which happens when curl was not built in and nothing was diff --git a/include/lootlocker/result.h b/include/lootlocker/result.h index ed1ce3f..8d7073d 100644 --- a/include/lootlocker/result.h +++ b/include/lootlocker/result.h @@ -73,7 +73,12 @@ struct Error { std::string trace_id; // From a Retry-After header, in seconds. 0 when absent. - int retry_after_seconds = 0; + // + // `retry_after_present` distinguishes "the server said 0" from "there was no header", + // because `Retry-After: 0` is a valid instruction to retry immediately and treating it + // as absent would apply the exponential back-off instead. + int retry_after_seconds = 0; + bool retry_after_present = false; bool Ok() const { return code == ErrorCode::None; } }; diff --git a/src/core/client.cpp b/src/core/client.cpp index b2db27f..2836cb4 100644 --- a/src/core/client.cpp +++ b/src/core/client.cpp @@ -77,17 +77,18 @@ Client::Client(const Config& config) : m_impl(new Impl()) #endif } - m_impl->executor.reset( - new core::Executor(config.queue, transport, m_impl->clock, logger)); + m_impl->executor.reset(new core::Executor(config.queue, transport, m_impl->clock, logger, + m_impl->config_error)); } Client::~Client() = default; bool Client::Update() { - if (!m_impl->config_error.Ok()) { - return false; - } + // The executor is driven even when the config is invalid, because that is the only way + // a rejected request's handler ever runs. `Submit` on an invalid client rejects with + // `InvalidConfig` and queues the handler; skipping `Update()` here would leave those + // handlers stranded for ever, which is the opposite of what "inert" should mean. return m_impl->executor->Update(); } @@ -101,9 +102,9 @@ const Error& Client::ConfigError() const return m_impl->config_error; } -void Client::SetTransport(std::weak_ptr transport) +bool Client::SetTransport(std::weak_ptr transport) { - m_impl->executor->SetTransport(std::move(transport)); + return m_impl->executor->SetTransport(std::move(transport)); } std::weak_ptr Client::GetTransport() const diff --git a/src/core/executor.cpp b/src/core/executor.cpp index bcc6be6..9fbbdcd 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -47,14 +47,35 @@ Executor::Executor(const QueueConfig& config, std::weak_ptr tran { } +Executor::Executor(const QueueConfig& config, std::weak_ptr transport, + Clock& clock, std::weak_ptr logger, Error config_error) + : m_config(config), m_config_error(std::move(config_error)), m_transport(std::move(transport)), + m_clock(clock), m_logger(std::move(logger)) +{ +} + Executor::~Executor() { Abandon(); } -void Executor::SetTransport(std::weak_ptr transport) +bool Executor::SetTransport(std::weak_ptr transport) { + // Refused while anything is in flight. An in-flight entry holds only a transfer id, + // which means nothing to a different transport: swapping underneath would poll and + // cancel that id on the new one, and the old transfer would never be cancelled. The + // caller drains first, because only the caller knows whether waiting is acceptable. + if (InFlightCount() > 0) { + if (std::shared_ptr logger = m_logger.lock()) { + logger->Log(LogLevel::Warning, + "SetTransport was refused: requests are still in flight, so the " + "current transport cannot be replaced yet"); + } + return false; + } + m_transport = std::move(transport); + return true; } std::weak_ptr Executor::GetTransport() const @@ -94,27 +115,87 @@ std::int64_t Executor::BackoffMs(int attempts, const Completion& completion) con // A server that told us when to come back is obeyed exactly. Guessing at a back-off // when the server has stated the answer is how a client gets itself rate limited // harder. - if (completion.error.retry_after_seconds > 0) { + // + // `>= 0` rather than `> 0`: `Retry-After: 0` is a valid instruction to retry + // immediately, and treating it as absent would apply the exponential back-off instead. + // The field is only set when the header was present, so 0 here means "the server said + // zero", not "no header". + if (completion.error.retry_after_seconds >= 0 && completion.error.retry_after_present) { return static_cast(completion.error.retry_after_seconds) * 1000; } // initial * factor^(attempts-1), capped so a long retry chain cannot overflow into a - // negative delay. The cap is a day, which is far beyond any sane back-off and exists - // only to keep the arithmetic total. + // negative delay. + // + // The cap is checked BEFORE the multiplication, not after. Checking afterwards is + // undefined behaviour rather than a late clamp: a large enough `backoff_factor` or + // retry count overflows signed `int64_t` on the multiply itself, and the compiler is + // entitled to assume that never happens. std::int64_t delay = m_config.initial_backoff_ms; for (int i = 1; i < attempts; ++i) { + if (m_config.backoff_factor <= 0) { + return kMaxBackoffMs; + } + if (delay > kMaxBackoffMs / m_config.backoff_factor) { + return kMaxBackoffMs; + } delay *= m_config.backoff_factor; - if (delay > 86400000) { - return 86400000; + } + return delay > kMaxBackoffMs ? kMaxBackoffMs : delay; +} + +void Executor::ParseRetryAfter(const std::string& value, Error& error) +{ + // `Retry-After` is server-controlled input, so it is not trusted to be small. The + // accumulator is 64-bit and checked against the public field's range before narrowing: + // a header of "99999999999999999999" would otherwise overflow a signed `int` on the + // multiply, which is undefined behaviour and can produce a negative delay. + std::int64_t seconds = 0; + bool any_digit = false; + + for (const char c : value) { + if (c < '0' || c > '9') { + // Not a delay-seconds value. The HTTP-date form is legal but we do not parse + // it, so it is treated as absent rather than guessed at. + return; } + any_digit = true; + if (seconds > (2147483647 - (c - '0')) / 10) { + // Clamp rather than reject: the server asked us to wait a very long time, and + // waiting the maximum we can represent is closer to obeying than ignoring it. + error.retry_after_seconds = 2147483647; + error.retry_after_present = true; + return; + } + seconds = seconds * 10 + (c - '0'); } - return delay; + + if (!any_digit) { + return; + } + + error.retry_after_seconds = static_cast(seconds); + error.retry_after_present = true; } std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done) { const std::int64_t now = m_clock.NowMs(); + // An invalid config rejects everything, and the handler still runs - on the next + // `Update()`, like every other rejection, because callbacks fire from `Update()` (D5). + // Silently dropping the handler would leave a caller waiting for a callback that never + // comes. + if (!m_config_error.Ok()) { + if (on_done) { + Completion completion; + completion.error = m_config_error; + m_rejected.push_back( + [handler = std::move(on_done), completion]() { handler(completion); }); + } + return 0; + } + // The queue is full. `deny_when_backed_up` decides whether that is an error or a wait: // a game that would rather stall than drop a request leaves it false and the request // simply waits its turn. @@ -219,15 +300,7 @@ void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64 // retry decision rather than after. std::string retry_after; if (completion.headers.Get("Retry-After", retry_after)) { - int seconds = 0; - for (const char c : retry_after) { - if (c < '0' || c > '9') { - seconds = 0; - break; - } - seconds = seconds * 10 + (c - '0'); - } - completion.error.retry_after_seconds = seconds; + ParseRetryAfter(retry_after, completion.error); } // --- Retry or deliver ------------------------------------------------------------- @@ -292,7 +365,17 @@ bool Executor::Update() // Collected first, then processed, because `FinishOrRetry` erases from `m_entries` and // a handler may submit. Iterating the map while either happens is the bug this // two-step exists to avoid. - std::vector finished; + // + // The response is kept here rather than re-polled in phase 2. `IHttpTransport::Poll` is + // documented as "called once per Update()", and a transport is entitled to consume its + // completion on the first poll - so polling again would lose the response and report an + // empty result. + struct Finished { + std::uint64_t id = 0; + IHttpTransport::Response response; + }; + + std::vector finished; std::vector timed_out; for (auto& pair : m_entries) { @@ -309,33 +392,32 @@ bool Executor::Update() continue; } - IHttpTransport::Response response; - if (transport->Poll(entry.transfer, response)) { - finished.push_back(entry.id); + Finished done; + done.id = entry.id; + if (transport->Poll(entry.transfer, done.response)) { + finished.push_back(std::move(done)); } } // --- Phase 2: collect completions ------------------------------------------------- - for (const std::uint64_t id : finished) { - const auto it = m_entries.find(id); + for (Finished& done : finished) { + const auto it = m_entries.find(done.id); if (it == m_entries.end()) { continue; } Entry& entry = it->second; - IHttpTransport::Response response; - transport->Poll(entry.transfer, response); transport->Cancel(entry.transfer); Completion completion; - completion.status_code = response.status_code; - completion.headers = std::move(response.headers); - completion.body = std::move(response.body); + completion.status_code = done.response.status_code; + completion.headers = std::move(done.response.headers); + completion.body = std::move(done.response.body); completion.attempts = entry.attempts; LogAttempt(entry, completion, now - entry.started_at_ms); - FinishOrRetry(id, std::move(completion), now, handlers, completions); + FinishOrRetry(done.id, std::move(completion), now, handlers, completions); } for (const std::uint64_t id : timed_out) { diff --git a/src/core/executor.h b/src/core/executor.h index d095738..e29e550 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -71,6 +71,11 @@ class Executor { public: Executor(const QueueConfig& config, std::weak_ptr transport, Clock& clock, std::weak_ptr logger); + + // The same, plus the config error the client found. A non-empty error makes every + // submission reject with it, which is how an inert client still delivers its handlers. + Executor(const QueueConfig& config, std::weak_ptr transport, Clock& clock, + std::weak_ptr logger, Error config_error); ~Executor(); Executor(const Executor&) = delete; @@ -90,7 +95,14 @@ class Executor { // Replaces the transport. The executor holds a `weak_ptr` and locks it per use, so a // transport that dies mid-flight is detected rather than dereferenced. - void SetTransport(std::weak_ptr transport); + // + // **Refused while anything is in flight**, and returns false when it refuses. An + // in-flight entry holds only a transfer id, which is meaningful to the transport that + // issued it and to no other: swapping the transport underneath would poll and cancel + // that id on the new one, and the old transfer would never be cancelled. Draining + // first is the caller's job, because only the caller knows whether waiting is + // acceptable. + bool SetTransport(std::weak_ptr transport); // The transport in use. Empty when the client has none, which happens when curl was // not built in and nothing was injected. @@ -128,6 +140,10 @@ class Executor { std::vector& out_handlers, std::vector& out_completions); + // Parse a `Retry-After` header into `error.retry_after_seconds`, clamping rather than + // overflowing. Server-controlled input, so it is not trusted to be small. + static void ParseRetryAfter(const std::string& value, Error& error); + void Deliver(std::vector& handlers, std::vector& completions); void DrainRejected(); @@ -139,7 +155,12 @@ class Executor { std::int64_t TimeoutMs() const; std::int64_t BackoffMs(int attempts, const Completion& completion) const; + // The longest delay a back-off may produce. A day is far beyond any sane back-off and + // exists only to keep the arithmetic total. + static constexpr std::int64_t kMaxBackoffMs = 86400000; + QueueConfig m_config; + Error m_config_error; std::weak_ptr m_transport; Clock& m_clock; std::weak_ptr m_logger; diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 9093c9b..c9f369c 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -64,6 +64,13 @@ add_test(NAME executor COMMAND test_executor) add_executable(test_transport_e2e test_transport_e2e.cpp) target_link_libraries(test_transport_e2e PRIVATE LootLocker::core lootlocker_compile_options) target_include_directories(test_transport_e2e PRIVATE ${CMAKE_SOURCE_DIR}/src/core) + +# The loopback server runs on its own thread, so this target needs the platform's thread +# library. On Windows that is ws2_32; on POSIX it is Threads::Threads, which is not folded +# into libc everywhere (glibc before 2.34 needs -lpthread explicitly). Linking only the +# socket library would fail to link on those toolchains. +find_package(Threads REQUIRED) +target_link_libraries(test_transport_e2e PRIVATE Threads::Threads) if(WIN32) target_link_libraries(test_transport_e2e PRIVATE ws2_32) endif() diff --git a/tests/loopback_server.h b/tests/loopback_server.h index 7c0032e..dd61a5c 100644 --- a/tests/loopback_server.h +++ b/tests/loopback_server.h @@ -162,26 +162,20 @@ class LoopbackServer { return; } - // `shutdown` before `close`, and this is not belt-and-braces: on Linux, closing a - // listening socket does NOT unblock a thread already blocked in `accept()`, so - // `join()` below would hang for ever. Windows and macOS do unblock it, which is - // exactly why this only showed up on one of the three CI targets. - // - // `shutdown` on a listening socket makes the pending `accept` return, which is the - // portable way to wake it. - if (m_listen >= 0) { -#if defined(_WIN32) - ::shutdown(static_cast(m_listen), SD_BOTH); -#else - ::shutdown(static_cast(m_listen), SHUT_RDWR); -#endif - } - CloseListen(); + // Wake the blocked `accept` with a real connection rather than by closing the + // socket underneath it. Closing a listening socket from another thread is not a + // portable way to interrupt `accept`: on Linux it does not interrupt it at all, and + // on platforms where it does, the thread may still be using the descriptor when it + // is invalidated. A self-connection is the portable wake-up, and it also removes the + // data race on `m_listen`. + WakeAccept(); if (m_thread.joinable()) { m_thread.join(); } + CloseListen(); + #if defined(_WIN32) if (m_wsa_started) { WSACleanup(); @@ -219,6 +213,29 @@ class LoopbackServer { } private: + // Connect to ourselves so the blocked `accept` returns. The accepted connection is + // closed immediately by `Run`, which sees `m_running` false and exits. + void WakeAccept() + { + const std::intptr_t wake = static_cast(::socket(AF_INET, SOCK_STREAM, 0)); + if (wake < 0) { + return; + } + + sockaddr_in address{}; + address.sin_family = AF_INET; + address.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + address.sin_port = htons(static_cast(m_port)); + + ::connect(static_cast(wake), reinterpret_cast(&address), sizeof(address)); + +#if defined(_WIN32) + ::closesocket(static_cast(wake)); +#else + ::close(static_cast(wake)); +#endif + } + void CloseListen() { if (m_listen >= 0) { @@ -237,7 +254,18 @@ class LoopbackServer { const std::intptr_t client = static_cast(::accept(static_cast(m_listen), nullptr, nullptr)); if (client < 0) { - // Either we are shutting down or the accept failed; both mean stop. + // The accept failed; stop rather than spin on a broken listener. + break; + } + + // The wake-up connection from `Stop()`. Nothing is read from it: the flag is + // already false, so the loop exits and the socket is closed below. + if (!m_running.load()) { +#if defined(_WIN32) + ::closesocket(static_cast(client)); +#else + ::close(static_cast(client)); +#endif break; } diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index 388aa6d..dbaacfb 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -479,7 +479,7 @@ void TestSetTransportReplacesTheSeam() Fixture f; auto replacement = std::make_shared(); - f.executor->SetTransport(replacement); + CHECK(f.executor->SetTransport(replacement)); f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); @@ -489,6 +489,33 @@ void TestSetTransportReplacesTheSeam() CHECK_EQ_INT(static_cast(f.transport->StartCount()), 0); } +void TestSetTransportIsRefusedWhileInFlight() +{ + Fixture f; + + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.executor->InFlightCount()), 1); + + // An in-flight transfer id means nothing to a different transport, so replacing it now + // would strand the old transfer. Refused, and said so. + auto replacement = std::make_shared(); + CHECK(!f.executor->SetTransport(replacement)); + + bool warned = false; + for (const std::string& message : f.logger->messages) { + if (message.find("SetTransport was refused") != std::string::npos) { + warned = true; + } + } + CHECK(warned); + + // Once drained, the replacement is accepted. + f.transport->Complete(f.transport->Order().back(), 200, "{}"); + CHECK(!f.executor->Update()); + CHECK(f.executor->SetTransport(replacement)); +} + // --- Logging --------------------------------------------------------------------------- void TestEachAttemptIsLoggedAndObfuscated() @@ -523,6 +550,123 @@ void TestEachAttemptIsLoggedAndObfuscated() CHECK(entry.response_body.find("abc") != std::string::npos); } +void TestRetryAfterZeroRetriesImmediately() +{ + Fixture f; + + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(f.executor->Update()); + + IHttpTransport::Response response; + response.status_code = 429; + response.body = "{}"; + // A valid instruction to retry immediately. Treating it as "no header" would apply the + // 50 ms exponential back-off instead, which is not what the server asked for. + response.headers.Set("Retry-After", "0"); + f.transport->Complete(id, response); + + // No clock advance at all, and the retry is already due. + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +void TestHugeRetryAfterIsClampedNotOverflowed() +{ + Fixture f; + + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(f.executor->Update()); + + IHttpTransport::Response response; + response.status_code = 429; + response.body = "{}"; + // Server-controlled input, so it is not trusted to be small. This overflows a signed + // int on the multiply if the accumulator is not checked. + response.headers.Set("Retry-After", "99999999999999999999"); + f.transport->Complete(id, response); + + // Clamped to the largest representable delay rather than wrapping negative. A negative + // delay would make the retry due immediately, which is the opposite of obeying. + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + f.clock.Advance(1000); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); +} + +void TestLargeBackoffFactorDoesNotOverflow() +{ + QueueConfig config = DefaultQueue(); + config.max_retries = 40; + config.backoff_factor = 1000000; // absurd, but a config field is adopter input + config.initial_backoff_ms = 1000000; + Fixture f(config); + + const std::uint64_t id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(f.executor->Update()); + f.transport->Complete(id, 503, "unavailable"); + f.executor->Update(); + + // The first delay is already 1,000,000 ms, so a second is not enough. + f.clock.Advance(1000); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // The point of the test: the delay is capped at a day and stays positive. Without the + // pre-multiplication cap, the multiply overflows signed int64 and the delay goes + // negative, which would make the retry due immediately - the opposite of a back-off. + f.clock.Advance(86400000); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); + + // And it keeps working rather than wrapping: another failure, another capped delay. + f.transport->Complete(f.transport->Order().back(), 503, "unavailable"); + f.executor->Update(); + f.clock.Advance(86400000); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 3); +} + +void TestInvalidConfigRejectsThroughUpdate() +{ + // An inert client still has to deliver its handlers, or a caller waits for a callback + // that never comes. + Error config_error; + config_error.code = ErrorCode::InvalidConfig; + config_error.message = "domain_key is required"; + + auto transport = std::make_shared(); + auto logger = std::make_shared(); + FakeClock clock; + Executor executor(DefaultQueue(), transport, clock, logger, config_error); + + int delivered = 0; + Completion last; + const std::uint64_t id = executor.Submit(Get("https://example.test/a"), + [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK_EQ_INT(static_cast(id), 0); + CHECK_EQ_INT(delivered, 0); + + // Delivered on Update, like every other rejection. + CHECK(!executor.Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.code == ErrorCode::InvalidConfig); + + // And nothing was ever sent. + CHECK_EQ_INT(static_cast(transport->StartCount()), 0); +} + void TestAbandonCancelsInFlightWithoutCallingBack() { Fixture f; @@ -562,7 +706,12 @@ int main() TestBackedUpQueueWaitsWhenDenyIsOff(); TestDeadTransportFailsInFlightRequests(); TestSetTransportReplacesTheSeam(); + TestSetTransportIsRefusedWhileInFlight(); TestEachAttemptIsLoggedAndObfuscated(); + TestRetryAfterZeroRetriesImmediately(); + TestHugeRetryAfterIsClampedNotOverflowed(); + TestLargeBackoffFactorDoesNotOverflow(); + TestInvalidConfigRejectsThroughUpdate(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report(); diff --git a/tests/test_transport_e2e.cpp b/tests/test_transport_e2e.cpp index cd55388..325ec03 100644 --- a/tests/test_transport_e2e.cpp +++ b/tests/test_transport_e2e.cpp @@ -220,7 +220,6 @@ void TestInjectedTransportIsUsedByTheClient() // The client reports the injected transport, not a default. CHECK(!client.GetTransport().expired()); CHECK(client.GetTransport().lock() == fake); - int delivered = 0; core::Completion last; core::PendingRequest request; @@ -265,7 +264,7 @@ void TestSetTransportReplacesTheInjectedOne() config.transport = first; Client client(config); - client.SetTransport(second); + CHECK(client.SetTransport(second)); CHECK(client.GetTransport().lock() == second); @@ -291,9 +290,26 @@ void TestInvalidConfigMakesTheClientInert() CHECK(!client.ConfigError().Ok()); CHECK(client.ConfigError().code == ErrorCode::InvalidConfig); - // Inert: Update reports nothing to do and nothing is ever sent. + // Inert: nothing is ever sent. CHECK(!client.Update()); CHECK_EQ_INT(static_cast(fake->StartCount()), 0); + + // But a submission is still answered rather than silently dropped. A caller waiting for + // a callback that never comes is worse than a clear error. + int delivered = 0; + core::Completion last; + core::PendingRequest request; + request.method = "GET"; + request.url = "http://127.0.0.1:1/x"; + core::GetExecutor(client).Submit(request, [&](const core::Completion& completion) { + ++delivered; + last = completion; + }); + + CHECK(!client.Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.code == ErrorCode::InvalidConfig); + CHECK_EQ_INT(static_cast(fake->StartCount()), 0); } } // namespace From bfd2f145fc9f30c2fbd985379a8cb68833edbf1f Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Wed, 18 Nov 2026 10:22:26 +0100 Subject: [PATCH 5/5] Classify 3xx as an error, and stop narrowing socket handles Two more review findings, both real. - A 3xx left completion.error as None, so a 302 was delivered to callers as a SUCCESS. That matters specifically because redirects are disabled in the default transport (D3): the redirect arrives as a plain response, and the module layer would try to decode the redirect body as a normal API response and report a confusing decode error instead of "the server redirected us". Every non-2xx is now an error; 429 keeps its own code, and 204 is still a success because it is a 2xx. Verified by sabotage: restoring >= 400 fails the new test. - The loopback server narrowed every socket handle to int. On 64-bit Windows SOCKET is a pointer-sized UINT_PTR, so a handle above 32 bits would be truncated and the call would operate on the wrong socket. Introduced a SocketHandle alias (SOCKET on Windows, int on POSIX) and a CloseSocket helper, and removed every narrowing cast. The one remaining int cast is a byte count, not a handle. Two new tests: a 302 is an error and is not retried, and a 204 is still a success - the second exists because widening the error range to "everything not 2xx" is exactly the change that would break EndSession. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/core/executor.cpp | 12 +++++- tests/loopback_server.h | 90 ++++++++++++++++++++++------------------- tests/test_executor.cpp | 63 +++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+), 44 deletions(-) diff --git a/src/core/executor.cpp b/src/core/executor.cpp index 9fbbdcd..2b5a5b4 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -284,14 +284,22 @@ void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64 Entry& entry = it->second; // --- Classify the outcome --------------------------------------------------------- - + // + // Every non-2xx status is an error, not just 4xx and 5xx. A 3xx matters specifically + // because redirects are disabled in the default transport (D3): a 302 arrives here as + // a plain response, and if it were left as `None` the module layer would try to decode + // the redirect body as a normal API response and report a confusing decode error + // instead of "the server redirected us". + // + // 204 is the one legitimate empty success (`EndSession`), and it is a 2xx, so it is + // unaffected. if (completion.status_code == 0) { completion.error = MakeError(ErrorCode::Transport, "no response arrived: the transport failed"); } else if (completion.status_code == 429) { completion.error = MakeError(ErrorCode::RateLimited, "the server rate limited us", completion.status_code); - } else if (completion.status_code >= 400) { + } else if (completion.status_code >= 300) { completion.error = MakeError(ErrorCode::Http, "the server returned an error status", completion.status_code); } diff --git a/tests/loopback_server.h b/tests/loopback_server.h index dd61a5c..13d3416 100644 --- a/tests/loopback_server.h +++ b/tests/loopback_server.h @@ -38,6 +38,20 @@ namespace testing { +// The platform's socket handle type, used everywhere instead of `int`. +// +// On 64-bit Windows `SOCKET` is a pointer-sized `UINT_PTR`, so narrowing it to `int` is not +// merely lossy in theory: a handle whose value exceeds 32 bits would be truncated and the +// call would operate on the wrong socket. On POSIX the handle is an `int`, so this is the +// same type there and the casts below are no-ops. +#if defined(_WIN32) +using SocketHandle = SOCKET; +static const SocketHandle kInvalidSocket = INVALID_SOCKET; +#else +using SocketHandle = int; +static const SocketHandle kInvalidSocket = -1; +#endif + // One request as it arrived on the wire. struct ReceivedRequest { std::string method; @@ -109,14 +123,14 @@ class LoopbackServer { m_wsa_started = true; #endif - m_listen = static_cast(::socket(AF_INET, SOCK_STREAM, 0)); - if (m_listen < 0) { + m_listen = ::socket(AF_INET, SOCK_STREAM, 0); + if (m_listen == kInvalidSocket) { return false; } // SO_REUSEADDR so a rerun in the same process does not fail on a lingering socket. int yes = 1; - ::setsockopt(static_cast(m_listen), SOL_SOCKET, SO_REUSEADDR, + ::setsockopt(m_listen, SOL_SOCKET, SO_REUSEADDR, reinterpret_cast(&yes), sizeof(yes)); sockaddr_in address{}; @@ -126,8 +140,7 @@ class LoopbackServer { address.sin_addr.s_addr = htonl(INADDR_LOOPBACK); address.sin_port = 0; // ephemeral - if (::bind(static_cast(m_listen), reinterpret_cast(&address), - sizeof(address)) != 0) { + if (::bind(m_listen, reinterpret_cast(&address), sizeof(address)) != 0) { CloseListen(); return false; } @@ -139,14 +152,13 @@ class LoopbackServer { #else socklen_t length = sizeof(bound); #endif - if (::getsockname(static_cast(m_listen), reinterpret_cast(&bound), - &length) != 0) { + if (::getsockname(m_listen, reinterpret_cast(&bound), &length) != 0) { CloseListen(); return false; } m_port = ntohs(bound.sin_port); - if (::listen(static_cast(m_listen), 8) != 0) { + if (::listen(m_listen, 8) != 0) { CloseListen(); return false; } @@ -213,12 +225,23 @@ class LoopbackServer { } private: + // Close a socket without narrowing it. On Windows the handle is pointer-sized, so it + // must go to `closesocket` as a `SOCKET` and never through an `int`. + static void CloseSocket(SocketHandle socket) + { +#if defined(_WIN32) + ::closesocket(socket); +#else + ::close(socket); +#endif + } + // Connect to ourselves so the blocked `accept` returns. The accepted connection is // closed immediately by `Run`, which sees `m_running` false and exits. void WakeAccept() { - const std::intptr_t wake = static_cast(::socket(AF_INET, SOCK_STREAM, 0)); - if (wake < 0) { + const SocketHandle wake = ::socket(AF_INET, SOCK_STREAM, 0); + if (wake == kInvalidSocket) { return; } @@ -227,33 +250,24 @@ class LoopbackServer { address.sin_addr.s_addr = htonl(INADDR_LOOPBACK); address.sin_port = htons(static_cast(m_port)); - ::connect(static_cast(wake), reinterpret_cast(&address), sizeof(address)); + ::connect(wake, reinterpret_cast(&address), sizeof(address)); -#if defined(_WIN32) - ::closesocket(static_cast(wake)); -#else - ::close(static_cast(wake)); -#endif + CloseSocket(wake); } void CloseListen() { - if (m_listen >= 0) { -#if defined(_WIN32) - ::closesocket(static_cast(m_listen)); -#else - ::close(static_cast(m_listen)); -#endif - m_listen = -1; + if (m_listen != kInvalidSocket) { + CloseSocket(m_listen); + m_listen = kInvalidSocket; } } void Run() { while (m_running.load()) { - const std::intptr_t client = - static_cast(::accept(static_cast(m_listen), nullptr, nullptr)); - if (client < 0) { + const SocketHandle client = ::accept(m_listen, nullptr, nullptr); + if (client == kInvalidSocket) { // The accept failed; stop rather than spin on a broken listener. break; } @@ -261,33 +275,25 @@ class LoopbackServer { // The wake-up connection from `Stop()`. Nothing is read from it: the flag is // already false, so the loop exits and the socket is closed below. if (!m_running.load()) { -#if defined(_WIN32) - ::closesocket(static_cast(client)); -#else - ::close(static_cast(client)); -#endif + CloseSocket(client); break; } HandleOne(client); -#if defined(_WIN32) - ::closesocket(static_cast(client)); -#else - ::close(static_cast(client)); -#endif + CloseSocket(client); } } // Read until the header terminator, then read exactly Content-Length bytes. - static bool ReadRequest(std::intptr_t client, ReceivedRequest& out) + static bool ReadRequest(SocketHandle client, ReceivedRequest& out) { std::string buffer; char chunk[4096]; std::size_t header_end = std::string::npos; while (header_end == std::string::npos) { - const int got = ::recv(static_cast(client), chunk, sizeof(chunk), 0); + const int got = ::recv(client, chunk, sizeof(chunk), 0); if (got <= 0) { return false; } @@ -352,7 +358,7 @@ class LoopbackServer { } while (body.size() < expected) { - const int got = ::recv(static_cast(client), chunk, sizeof(chunk), 0); + const int got = ::recv(client, chunk, sizeof(chunk), 0); if (got <= 0) { break; } @@ -363,7 +369,7 @@ class LoopbackServer { return true; } - void HandleOne(std::intptr_t client) + void HandleOne(SocketHandle client) { ReceivedRequest request; if (!ReadRequest(client, request)) { @@ -396,7 +402,7 @@ class LoopbackServer { std::size_t sent = 0; while (sent < out.size()) { - const int wrote = ::send(static_cast(client), out.data() + sent, + const int wrote = ::send(client, out.data() + sent, static_cast(out.size() - sent), 0); if (wrote <= 0) { return; @@ -405,7 +411,7 @@ class LoopbackServer { } } - std::intptr_t m_listen = -1; + SocketHandle m_listen = kInvalidSocket; int m_port = 0; // Windows-only: WSAStartup has to be paired with WSACleanup. Guarded rather than left diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index dbaacfb..0514b09 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -667,6 +667,67 @@ void TestInvalidConfigRejectsThroughUpdate() CHECK_EQ_INT(static_cast(transport->StartCount()), 0); } +void TestRedirectIsAnErrorNotASuccess() +{ + Fixture f; + + int delivered = 0; + Completion last; + const std::uint64_t id = f.executor->Submit( + Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK(f.executor->Update()); + + // Redirects are disabled in the default transport (D3), so a 302 arrives as a plain + // response. It must not be delivered as a success: the module layer would try to decode + // the redirect body as an API response and report a confusing decode error instead of + // "the server redirected us". + IHttpTransport::Response response; + response.status_code = 302; + response.body = "moved"; + response.headers.Set("Location", "https://elsewhere.test/"); + f.transport->Complete(id, response); + + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.code == ErrorCode::Http); + CHECK_EQ_INT(last.status_code, 302); + + // Not retried: a 3xx is not in the retryable set, and retrying would just redirect + // again. + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + // The body is still carried, so the adopter can see what the server actually sent (D7). + CHECK_EQ(last.body, std::string("moved")); +} + +void TestNoContentIsStillASuccess() +{ + Fixture f; + + int delivered = 0; + Completion last; + const std::uint64_t id = f.executor->Submit( + Get("https://example.test/a"), [&](const Completion& c) { + ++delivered; + last = c; + }); + + CHECK(f.executor->Update()); + + // 204 is the one legitimate empty success (`EndSession`). Widening the error range to + // "everything that is not 2xx" must not catch it. + f.transport->Complete(id, 204, ""); + + CHECK(!f.executor->Update()); + CHECK_EQ_INT(delivered, 1); + CHECK(last.error.Ok()); + CHECK_EQ_INT(last.status_code, 204); +} + void TestAbandonCancelsInFlightWithoutCallingBack() { Fixture f; @@ -712,6 +773,8 @@ int main() TestHugeRetryAfterIsClampedNotOverflowed(); TestLargeBackoffFactorDoesNotOverflow(); TestInvalidConfigRejectsThroughUpdate(); + TestRedirectIsAnErrorNotASuccess(); + TestNoContentIsStillASuccess(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report();