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..3257730 --- /dev/null +++ b/include/lootlocker/client.h @@ -0,0 +1,82 @@ +#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. + // + // 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 + // 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/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 new file mode 100644 index 0000000..2836cb4 --- /dev/null +++ b/src/core/client.cpp @@ -0,0 +1,124 @@ +#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, + m_impl->config_error)); +} + +Client::~Client() = default; + +bool Client::Update() +{ + // 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(); +} + +const Config& Client::GetConfig() const +{ + return m_impl->config; +} + +const Error& Client::ConfigError() const +{ + return m_impl->config_error; +} + +bool Client::SetTransport(std::weak_ptr transport) +{ + return 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..2b5a5b4 --- /dev/null +++ b/src/core/executor.cpp @@ -0,0 +1,561 @@ +#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(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(); +} + +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 +{ + 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. + // + // `>= 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 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; + } + 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'); + } + + 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. + 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 --------------------------------------------------------- + // + // 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 >= 300) { + 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)) { + ParseRetryAfter(retry_after, completion.error); + } + + // --- 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. + // + // 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) { + 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; + } + + Finished done; + done.id = entry.id; + if (transport->Poll(entry.transfer, done.response)) { + finished.push_back(std::move(done)); + } + } + + // --- Phase 2: collect completions ------------------------------------------------- + + for (Finished& done : finished) { + const auto it = m_entries.find(done.id); + if (it == m_entries.end()) { + continue; + } + Entry& entry = it->second; + + transport->Cancel(entry.transfer); + + Completion completion; + 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(done.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..e29e550 --- /dev/null +++ b/src/core/executor.h @@ -0,0 +1,180 @@ +#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); + + // 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; + 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. + // + // **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. + 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); + + // 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(); + + 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; + + // 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; + + 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..c9f369c 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -44,6 +44,44 @@ 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) + +# 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() +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 new file mode 100644 index 0000000..13d3416 --- /dev/null +++ b/tests/loopback_server.h @@ -0,0 +1,432 @@ +// 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 { + +// 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; + 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 = ::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(m_listen, SOL_SOCKET, SO_REUSEADDR, + reinterpret_cast(&yes), sizeof(yes)); + + sockaddr_in address{}; + address.sin_family = AF_INET; + // 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(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(m_listen, reinterpret_cast(&bound), &length) != 0) { + CloseListen(); + return false; + } + m_port = ntohs(bound.sin_port); + + if (::listen(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; + } + + // 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(); + 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: + // 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 SocketHandle wake = ::socket(AF_INET, SOCK_STREAM, 0); + if (wake == kInvalidSocket) { + 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(wake, reinterpret_cast(&address), sizeof(address)); + + CloseSocket(wake); + } + + void CloseListen() + { + if (m_listen != kInvalidSocket) { + CloseSocket(m_listen); + m_listen = kInvalidSocket; + } + } + + void Run() + { + while (m_running.load()) { + const SocketHandle client = ::accept(m_listen, nullptr, nullptr); + if (client == kInvalidSocket) { + // 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()) { + CloseSocket(client); + break; + } + + HandleOne(client); + + CloseSocket(client); + } + } + + // Read until the header terminator, then read exactly Content-Length bytes. + 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(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(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(SocketHandle 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(client, out.data() + sent, + static_cast(out.size() - sent), 0); + if (wrote <= 0) { + return; + } + sent += static_cast(wrote); + } + } + + SocketHandle m_listen = kInvalidSocket; + 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; + + 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..0514b09 --- /dev/null +++ b/tests/test_executor.cpp @@ -0,0 +1,781 @@ +// 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(); + CHECK(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); +} + +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() +{ + 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 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 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; + + 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(); + TestSetTransportIsRefusedWhileInFlight(); + TestEachAttemptIsLoggedAndObfuscated(); + TestRetryAfterZeroRetriesImmediately(); + TestHugeRetryAfterIsClampedNotOverflowed(); + TestLargeBackoffFactorDoesNotOverflow(); + TestInvalidConfigRejectsThroughUpdate(); + TestRedirectIsAnErrorNotASuccess(); + TestNoContentIsStillASuccess(); + TestAbandonCancelsInFlightWithoutCallingBack(); + + return testing::Report(); +} diff --git a/tests/test_transport_e2e.cpp b/tests/test_transport_e2e.cpp new file mode 100644 index 0000000..325ec03 --- /dev/null +++ b/tests/test_transport_e2e.cpp @@ -0,0 +1,332 @@ +// 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); + CHECK(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: 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 + +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(); +}