Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Expand Down
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
63 changes: 63 additions & 0 deletions include/lootlocker/request_id.h
Original file line number Diff line number Diff line change
@@ -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 <cstdint>
#include <string>

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
85 changes: 51 additions & 34 deletions src/core/executor.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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();

Expand All @@ -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:
Expand All @@ -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;
}
Expand Down Expand Up @@ -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)) {
Expand All @@ -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<CompletionHandler>& out_handlers,
std::vector<Completion>& out_completions)
{
Expand Down Expand Up @@ -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) {
Comment thread
kirre-bylund marked this conversation as resolved.
Resolved
entry.in_flight = false;
entry.transfer = 0;
entry.ready_at_ms = now + BackoffMs(entry.attempts, completion);
Expand All @@ -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()
Expand Down Expand Up @@ -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> finished;
std::vector<std::uint64_t> timed_out;
std::vector<RequestId> timed_out;

for (auto& pair : m_entries) {
Entry& entry = pair.second;
Expand Down Expand Up @@ -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;
Expand All @@ -455,7 +464,7 @@ bool Executor::Update()
// rather than one item.

{
std::vector<std::uint64_t> ready;
std::vector<RequestId> ready;
for (const auto& pair : m_entries) {
const Entry& entry = pair.second;
if (!entry.in_flight && entry.ready_at_ms <= now) {
Expand All @@ -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<int>(InFlightCount()) >= m_config.max_in_flight) {
break;
}
Expand All @@ -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;

Expand Down Expand Up @@ -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();

Expand Down
37 changes: 21 additions & 16 deletions src/core/executor.h
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
#include <lootlocker/header_map.h>
#include <lootlocker/http_transport.h>
#include <lootlocker/log.h>
#include <lootlocker/request_id.h>
#include <lootlocker/result.h>

#include "clock.h"
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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<CompletionHandler>& out_handlers,
std::vector<Completion>& out_completions);

Expand Down Expand Up @@ -165,8 +171,7 @@ class Executor {
Clock& m_clock;
std::weak_ptr<Logger> m_logger;

std::uint64_t m_next_id = 1;
std::map<std::uint64_t, Entry> m_entries;
std::map<RequestId, Entry> 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()`.
Expand Down
Loading
Loading