diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 89834c3..ee95663 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -39,6 +39,24 @@ 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 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 run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release @@ -66,6 +84,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..585b4ea 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -18,6 +18,23 @@ endif() option(LOOTLOCKER_BUILD_TESTS "Build the SDK's own tests" 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. # # OFF by default, and it must stay that way. The generator is Python, and requiring Python @@ -121,7 +138,23 @@ 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 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 PUBLIC LOOTLOCKER_HAVE_CURL) +endif() + add_library(LootLocker::core ALIAS lootlocker_core) target_include_directories(lootlocker_core diff --git a/README.md b/README.md index 23d885e..837711d 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,102 @@ 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, own it with a `shared_ptr`, and hand the SDK a `weak_ptr`: + +```cpp +class MyTransport : public lootlocker::IHttpTransport { + // Start / Poll / Cancel +}; + +auto transport = std::make_shared(); + +lootlocker::Config config; +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. + +### 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, 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/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..78ff7b0 --- /dev/null +++ b/include/lootlocker/http_transport.h @@ -0,0 +1,80 @@ +#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. + // + // **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` + // 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..286c658 --- /dev/null +++ b/src/core/curl_http_transport.cpp @@ -0,0 +1,327 @@ +// 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; + + // 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() +{ + AcquireCurl(); + 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; + } + + ReleaseCurl(); +} + +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); + + // 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)); + + // 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 + // 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(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()) { + 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..d6c997b 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) @@ -55,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() - - - - 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(); 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(); +}