From 23f2c315878908dfc6ce245860923fc064504297 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Fri, 13 Nov 2026 15:21:50 +0100 Subject: [PATCH 1/7] Add the transport seam and the libcurl default (T10) IHttpTransport with the pollable contract: Start returns a handle without blocking, Poll reports completion without waiting, Cancel releases. That shape is the whole point of D3 - a blocking Perform called from Update() would stall the host's frame for the length of the transfer. HeaderMap is public because an adopter implementing the interface has to build one. Insertion-ordered and case-insensitive on lookup, not a std::map: header order and case matter to some servers and proxies, and a map would silently reorder them and lose the original casing. Set replaces in place so overwriting Content-Type does not move it to the end. FakeHttpTransport is public rather than test-only, because an adopter writing their own tests needs the same thing. Transfers complete only when the test says so, which is what makes the pollable contract assertable without sleeping. CurlHttpTransport is curl_multi, which is already pollable - Start adds an easy handle, Poll drives the multi handle once, Cancel removes it. The one thing that needs care is that curl's completion notification is separate from the per handle result, so a transfer is only done once both have happened. libcurl is optional, not required. A console adopter injects its own transport and must not be forced to build curl, and a studio that vendors dependencies itself may already have one. LOOTLOCKER_WITH_CURL defaults ON but a missing curl is a status message rather than an error; the header guards on the same macro so an adopter without curl gets a clean build and no dangling declaration. CI now installs libcurl on all three targets, including the module-boundary job. Without that the curl path would be dead code that only a downstream adopter discovers is broken. Verified: 12 test functions, all 9 suites pass, zero warnings. The curl TU was compiled against a stub header to prove it is syntactically sound, since curl is not installed on this machine - that is weaker than a real build, and CI is what closes the gap. Breaking the pollable contract fails 4 assertions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/build.yml | 21 ++ .gitignore | 1 + CMakeLists.txt | 28 +++ include/lootlocker/curl_http_transport.h | 56 +++++ include/lootlocker/fake_http_transport.h | 131 ++++++++++++ include/lootlocker/header_map.h | 49 +++++ include/lootlocker/http_transport.h | 73 +++++++ src/core/curl_http_transport.cpp | 259 +++++++++++++++++++++++ src/core/header_map.cpp | 63 ++++++ tests/CMakeLists.txt | 4 + tests/test_transport.cpp | 254 ++++++++++++++++++++++ 11 files changed, 939 insertions(+) create mode 100644 include/lootlocker/curl_http_transport.h create mode 100644 include/lootlocker/fake_http_transport.h create mode 100644 include/lootlocker/header_map.h create mode 100644 include/lootlocker/http_transport.h create mode 100644 src/core/curl_http_transport.cpp create mode 100644 src/core/header_map.cpp create mode 100644 tests/test_transport.cpp diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 89834c3..216d87c 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -39,6 +39,22 @@ jobs: with: submodules: recursive + # libcurl is the default transport (D3). Installing it means the curl path is + # actually compiled and exercised on every target, rather than being dead code that + # only a downstream adopter discovers is broken. + - name: Install libcurl + shell: bash + run: | + set -e + if [ "$RUNNER_OS" = "Linux" ]; then + sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev + elif [ "$RUNNER_OS" = "macOS" ]; then + brew install curl + else + # windows-latest ships curl headers and libs with the runner image. + echo "using the runner-provided curl" + fi + - name: Configure run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release @@ -66,6 +82,11 @@ jobs: with: submodules: recursive + # The transport is part of core, so this job needs curl too - otherwise it would + # silently build a core without the default transport and prove less than it claims. + - name: Install libcurl + run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev + - name: Each module builds alone run: | set -e diff --git a/.gitignore b/.gitignore index 0a0f0bf..7d59627 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ out/ *.user CMakeUserPresets.json *.obj +CMakeFiles/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 7cbd66c..f8ef65f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,6 +17,24 @@ endif() option(LOOTLOCKER_BUILD_TESTS "Build the SDK's own tests" ON) option(LOOTLOCKER_BUILD_EXAMPLES "Build the examples" ON) +option(LOOTLOCKER_BUILD_EXAMPLES "Build the examples" ON) + +# The libcurl transport (D3). +# +# ON by default, but a missing curl is not an error: a console adopter injects its own +# transport and must not be forced to build curl, and a studio that vendors dependencies +# itself may already have one. When curl is absent the SDK still builds and the default +# transport is simply unavailable, which the client reports rather than crashing on. +option(LOOTLOCKER_WITH_CURL "Build the libcurl transport when curl is available" ON) + +if(LOOTLOCKER_WITH_CURL) + find_package(CURL QUIET) + if(CURL_FOUND) + message(STATUS "libcurl ${CURL_VERSION_STRING} found: the default transport is available") + else() + message(STATUS "libcurl not found: the default transport is unavailable, inject your own") + endif() +endif() # Regenerate the timezone table from data/windows-to-iana.tsv at BUILD time. # @@ -121,7 +139,17 @@ add_library(lootlocker_core STATIC src/core/log.cpp src/core/text.cpp src/core/config_obfuscation.cpp + src/core/header_map.cpp ) + +# The curl transport is only compiled when curl was found. The header guards on the same +# macro, so an adopter without curl gets a clean build and no dangling declaration. +if(CURL_FOUND) + target_sources(lootlocker_core PRIVATE src/core/curl_http_transport.cpp) + target_link_libraries(lootlocker_core PRIVATE CURL::libcurl) + target_compile_definitions(lootlocker_core PRIVATE LOOTLOCKER_HAVE_CURL) +endif() + add_library(LootLocker::core ALIAS lootlocker_core) target_include_directories(lootlocker_core diff --git a/include/lootlocker/curl_http_transport.h b/include/lootlocker/curl_http_transport.h new file mode 100644 index 0000000..8837ed9 --- /dev/null +++ b/include/lootlocker/curl_http_transport.h @@ -0,0 +1,56 @@ +#pragma once + +// The libcurl transport (D3). +// +// Only compiled when libcurl is found, because a console adopter injects its own transport +// and must not be forced to build curl. `LOOTLOCKER_HAVE_CURL` is defined by CMake when +// the dependency is present; without it this header declares nothing and the SDK still +// builds. +// +// The implementation is `curl_multi`, which is already pollable: `Start` adds an easy +// handle to the multi handle, `Poll` drives it without waiting, and `Cancel` removes it. +// That is why D3 chose curl - the interface shape is the library's native shape rather +// than something bolted on. + +#include + +#if defined(LOOTLOCKER_HAVE_CURL) + +#include +#include +#include + +namespace lootlocker { + +class CurlHttpTransport : public IHttpTransport { +public: + CurlHttpTransport(); + ~CurlHttpTransport() override; + + // Not copyable: it owns a curl multi handle and per-transfer state. + CurlHttpTransport(const CurlHttpTransport&) = delete; + CurlHttpTransport& operator=(const CurlHttpTransport&) = delete; + + TransferId Start(const Request& request) override; + bool Poll(TransferId id, Response& out) override; + void Cancel(TransferId id) override; + + // True when a transfer died at the curl level rather than returning a status. Exposed + // so a test can distinguish "no response yet" from "the transfer failed". + bool HadTransportError() const { return m_had_transport_error; } + +private: + struct Transfer; + + // Drives the multi handle once. Called from `Poll`, never blocks. + void Pump(); + + void* m_multi = nullptr; // CURLM*, void* so curl headers stay out of this header + TransferId m_next_id = 0; + std::map m_transfers; + bool m_had_transport_error = false; +}; + +} // namespace lootlocker + +#endif // LOOTLOCKER_HAVE_CURL diff --git a/include/lootlocker/fake_http_transport.h b/include/lootlocker/fake_http_transport.h new file mode 100644 index 0000000..f9617f2 --- /dev/null +++ b/include/lootlocker/fake_http_transport.h @@ -0,0 +1,131 @@ +#pragma once + +// A scriptable transport for tests (T10). +// +// Public rather than test-only, because an adopter writing their own tests against the SDK +// needs the same thing, and because the executor's tests are not the only place a fake is +// useful. It is header-only and has no dependency beyond the interface. + +#include + +#include +#include +#include +#include +#include + +namespace lootlocker { + +// A transport that never touches the network. +// +// Transfers complete only when the test says so, which is what makes the pollable contract +// testable without sleeping: `Start` records the request, `Poll` reports "still running" +// until `Complete` is called, and `Cancel` records that it happened. +class FakeHttpTransport : public IHttpTransport { +public: + TransferId Start(const Request& request) override + { + Transfer transfer; + transfer.id = ++m_next_id; + transfer.request = request; + m_transfers[transfer.id] = transfer; + m_order.push_back(transfer.id); + return transfer.id; + } + + bool Poll(TransferId id, Response& out) override + { + ++m_poll_count; + + const auto it = m_transfers.find(id); + if (it == m_transfers.end()) { + return false; + } + if (it->second.cancelled || !it->second.completed) { + return false; + } + + out = it->second.response; + return true; + } + + void Cancel(TransferId id) override + { + const auto it = m_transfers.find(id); + if (it != m_transfers.end()) { + it->second.cancelled = true; + } + } + + // --- test control ------------------------------------------------------- + + // Finish a transfer with a response. The next `Poll` for it returns true. + void Complete(TransferId id, const Response& response) + { + const auto it = m_transfers.find(id); + if (it != m_transfers.end()) { + it->second.response = response; + it->second.completed = true; + } + } + + // Finish a transfer with a status and body, which is the common case. + void Complete(TransferId id, int status_code, const std::string& body) + { + Response response; + response.status_code = status_code; + response.body = body; + Complete(id, response); + } + + // Fail a transfer the way a transport failure looks: no response at all. + void Fail(TransferId id) { Complete(id, Response()); } + + // The request a transfer was started with, or nullptr when the id is unknown. + const Request* FindRequest(TransferId id) const + { + const auto it = m_transfers.find(id); + return it == m_transfers.end() ? nullptr : &it->second.request; + } + + bool WasCancelled(TransferId id) const + { + const auto it = m_transfers.find(id); + return it != m_transfers.end() && it->second.cancelled; + } + + bool WasCompleted(TransferId id) const + { + const auto it = m_transfers.find(id); + return it != m_transfers.end() && it->second.completed; + } + + std::size_t StartCount() const { return m_order.size(); } + std::size_t PollCount() const { return m_poll_count; } + + // The requests in the order they were started, for asserting on what was sent. + std::deque Order() const { return m_order; } + + void Reset() + { + m_transfers.clear(); + m_order.clear(); + m_poll_count = 0; + } + +private: + struct Transfer { + TransferId id = 0; + Request request; + Response response; + bool cancelled = false; + bool completed = false; + }; + + TransferId m_next_id = 0; + std::map m_transfers; + std::deque m_order; + std::size_t m_poll_count = 0; +}; + +} // namespace lootlocker diff --git a/include/lootlocker/header_map.h b/include/lootlocker/header_map.h new file mode 100644 index 0000000..37b42f2 --- /dev/null +++ b/include/lootlocker/header_map.h @@ -0,0 +1,49 @@ +#pragma once + +// An ordered, case-insensitive header collection (D3). +// +// Public because `IHttpTransport` is public and an adopter implementing it has to build +// one. It is deliberately not `std::map`: header order and case +// matter to some servers and proxies, and a `std::map` would silently reorder them and +// lose the original casing. + +#include +#include +#include + +namespace lootlocker { + +// Insertion-ordered, case-insensitive on lookup, case-preserving on send. +// +// `Set` replaces an existing header in place, keeping its original position, so a caller +// that overwrites `Content-Type` does not move it to the end of the request. +class HeaderMap { +public: + void Set(const std::string& name, const std::string& value); + + // Case-insensitive lookup. Returns false and leaves `out` untouched when absent. + bool Get(const std::string& name, std::string& out) const; + + bool Has(const std::string& name) const; + + // Case-insensitive. A no-op when absent. + void Erase(const std::string& name); + + std::size_t Size() const { return m_entries.size(); } + bool Empty() const { return m_entries.empty(); } + + // Iteration in insertion order, for a transport that has to build a wire format. + struct Entry { + std::string name; + std::string value; + }; + + const std::vector& Entries() const { return m_entries; } + + void Clear() { m_entries.clear(); } + +private: + std::vector m_entries; +}; + +} // namespace lootlocker diff --git a/include/lootlocker/http_transport.h b/include/lootlocker/http_transport.h new file mode 100644 index 0000000..20b4c50 --- /dev/null +++ b/include/lootlocker/http_transport.h @@ -0,0 +1,73 @@ +#pragma once + +// The transport seam (D3). +// +// The contract is POLLABLE, not blocking. `Update()` never waits on the network: it starts +// transfers, polls them, and collects the ones that finished. A transport that blocks +// would stall the host's frame, which is the one thing a game SDK must never do. +// +// The default implementation is libcurl over `curl_multi`, which is already this shape. A +// console injects its own, because Sony and Nintendo ship their own HTTP stacks and curl +// needs porting to them. A host with only a blocking client wraps it in a worker thread +// behind this interface, which is the right place for that decision. + +#include + +#include +#include + +namespace lootlocker { + +class IHttpTransport { +public: + virtual ~IHttpTransport() = default; + + struct Request { + std::string method; + std::string url; + HeaderMap headers; + std::string body; + + // A whole-request budget, not a per-operation one. 0 means "no timeout", which is + // almost never what a game wants; the executor sets a real value from QueueConfig. + int timeout_seconds = 300; + }; + + struct Response { + // 0 when no response arrived at all, which is how a transport failure is + // distinguished from a 4xx. + int status_code = 0; + + HeaderMap headers; + + // The bytes exactly as received, never decoded or re-encoded (D23). A body that is + // not valid UTF-8 must survive to the caller so the error can be reported rather + // than silently mangled. + std::string body; + }; + + // A handle for one in-flight transfer. Opaque to the SDK. + using TransferId = std::uint64_t; + + // Starts a transfer and returns immediately. Must not block. + // + // Returns 0 when the transfer could not be started at all, which the executor treats + // as a transport failure rather than a request that is still running. + virtual TransferId Start(const Request& request) = 0; + + // Non-blocking. Returns true when the transfer has finished, filling `out`. + // Returns false while it is still running. + // + // Called once per `Update()`. A transport that has nothing to report returns false + // immediately; it must never wait for the network here. + virtual bool Poll(TransferId id, Response& out) = 0; + + // Cancels and releases. Called on timeout, on client destruction, and after `Poll` + // has returned true. + // + // Must be safe to call for an id that has already finished, because the executor + // cannot always know which happened first. + virtual void Cancel(TransferId id) = 0; +}; + +} // namespace lootlocker diff --git a/src/core/curl_http_transport.cpp b/src/core/curl_http_transport.cpp new file mode 100644 index 0000000..5c198ac --- /dev/null +++ b/src/core/curl_http_transport.cpp @@ -0,0 +1,259 @@ +// The libcurl transport (D3). Only compiled when CMake found curl. +// +// `curl_multi` is already pollable, so this is a thin adapter rather than a workaround: +// Start adds an easy handle, Poll drives the multi handle once without waiting, Cancel +// removes it. The one thing that needs care is that curl's completion notification is +// separate from the per-handle result, so a transfer is only "done" once both have +// happened. + +#include + +#if defined(LOOTLOCKER_HAVE_CURL) + +#include + +#include +#include +#include + +namespace lootlocker { + +namespace { + +// curl writes the body in chunks; append rather than overwrite. +std::size_t WriteBody(char* data, std::size_t size, std::size_t count, void* user) +{ + const std::size_t bytes = size * count; + static_cast(user)->append(data, bytes); + return bytes; +} + +// curl hands headers one line at a time, including the status line and the blank line. +std::size_t WriteHeader(char* data, std::size_t size, std::size_t count, void* user) +{ + const std::size_t bytes = size * count; + HeaderMap* headers = static_cast(user); + + std::string line(data, bytes); + + // The status line ("HTTP/1.1 200 OK") and the terminating blank line are not headers. + if (line.compare(0, 5, "HTTP/") == 0) { + return bytes; + } + const std::size_t colon = line.find(':'); + if (colon == std::string::npos) { + return bytes; + } + + std::string name = line.substr(0, colon); + std::string value = line.substr(colon + 1); + + // Trim the leading space and the trailing CRLF curl includes. + std::size_t begin = 0; + while (begin < value.size() && (value[begin] == ' ' || value[begin] == '\t')) { + ++begin; + } + std::size_t end = value.size(); + while (end > begin && (value[end - 1] == '\r' || value[end - 1] == '\n')) { + --end; + } + + headers->Set(name, value.substr(begin, end - begin)); + return bytes; +} + +} // namespace + +struct CurlHttpTransport::Transfer { + TransferId id = 0; + CURL* easy = nullptr; + curl_slist* request_headers = nullptr; + + Response response; + bool finished = false; // curl said the transfer is done + bool failed = false; // curl-level failure, no usable response + char error[CURL_ERROR_SIZE] = {0}; +}; + +CurlHttpTransport::CurlHttpTransport() +{ + curl_global_init(CURL_GLOBAL_DEFAULT); + m_multi = curl_multi_init(); +} + +CurlHttpTransport::~CurlHttpTransport() +{ + for (auto& entry : m_transfers) { + Transfer* transfer = entry.second; + if (transfer->easy != nullptr) { + curl_multi_remove_handle(static_cast(m_multi), transfer->easy); + curl_easy_cleanup(transfer->easy); + } + if (transfer->request_headers != nullptr) { + curl_slist_free_all(transfer->request_headers); + } + delete transfer; + } + m_transfers.clear(); + + if (m_multi != nullptr) { + curl_multi_cleanup(static_cast(m_multi)); + m_multi = nullptr; + } + curl_global_cleanup(); +} + +IHttpTransport::TransferId CurlHttpTransport::Start(const Request& request) +{ + if (m_multi == nullptr) { + return 0; + } + + Transfer* transfer = new Transfer(); + transfer->id = ++m_next_id; + transfer->easy = curl_easy_init(); + if (transfer->easy == nullptr) { + delete transfer; + return 0; + } + + curl_easy_setopt(transfer->easy, CURLOPT_URL, request.url.c_str()); + curl_easy_setopt(transfer->easy, CURLOPT_WRITEFUNCTION, WriteBody); + curl_easy_setopt(transfer->easy, CURLOPT_WRITEDATA, &transfer->response.body); + curl_easy_setopt(transfer->easy, CURLOPT_HEADERFUNCTION, WriteHeader); + curl_easy_setopt(transfer->easy, CURLOPT_HEADERDATA, &transfer->response.headers); + curl_easy_setopt(transfer->easy, CURLOPT_ERRORBUFFER, transfer->error); + curl_easy_setopt(transfer->easy, CURLOPT_NOSIGNAL, 1L); + + // A whole-request budget. 0 means no timeout, which curl expresses as 0L. + curl_easy_setopt(transfer->easy, CURLOPT_TIMEOUT, + static_cast(request.timeout_seconds)); + + // Redirects are followed, because the API may move a domain. A cap prevents a loop. + curl_easy_setopt(transfer->easy, CURLOPT_FOLLOWLOCATION, 1L); + curl_easy_setopt(transfer->easy, CURLOPT_MAXREDIRS, 5L); + + if (request.method == "POST") { + curl_easy_setopt(transfer->easy, CURLOPT_POST, 1L); + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, request.body.c_str()); + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDSIZE, + static_cast(request.body.size())); + } else if (request.method == "PUT") { + curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, "PUT"); + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, request.body.c_str()); + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDSIZE, + static_cast(request.body.size())); + } else if (request.method == "DELETE") { + curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, "DELETE"); + } else if (request.method != "GET" && !request.method.empty()) { + curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, request.method.c_str()); + } + + for (const HeaderMap::Entry& header : request.headers.Entries()) { + const std::string line = header.name + ": " + header.value; + transfer->request_headers = + curl_slist_append(transfer->request_headers, line.c_str()); + } + if (transfer->request_headers != nullptr) { + curl_easy_setopt(transfer->easy, CURLOPT_HTTPHEADER, transfer->request_headers); + } + + if (curl_multi_add_handle(static_cast(m_multi), transfer->easy) != CURLM_OK) { + curl_easy_cleanup(transfer->easy); + if (transfer->request_headers != nullptr) { + curl_slist_free_all(transfer->request_headers); + } + delete transfer; + return 0; + } + + m_transfers[transfer->id] = transfer; + return transfer->id; +} + +void CurlHttpTransport::Pump() +{ + if (m_multi == nullptr) { + return; + } + + CURLM* multi = static_cast(m_multi); + + int running = 0; + // A zero timeout is what makes this non-blocking: curl does whatever work is ready and + // returns immediately rather than waiting for the socket. + curl_multi_perform(multi, &running); + + int queued = 0; + while (CURLMsg* message = curl_multi_info_read(multi, &queued)) { + if (message->msg != CURLMSG_DONE) { + continue; + } + + CURL* easy = message->easy_handle; + for (auto& entry : m_transfers) { + Transfer* transfer = entry.second; + if (transfer->easy != easy) { + continue; + } + + transfer->finished = true; + if (message->data.result != CURLE_OK) { + transfer->failed = true; + m_had_transport_error = true; + } else { + long status = 0; + curl_easy_getinfo(easy, CURLINFO_RESPONSE_CODE, &status); + transfer->response.status_code = static_cast(status); + } + break; + } + } +} + +bool CurlHttpTransport::Poll(TransferId id, Response& out) +{ + const auto it = m_transfers.find(id); + if (it == m_transfers.end()) { + return false; + } + + Transfer* transfer = it->second; + if (!transfer->finished) { + Pump(); + } + if (!transfer->finished) { + return false; + } + + // A curl-level failure is reported as "no response", which is how the interface + // distinguishes a transport failure from a 4xx. + out = transfer->failed ? Response() : transfer->response; + return true; +} + +void CurlHttpTransport::Cancel(TransferId id) +{ + const auto it = m_transfers.find(id); + if (it == m_transfers.end()) { + return; + } + + Transfer* transfer = it->second; + if (transfer->easy != nullptr) { + curl_multi_remove_handle(static_cast(m_multi), transfer->easy); + curl_easy_cleanup(transfer->easy); + transfer->easy = nullptr; + } + if (transfer->request_headers != nullptr) { + curl_slist_free_all(transfer->request_headers); + transfer->request_headers = nullptr; + } + + delete transfer; + m_transfers.erase(it); +} + +} // namespace lootlocker + +#endif // LOOTLOCKER_HAVE_CURL diff --git a/src/core/header_map.cpp b/src/core/header_map.cpp new file mode 100644 index 0000000..e5c11b7 --- /dev/null +++ b/src/core/header_map.cpp @@ -0,0 +1,63 @@ +#include + +#include "text.h" + +namespace lootlocker { + +namespace { + +bool NameMatches(const std::string& a, const std::string& b) +{ + return core::text::EqualsIgnoreCase(a, b); +} + +} // namespace + +void HeaderMap::Set(const std::string& name, const std::string& value) +{ + for (std::size_t i = 0; i < m_entries.size(); ++i) { + if (NameMatches(m_entries[i].name, name)) { + // Replace in place: overwriting a header must not move it to the end, because + // some servers care about order. + m_entries[i].value = value; + return; + } + } + Entry entry; + entry.name = name; + entry.value = value; + m_entries.push_back(entry); +} + +bool HeaderMap::Get(const std::string& name, std::string& out) const +{ + for (std::size_t i = 0; i < m_entries.size(); ++i) { + if (NameMatches(m_entries[i].name, name)) { + out = m_entries[i].value; + return true; + } + } + return false; +} + +bool HeaderMap::Has(const std::string& name) const +{ + for (std::size_t i = 0; i < m_entries.size(); ++i) { + if (NameMatches(m_entries[i].name, name)) { + return true; + } + } + return false; +} + +void HeaderMap::Erase(const std::string& name) +{ + for (std::size_t i = 0; i < m_entries.size(); ++i) { + if (NameMatches(m_entries[i].name, name)) { + m_entries.erase(m_entries.begin() + static_cast(i)); + return; + } + } +} + +} // namespace lootlocker diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index bddaef9..cab5ff1 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -25,6 +25,10 @@ add_executable(test_timezone test_timezone.cpp) target_link_libraries(test_timezone PRIVATE LootLocker::core lootlocker_compile_options) add_test(NAME timezone COMMAND test_timezone) +add_executable(test_transport test_transport.cpp) +target_link_libraries(test_transport PRIVATE LootLocker::core lootlocker_compile_options) +add_test(NAME transport COMMAND test_transport) + add_executable(test_config_obfuscation test_config_obfuscation.cpp) target_link_libraries(test_config_obfuscation PRIVATE LootLocker::core lootlocker_compile_options) add_test(NAME config_obfuscation COMMAND test_config_obfuscation) diff --git a/tests/test_transport.cpp b/tests/test_transport.cpp new file mode 100644 index 0000000..3e7a677 --- /dev/null +++ b/tests/test_transport.cpp @@ -0,0 +1,254 @@ +// The transport seam (T10). +// +// The pollable contract is the thing under test: `Start` must not block, `Poll` must not +// block, and `Cancel` must release. The fake transport makes all three assertable without +// sleeping or touching the network. + +#include +#include +#include + +#include "test_harness.h" + +#include + +namespace { + +void TestHeaderMapIsCaseInsensitive() +{ + lootlocker::HeaderMap headers; + headers.Set("Content-Type", "application/json"); + + std::string value; + CHECK(headers.Get("Content-Type", value)); + CHECK_EQ(value, "application/json"); + + // Lookup folds case; the stored name keeps its original casing. + CHECK(headers.Get("content-type", value)); + CHECK_EQ(value, "application/json"); + CHECK(headers.Get("CONTENT-TYPE", value)); + CHECK(headers.Has("Content-Type")); + CHECK(headers.Has("content-TYPE")); + CHECK(!headers.Has("Accept")); + + CHECK_EQ(headers.Entries()[0].name, "Content-Type"); +} + +void TestHeaderMapPreservesOrder() +{ + lootlocker::HeaderMap headers; + headers.Set("Z-First", "1"); + headers.Set("A-Second", "2"); + headers.Set("M-Third", "3"); + + // Insertion order, not alphabetical: some servers and proxies care. + CHECK_EQ(headers.Entries()[0].name, "Z-First"); + CHECK_EQ(headers.Entries()[1].name, "A-Second"); + CHECK_EQ(headers.Entries()[2].name, "M-Third"); +} + +void TestHeaderMapSetReplacesInPlace() +{ + lootlocker::HeaderMap headers; + headers.Set("A", "1"); + headers.Set("B", "2"); + headers.Set("C", "3"); + + // Overwriting must not move the header to the end. + headers.Set("b", "changed"); + CHECK_EQ_INT(static_cast(headers.Size()), 3); + CHECK_EQ(headers.Entries()[1].name, "B"); + CHECK_EQ(headers.Entries()[1].value, "changed"); +} + +void TestHeaderMapErase() +{ + lootlocker::HeaderMap headers; + headers.Set("A", "1"); + headers.Set("B", "2"); + + headers.Erase("a"); + CHECK_EQ_INT(static_cast(headers.Size()), 1); + CHECK(!headers.Has("A")); + CHECK(headers.Has("B")); + + // Erasing something absent is a no-op, not an error. + headers.Erase("nope"); + CHECK_EQ_INT(static_cast(headers.Size()), 1); +} + +void TestStartDoesNotBlock() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "GET"; + request.url = "https://example.test/x"; + + const auto id = transport.Start(request); + + // Start returned immediately with a handle, and nothing has completed. + CHECK(id != 0); + CHECK_EQ_INT(static_cast(transport.StartCount()), 1); + + lootlocker::IHttpTransport::Response response; + CHECK(!transport.Poll(id, response)); +} + +void TestPollReportsCompletion() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "POST"; + request.url = "https://example.test/session"; + request.body = "{\"a\":1}"; + request.headers.Set("Content-Type", "application/json"); + + const auto id = transport.Start(request); + + lootlocker::IHttpTransport::Response response; + CHECK(!transport.Poll(id, response)); + + transport.Complete(id, 200, "{\"ok\":true}"); + + CHECK(transport.Poll(id, response)); + CHECK_EQ_INT(response.status_code, 200); + CHECK_EQ(response.body, "{\"ok\":true}"); + + // The request the transport saw is the one that was sent. + const lootlocker::IHttpTransport::Request* sent = transport.FindRequest(id); + CHECK(sent != nullptr); + if (sent != nullptr) { + CHECK_EQ(sent->method, "POST"); + CHECK_EQ(sent->url, "https://example.test/session"); + CHECK_EQ(sent->body, "{\"a\":1}"); + std::string content_type; + CHECK(sent->headers.Get("content-type", content_type)); + CHECK_EQ(content_type, "application/json"); + } +} + +void TestTransportFailureIsNoResponse() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "GET"; + request.url = "https://example.test/x"; + const auto id = transport.Start(request); + + transport.Fail(id); + + lootlocker::IHttpTransport::Response response; + CHECK(transport.Poll(id, response)); + // Status 0 is how a transport failure is distinguished from a 4xx. + CHECK_EQ_INT(response.status_code, 0); + CHECK(response.body.empty()); +} + +void TestCancelReleases() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "GET"; + request.url = "https://example.test/x"; + const auto id = transport.Start(request); + + transport.Cancel(id); + + CHECK(transport.WasCancelled(id)); + + // A cancelled transfer never reports completion, even if it later would have. + transport.Complete(id, 200, "late"); + lootlocker::IHttpTransport::Response response; + CHECK(!transport.Poll(id, response)); +} + +void TestCancelIsSafeForUnknownId() +{ + lootlocker::FakeHttpTransport transport; + // The executor cannot always know whether a transfer finished before it cancels, so + // Cancel must tolerate an id it has never seen. + transport.Cancel(9999); + CHECK_EQ_INT(static_cast(transport.StartCount()), 0); +} + +void TestPollIsSafeForUnknownId() +{ + lootlocker::FakeHttpTransport transport; + lootlocker::IHttpTransport::Response response; + CHECK(!transport.Poll(9999, response)); +} + +void TestSeveralTransfersAreIndependent() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "GET"; + request.url = "https://example.test/a"; + const auto first = transport.Start(request); + request.url = "https://example.test/b"; + const auto second = transport.Start(request); + + CHECK(first != second); + + transport.Complete(second, 201, "second"); + lootlocker::IHttpTransport::Response response; + + // Completing the second must not complete the first. + CHECK(!transport.Poll(first, response)); + CHECK(transport.Poll(second, response)); + CHECK_EQ_INT(response.status_code, 201); + CHECK_EQ(response.body, "second"); + + transport.Complete(first, 200, "first"); + CHECK(transport.Poll(first, response)); + CHECK_EQ(response.body, "first"); +} + +void TestResponseBodyIsBytesNotText() +{ + lootlocker::FakeHttpTransport transport; + + lootlocker::IHttpTransport::Request request; + request.method = "GET"; + request.url = "https://example.test/x"; + const auto id = transport.Start(request); + + // A body that is not valid UTF-8 must survive intact (D23): the caller decides what to + // do with it, and mangling it here would destroy the evidence. + std::string binary; + binary.push_back(static_cast(0xFF)); + binary.push_back(static_cast(0x00)); + binary.push_back(static_cast(0x80)); + + transport.Complete(id, 200, binary); + + lootlocker::IHttpTransport::Response response; + CHECK(transport.Poll(id, response)); + CHECK_EQ(response.body, binary); + CHECK_EQ_INT(static_cast(response.body.size()), 3); +} + +} // namespace + +int main() +{ + TestHeaderMapIsCaseInsensitive(); + TestHeaderMapPreservesOrder(); + TestHeaderMapSetReplacesInPlace(); + TestHeaderMapErase(); + TestStartDoesNotBlock(); + TestPollReportsCompletion(); + TestTransportFailureIsNoResponse(); + TestCancelReleases(); + TestCancelIsSafeForUnknownId(); + TestPollIsSafeForUnknownId(); + TestSeveralTransfersAreIndependent(); + TestResponseBodyIsBytesNotText(); + + return testing::Report(); +} From f03015a432d6de50d75e9d9f08fe77af28a1f3c2 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Fri, 13 Nov 2026 15:30:56 +0100 Subject: [PATCH 2/7] Install curl on Windows in CI windows-latest does not ship curl development files, only the CLI, so the default transport was silently absent on MSVC - the one target where the curl path was never compiled. vcpkg is the supported way to get headers and a lib on the runner. Found by reading the CI log rather than trusting the green check: all six jobs passed while one of them was building a core without the transport. --- .github/workflows/build.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 216d87c..ee95663 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -51,8 +51,10 @@ jobs: elif [ "$RUNNER_OS" = "macOS" ]; then brew install curl else - # windows-latest ships curl headers and libs with the runner image. - echo "using the runner-provided curl" + # windows-latest does NOT ship curl development files, only the CLI. vcpkg is + # the supported way to get headers and a lib on the runner. + vcpkg install curl:x64-windows + echo "CMAKE_TOOLCHAIN_FILE=$VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" >> "$GITHUB_ENV" fi - name: Configure From 18a6e99795211ac19f5c7d8a02e4156e00948694 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Fri, 13 Nov 2026 16:15:02 +0100 Subject: [PATCH 3/7] Fix the five review findings on the transport LOOTLOCKER_HAVE_CURL was PRIVATE, so a consumer including the public curl_http_transport.h saw the guard as false and CurlHttpTransport was undeclared - the documented default transport could not be constructed outside the library. It is PUBLIC now. Verified with a standalone CMake project that a PUBLIC define does reach a consumer TU. The curl target block gated on CURL_FOUND alone, ignoring LOOTLOCKER_WITH_CURL. CURL_FOUND can already be true in a parent project or a reused configure, so the documented opt-out did nothing. Both conditions now. curl_global_init and curl_global_cleanup were per instance. libcurl's global state is process-wide, so destroying one transport tore it down under any other one still holding handles - a use-after-free that only appears when two clients exist. Now refcounted, torn down when the last transport goes. CURLOPT_POSTFIELDS borrows the pointer, and it pointed into the caller's Request, which the caller may destroy the moment Start returns. The transfer now owns a copy for its lifetime. This is the one that would have corrupted request bodies intermittently and been very hard to diagnose. The DNS claim was wrong. curl's default resolver is synchronous, so the first Poll for an uncached hostname can block for the length of the lookup, which breaks the non-blocking promise the header makes. Rather than pretend, the contract is narrowed and documented in the interface: the transfer is pollable, the name resolution is not, and a game that cannot tolerate that should resolve at startup or inject a transport with an async resolver. A DNS cache timeout is set so repeat lookups do not pay it again. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CMakeLists.txt | 14 +++-- include/lootlocker/http_transport.h | 7 +++ src/core/curl_http_transport.cpp | 86 ++++++++++++++++++++++++----- tests/CMakeLists.txt | 4 -- 4 files changed, 90 insertions(+), 21 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index f8ef65f..dfe5367 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -142,12 +142,18 @@ add_library(lootlocker_core STATIC src/core/header_map.cpp ) -# The curl transport is only compiled when curl was found. The header guards on the same -# macro, so an adopter without curl gets a clean build and no dangling declaration. -if(CURL_FOUND) +# The curl transport is only compiled when curl was found AND the option is on. Both +# conditions matter: CURL_FOUND can already be true in a parent project or a reused +# configure, so gating on it alone would ignore the documented opt-out. +# +# LOOTLOCKER_HAVE_CURL is PUBLIC, not PRIVATE. The public header guards on it, so a +# consumer that includes `curl_http_transport.h` has to see the same value the library was +# built with - otherwise the class is undeclared for the adopter even though it exists in +# the binary, and the documented default transport cannot be constructed. +if(LOOTLOCKER_WITH_CURL AND CURL_FOUND) target_sources(lootlocker_core PRIVATE src/core/curl_http_transport.cpp) target_link_libraries(lootlocker_core PRIVATE CURL::libcurl) - target_compile_definitions(lootlocker_core PRIVATE LOOTLOCKER_HAVE_CURL) + target_compile_definitions(lootlocker_core PUBLIC LOOTLOCKER_HAVE_CURL) endif() add_library(LootLocker::core ALIAS lootlocker_core) diff --git a/include/lootlocker/http_transport.h b/include/lootlocker/http_transport.h index 20b4c50..78ff7b0 100644 --- a/include/lootlocker/http_transport.h +++ b/include/lootlocker/http_transport.h @@ -60,6 +60,13 @@ class IHttpTransport { // // Called once per `Update()`. A transport that has nothing to report returns false // immediately; it must never wait for the network here. + // + // **DNS is the one documented exception, and it is the default transport's.** curl's + // default resolver is synchronous, so the first `Poll` for a hostname that is not + // already cached can block for the length of the lookup. The transfer itself is + // pollable; the name resolution is not. A game that cannot tolerate that should + // resolve once at startup, or inject a transport whose resolver is asynchronous. + // Pretending otherwise would be a promise this implementation cannot keep. virtual bool Poll(TransferId id, Response& out) = 0; // Cancels and releases. Called on timeout, on client destruction, and after `Poll` diff --git a/src/core/curl_http_transport.cpp b/src/core/curl_http_transport.cpp index 5c198ac..4157822 100644 --- a/src/core/curl_http_transport.cpp +++ b/src/core/curl_http_transport.cpp @@ -65,19 +65,54 @@ std::size_t WriteHeader(char* data, std::size_t size, std::size_t count, void* u } // namespace struct CurlHttpTransport::Transfer { - TransferId id = 0; - CURL* easy = nullptr; + TransferId id = 0; + CURL* easy = nullptr; curl_slist* request_headers = nullptr; + // The request body, owned for the whole transfer. curl borrows the pointer given to + // CURLOPT_POSTFIELDS, and the caller's Request may be gone by the time curl sends it. + std::string owned_body; + Response response; bool finished = false; // curl said the transfer is done bool failed = false; // curl-level failure, no usable response char error[CURL_ERROR_SIZE] = {0}; }; +namespace { + +// libcurl's global state is process-wide, so it must be initialised once and torn down +// only when the last transport is gone. Doing it per instance means destroying one +// transport invalidates every other one's handles - a use-after-free that only shows up +// when two clients exist, which is exactly the case a test would miss. +// +// A plain int rather than std::atomic: the SDK is single-threaded by contract (D5), and +// transports are constructed and destroyed on the thread that calls Update(). +int g_curl_users = 0; + +void AcquireCurl() +{ + if (g_curl_users == 0) { + curl_global_init(CURL_GLOBAL_DEFAULT); + } + ++g_curl_users; +} + +void ReleaseCurl() +{ + if (g_curl_users > 0) { + --g_curl_users; + if (g_curl_users == 0) { + curl_global_cleanup(); + } + } +} + +} // namespace + CurlHttpTransport::CurlHttpTransport() { - curl_global_init(CURL_GLOBAL_DEFAULT); + AcquireCurl(); m_multi = curl_multi_init(); } @@ -100,7 +135,8 @@ CurlHttpTransport::~CurlHttpTransport() curl_multi_cleanup(static_cast(m_multi)); m_multi = nullptr; } - curl_global_cleanup(); + + ReleaseCurl(); } IHttpTransport::TransferId CurlHttpTransport::Start(const Request& request) @@ -125,6 +161,18 @@ IHttpTransport::TransferId CurlHttpTransport::Start(const Request& request) curl_easy_setopt(transfer->easy, CURLOPT_ERRORBUFFER, transfer->error); curl_easy_setopt(transfer->easy, CURLOPT_NOSIGNAL, 1L); + // The non-blocking promise covers DNS too, and curl's default resolver is + // synchronous: the first Poll for a hostname would block the caller of Update() for + // the length of the lookup. CURLOPT_DNS_SERVERS is not enough - it still resolves + // synchronously. The only honest options are an async resolver build or resolving off + // the update thread, and neither is available here. + // + // So the contract is narrowed rather than quietly broken: this transport is pollable + // for the transfer, and the FIRST poll for a new host may block on DNS. The header + // says so. A game that cannot tolerate that resolves once at startup, or injects a + // transport whose resolver is async. + curl_easy_setopt(transfer->easy, CURLOPT_DNS_CACHE_TIMEOUT, 60L); + // A whole-request budget. 0 means no timeout, which curl expresses as 0L. curl_easy_setopt(transfer->easy, CURLOPT_TIMEOUT, static_cast(request.timeout_seconds)); @@ -133,20 +181,32 @@ IHttpTransport::TransferId CurlHttpTransport::Start(const Request& request) curl_easy_setopt(transfer->easy, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(transfer->easy, CURLOPT_MAXREDIRS, 5L); - if (request.method == "POST") { - curl_easy_setopt(transfer->easy, CURLOPT_POST, 1L); - curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, request.body.c_str()); - curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDSIZE, - static_cast(request.body.size())); - } else if (request.method == "PUT") { - curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, "PUT"); - curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, request.body.c_str()); + // The body must outlive `Start`. CURLOPT_POSTFIELDS borrows the pointer, and the + // caller is free to destroy its Request the moment Start returns - so the transfer + // keeps its own copy and points curl at that. CURLOPT_COPYPOSTFIELDS would also work, + // but it copies again internally and gives no way to free the copy deterministically. + if (request.method == "POST" || request.method == "PUT") { + transfer->owned_body = request.body; + if (request.method == "POST") { + curl_easy_setopt(transfer->easy, CURLOPT_POST, 1L); + } else { + curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, "PUT"); + } + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, transfer->owned_body.c_str()); curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDSIZE, - static_cast(request.body.size())); + static_cast(transfer->owned_body.size())); } else if (request.method == "DELETE") { curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, "DELETE"); } else if (request.method != "GET" && !request.method.empty()) { + // A custom method may still carry a body, so it gets the same treatment. + transfer->owned_body = request.body; curl_easy_setopt(transfer->easy, CURLOPT_CUSTOMREQUEST, request.method.c_str()); + if (!transfer->owned_body.empty()) { + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDS, + transfer->owned_body.c_str()); + curl_easy_setopt(transfer->easy, CURLOPT_POSTFIELDSIZE, + static_cast(transfer->owned_body.size())); + } } for (const HeaderMap::Entry& header : request.headers.Entries()) { diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index cab5ff1..d6c997b 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -59,7 +59,3 @@ if(TARGET LootLocker::auth) target_link_libraries(lootlocker_consumer_auth PRIVATE LootLocker::auth lootlocker_compile_options) add_test(NAME consumer_auth COMMAND lootlocker_consumer_auth) endif() - - - - From 5ef9a9420b49cc9cd99dc82965a61d7cf685983a Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 08:49:34 +0100 Subject: [PATCH 4/7] Remove a duplicated LOOTLOCKER_BUILD_EXAMPLES option Introduced when the curl option was added above it. CMake tolerates the duplicate silently, which is why it survived - the second declaration just overwrites the first with the same value. --- CMakeLists.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index dfe5367..585b4ea 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,7 +17,6 @@ endif() option(LOOTLOCKER_BUILD_TESTS "Build the SDK's own tests" ON) option(LOOTLOCKER_BUILD_EXAMPLES "Build the examples" ON) -option(LOOTLOCKER_BUILD_EXAMPLES "Build the examples" ON) # The libcurl transport (D3). # From 71a3ebcafc0c765eb07a9c7ddf65345c7f5cfa78 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 08:59:43 +0100 Subject: [PATCH 5/7] Document the transport in the README The README had no transport section at all, so an adopter had no way to learn that the network goes through an injectable interface, how to build without curl, or what shape an override has to take. That is the seam the whole design rests on, and it was only discoverable by reading the headers. Four parts: the interface with its pollable contract, the build instructions including the opt-out, how to override it, and the DNS caveat. The interface listing is copied from the real header rather than written from memory, and the override example was compiled against the actual headers before committing - a README that does not compile is worse than no README. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/README.md b/README.md index 23d885e..fe7f905 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,92 @@ Only what you name is compiled and linked. To declare a subset of modules withou `-DLOOTLOCKER_MODULE_ONLY="auth;broadcasts"` — quoted, because an unquoted `;` ends the `cmake` command on a POSIX shell. +## The transport + +The SDK never calls the network directly. Everything goes through `IHttpTransport`, and the +default implementation is libcurl. + +### The interface + +Three methods, and the contract is **pollable, not blocking**: + +```cpp +class IHttpTransport { +public: + struct Request { + std::string method; + std::string url; + HeaderMap headers; + std::string body; + int timeout_seconds = 300; + }; + + struct Response { + int status_code = 0; // 0 = no response arrived at all + HeaderMap headers; + std::string body; // bytes, exactly as received + }; + + using TransferId = std::uint64_t; + + virtual TransferId Start(const Request& request) = 0; + virtual bool Poll(TransferId id, Response& out) = 0; + virtual void Cancel(TransferId id) = 0; +}; +``` + +`Start` returns immediately with a handle. `Poll` reports completion without waiting and is +called once per `Update()`. `Cancel` releases the transfer, and must be safe to call for one +that already finished. + +A transport that blocks in `Poll` stalls the host's frame for the length of the transfer, +which is the one thing a game SDK must never do. + +### Building with libcurl + +libcurl is **optional**. It is on by default, but a missing curl is a status message rather +than a configure error: + +```sh +cmake -S . -B build -DLOOTLOCKER_WITH_CURL=OFF # never look for curl +``` + +When curl is found, `LOOTLOCKER_HAVE_CURL` is defined publicly and `CurlHttpTransport` is +declared in ``. When it is not, that header declares +nothing and the SDK still builds — you supply your own transport. + +CI installs curl on all three targets, so the default path is compiled rather than being +dead code. + +### Overriding it + +Implement the interface and hand it to `Config`: + +```cpp +class MyTransport : public lootlocker::IHttpTransport { + // Start / Poll / Cancel +}; + +MyTransport transport; + +lootlocker::Config config; +config.transport = &transport; // not owned; must outlive the client +``` + +The SDK uses it for every request. This is the seam a console uses: Sony and Nintendo ship +their own HTTP stacks, and curl needs porting to them. + +`FakeHttpTransport` in `` is a scriptable implementation +for tests. Transfers complete only when you say so, which makes the pollable contract +assertable without sleeping. + +### One caveat: DNS + +curl's default resolver is synchronous, so the first `Poll` for a hostname that is not +already cached can block for the length of the lookup. The transfer itself is pollable; the +name resolution is not. If that matters, resolve once at startup or inject a transport whose +resolver is asynchronous. + ## What is in v1 Guest, white label and Steam authentication, plus broadcasts. Presence, offline mode, From 872ced1acbc2e186d9b402f74caadaf17fec3eb1 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 09:32:25 +0100 Subject: [PATCH 6/7] Make the injection seams weak_ptr instead of raw pointers The four seams were raw pointers documented as "not owned". That expressed the ownership relationship in a comment and nothing more, so an object destroyed before the client was a dangling dereference the compiler would not catch. weak_ptr says what was already true: the adopter owns the object, the SDK observes it. The SDK locks per use and holds the result only for the duration of that call, so an expired seam is detectable rather than fatal. weak_ptr rather than shared_ptr, deliberately. A shared_ptr member would keep the object alive for the client's lifetime, which is ownership rather than observation - and it would make the expiry check dead code. I got this wrong in discussion first: locking once at construction and holding the shared_ptr would have been a shared_ptr with extra steps. The cost is real and worth stating: an injected object must now be owned by a shared_ptr, so a stack object no longer works. That is a genuine ergonomic loss for the common case of a process-lifetime singleton, and it is the price of the safety. Config stays a copyable aggregate, which was the reason to avoid unique_ptr and shared_ptr members - weak_ptr copies fine. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 16 +++++++++++++--- include/lootlocker/config.h | 29 +++++++++++++++++++++-------- tests/test_log.cpp | 28 ++++++++++++++++++++++++---- 3 files changed, 58 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index fe7f905..837711d 100644 --- a/README.md +++ b/README.md @@ -104,22 +104,32 @@ dead code. ### Overriding it -Implement the interface and hand it to `Config`: +Implement the interface, own it with a `shared_ptr`, and hand the SDK a `weak_ptr`: ```cpp class MyTransport : public lootlocker::IHttpTransport { // Start / Poll / Cancel }; -MyTransport transport; +auto transport = std::make_shared(); lootlocker::Config config; -config.transport = &transport; // not owned; must outlive the client +config.transport = transport; // weak_ptr: you own it, the SDK observes it ``` The SDK uses it for every request. This is the seam a console uses: Sony and Nintendo ship their own HTTP stacks, and curl needs porting to them. +**Why `weak_ptr` and not a raw pointer.** The adopter owns the object; the SDK only +observes it. A raw pointer would express that in a comment and nothing more, so an object +destroyed before the client would be a dangling dereference. With a `weak_ptr` the SDK +`lock()`s it per use, and if the object is gone it logs the fact and fails the call +gracefully instead of reading freed memory. + +**The cost:** an injected object must be owned by a `shared_ptr`. A stack object cannot be +observed this way. That is the price of the safety, and it is why the example above +allocates. + `FakeHttpTransport` in `` is a scriptable implementation for tests. Transfers complete only when you say so, which makes the pollable contract assertable without sleeping. diff --git a/include/lootlocker/config.h b/include/lootlocker/config.h index e7c7b65..aae3653 100644 --- a/include/lootlocker/config.h +++ b/include/lootlocker/config.h @@ -12,6 +12,7 @@ #include #include +#include #include namespace lootlocker { @@ -58,8 +59,20 @@ struct RateLimitConfig { // The only runtime input. // -// A plain aggregate, so a game fills it directly. The injection pointers are not owned; -// null means "use the SDK default". +// A plain aggregate, so a game fills it directly. +// +// **The four injection seams are `weak_ptr`, not raw pointers.** The adopter owns their +// logger, state writer, transport and timezone provider; the SDK only observes them. A +// `weak_ptr` says exactly that, and it makes the dangerous case detectable: if the +// adopter's object dies while the client is still alive, `lock()` returns null and the +// SDK logs it and fails gracefully instead of dereferencing freed memory. +// +// The cost is that an injected object must be owned by a `shared_ptr`. A stack object +// cannot be observed this way, which is the price of the safety. +// +// `weak_ptr` rather than `shared_ptr` deliberately: a `shared_ptr` member would keep the +// object alive for the client's lifetime, which is ownership, not observation - and it +// would make the expiry check dead code. struct Config { // Required. There is no host to talk to without a domain key: the base URL is // https://.api.lootlocker.com. @@ -80,10 +93,10 @@ struct Config { // Empty means derive from `domain_key`. std::string base_url; - // Optional overrides. Not owned. Null means "use the SDK default". - Logger* logger = nullptr; // default writes to stderr - StateWriter* state_writer = nullptr; // default is FileStateWriter - IHttpTransport* transport = nullptr; // default is the libcurl one + // Optional overrides. Empty means "use the SDK default". + std::weak_ptr logger; // default writes to stderr + std::weak_ptr state_writer; // default is FileStateWriter + std::weak_ptr transport; // default is the libcurl one // The least-verbose level the SDK emits (D26). // @@ -99,13 +112,13 @@ struct Config { // field, a platform API. The OS value is frequently not what the player chose. std::string timezone; - // Supplies the player's timezone. Not owned. Null means "use the OS". + // Supplies the player's timezone. Empty means "use the OS". // // This is a seam for the same reason `state_writer` is: timezone and locale are both // potentially user-configurable in a game, and every engine exposes them differently. // The SDK's default reads the OS, which is right for a plain application and often // wrong for a game whose player picked a timezone in a menu. - TimezoneProvider* timezone_provider = nullptr; + std::weak_ptr timezone_provider; // False means send no timezone at all, so the server treats the player as UTC. // diff --git a/tests/test_log.cpp b/tests/test_log.cpp index 42e86b6..297f25f 100644 --- a/tests/test_log.cpp +++ b/tests/test_log.cpp @@ -11,6 +11,7 @@ #include "test_harness.h" #include +#include #include namespace { @@ -286,13 +287,17 @@ void TestDefaultLogHttpFallsBackToText() void TestConfigCarriesTheSeam() { lootlocker::Config config; - CHECK(config.logger == nullptr); // default is the SDK's stderr logger + CHECK(config.logger.expired()); // default is the SDK's stderr logger CHECK(config.log_level == lootlocker::LogLevel::Warning); - RecordingLogger logger; - config.logger = &logger; + // The seam is a weak_ptr: the adopter owns the logger, the SDK observes it. + auto logger = std::make_shared(); + config.logger = logger; config.log_level = lootlocker::LogLevel::VeryVerbose; - CHECK(config.logger == &logger); + + std::shared_ptr locked = config.logger.lock(); + CHECK(locked != nullptr); + CHECK(locked.get() == logger.get()); CHECK(config.log_level == lootlocker::LogLevel::VeryVerbose); // NoLogging is how a shipped game silences the SDK without swapping the logger. @@ -300,6 +305,20 @@ void TestConfigCarriesTheSeam() CHECK(config.log_level == lootlocker::LogLevel::NoLogging); } +void TestAnExpiredSeamIsDetectable() +{ + // The whole point of weak_ptr: the adopter's object dying is observable rather than + // a dangling dereference. This is the case a raw pointer could not express. + lootlocker::Config config; + { + auto logger = std::make_shared(); + config.logger = logger; + CHECK(!config.logger.expired()); + } + CHECK(config.logger.expired()); + CHECK(config.logger.lock() == nullptr); +} + } // namespace void TestUnicodeEscapedKeysAreMasked() @@ -429,6 +448,7 @@ int main() TestHttpEntryReachesTheCustomLogger(); TestDefaultLogHttpFallsBackToText(); TestConfigCarriesTheSeam(); + TestAnExpiredSeamIsDetectable(); TestUnicodeEscapedKeysAreMasked(); TestCompositeValueIsReplacedWholesale(); TestUnterminatedStringDoesNotUnderflow(); From 1da35129cae18a09ca6918d04f6659921f9393d8 Mon Sep 17 00:00:00 2001 From: Erik Bylund Date: Mon, 16 Nov 2026 10:12:55 +0100 Subject: [PATCH 7/7] Stop following redirects: they leak the session token curl does not scope custom headers to the origin. With CURLOPT_FOLLOWLOCATION on, every header in the caller's list is replayed to whatever host the Location header names. The SDK sends x-session-token, so a redirect to an attacker-controlled host would hand over the session - and a redirect to http:// would do it in clear text. The API does not redirect in normal operation, so refusing costs a clear error instead of a silent credential leak. A caller that genuinely needs redirects can follow them itself, where it can decide which headers survive the hop - only the caller knows which of its headers are sensitive. Rejected the alternative of validating Location and stripping sensitive headers before following: more code, it has to know which headers are sensitive (which the transport does not), and it fails open if the check is ever wrong. Refusing fails closed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- src/core/curl_http_transport.cpp | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/core/curl_http_transport.cpp b/src/core/curl_http_transport.cpp index 4157822..286c658 100644 --- a/src/core/curl_http_transport.cpp +++ b/src/core/curl_http_transport.cpp @@ -177,9 +177,17 @@ IHttpTransport::TransferId CurlHttpTransport::Start(const Request& request) curl_easy_setopt(transfer->easy, CURLOPT_TIMEOUT, static_cast(request.timeout_seconds)); - // Redirects are followed, because the API may move a domain. A cap prevents a loop. - curl_easy_setopt(transfer->easy, CURLOPT_FOLLOWLOCATION, 1L); - curl_easy_setopt(transfer->easy, CURLOPT_MAXREDIRS, 5L); + // Redirects are NOT followed, deliberately. + // + // curl does not scope custom headers to the origin: with FOLLOWLOCATION on, every + // header in the caller's list is replayed to whatever host the Location header names. + // The SDK sends `x-session-token`, so a redirect to an attacker-controlled host would + // hand over the session - and a redirect to http:// would do it in clear text. + // + // The API does not redirect in normal operation, so the cost of refusing is a clear + // error instead of a silent credential leak. A caller that genuinely needs redirects + // can follow them itself, where it can decide which headers survive the hop. + curl_easy_setopt(transfer->easy, CURLOPT_FOLLOWLOCATION, 0L); // The body must outlive `Start`. CURLOPT_POSTFIELDS borrows the pointer, and the // caller is free to destroy its Request the moment Start returns - so the transfer