diff --git a/CMakeLists.txt b/CMakeLists.txt index 00549c6..b45f4ff 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -139,6 +139,7 @@ add_library(lootlocker_core STATIC src/core/text.cpp src/core/config_obfuscation.cpp src/core/header_map.cpp + src/core/request_id.cpp src/core/executor.cpp src/core/client.cpp ) diff --git a/README.md b/README.md index ce85d4c..f33ae4d 100644 --- a/README.md +++ b/README.md @@ -92,11 +92,15 @@ 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. +- **A lost response is retried whatever the method.** A POST that timed out may have + succeeded, and retrying it can double-grant — that is a real risk we accept rather than + guard against, because the alternative was a per-request `idempotent` flag that moved a + correctness decision onto the caller. See R25 in the spec. + +**There is no request deduplication or grouping.** Two identical submissions are two +requests, and both are sent. The API is not guaranteed to be idempotent: "add 5 gold" +performed five times must yield 25, not 5, and the SDK cannot tell that apart from a +harmless repeated read. ## The transport diff --git a/include/lootlocker/request_id.h b/include/lootlocker/request_id.h new file mode 100644 index 0000000..fff9a1d --- /dev/null +++ b/include/lootlocker/request_id.h @@ -0,0 +1,63 @@ +#pragma once + +// The id every async call returns (D25). +// +// A value type wrapping a `uint64`, not a string: a string id would allocate on every call, +// which is exactly the kind of thing a game SDK should not do on a hot path. It is the same +// id the queue uses internally and the same id sent as `LL-Request-Id`, so a support ticket +// can be matched to a server log line. +// +// It is also what `Cancel(RequestId)` will take when cancellation lands, so the return type +// does not have to change for that. +// +// **The counter is process-wide, not per-client.** Two clients in one process are legal +// (D20), and a per-client counter would let both mint id 5 - so a support ticket quoting +// "request 5" would be ambiguous. Minting from one static counter makes the id unique +// across the process, which is the whole point of a correlation id. + +#include +#include + +namespace lootlocker { + +class RequestId { +public: + // Invalid. `IsValid()` is false, and it is what a rejected submission returns. + RequestId() = default; + + explicit RequestId(std::uint64_t value) : m_value(value) {} + + // Mint the next id. Process-wide and monotonic, so ids are unique across every client + // in the process and increasing in submission order. + // + // Never returns an invalid id: 0 is skipped, so a wrap cannot produce one. The wrap is + // unreachable in practice - a `uint64` at a million requests a second lasts longer than + // the hardware - but skipping 0 costs one comparison and removes the edge case + // entirely. + static RequestId Next(); + + std::uint64_t Value() const { return m_value; } + + // False for the default-constructed id, which is what a rejected submission returns. + // Ids start at 1, so 0 is unambiguous. + bool IsValid() const { return m_value != 0; } + + // For logs and for the `LL-Request-Id` header. Allocates, so not on a hot path. + std::string ToString() const; + + bool operator==(const RequestId& other) const { return m_value == other.m_value; } + bool operator!=(const RequestId& other) const { return m_value != other.m_value; } + + // Ordering exists so the queue can keep FIFO order among requests that are equally + // ready, and so an id can be a map key. Because ids are minted monotonically, this is + // also submission order within one client. + // + // It is deliberately not a documented guarantee: the other SDKs mint a GUID and have no + // ordering at all, and nothing in the public surface should come to depend on it. + bool operator<(const RequestId& other) const { return m_value < other.m_value; } + +private: + std::uint64_t m_value = 0; +}; + +} // namespace lootlocker diff --git a/src/core/executor.cpp b/src/core/executor.cpp index 2b5a5b4..b9f6657 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -178,7 +178,7 @@ void Executor::ParseRetryAfter(const std::string& value, Error& error) error.retry_after_present = true; } -std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done) +RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) { const std::int64_t now = m_clock.NowMs(); @@ -193,7 +193,7 @@ std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done m_rejected.push_back( [handler = std::move(on_done), completion]() { handler(completion); }); } - return 0; + return RequestId(); } // The queue is full. `deny_when_backed_up` decides whether that is an error or a wait: @@ -208,16 +208,16 @@ std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done m_rejected.push_back( [handler = std::move(on_done), completion]() { handler(completion); }); } - return 0; + return RequestId(); } Entry entry; - entry.id = m_next_id++; + entry.id = RequestId::Next(); entry.request = std::move(request); entry.on_done = std::move(on_done); entry.ready_at_ms = now; - const std::uint64_t id = entry.id; + const RequestId id = entry.id; m_entries.emplace(id, std::move(entry)); return id; } @@ -262,6 +262,7 @@ void Executor::LogAttempt(const Entry& entry, const Completion& completion, http.status_code = completion.status_code; http.duration_ms = duration_ms; http.attempt = entry.attempts; + http.request_id = entry.id.ToString(); std::string trace_id; if (completion.headers.Get("LL-Trace-Id", trace_id)) { @@ -273,7 +274,7 @@ void Executor::LogAttempt(const Entry& entry, const Completion& completion, log::LogExchange(*logger, http); } -void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64_t now, +void Executor::FinishOrRetry(RequestId id, Completion completion, std::int64_t now, std::vector& out_handlers, std::vector& out_completions) { @@ -311,17 +312,27 @@ void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64 ParseRetryAfter(retry_after, completion.error); } + // The id goes on the completion as well as the log, so a caller holding a failed result + // can quote the same id the server saw. `Error::request_id` documents itself as "also + // sent as the LL-Request-Id header", and a support ticket is usually raised from a + // failure, not a success - so leaving it empty on failure defeats the purpose. + completion.error.request_id = id.ToString(); + // --- 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) { + // **A lost response is retried, whatever the method** (owner, 2026-11-20). This + // deliberately does not distinguish a POST from a GET. + // + // The earlier design carried a per-request `idempotent` flag and refused to retry a + // non-idempotent request whose response was lost, because a POST that timed out may + // have succeeded and retrying it can double-grant (R25). The owner's call is that the + // other SDKs do not do this and we should not either: the flag moves a correctness + // decision onto the caller, and a caller who forgets it gets a request that silently + // never retries. R25 is therefore an **accepted risk**, not a closed one - see the + // spec's risk table. + if (retryable && entry.attempts <= m_config.max_retries) { entry.in_flight = false; entry.transfer = 0; entry.ready_at_ms = now + BackoffMs(entry.attempts, completion); @@ -330,11 +341,9 @@ void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64 // 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_handlers.push_back(std::move(entry.on_done)); out_completions.push_back(std::move(completion)); + m_entries.erase(it); } bool Executor::Update() @@ -379,12 +388,12 @@ bool Executor::Update() // completion on the first poll - so polling again would lose the response and report an // empty result. struct Finished { - std::uint64_t id = 0; + RequestId id; IHttpTransport::Response response; }; std::vector finished; - std::vector timed_out; + std::vector timed_out; for (auto& pair : m_entries) { Entry& entry = pair.second; @@ -428,7 +437,7 @@ bool Executor::Update() FinishOrRetry(done.id, std::move(completion), now, handlers, completions); } - for (const std::uint64_t id : timed_out) { + for (const RequestId id : timed_out) { const auto it = m_entries.find(id); if (it == m_entries.end()) { continue; @@ -455,7 +464,7 @@ bool Executor::Update() // rather than one item. { - std::vector ready; + std::vector ready; for (const auto& pair : m_entries) { const Entry& entry = pair.second; if (!entry.in_flight && entry.ready_at_ms <= now) { @@ -465,7 +474,7 @@ bool Executor::Update() // 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) { + for (const RequestId id : ready) { if (static_cast(InFlightCount()) >= m_config.max_in_flight) { break; } @@ -483,6 +492,14 @@ bool Executor::Update() request.body = entry.request.body; request.timeout_seconds = m_config.request_timeout_seconds; + // The id goes on the wire as `LL-Request-Id`, so a support ticket can be + // matched to a server log line (D25). + // + // Set here, at send time, rather than on the stored request, so that a retry + // re-sends the same logical request with the same id - which is what makes a + // server log show one id across attempts rather than one per attempt. + request.headers.Set("LL-Request-Id", entry.id.ToString()); + ++entry.attempts; entry.started_at_ms = now; @@ -522,18 +539,18 @@ void Executor::FailAll(const std::string& reason) 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)); - } + 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); + completion.error.request_id = entry.id.ToString(); + + handlers.push_back(std::move(entry.on_done)); + completions.push_back(std::move(completion)); } m_entries.clear(); diff --git a/src/core/executor.h b/src/core/executor.h index e29e550..f8836da 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -14,6 +14,7 @@ #include #include #include +#include #include #include "clock.h" @@ -38,14 +39,6 @@ struct PendingRequest { 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. @@ -85,9 +78,17 @@ class Executor { // 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); + // Returns an invalid `RequestId` when the request was rejected outright, which happens + // when the queue is full and `deny_when_backed_up` is set, or when the config is + // invalid. The handler still runs, with `QueueFull` or `InvalidConfig`. + // + // **Every submission is its own request. There is no deduplication or grouping** + // (owner, 2026-11-19). Two identical submissions are two requests, and both are sent. + // The reason is that the API is not guaranteed to be idempotent: "add 5 gold" sent + // five times must yield 25, not 5, and the SDK cannot tell that case apart from a + // harmless repeated read. The Unity SDK built this and then turned it off for the same + // reason. + RequestId 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. @@ -118,8 +119,13 @@ class Executor { private: struct Entry { - std::uint64_t id = 0; + RequestId id; PendingRequest request; + + // The one handler waiting on this request. A single handler, not a vector: requests + // are never grouped (owner, 2026-11-19), so an entry has exactly one caller. A + // vector would add an allocation per submission and imply an invariant that no + // longer exists. CompletionHandler on_done; // Attempts started so far, 1-based once the first one begins. @@ -134,9 +140,9 @@ class Executor { }; // 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 + // move its handlers 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, + void FinishOrRetry(RequestId id, Completion completion, std::int64_t now, std::vector& out_handlers, std::vector& out_completions); @@ -165,8 +171,7 @@ class Executor { Clock& m_clock; std::weak_ptr m_logger; - std::uint64_t m_next_id = 1; - std::map m_entries; + 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()`. diff --git a/src/core/request_id.cpp b/src/core/request_id.cpp new file mode 100644 index 0000000..cc962ab --- /dev/null +++ b/src/core/request_id.cpp @@ -0,0 +1,68 @@ +#include + +#include + +namespace lootlocker { + +namespace { + +// Process-wide, so two clients in one process cannot mint the same id (D20). +// +// Relaxed ordering is enough: the only requirement is that each call gets a distinct value, +// not that other threads observe any particular order. `fetch_add` is atomic regardless of +// the memory order, so this is a single uncontended instruction on the hot path. +std::atomic g_next_request_id{1}; + +} // namespace + +RequestId RequestId::Next() +{ + // A CAS loop rather than `fetch_add` plus a fix-up, so that "never 0" is an invariant of + // the loop rather than a special case bolted on afterwards. + // + // The `fetch_add` version was not actually racy: `fetch_add` hands out each value + // exactly once, so only one thread could ever observe 0 and take the next value. But + // that reasoning needs a paragraph to justify, and a loop that visibly skips 0 needs + // none. The cost is one compare-exchange on an uncontended atomic, the same order as the + // `fetch_add` it replaces. + std::uint64_t current = g_next_request_id.load(std::memory_order_relaxed); + for (;;) { + // Skip 0, which is the invalid id. Unreachable in practice - a uint64 at a million + // requests a second lasts longer than the hardware - but the loop makes the wrap + // safe by construction rather than by argument. + const std::uint64_t next = (current == 0) ? 1 : current + 1; + + if (g_next_request_id.compare_exchange_weak(current, next, std::memory_order_relaxed, + std::memory_order_relaxed)) { + return RequestId(current); + } + // `current` was reloaded by the failed exchange; loop and retry. + } +} + +std::string RequestId::ToString() const +{ + // Hand-rolled rather than std::to_string: this is called once per request for the + // header and once per log line, and std::to_string goes through the locale-aware + // formatting machinery for a value that is always plain decimal digits. + if (m_value == 0) { + return std::string("0"); + } + + char buffer[20]; // 2^64 - 1 is 20 digits + std::size_t length = 0; + std::uint64_t value = m_value; + while (value != 0) { + buffer[length++] = static_cast('0' + (value % 10)); + value /= 10; + } + + std::string out; + out.reserve(length); + while (length > 0) { + out.push_back(buffer[--length]); + } + return out; +} + +} // namespace lootlocker diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index 0514b09..7ff1e51 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -11,9 +11,12 @@ #include "executor.h" #include "test_harness.h" +#include +#include #include #include #include +#include #include using namespace lootlocker; @@ -74,7 +77,6 @@ PendingRequest Post(const std::string& url) request.method = "POST"; request.url = url; request.body = "{}"; - request.idempotent = false; // a write: never retried when the response is lost return request; } @@ -100,14 +102,14 @@ void TestOneUpdateDrainsSeveralCompletions() Fixture f; int delivered = 0; - std::vector ids; + 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); + CHECK(ids[0].IsValid() && ids[1].IsValid() && ids[2].IsValid()); // One Update starts all three, because max_in_flight is 50. CHECK(f.executor->Update()); @@ -116,8 +118,10 @@ void TestOneUpdateDrainsSeveralCompletions() // 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, "{}"); + const auto order = f.transport->Order(); + CHECK_EQ_INT(static_cast(order.size()), 3); + for (const auto transfer : order) { + f.transport->Complete(transfer, 200, "{}"); } CHECK(!f.executor->Update()); @@ -136,16 +140,16 @@ void TestUpdateReturnsFalseOnlyWhenEmpty() CHECK(!f.executor->Update()); bool delivered = false; - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [&delivered](const Completion&) { delivered = true; }); - CHECK(id != 0); + CHECK(id.IsValid()); // Queued, so there is work. CHECK(f.executor->Update()); CHECK(!delivered); - f.transport->Complete(id, 200, "{}"); + f.transport->Complete(f.transport->Order().back(), 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 @@ -213,14 +217,14 @@ void TestClientErrorDoesNotRetry() int delivered = 0; Completion last; - const std::uint64_t id = f.executor->Submit( + const RequestId 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\"}"); + f.transport->Complete(f.transport->Order().back(), 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()); @@ -238,7 +242,7 @@ void TestRetryAfterIsHonoured() { Fixture f; - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); @@ -247,7 +251,7 @@ void TestRetryAfterIsHonoured() response.status_code = 429; response.body = "{}"; response.headers.Set("Retry-After", "7"); - f.transport->Complete(id, response); + f.transport->Complete(f.transport->Order().back(), response); CHECK(f.executor->Update()); @@ -296,31 +300,36 @@ void TestRetriesStopAtTheBudget() CHECK_EQ_INT(last.attempts, 3); } -// --- R25: never retry a non-idempotent request whose response was lost ----------------- +// --- A lost response is retried, whatever the method (owner, 2026-11-20) --------------- +// +// R25 used to be closed here: a non-idempotent request whose response was lost was never +// retried, because a POST that timed out may have succeeded. The owner's call is that the +// other SDKs do not do this and we should not either, so R25 is now an accepted risk. These +// tests assert the new behaviour, and they exist so the change is visible rather than +// silent. -void TestTimedOutPostIsNotRetried() +void TestTimedOutPostIsRetried() { Fixture f; int delivered = 0; - Completion last; f.executor->Submit(Post("https://example.test/grant"), [&](const Completion& c) { ++delivered; - last = c; + (void)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. + // The response never arrives. It is retried like any other transport failure - which + // means a POST that actually succeeded may be sent twice. That is the accepted risk. f.clock.Advance(300 * 1000); - CHECK(!f.executor->Update()); + CHECK(f.executor->Update()); + CHECK_EQ_INT(delivered, 0); - 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); + f.clock.Advance(50); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); } void TestTimedOutGetIsRetried() @@ -336,7 +345,6 @@ void TestTimedOutGetIsRetried() 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); @@ -346,19 +354,17 @@ void TestTimedOutGetIsRetried() CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); } -void TestServerErrorOnPostIsStillRetried() +void TestServerErrorOnPostIsRetried() { Fixture f; int delivered = 0; - const std::uint64_t id = f.executor->Submit(Post("https://example.test/grant"), - [&](const Completion&) { ++delivered; }); + 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"); + f.transport->Complete(f.transport->Order().back(), 500, "boom"); CHECK(f.executor->Update()); CHECK_EQ_INT(delivered, 0); @@ -399,20 +405,20 @@ void TestFullQueueRejectsAndReportsOnNextUpdate() config.deny_when_backed_up = true; Fixture f(config); - const std::uint64_t first = + const RequestId first = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); - CHECK(first != 0); + CHECK(first.IsValid()); int rejected = 0; Completion rejection; - const std::uint64_t second = f.executor->Submit( + const RequestId 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); + CHECK(!second.IsValid()); // The handler is not called synchronously: callbacks fire from Update() (D5). CHECK_EQ_INT(rejected, 0); @@ -429,14 +435,14 @@ void TestBackedUpQueueWaitsWhenDenyIsOff() config.deny_when_backed_up = false; Fixture f(config); - const std::uint64_t first = + const RequestId first = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); - const std::uint64_t second = + const RequestId 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); + CHECK(first.IsValid()); + CHECK(second.IsValid()); } // --- The transport seam ---------------------------------------------------------------- @@ -522,7 +528,7 @@ void TestEachAttemptIsLoggedAndObfuscated() { Fixture f; - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); @@ -531,7 +537,7 @@ void TestEachAttemptIsLoggedAndObfuscated() response.status_code = 200; response.body = "{\"session_token\":\"abcdef1234567890\"}"; response.headers.Set("LL-Trace-Id", "trace-42"); - f.transport->Complete(id, response); + f.transport->Complete(f.transport->Order().back(), response); CHECK(!f.executor->Update()); @@ -554,7 +560,7 @@ void TestRetryAfterZeroRetriesImmediately() { Fixture f; - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); @@ -565,7 +571,7 @@ void TestRetryAfterZeroRetriesImmediately() // 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); + f.transport->Complete(f.transport->Order().back(), response); // No clock advance at all, and the retry is already due. CHECK(f.executor->Update()); @@ -576,7 +582,7 @@ void TestHugeRetryAfterIsClampedNotOverflowed() { Fixture f; - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); @@ -587,7 +593,7 @@ void TestHugeRetryAfterIsClampedNotOverflowed() // 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); + f.transport->Complete(f.transport->Order().back(), 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. @@ -607,11 +613,11 @@ void TestLargeBackoffFactorDoesNotOverflow() config.initial_backoff_ms = 1000000; Fixture f(config); - const std::uint64_t id = + const RequestId id = f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); CHECK(f.executor->Update()); - f.transport->Complete(id, 503, "unavailable"); + f.transport->Complete(f.transport->Order().back(), 503, "unavailable"); f.executor->Update(); // The first delay is already 1,000,000 ms, so a second is not enough. @@ -649,13 +655,13 @@ void TestInvalidConfigRejectsThroughUpdate() int delivered = 0; Completion last; - const std::uint64_t id = executor.Submit(Get("https://example.test/a"), + const RequestId id = executor.Submit(Get("https://example.test/a"), [&](const Completion& c) { ++delivered; last = c; }); - CHECK_EQ_INT(static_cast(id), 0); + CHECK(!id.IsValid()); CHECK_EQ_INT(delivered, 0); // Delivered on Update, like every other rejection. @@ -673,7 +679,7 @@ void TestRedirectIsAnErrorNotASuccess() int delivered = 0; Completion last; - const std::uint64_t id = f.executor->Submit( + const RequestId id = f.executor->Submit( Get("https://example.test/a"), [&](const Completion& c) { ++delivered; last = c; @@ -689,7 +695,7 @@ void TestRedirectIsAnErrorNotASuccess() response.status_code = 302; response.body = "moved"; response.headers.Set("Location", "https://elsewhere.test/"); - f.transport->Complete(id, response); + f.transport->Complete(f.transport->Order().back(), response); CHECK(!f.executor->Update()); CHECK_EQ_INT(delivered, 1); @@ -710,7 +716,7 @@ void TestNoContentIsStillASuccess() int delivered = 0; Completion last; - const std::uint64_t id = f.executor->Submit( + const RequestId id = f.executor->Submit( Get("https://example.test/a"), [&](const Completion& c) { ++delivered; last = c; @@ -720,7 +726,7 @@ void TestNoContentIsStillASuccess() // 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, ""); + f.transport->Complete(f.transport->Order().back(), 204, ""); CHECK(!f.executor->Update()); CHECK_EQ_INT(delivered, 1); @@ -728,6 +734,276 @@ void TestNoContentIsStillASuccess() CHECK_EQ_INT(last.status_code, 204); } +// --- RequestId (T11d) ------------------------------------------------------------------ + +void TestRequestIdIsSentAsTheHeader() +{ + Fixture f; + + const RequestId id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(id.IsValid()); + + CHECK(f.executor->Update()); + + // The id the caller got is the id that went on the wire, so a support ticket can be + // matched to a server log line (D25). + const auto order = f.transport->Order(); + CHECK_EQ_INT(static_cast(order.size()), 1); + const IHttpTransport::Request* sent = f.transport->FindRequest(order[0]); + CHECK(sent != nullptr); + if (sent != nullptr) { + CHECK(sent->headers.Has("LL-Request-Id")); + } +} + +void TestRequestIdHeaderMatchesTheReturnedId() +{ + Fixture f; + + const RequestId id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(f.executor->Update()); + + const auto order = f.transport->Order(); + const IHttpTransport::Request* sent = f.transport->FindRequest(order[0]); + CHECK(sent != nullptr); + if (sent != nullptr) { + std::string header; + CHECK(sent->headers.Get("LL-Request-Id", header)); + CHECK_EQ(header, id.ToString()); + } +} + +void TestRetryKeepsTheSameRequestId() +{ + Fixture f; + + const RequestId id = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(f.executor->Update()); + f.transport->Complete(f.transport->Order().back(), 500, "boom"); + f.executor->Update(); + f.clock.Advance(50); + CHECK(f.executor->Update()); + + // Both attempts carry the same id: it is the same logical request, and a server log + // should show one id across attempts rather than one per attempt. + const auto order = f.transport->Order(); + CHECK_EQ_INT(static_cast(order.size()), 2); + for (const auto transfer : order) { + const IHttpTransport::Request* sent = f.transport->FindRequest(transfer); + CHECK(sent != nullptr); + if (sent != nullptr) { + std::string header; + CHECK(sent->headers.Get("LL-Request-Id", header)); + CHECK_EQ(header, id.ToString()); + } + } +} + +void TestIdenticalRequestsAreBothSent() +{ + Fixture f; + + int first_delivered = 0; + int second_delivered = 0; + + // Two identical submissions are two requests, and both are sent. There is no + // deduplication or grouping (owner, 2026-11-19): the API is not guaranteed to be + // idempotent, so "add 5 gold" sent twice must yield 10, not 5. The SDK cannot tell that + // case apart from a harmless repeated read, so it never merges. + const RequestId first = f.executor->Submit( + Get("https://example.test/broadcasts"), [&](const Completion&) { ++first_delivered; }); + const RequestId second = f.executor->Submit( + Get("https://example.test/broadcasts"), [&](const Completion&) { ++second_delivered; }); + + CHECK(first.IsValid()); + CHECK(second.IsValid()); + CHECK(first != second); + + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); + + const auto order = f.transport->Order(); + f.transport->Complete(order[0], 200, "{}"); + f.transport->Complete(order[1], 200, "{}"); + CHECK(!f.executor->Update()); + + // Each caller was answered exactly once, by its own request. + CHECK_EQ_INT(first_delivered, 1); + CHECK_EQ_INT(second_delivered, 1); +} + +void TestIdenticalWritesAreBothSent() +{ + Fixture f; + + // The case that made us drop deduplication entirely: two identical "add 5 gold" calls + // must both reach the server, because merging them would grant 5 instead of 10. + const RequestId first = + f.executor->Submit(Post("https://example.test/grant"), [](const Completion&) {}); + const RequestId second = + f.executor->Submit(Post("https://example.test/grant"), [](const Completion&) {}); + + CHECK(first != second); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +void TestRequestIdToString() +{ + CHECK_EQ(RequestId().ToString(), std::string("0")); + CHECK_EQ(RequestId(1).ToString(), std::string("1")); + CHECK_EQ(RequestId(42).ToString(), std::string("42")); + CHECK_EQ(RequestId(1000000).ToString(), std::string("1000000")); + + // The largest value, which is where a hand-rolled decimal conversion is most likely to + // be wrong. + CHECK_EQ(RequestId(18446744073709551615ULL).ToString(), + std::string("18446744073709551615")); + + CHECK(!RequestId().IsValid()); + CHECK(RequestId(1).IsValid()); +} + +void TestFailureCarriesTheRequestId() +{ + // No retries, so the first failure is delivered rather than requeued. + QueueConfig config = DefaultQueue(); + config.max_retries = 0; + Fixture f(config); + + Completion last; + const RequestId id = f.executor->Submit( + Get("https://example.test/a"), [&](const Completion& c) { last = c; }); + + CHECK(f.executor->Update()); + f.transport->Complete(f.transport->Order().back(), 500, "boom"); + CHECK(!f.executor->Update()); + + // A support ticket is usually raised from a failure, not a success, so the id has to be + // on the error as well as in the log. `Error::request_id` documents itself as the id + // sent in `LL-Request-Id`. + CHECK(!last.error.Ok()); + CHECK_EQ(last.error.request_id, id.ToString()); +} + +void TestTimeoutCarriesTheRequestId() +{ + QueueConfig config = DefaultQueue(); + config.max_retries = 0; + Fixture f(config); + + Completion last; + const RequestId id = f.executor->Submit( + Get("https://example.test/a"), [&](const Completion& c) { last = c; }); + + CHECK(f.executor->Update()); + + // Let it time out. With no retries the timeout is delivered immediately. + f.clock.Advance(300 * 1000); + CHECK(!f.executor->Update()); + + CHECK(!last.error.Ok()); + CHECK(last.error.code == ErrorCode::Transport); + CHECK_EQ(last.error.request_id, id.ToString()); +} + +void TestRequestIdsAreUniqueAcrossClients() +{ + // Two clients in one process are legal (D20). A per-client counter would let both mint + // the same id, so a support ticket quoting "request 5" would be ambiguous. + Fixture a; + Fixture b; + const RequestId first = + a.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + const RequestId second = + b.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + + CHECK(first.IsValid()); + CHECK(second.IsValid()); + CHECK(first != second); +} + +void TestRequestIdNextIsMonotonic() +{ + const RequestId first = RequestId::Next(); + const RequestId second = RequestId::Next(); + const RequestId third = RequestId::Next(); + + CHECK(first.IsValid()); + CHECK(first < second); + CHECK(second < third); + + // Never invalid, even at the wrap point: 0 is skipped. + CHECK(RequestId::Next().IsValid()); +} + +void TestRequestIdNextIsUniqueUnderConcurrency() +{ + // The claim under test: every call gets a distinct value, including across threads. A + // duplicate here would mean two requests sharing a correlation id, which is exactly what + // the id exists to prevent. + // + // The counts are deliberately large and the threads start together. A smaller run does + // not reliably expose a non-atomic counter - verified by sabotage, where a plain + // read-then-write passed at 4x2000 and only failed once the contention was real. + constexpr int kThreads = 8; + constexpr int kPerThread = 20000; + + std::vector> minted(kThreads); + std::vector threads; + threads.reserve(kThreads); + + // A barrier, so the threads contend from the same instant rather than starting in + // sequence and never overlapping. + std::atomic ready{0}; + std::atomic go{false}; + + for (int t = 0; t < kThreads; ++t) { + threads.emplace_back([&minted, &ready, &go, t]() { + // Pre-sized, and written by index rather than push_back: an allocating + // push_back spends most of its time in the allocator, which shrinks the window + // where two threads are inside the counter at once. Verified by sabotage - with + // push_back a non-atomic counter passed, and only this version exposes it. + minted[t].resize(kPerThread); + ready.fetch_add(1); + while (!go.load()) { + // spin until every thread is in place + } + for (int i = 0; i < kPerThread; ++i) { + minted[t][static_cast(i)] = RequestId::Next().Value(); + } + }); + } + + while (ready.load() < kThreads) { + // wait for all threads to be ready + } + go.store(true); + + for (std::thread& thread : threads) { + thread.join(); + } + + std::vector all; + all.reserve(static_cast(kThreads) * kPerThread); + for (const auto& per_thread : minted) { + all.insert(all.end(), per_thread.begin(), per_thread.end()); + } + + CHECK_EQ_INT(static_cast(all.size()), + static_cast(kThreads) * kPerThread); + + std::sort(all.begin(), all.end()); + const auto duplicate = std::adjacent_find(all.begin(), all.end()); + CHECK(duplicate == all.end()); + + // And none of them is the invalid id. + CHECK(all.front() != 0); +} + void TestAbandonCancelsInFlightWithoutCallingBack() { Fixture f; @@ -759,9 +1035,9 @@ int main() TestClientErrorDoesNotRetry(); TestRetryAfterIsHonoured(); TestRetriesStopAtTheBudget(); - TestTimedOutPostIsNotRetried(); + TestTimedOutPostIsRetried(); TestTimedOutGetIsRetried(); - TestServerErrorOnPostIsStillRetried(); + TestServerErrorOnPostIsRetried(); TestConcurrencyCapIsRespected(); TestFullQueueRejectsAndReportsOnNextUpdate(); TestBackedUpQueueWaitsWhenDenyIsOff(); @@ -775,6 +1051,17 @@ int main() TestInvalidConfigRejectsThroughUpdate(); TestRedirectIsAnErrorNotASuccess(); TestNoContentIsStillASuccess(); + TestRequestIdIsSentAsTheHeader(); + TestRequestIdHeaderMatchesTheReturnedId(); + TestRetryKeepsTheSameRequestId(); + TestIdenticalRequestsAreBothSent(); + TestIdenticalWritesAreBothSent(); + TestRequestIdToString(); + TestFailureCarriesTheRequestId(); + TestTimeoutCarriesTheRequestId(); + TestRequestIdsAreUniqueAcrossClients(); + TestRequestIdNextIsMonotonic(); + TestRequestIdNextIsUniqueUnderConcurrency(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report();