From e6f81a1e9c1cb793b55316b1f6b1a7d2cc895b4c Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Thu, 19 Nov 2026 12:29:35 +0100 Subject: [PATCH 1/4] Add RequestId, sent as LL-Request-Id, with deduplication Every async call now returns a RequestId instead of void (D25). It is a value type wrapping a uint64, not a string, because a string id would allocate on every call and this is a game SDK's hot path. The id goes on the wire as LL-Request-Id so a support ticket can be matched to a server log line. It is stamped at SEND time, not on the stored request, for two reasons: the stored request is what deduplication compares, so stamping it would make every request unique and dedupe would never fire; and a retry re-sends the same logical request, so it carries the same id, which is what makes a server log show one id across attempts rather than one per attempt. Deduplication, with the rule I proposed and the owner approved: - Only an idempotent request is ever merged. Merging two writes would silently drop one, which is the same class of bug as retrying a lost POST (R25). - "Identical" means same method, same URL, same headers in the same order, and same body byte for byte. Headers are compared as an ordered list rather than a set, because order and case are part of what goes on the wire. - The existing id is returned, which is how the caller can tell it happened, and every handler on the entry is called with the same completion. Two bugs found by the tests while writing this: - Stamping LL-Request-Id on the stored request made dedupe impossible, because no incoming request could ever match a stamped one. Moved to send time. - Three existing tests submitted identical GETs and asserted three separate requests. That is now correctly one request, so those tests use distinct URLs - they were measuring the concurrency cap, not dedupe. Verified by sabotage: disabling the dedupe lookup fails five assertions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CMakeLists.txt | 1 + include/lootlocker/request_id.h | 45 ++++++ src/core/executor.cpp | 126 ++++++++++++---- src/core/executor.h | 39 +++-- src/core/request_id.cpp | 30 ++++ tests/test_executor.cpp | 259 +++++++++++++++++++++++++++----- 6 files changed, 426 insertions(+), 74 deletions(-) create mode 100644 include/lootlocker/request_id.h create mode 100644 src/core/request_id.cpp 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/include/lootlocker/request_id.h b/include/lootlocker/request_id.h new file mode 100644 index 0000000..d1ff154 --- /dev/null +++ b/include/lootlocker/request_id.h @@ -0,0 +1,45 @@ +#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. + +#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) {} + + 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, so an id can be a map key or sorted. Ids are assigned in submission order, + // so this is also submission order. + 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..e7e1b28 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -178,7 +178,47 @@ void Executor::ParseRetryAfter(const std::string& value, Error& error) error.retry_after_present = true; } -std::uint64_t Executor::Submit(PendingRequest request, CompletionHandler on_done) +bool Executor::IsSameRequest(const PendingRequest& a, const PendingRequest& b) +{ + // Only an idempotent request is ever merged. Merging two writes would silently drop + // one, which is the same class of bug as retrying a lost POST (R25). + if (!a.idempotent || !b.idempotent) { + return false; + } + + if (a.method != b.method || a.url != b.url || a.body != b.body) { + return false; + } + + // Headers compared as an ordered list, not as a set: order and case are part of what + // goes on the wire, and two requests that differ in either are not the same request. + const std::vector& left = a.headers.Entries(); + const std::vector& right = b.headers.Entries(); + if (left.size() != right.size()) { + return false; + } + for (std::size_t i = 0; i < left.size(); ++i) { + if (left[i].name != right[i].name || left[i].value != right[i].value) { + return false; + } + } + return true; +} + +Executor::Entry* Executor::FindDuplicate(const PendingRequest& request) +{ + if (!request.idempotent) { + return nullptr; + } + for (auto& pair : m_entries) { + if (IsSameRequest(pair.second.request, request)) { + return &pair.second; + } + } + return nullptr; +} + +RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) { const std::int64_t now = m_clock.NowMs(); @@ -193,7 +233,17 @@ 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(); + } + + // A submission identical to one already queued or in flight is merged onto it, so the + // server sees one request and both callers get the same completion. The existing id is + // returned, which is how the caller can tell that it happened. + if (Entry* existing = FindDuplicate(request)) { + if (on_done) { + existing->on_done.push_back(std::move(on_done)); + } + return existing->id; } // The queue is full. `deny_when_backed_up` decides whether that is an error or a wait: @@ -208,16 +258,18 @@ 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(m_next_id++); entry.request = std::move(request); - entry.on_done = std::move(on_done); + if (on_done) { + entry.on_done.push_back(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 +314,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 +326,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) { @@ -328,13 +381,17 @@ void Executor::FinishOrRetry(std::uint64_t id, Completion completion, std::int64 return; } - // Delivered. The entry is erased before the handler runs, so a handler that submits a + // Delivered. The entry is erased before the handlers run, so a handler that submits a // new request cannot invalidate the map under us. - CompletionHandler handler = std::move(entry.on_done); + // + // Every handler on the entry is called with the same completion. There is more than one + // only when a submission was deduplicated onto this entry, and each of those callers + // asked for the same thing, so each gets the same answer. + for (CompletionHandler& handler : entry.on_done) { + out_handlers.push_back(std::move(handler)); + out_completions.push_back(completion); + } m_entries.erase(it); - - out_handlers.push_back(std::move(handler)); - out_completions.push_back(std::move(completion)); } bool Executor::Update() @@ -379,12 +436,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 +485,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 +512,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 +522,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 +540,16 @@ 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. Two reasons: the + // stored request is what deduplication compares, so stamping it would make + // every request unique and dedupe would never fire; and a retry re-sends the + // same logical request, so it carries the same id, which is what makes a + // server log show one id across attempts. + request.headers.Set("LL-Request-Id", entry.id.ToString()); + ++entry.attempts; entry.started_at_ms = now; @@ -522,17 +589,20 @@ 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); + + // Every handler on the entry, because a deduplicated submission has more than one + // and each of those callers is waiting. + for (CompletionHandler& handler : entry.on_done) { + handlers.push_back(std::move(handler)); + completions.push_back(completion); } } m_entries.clear(); diff --git a/src/core/executor.h b/src/core/executor.h index e29e550..5d968cb 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -14,6 +14,7 @@ #include #include #include +#include #include #include "clock.h" @@ -85,9 +86,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`. + // + // **Deduplication (D25).** A submission that is identical to one already queued or in + // flight is merged onto it: the new handler is appended to the existing entry and the + // existing id is returned, so the caller can see that it happened. "Identical" means + // same method, same URL, same headers and same body, byte for byte - and only for an + // idempotent request. Merging two writes would silently drop one, which is the same + // class of bug as retrying a lost POST (R25). + 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,9 +127,13 @@ class Executor { private: struct Entry { - std::uint64_t id = 0; + RequestId id; PendingRequest request; - CompletionHandler on_done; + + // Every handler waiting on this request. More than one only when a submission was + // deduplicated onto this entry, in which case all of them are called with the same + // completion. + std::vector on_done; // Attempts started so far, 1-based once the first one begins. int attempts = 0; @@ -133,10 +146,18 @@ class Executor { bool in_flight = false; }; + // Whether two requests are the same for deduplication. Method, URL, headers and body + // must match exactly, and the request must be idempotent. + static bool IsSameRequest(const PendingRequest& a, const PendingRequest& b); + + // The entry a submission can be merged onto, or nullptr. Only an idempotent request is + // ever merged, and only onto an entry that has not yet been delivered. + Entry* FindDuplicate(const PendingRequest& request); + // 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 +186,8 @@ class Executor { Clock& m_clock; std::weak_ptr m_logger; - std::uint64_t m_next_id = 1; - std::map m_entries; + 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()`. diff --git a/src/core/request_id.cpp b/src/core/request_id.cpp new file mode 100644 index 0000000..0dcdee5 --- /dev/null +++ b/src/core/request_id.cpp @@ -0,0 +1,30 @@ +#include + +namespace lootlocker { + +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..8b42c73 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -100,14 +100,16 @@ 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"), + // Distinct URLs, because three identical GETs would now dedupe onto one entry - + // which is correct behaviour, and would make this test measure the wrong thing. + ids.push_back(f.executor->Submit(Get("https://example.test/a" + std::to_string(i)), [&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()); @@ -351,14 +355,14 @@ void TestServerErrorOnPostIsStillRetried() Fixture f; int delivered = 0; - const std::uint64_t id = f.executor->Submit(Post("https://example.test/grant"), + const RequestId 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"); + f.transport->Complete(f.transport->Order().back(), 500, "boom"); CHECK(f.executor->Update()); CHECK_EQ_INT(delivered, 0); @@ -376,7 +380,10 @@ void TestConcurrencyCapIsRespected() Fixture f(config); for (int i = 0; i < 5; ++i) { - f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + // Distinct URLs: five identical GETs would dedupe onto one entry, which is correct + // behaviour but not what this test is measuring. + f.executor->Submit(Get("https://example.test/a" + std::to_string(i)), + [](const Completion&) {}); } CHECK(f.executor->Update()); @@ -399,20 +406,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 +436,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 +529,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 +538,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 +561,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 +572,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 +583,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 +594,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 +614,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 +656,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 +680,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 +696,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 +717,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 +727,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 +735,176 @@ 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 TestIdenticalConcurrentRequestsDedupe() +{ + Fixture f; + + int first_delivered = 0; + int second_delivered = 0; + Completion first_completion; + Completion second_completion; + + const RequestId first = f.executor->Submit( + Get("https://example.test/broadcasts"), [&](const Completion& c) { + ++first_delivered; + first_completion = c; + }); + const RequestId second = f.executor->Submit( + Get("https://example.test/broadcasts"), [&](const Completion& c) { + ++second_delivered; + second_completion = c; + }); + + // Merged onto the first: the same id comes back, which is how the caller can tell. + CHECK(first.IsValid()); + CHECK(first == second); + + CHECK(f.executor->Update()); + + // One request on the wire, not two. + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); + + f.transport->Complete(f.transport->Order().back(), 200, "{\"broadcasts\":[]}"); + CHECK(!f.executor->Update()); + + // Both callers were answered, with the same completion. + CHECK_EQ_INT(first_delivered, 1); + CHECK_EQ_INT(second_delivered, 1); + CHECK_EQ(first_completion.body, second_completion.body); + CHECK_EQ(first_completion.body, std::string("{\"broadcasts\":[]}")); +} + +void TestDifferentRequestsDoNotDedupe() +{ + Fixture f; + + const RequestId first = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + const RequestId second = + f.executor->Submit(Get("https://example.test/b"), [](const Completion&) {}); + + CHECK(first != second); + CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); +} + +void TestNonIdempotentRequestsNeverDedupe() +{ + Fixture f; + + // Two identical writes. Merging them would silently drop one, which is the same class + // of bug as retrying a lost POST (R25). + 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 TestDedupeDoesNotMergeOntoADeliveredRequest() +{ + Fixture f; + + const RequestId first = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(f.executor->Update()); + f.transport->Complete(f.transport->Order().back(), 200, "{}"); + CHECK(!f.executor->Update()); + + // The first is gone, so this is a new request rather than a merge onto a finished one. + const RequestId second = + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); + CHECK(second.IsValid()); + CHECK(first != second); +} + +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 TestAbandonCancelsInFlightWithoutCallingBack() { Fixture f; @@ -775,6 +952,14 @@ int main() TestInvalidConfigRejectsThroughUpdate(); TestRedirectIsAnErrorNotASuccess(); TestNoContentIsStillASuccess(); + TestRequestIdIsSentAsTheHeader(); + TestRequestIdHeaderMatchesTheReturnedId(); + TestRetryKeepsTheSameRequestId(); + TestIdenticalConcurrentRequestsDedupe(); + TestDifferentRequestsDoNotDedupe(); + TestNonIdempotentRequestsNeverDedupe(); + TestDedupeDoesNotMergeOntoADeliveredRequest(); + TestRequestIdToString(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report(); From 5c1327ad541fa6b41c4be4342c63a1a6f1582876 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Thu, 19 Nov 2026 12:53:22 +0100 Subject: [PATCH 2/4] Remove request deduplication entirely The owner built this in the Unity SDK and then turned it off, and the reason is decisive: the API is not guaranteed to be idempotent. "Add 5 gold" performed five times must yield 25, not 5. Merging those five into one would silently grant a fifth of what the caller asked for, and the SDK cannot tell that case apart from a harmless repeated read. My earlier rule - merge only when the caller says the request is idempotent - was worse than no rule, because it moved the decision onto a flag the caller has to get right, and a wrong flag loses a grant silently. There is no version of this the SDK can decide correctly, so it does not decide at all. Every submission is now its own request, always. RequestId stays: it is still the correlation id for LL-Request-Id and the handle Cancel will take. Only the merging goes. Two tests replace the four dedupe tests, and they assert the opposite of what the old ones did: two identical GETs are both sent, and two identical writes are both sent. Verified by sabotage - reintroducing a merge fails four assertions across two tests. The distinct-URL workarounds I added to two existing tests are reverted, since identical URLs are no longer a problem. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/core/executor.cpp | 50 ------------------------ src/core/executor.h | 23 +++++------ tests/test_executor.cpp | 86 ++++++++++------------------------------- 3 files changed, 30 insertions(+), 129 deletions(-) diff --git a/src/core/executor.cpp b/src/core/executor.cpp index e7e1b28..8ac8a9f 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -178,46 +178,6 @@ void Executor::ParseRetryAfter(const std::string& value, Error& error) error.retry_after_present = true; } -bool Executor::IsSameRequest(const PendingRequest& a, const PendingRequest& b) -{ - // Only an idempotent request is ever merged. Merging two writes would silently drop - // one, which is the same class of bug as retrying a lost POST (R25). - if (!a.idempotent || !b.idempotent) { - return false; - } - - if (a.method != b.method || a.url != b.url || a.body != b.body) { - return false; - } - - // Headers compared as an ordered list, not as a set: order and case are part of what - // goes on the wire, and two requests that differ in either are not the same request. - const std::vector& left = a.headers.Entries(); - const std::vector& right = b.headers.Entries(); - if (left.size() != right.size()) { - return false; - } - for (std::size_t i = 0; i < left.size(); ++i) { - if (left[i].name != right[i].name || left[i].value != right[i].value) { - return false; - } - } - return true; -} - -Executor::Entry* Executor::FindDuplicate(const PendingRequest& request) -{ - if (!request.idempotent) { - return nullptr; - } - for (auto& pair : m_entries) { - if (IsSameRequest(pair.second.request, request)) { - return &pair.second; - } - } - return nullptr; -} - RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) { const std::int64_t now = m_clock.NowMs(); @@ -236,16 +196,6 @@ RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) return RequestId(); } - // A submission identical to one already queued or in flight is merged onto it, so the - // server sees one request and both callers get the same completion. The existing id is - // returned, which is how the caller can tell that it happened. - if (Entry* existing = FindDuplicate(request)) { - if (on_done) { - existing->on_done.push_back(std::move(on_done)); - } - return existing->id; - } - // 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. diff --git a/src/core/executor.h b/src/core/executor.h index 5d968cb..e84fe38 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -46,6 +46,9 @@ struct PendingRequest { // 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. + // + // This guards retries only. It does NOT enable any form of request merging: every + // submission is its own request, always (owner, 2026-11-19). bool idempotent = true; }; @@ -90,12 +93,12 @@ class Executor { // 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`. // - // **Deduplication (D25).** A submission that is identical to one already queued or in - // flight is merged onto it: the new handler is appended to the existing entry and the - // existing id is returned, so the caller can see that it happened. "Identical" means - // same method, same URL, same headers and same body, byte for byte - and only for an - // idempotent request. Merging two writes would silently drop one, which is the same - // class of bug as retrying a lost POST (R25). + // **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 @@ -146,14 +149,6 @@ class Executor { bool in_flight = false; }; - // Whether two requests are the same for deduplication. Method, URL, headers and body - // must match exactly, and the request must be idempotent. - static bool IsSameRequest(const PendingRequest& a, const PendingRequest& b); - - // The entry a submission can be merged onto, or nullptr. Only an idempotent request is - // ever merged, and only onto an entry that has not yet been delivered. - Entry* FindDuplicate(const PendingRequest& request); - // Decide whether a finished attempt is retried or delivered, and either requeue it or // 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. diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index 8b42c73..6d9ecc9 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -102,9 +102,7 @@ void TestOneUpdateDrainsSeveralCompletions() int delivered = 0; std::vector ids; for (int i = 0; i < 3; ++i) { - // Distinct URLs, because three identical GETs would now dedupe onto one entry - - // which is correct behaviour, and would make this test measure the wrong thing. - ids.push_back(f.executor->Submit(Get("https://example.test/a" + std::to_string(i)), + ids.push_back(f.executor->Submit(Get("https://example.test/a"), [&delivered](const Completion&) { ++delivered; })); } @@ -380,10 +378,7 @@ void TestConcurrencyCapIsRespected() Fixture f(config); for (int i = 0; i < 5; ++i) { - // Distinct URLs: five identical GETs would dedupe onto one entry, which is correct - // behaviour but not what this test is measuring. - f.executor->Submit(Get("https://example.test/a" + std::to_string(i)), - [](const Completion&) {}); + f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); } CHECK(f.executor->Update()); @@ -803,65 +798,45 @@ void TestRetryKeepsTheSameRequestId() } } -void TestIdenticalConcurrentRequestsDedupe() +void TestIdenticalRequestsAreBothSent() { Fixture f; int first_delivered = 0; int second_delivered = 0; - Completion first_completion; - Completion second_completion; + // 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& c) { - ++first_delivered; - first_completion = c; - }); + Get("https://example.test/broadcasts"), [&](const Completion&) { ++first_delivered; }); const RequestId second = f.executor->Submit( - Get("https://example.test/broadcasts"), [&](const Completion& c) { - ++second_delivered; - second_completion = c; - }); + Get("https://example.test/broadcasts"), [&](const Completion&) { ++second_delivered; }); - // Merged onto the first: the same id comes back, which is how the caller can tell. CHECK(first.IsValid()); - CHECK(first == second); + CHECK(second.IsValid()); + CHECK(first != second); CHECK(f.executor->Update()); + CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); - // One request on the wire, not two. - CHECK_EQ_INT(static_cast(f.transport->StartCount()), 1); - - f.transport->Complete(f.transport->Order().back(), 200, "{\"broadcasts\":[]}"); + const auto order = f.transport->Order(); + f.transport->Complete(order[0], 200, "{}"); + f.transport->Complete(order[1], 200, "{}"); CHECK(!f.executor->Update()); - // Both callers were answered, with the same completion. + // Each caller was answered exactly once, by its own request. CHECK_EQ_INT(first_delivered, 1); CHECK_EQ_INT(second_delivered, 1); - CHECK_EQ(first_completion.body, second_completion.body); - CHECK_EQ(first_completion.body, std::string("{\"broadcasts\":[]}")); -} - -void TestDifferentRequestsDoNotDedupe() -{ - Fixture f; - - const RequestId first = - f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); - const RequestId second = - f.executor->Submit(Get("https://example.test/b"), [](const Completion&) {}); - - CHECK(first != second); - CHECK(f.executor->Update()); - CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); } -void TestNonIdempotentRequestsNeverDedupe() +void TestIdenticalWritesAreBothSent() { Fixture f; - // Two identical writes. Merging them would silently drop one, which is the same class - // of bug as retrying a lost POST (R25). + // 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 = @@ -872,23 +847,6 @@ void TestNonIdempotentRequestsNeverDedupe() CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); } -void TestDedupeDoesNotMergeOntoADeliveredRequest() -{ - Fixture f; - - const RequestId first = - f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); - CHECK(f.executor->Update()); - f.transport->Complete(f.transport->Order().back(), 200, "{}"); - CHECK(!f.executor->Update()); - - // The first is gone, so this is a new request rather than a merge onto a finished one. - const RequestId second = - f.executor->Submit(Get("https://example.test/a"), [](const Completion&) {}); - CHECK(second.IsValid()); - CHECK(first != second); -} - void TestRequestIdToString() { CHECK_EQ(RequestId().ToString(), std::string("0")); @@ -955,10 +913,8 @@ int main() TestRequestIdIsSentAsTheHeader(); TestRequestIdHeaderMatchesTheReturnedId(); TestRetryKeepsTheSameRequestId(); - TestIdenticalConcurrentRequestsDedupe(); - TestDifferentRequestsDoNotDedupe(); - TestNonIdempotentRequestsNeverDedupe(); - TestDedupeDoesNotMergeOntoADeliveredRequest(); + TestIdenticalRequestsAreBothSent(); + TestIdenticalWritesAreBothSent(); TestRequestIdToString(); TestAbandonCancelsInFlightWithoutCallingBack(); From 69bcb61c895c0f70cd7580194c24c79968c0b2c0 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Fri, 20 Nov 2026 11:55:09 +0100 Subject: [PATCH 3/4] Drop the idempotent flag, and put the request id on failures Four review comments, all acted on. Owner, on PendingRequest::idempotent: "The other SDKs don't have this. We should be ok skipping it." Dropped, along with the R25 guard it fed. A lost response is now retried whatever the method, which means a POST that actually succeeded may be sent twice. That is a deliberate reversal of R25, so it is recorded as an ACCEPTED RISK in the spec rather than quietly deleted - the flag moved a correctness decision onto the caller, and a caller who forgot it got a request that silently never retried. Owner, on the id counter: it should live on RequestId as a static atomic with wrap handling, not on the executor. Done. It is process-wide rather than per-client, because two clients in one process are legal (D20) and a per-client counter would let both mint id 5, making a support ticket quoting "request 5" ambiguous. 0 is skipped so a wrap cannot produce an invalid id. Copilot, on Completion::error.request_id: it was never populated, so a caller holding a failed result had no support id even though Error documents the field as the id sent in LL-Request-Id. Set in FinishOrRetry and in FailAll. A support ticket is usually raised from a failure, not a success, so leaving it empty on failure defeated the purpose. Verified by sabotage: removing it fails both new tests. Copilot, on the dedupe scan being quadratic: moot, dedupe is gone. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- include/lootlocker/request_id.h | 22 +++++- src/core/executor.cpp | 33 +++++---- src/core/executor.h | 12 ---- src/core/request_id.cpp | 27 ++++++++ tests/test_executor.cpp | 118 ++++++++++++++++++++++++++------ 5 files changed, 164 insertions(+), 48 deletions(-) diff --git a/include/lootlocker/request_id.h b/include/lootlocker/request_id.h index d1ff154..fff9a1d 100644 --- a/include/lootlocker/request_id.h +++ b/include/lootlocker/request_id.h @@ -9,6 +9,11 @@ // // 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 @@ -22,6 +27,15 @@ class RequestId { 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. @@ -34,8 +48,12 @@ class RequestId { 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, so an id can be a map key or sorted. Ids are assigned in submission order, - // so this is also submission order. + // 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: diff --git a/src/core/executor.cpp b/src/core/executor.cpp index 8ac8a9f..235e918 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -212,7 +212,7 @@ RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) } Entry entry; - entry.id = RequestId(m_next_id++); + entry.id = RequestId::Next(); entry.request = std::move(request); if (on_done) { entry.on_done.push_back(std::move(on_done)); @@ -314,17 +314,27 @@ void Executor::FinishOrRetry(RequestId id, Completion completion, std::int64_t n 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); @@ -333,10 +343,6 @@ void Executor::FinishOrRetry(RequestId id, Completion completion, std::int64_t n // Delivered. The entry is erased before the handlers run, so a handler that submits a // new request cannot invalidate the map under us. - // - // Every handler on the entry is called with the same completion. There is more than one - // only when a submission was deduplicated onto this entry, and each of those callers - // asked for the same thing, so each gets the same answer. for (CompletionHandler& handler : entry.on_done) { out_handlers.push_back(std::move(handler)); out_completions.push_back(completion); @@ -547,9 +553,8 @@ void Executor::FailAll(const std::string& reason) // 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(); - // Every handler on the entry, because a deduplicated submission has more than one - // and each of those callers is waiting. for (CompletionHandler& handler : entry.on_done) { handlers.push_back(std::move(handler)); completions.push_back(completion); diff --git a/src/core/executor.h b/src/core/executor.h index e84fe38..b19b069 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -39,17 +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. - // - // This guards retries only. It does NOT enable any form of request merging: every - // submission is its own request, always (owner, 2026-11-19). - bool idempotent = true; }; // The outcome of one request, delivered exactly once. @@ -181,7 +170,6 @@ class Executor { 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 diff --git a/src/core/request_id.cpp b/src/core/request_id.cpp index 0dcdee5..2a1c0d9 100644 --- a/src/core/request_id.cpp +++ b/src/core/request_id.cpp @@ -1,7 +1,34 @@ #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() +{ + std::uint64_t value = g_next_request_id.fetch_add(1, std::memory_order_relaxed); + + // Skip 0, which is the invalid id. Unreachable in practice - a uint64 at a million + // requests a second lasts longer than the hardware - but one comparison removes the + // edge case entirely rather than leaving a wrap that would silently produce an invalid + // id. + if (value == 0) { + value = g_next_request_id.fetch_add(1, std::memory_order_relaxed); + } + return RequestId(value); +} + std::string RequestId::ToString() const { // Hand-rolled rather than std::to_string: this is called once per request for the diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index 6d9ecc9..8de59e7 100644 --- a/tests/test_executor.cpp +++ b/tests/test_executor.cpp @@ -74,7 +74,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; } @@ -298,31 +297,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() @@ -338,7 +342,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); @@ -348,18 +351,16 @@ void TestTimedOutGetIsRetried() CHECK_EQ_INT(static_cast(f.transport->StartCount()), 2); } -void TestServerErrorOnPostIsStillRetried() +void TestServerErrorOnPostIsRetried() { Fixture f; int delivered = 0; - const RequestId 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(f.transport->Order().back(), 500, "boom"); CHECK(f.executor->Update()); CHECK_EQ_INT(delivered, 0); @@ -863,6 +864,79 @@ void TestRequestIdToString() 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 TestAbandonCancelsInFlightWithoutCallingBack() { Fixture f; @@ -894,9 +968,9 @@ int main() TestClientErrorDoesNotRetry(); TestRetryAfterIsHonoured(); TestRetriesStopAtTheBudget(); - TestTimedOutPostIsNotRetried(); + TestTimedOutPostIsRetried(); TestTimedOutGetIsRetried(); - TestServerErrorOnPostIsStillRetried(); + TestServerErrorOnPostIsRetried(); TestConcurrencyCapIsRespected(); TestFullQueueRejectsAndReportsOnNextUpdate(); TestBackedUpQueueWaitsWhenDenyIsOff(); @@ -916,6 +990,10 @@ int main() TestIdenticalRequestsAreBothSent(); TestIdenticalWritesAreBothSent(); TestRequestIdToString(); + TestFailureCarriesTheRequestId(); + TestTimeoutCarriesTheRequestId(); + TestRequestIdsAreUniqueAcrossClients(); + TestRequestIdNextIsMonotonic(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report(); From 4dd8226251bc20fb6d6fbdc8e57d235a2c335baf Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Fri, 20 Nov 2026 14:06:40 +0100 Subject: [PATCH 4/4] Fix four review findings, and make the id counter's invariant local - The README still documented the removed idempotent flag and claimed a lost response is never retried. It now states the accepted risk and the no-dedupe rule. The PR description was stale in the same way and is updated separately. - The LL-Request-Id comment still justified send-time stamping by deduplication, which no longer exists. It now gives the only reason that is still true: a retry re-sends the same logical request with the same id. - Entry::on_done is a single handler again, not a vector. Requests are never grouped, so an entry has exactly one caller; the vector added an allocation per submission and implied an invariant that no longer exists. - RequestId::Next is a CAS loop that skips 0, rather than fetch_add plus a fix-up. On that last one: Copilot's claim that the fetch_add version was racy is wrong. fetch_add hands out each value exactly once, so only one thread could ever observe 0 and take the next value - two threads cannot both return 1. I changed it anyway, because the CAS loop makes "never 0" an invariant of the loop rather than a special case that needs a paragraph to justify. The concurrency test needed two attempts to be worth anything. At 4x2000 with push_back it passed against a deliberately non-atomic counter, because the allocator dominated and the race window was too small. It is now 8x20000, threads start on a barrier, and the vectors are pre-sized so the increment is the hot path - which does catch it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 14 ++++++--- src/core/executor.cpp | 26 ++++++---------- src/core/executor.h | 9 +++--- src/core/request_id.cpp | 29 ++++++++++++------ tests/test_executor.cpp | 68 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 111 insertions(+), 35 deletions(-) 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/src/core/executor.cpp b/src/core/executor.cpp index 235e918..b9f6657 100644 --- a/src/core/executor.cpp +++ b/src/core/executor.cpp @@ -214,9 +214,7 @@ RequestId Executor::Submit(PendingRequest request, CompletionHandler on_done) Entry entry; entry.id = RequestId::Next(); entry.request = std::move(request); - if (on_done) { - entry.on_done.push_back(std::move(on_done)); - } + entry.on_done = std::move(on_done); entry.ready_at_ms = now; const RequestId id = entry.id; @@ -341,12 +339,10 @@ void Executor::FinishOrRetry(RequestId id, Completion completion, std::int64_t n return; } - // Delivered. The entry is erased before the handlers run, so a handler that submits a + // Delivered. The entry is erased before the handler runs, so a handler that submits a // new request cannot invalidate the map under us. - for (CompletionHandler& handler : entry.on_done) { - out_handlers.push_back(std::move(handler)); - out_completions.push_back(completion); - } + out_handlers.push_back(std::move(entry.on_done)); + out_completions.push_back(std::move(completion)); m_entries.erase(it); } @@ -499,11 +495,9 @@ bool Executor::Update() // 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. Two reasons: the - // stored request is what deduplication compares, so stamping it would make - // every request unique and dedupe would never fire; and a retry re-sends the - // same logical request, so it carries the same id, which is what makes a - // server log show one id across attempts. + // 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; @@ -555,10 +549,8 @@ void Executor::FailAll(const std::string& reason) completion.error = MakeError(ErrorCode::Transport, reason); completion.error.request_id = entry.id.ToString(); - for (CompletionHandler& handler : entry.on_done) { - handlers.push_back(std::move(handler)); - completions.push_back(completion); - } + 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 b19b069..f8836da 100644 --- a/src/core/executor.h +++ b/src/core/executor.h @@ -122,10 +122,11 @@ class Executor { RequestId id; PendingRequest request; - // Every handler waiting on this request. More than one only when a submission was - // deduplicated onto this entry, in which case all of them are called with the same - // completion. - std::vector on_done; + // 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. int attempts = 0; diff --git a/src/core/request_id.cpp b/src/core/request_id.cpp index 2a1c0d9..cc962ab 100644 --- a/src/core/request_id.cpp +++ b/src/core/request_id.cpp @@ -17,16 +17,27 @@ std::atomic g_next_request_id{1}; RequestId RequestId::Next() { - std::uint64_t value = g_next_request_id.fetch_add(1, std::memory_order_relaxed); - - // Skip 0, which is the invalid id. Unreachable in practice - a uint64 at a million - // requests a second lasts longer than the hardware - but one comparison removes the - // edge case entirely rather than leaving a wrap that would silently produce an invalid - // id. - if (value == 0) { - value = g_next_request_id.fetch_add(1, std::memory_order_relaxed); + // 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. } - return RequestId(value); } std::string RequestId::ToString() const diff --git a/tests/test_executor.cpp b/tests/test_executor.cpp index 8de59e7..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; @@ -937,6 +940,70 @@ void TestRequestIdNextIsMonotonic() 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; @@ -994,6 +1061,7 @@ int main() TestTimeoutCarriesTheRequestId(); TestRequestIdsAreUniqueAcrossClients(); TestRequestIdNextIsMonotonic(); + TestRequestIdNextIsUniqueUnderConcurrency(); TestAbandonCancelsInFlightWithoutCallingBack(); return testing::Report();