@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/tm/cpp/feature/test.hpp

@@ -57,6 +57,22 @@ public:
   }
 
 private:
+  // The key a list's response transform
+  // ["`$EACH`", "body", {"`$MERGE`": "`.<key>`"}] reads each item's record
+  // under; empty for any other transform.
+  static std::string itemEnvelopeKey(const Value& restf) {
+    if (!restf.is_list()) return "";
+    const List& spec = *restf.as_list();
+    if (3 != spec.size() || !spec[0].is_string() || "`$EACH`" != spec[0].as_string() ||
+        !spec[1].is_string() || "body" != spec[1].as_string()) return "";
+    Value merge = getp(spec[2], Value("`$MERGE`"));
+    if (!merge.is_string()) return "";
+    std::string m = merge.as_string();
+    if (m.size() < 4 || 0 != m.compare(0, 2, "`.") || '`' != m[m.size() - 1]) return "";
+    std::string key = m.substr(2, m.size() - 3);
+    return std::string::npos == key.find_first_of(".`$") ? key : "";
+  }
+
   // THE MOCK HAS TO AGREE WITH THE MODEL. A point carrying
   // `transform.res: `body.item`` describes an API that answers {"item": {...}}
   // and the response transform unwraps that key on the way back. Returning the
@@ -66,6 +82,16 @@ private:
     if (is_nullish(data) || !ctx) return data;
     Value tm = getp(ctx->point, "transform");
     Value restf = getp(tm, "res");
+    std::string key = itemEnvelopeKey(restf);
+    if (!key.empty() && data.is_list()) {
+      Value out = vlist();
+      for (const auto& item : *data.as_list()) {
+        Value wrapped = vmap();
+        map_put(wrapped, key, item);
+        out.as_list()->push_back(wrapped);
+      }
+      return out;
+    }
     if (!restf.is_string()) return data;
     std::string spec = restf.as_string();
     // Rebuild whatever nesting the transform unwraps. Multi-segment on purpose:
@@ -148,7 +174,7 @@ private:
       }
       Value out = Struct::clone(outlist);
       return respond(ctx, 200, out, Value::undef());
-    } else if (op->name == "update") {
+    } else if (op->name == "update" || op->name == "patch") {
       Value updateMatch = vmap();
       if (ctx->reqdata.is_map()) {
         if (map_contains(ctx->reqdata, "id")) {
@@ -173,7 +199,10 @@ private:
       // update miss: 404, never another record
       if (is_nullish(ent)) return respond(ctx, 404, Value(nullptr), extra1("statusText", Value("Not found")));
       if (ent.is_map() && ctx->reqdata.is_map()) {
-        Struct::merge(vlist({ent, ctx->reqdata}));
+        // `$body` travels on the wire alone; the record is the rest.
+        Value rec = Struct::clone(ctx->reqdata);
+        Struct::delprop(rec, Value("$body"));
+        Struct::merge(vlist({ent, rec}));
       }
       Struct::delprop(ent, Value("$KEY"));
       Value out = Struct::clone(ent);
@@ -203,6 +232,7 @@ private:
       }
       Value ent = Struct::clone(ctx->reqdata);
       if (ent.is_map()) {
+        Struct::delprop(ent, Value("$body"));
         map_put(ent, "id", id);
         if (id.is_string()) map_put(entmap, id.as_string(), ent);
         Struct::delprop(ent, Value("$KEY"));

package/project/.sdk/tm/cpp/feature/timeout.hpp

@@ -8,7 +8,10 @@
 #ifndef SDK_FEATURE_TIMEOUT_HPP
 #define SDK_FEATURE_TIMEOUT_HPP
 
+#include <algorithm>
+#include <atomic>
 #include <chrono>
+#include <climits>
 #include <exception>
 #include <future>
 #include <memory>
@@ -53,14 +56,24 @@ private:
       return inner(ctx, url, fetchdef);
     }
 
-    // Run inner on a detached thread; the shared promise keeps the future's
-    // shared state alive even after the loser resolves unobserved.
+    // The deadline runs from here, not from the wait below: a caller paused
+    // between the two would otherwise find a late response complete and take
+    // it. The worker notes when it finished, so a response or a failure after
+    // the deadline is a timeout however late the caller looks. The shared
+    // promise keeps the future's state alive after the loser resolves
+    // unobserved on its detached thread.
+    fopt::NowFn now = fopt::foptNow(options);
+    const long long start = now();
+    auto arrived = std::make_shared<std::atomic<long long>>(LLONG_MAX);
     auto prom = std::make_shared<std::promise<Value>>();
     std::future<Value> fut = prom->get_future();
-    std::thread([ctx, url, fetchdef, inner, prom]() {
+    std::thread([ctx, url, fetchdef, inner, prom, now, arrived]() {
       try {
-        prom->set_value(inner(ctx, url, fetchdef));
+        Value out = inner(ctx, url, fetchdef);
+        arrived->store(now());
+        prom->set_value(out);
       } catch (...) {
+        arrived->store(now());
         try {
           prom->set_exception(std::current_exception());
         } catch (...) {
@@ -68,15 +81,22 @@ private:
       }
     }).detach();
 
-    if (fut.wait_for(std::chrono::milliseconds(deadline)) == std::future_status::timeout) {
-      track(deadline);
-      throw ctx->makeError("timeout",
-          "Request exceeded timeout of " + std::to_string(deadline) + "ms");
+    long long remaining = std::max(0LL, static_cast<long long>(deadline) - (now() - start));
+    if (fut.wait_for(std::chrono::milliseconds(remaining)) == std::future_status::timeout) {
+      throw timeout(ctx, deadline);
+    }
+    if (deadline < arrived->load() - start) {
+      throw timeout(ctx, deadline);
     }
-
     return fut.get();
   }
 
+  SdkErrorPtr timeout(CtxPtr ctx, int deadline) {
+    track(deadline);
+    return ctx->makeError("timeout",
+        "Request exceeded timeout of " + std::to_string(deadline) + "ms");
+  }
+
   void track(int deadline) {
     count++;
     ms = deadline;

package/project/.sdk/tm/cpp/feature/validate.hpp

@@ -183,6 +183,8 @@ private:
     // fields will never name it — and under `strict` every custom-action call
     // would be rejected for the one key that made it reachable.
     map_remove(out, "$action");
+    // Nor is `$body`, the raw request body.
+    map_remove(out, "$body");
 
     return out;
   }

package/project/.sdk/tm/cpp/test/concurrency_test.cpp

@@ -0,0 +1,348 @@
+// ProjectName SDK - requests in flight at once on one client. Each resolves
+// its operation through the cache the client's root context shares with
+// every request, and registers and cleans secrets through the one registry
+// the client holds.
+
+#include "testlib.hpp"
+
+#include <algorithm>
+#include <atomic>
+#include <cstdlib>
+#include <functional>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+using namespace sdk;
+
+// PROJECTENV_TEST_CONCURRENCY_ROUNDS sets the rounds: fewer where each costs
+// more, as under ThreadSanitizer.
+static int envRounds() {
+  const char* set = std::getenv("PROJECTENV_TEST_CONCURRENCY_ROUNDS");
+  int rounds = nullptr == set ? 0 : std::atoi(set);
+  return 0 < rounds ? rounds : 200;
+}
+
+static const int ROUNDS = envRounds();
+static const int QUARTER = std::max(1, ROUNDS / 4);
+static const int WIDTH = 8;
+static const int OPS = 32;
+
+static const std::string BASIC_USER = "CONCURRENCY-BASIC-USER";
+static const std::string BASIC_PASS = "CONCURRENCY-BASIC-PASS";
+
+static Value liveOptions() {
+  return vmap({{"base", Value(std::string("http://concurrency.test/api"))},
+               {"allow", vmap({{"op", Value(std::string("direct"))}})}});
+}
+
+// A live client whose transport answers at once, showing `seen` the headers
+// of each request.
+static std::shared_ptr<ProjectNameSDK> liveClient(
+    const Value& options = liveOptions(), std::function<void(const Value&)> seen = nullptr) {
+  auto client = std::make_shared<ProjectNameSDK>(options);
+  // Through the base: an entity accessor may share the member's name.
+  SdkClient& base = *client;
+  base.utility->fetcher = [seen](CtxPtr, const std::string&, const Value& fetchdef) -> Value {
+    if (seen) seen(getp(fetchdef, "headers"));
+    vs::Injector json = [](vs::Injection&, const Value&, const std::string&, const Value&) -> Value {
+      return vmap({{"ok", Value(true)}});
+    };
+    return vmap({{"status", Value(200)}, {"statusText", Value(std::string("OK"))},
+                 {"headers", vmap()}, {"json", Value(json)}});
+  };
+  return client;
+}
+
+// Runs body on WIDTH threads released together, and returns what they threw.
+template <typename F>
+static std::vector<std::string> atOnce(F body) {
+  std::atomic<int> ready{0};
+  std::mutex mu;
+  std::vector<std::string> thrown;
+  std::vector<std::thread> threads;
+  for (int n = 0; n < WIDTH; n++) {
+    threads.emplace_back([&, n]() {
+      ready.fetch_add(1);
+      while (ready.load() < WIDTH) std::this_thread::yield();
+      try {
+        body(n);
+      } catch (const SdkErrorPtr& e) {
+        std::lock_guard<std::mutex> lk(mu);
+        thrown.push_back(e->msg);
+      } catch (const std::exception& e) {
+        std::lock_guard<std::mutex> lk(mu);
+        thrown.push_back(e.what());
+      }
+    });
+  }
+  for (auto& t : threads) t.join();
+  return thrown;
+}
+
+static void concurrent_first_requests_succeed() {
+  for (int round = 0; round < ROUNDS; round++) {
+    // A fresh client each round, so every request in it is a first request.
+    auto client = liveClient();
+    std::vector<Value> results(WIDTH);
+    auto thrown = atOnce([&](int n) {
+      results[n] = client->direct(vmap({{"path", Value("p" + std::to_string(n))}}));
+    });
+    if (!thrown.empty()) {
+      ASSERT_TRUE(false, "round " + std::to_string(round) + " threw: " + thrown[0]);
+      return;
+    }
+    for (int n = 0; n < WIDTH; n++) {
+      if (!is_true(getp(results[n], "ok"))) {
+        ASSERT_TRUE(false, "round " + std::to_string(round) + ", request " + std::to_string(n) +
+                    " failed: " + sdktest::vstr(results[n]));
+        return;
+      }
+    }
+  }
+  ASSERT_TRUE(true, "every request succeeded");
+}
+
+static void concurrent_resolutions_share_one_cached_operation() {
+  for (int round = 0; round < ROUNDS; round++) {
+    auto client = liveClient();
+    auto utility = client->getUtility();
+    auto root = client->getRootCtx();
+    std::vector<std::vector<OperationPtr>> ops(WIDTH, std::vector<OperationPtr>(OPS));
+    auto resolve = [&](int k) {
+      CtxSpec cs;
+      cs.setOpname("op" + std::to_string(k));
+      return utility->makeContext(cs, root)->op;
+    };
+    auto thrown = atOnce([&](int n) {
+      for (int k = 0; k < OPS; k++) ops[n][k] = resolve(k);
+    });
+    if (!thrown.empty()) {
+      ASSERT_TRUE(false, "round " + std::to_string(round) + " threw: " + thrown[0]);
+      return;
+    }
+    for (int k = 0; k < OPS; k++) {
+      OperationPtr cached = resolve(k);
+      for (int n = 0; n < WIDTH; n++) {
+        if (ops[n][k] != cached) {
+          ASSERT_TRUE(false, "round " + std::to_string(round) + ": op" + std::to_string(k) +
+                      " resolved to more than one Operation");
+          return;
+        }
+      }
+    }
+  }
+  ASSERT_TRUE(true, "every operation resolved to one cached Operation");
+}
+
+// The k-th secret registering thread n adds in round r.
+static std::string addedSecret(const std::string& r, int n, int k) {
+  return "ADDED-SECRET-" + r + "-" + std::to_string(n) + "-" + std::to_string(k);
+}
+
+// Registers thread n's secrets, then counts the thread out of `left`.
+static void registerSecrets(UtilityPtr utility, CtxPtr root, const std::string& r, int n,
+                            std::atomic<int>& left) {
+  struct Done {
+    std::atomic<int>& left;
+    ~Done() { left.fetch_sub(1); }
+  } done{left};
+  for (int k = 0; k < OPS; k++) utility->cleanAdd(root, Value(addedSecret(r, n, k)));
+}
+
+// The first of `known` and the secrets `registrars` threads registered in
+// round r that a clean leaves raw, or "".
+static std::string unmaskedSecret(UtilityPtr utility, CtxPtr root, const std::string& r,
+                                  int registrars, std::vector<std::string> known = {}) {
+  for (int n = 0; n < registrars; n++) {
+    for (int k = 0; k < OPS; k++) known.push_back(addedSecret(r, n, k));
+  }
+  for (const auto& secret : known) {
+    Value got = utility->clean(root, Value(secret));
+    if (!got.is_string() || "[redacted]" != got.as_string()) return secret;
+  }
+  return "";
+}
+
+// Secrets registered on some threads while others clean: every clean masks
+// what was registered before it, the longer secret whole, and no
+// registration is lost.
+static void concurrent_registration_keeps_every_secret_masked() {
+  const std::string masked = "a [redacted] b [redacted] c";
+  for (int round = 0; round < QUARTER; round++) {
+    auto client = liveClient();
+    auto utility = client->getUtility();
+    auto root = client->getRootCtx();
+    std::string r = std::to_string(round);
+    std::string inner = "INNER-SECRET-" + r;
+    utility->cleanAdd(root, Value(inner));
+    utility->cleanAdd(root, Value("OUTER-" + inner + "-TAIL"));
+    Value text("a " + inner + " b OUTER-" + inner + "-TAIL c");
+    Value before = utility->clean(root, text);
+    if (!before.is_string() || masked != before.as_string()) {
+      ASSERT_TRUE(false, "round " + r + " cleaned to: " + sdktest::vstr(before));
+      return;
+    }
+
+    std::atomic<int> registering{WIDTH / 2};
+    std::mutex mu;
+    std::vector<std::string> wrong;
+    auto thrown = atOnce([&](int n) {
+      if (n < WIDTH / 2) {
+        registerSecrets(utility, root, r, n, registering);
+        return;
+      }
+      while (0 < registering.load()) {
+        Value got = utility->clean(root, text);
+        if (!got.is_string() || masked != got.as_string()) {
+          std::lock_guard<std::mutex> lk(mu);
+          wrong.push_back(sdktest::vstr(got));
+          return;
+        }
+      }
+    });
+    if (!thrown.empty()) {
+      ASSERT_TRUE(false, "round " + r + " threw: " + thrown[0]);
+      return;
+    }
+    if (!wrong.empty()) {
+      ASSERT_TRUE(false, "round " + r + " cleaned to: " + wrong[0]);
+      return;
+    }
+    std::string raw = unmaskedSecret(utility, root, r, WIDTH / 2);
+    if (!raw.empty()) {
+      ASSERT_TRUE(false, "round " + r + ": " + raw + " was registered but not masked");
+      return;
+    }
+  }
+  ASSERT_TRUE(true, "every secret stayed masked");
+}
+
+// Requests on one client while secrets register on it: each request copies
+// the client's options, the registry among them.
+static void concurrent_requests_survive_registration() {
+  for (int round = 0; round < QUARTER; round++) {
+    auto client = liveClient();
+    auto utility = client->getUtility();
+    auto root = client->getRootCtx();
+    std::string r = std::to_string(round);
+    std::atomic<int> registering{WIDTH / 2};
+    std::mutex mu;
+    std::vector<std::string> failed;
+    auto thrown = atOnce([&](int n) {
+      if (n < WIDTH / 2) {
+        registerSecrets(utility, root, r, n, registering);
+        return;
+      }
+      while (0 < registering.load()) {
+        Value got = client->direct(vmap({{"path", Value("p" + std::to_string(n))}}));
+        if (!is_true(getp(got, "ok"))) {
+          std::lock_guard<std::mutex> lk(mu);
+          failed.push_back(sdktest::vstr(got));
+          return;
+        }
+      }
+    });
+    if (!thrown.empty()) {
+      ASSERT_TRUE(false, "round " + r + " threw: " + thrown[0]);
+      return;
+    }
+    if (!failed.empty()) {
+      ASSERT_TRUE(false, "round " + r + ", a request failed: " + failed[0]);
+      return;
+    }
+    std::string raw = unmaskedSecret(utility, root, r, WIDTH / 2);
+    if (!raw.empty()) {
+      ASSERT_TRUE(false, "round " + r + ": " + raw + " was registered but not masked");
+      return;
+    }
+  }
+  ASSERT_TRUE(true, "every request succeeded while secrets registered");
+}
+
+// Whether a header value holds `text`.
+static bool carries(const Value& headers, const std::string& text) {
+  if (!headers.is_map()) return false;
+  for (const auto& kv : *headers.as_map()) {
+    if (kv.second.is_string() && std::string::npos != kv.second.as_string().find(text)) return true;
+  }
+  return false;
+}
+
+// First requests on a client carrying Basic credentials while secrets
+// register on it: where the API takes HTTP Basic, prepareAuth registers the
+// encoded pair as the other requests copy the options.
+static void concurrent_basic_requests_survive_registration() {
+  const std::string pair = util::cleanBase64(BASIC_USER + ":" + BASIC_PASS);
+  int sent = 0;
+  int paired = 0;
+  for (int round = 0; round < QUARTER; round++) {
+    std::atomic<int> roundSent{0};
+    std::atomic<int> roundPaired{0};
+    Value options = liveOptions();
+    map_put(options, "apikey", Value(BASIC_USER));
+    map_put(options, "secret", Value(BASIC_PASS));
+    auto client = liveClient(options, [&](const Value& headers) {
+      roundSent.fetch_add(1);
+      if (carries(headers, pair)) roundPaired.fetch_add(1);
+    });
+    auto utility = client->getUtility();
+    auto root = client->getRootCtx();
+    std::string r = "basic-" + std::to_string(round);
+    std::atomic<int> registering{1};
+    std::mutex mu;
+    std::vector<std::string> failed;
+    auto thrown = atOnce([&](int n) {
+      if (0 == n) {
+        registerSecrets(utility, root, r, n, registering);
+        return;
+      }
+      // Bounded, as requests that never pause can hold off a registration.
+      int made = 0;
+      do {
+        Value got = client->direct(vmap({{"path", Value("p" + std::to_string(n))}}));
+        if (!is_true(getp(got, "ok"))) {
+          std::lock_guard<std::mutex> lk(mu);
+          failed.push_back(sdktest::vstr(got));
+          return;
+        }
+      } while (0 < registering.load() && ++made < OPS);
+    });
+    if (!thrown.empty()) {
+      ASSERT_TRUE(false, "round " + r + " threw: " + thrown[0]);
+      return;
+    }
+    if (!failed.empty()) {
+      ASSERT_TRUE(false, "round " + r + ", a request failed: " + failed[0]);
+      return;
+    }
+    int rsent = roundSent.load();
+    int rpaired = roundPaired.load();
+    if (0 < rpaired && rpaired != rsent) {
+      ASSERT_TRUE(false, "round " + r + ": " + std::to_string(rpaired) + " of " +
+                  std::to_string(rsent) + " requests carried the Basic pair");
+      return;
+    }
+    std::vector<std::string> known{BASIC_USER, BASIC_PASS};
+    if (0 < rpaired) known.push_back(pair);
+    std::string raw = unmaskedSecret(utility, root, r, 1, known);
+    if (!raw.empty()) {
+      ASSERT_TRUE(false, "round " + r + ": " + raw + " was registered but not masked");
+      return;
+    }
+    sent += rsent;
+    paired += rpaired;
+  }
+  std::cout << "concurrency_test: " << paired << " of " << sent
+            << " requests carried the Basic pair\n";
+  ASSERT_TRUE(true, "every request succeeded while the Basic pair and secrets registered");
+}
+
+int main() {
+  T_RUN(concurrent_first_requests_succeed);
+  T_RUN(concurrent_resolutions_share_one_cached_operation);
+  T_RUN(concurrent_registration_keeps_every_secret_masked);
+  T_RUN(concurrent_requests_survive_registration);
+  T_RUN(concurrent_basic_requests_survive_registration);
+  return sdktest::summary("concurrency_test");
+}

package/project/.sdk/tm/cpp/test/feature_test.cpp

@@ -4,6 +4,7 @@
 // its feature is present in this SDK.
 
 #include <chrono>
+#include <memory>
 #include <regex>
 #include <thread>
 #include <vector>
@@ -246,6 +247,40 @@ static void timeout_slowRequestTimesOut() {
   ASSERT_EQ(f->count, 1, "expected 1 timeout");
 }
 
+// A clock standing at 0 for the calling thread and at `later` for any other.
+static vs::Injector workerClock(long long later) {
+  auto caller = std::this_thread::get_id();
+  return [caller, later](vs::Injection&, const Value&, const std::string&, const Value&) -> Value {
+    return Value(std::this_thread::get_id() == caller ? 0LL : later);
+  };
+}
+
+// The deadline runs from the request's start, not from the wait: a response
+// that arrives after it is a timeout even when the caller only looks once it
+// is complete. The clock stands at the start for the caller and 300 ms later
+// for the worker.
+static void timeout_lateResponseTimesOutHoweverLateTheCallerLooks() {
+  if (!have({"timeout"})) return;
+  auto f = std::make_shared<TimeoutFeature>();
+  auto h = fhMake(nullptr, {FF(f, fhMap({{"ms", Value(20)}, {"now", Value(workerClock(300))}}))});
+  FhOpResult res = h->op(fhOp("load"));
+  ASSERT_EQ(fhErrCode(res.err), std::string("timeout"), "expected timeout error");
+  ASSERT_EQ(f->count, 1, "expected 1 timeout");
+}
+
+// A transport failure after the deadline is a timeout too, not the failure.
+static void timeout_lateFailureTimesOut() {
+  if (!have({"timeout"})) return;
+  auto f = std::make_shared<TimeoutFeature>();
+  FetcherFn failing = [](CtxPtr ctx, const std::string&, const Value&) -> Value {
+    throw ctx->makeError("socket_closed", "socket closed");
+  };
+  auto h = fhMake(failing, {FF(f, fhMap({{"ms", Value(20)}, {"now", Value(workerClock(300))}}))});
+  FhOpResult res = h->op(fhOp("load"));
+  ASSERT_EQ(fhErrCode(res.err), std::string("timeout"), "expected timeout error");
+  ASSERT_EQ(f->count, 1, "expected 1 timeout");
+}
+
 static void timeout_fastRequestPasses() {
   if (!have({"timeout"})) return;
   auto h = fhMake(nullptr, {FF(std::make_shared<TimeoutFeature>(), fhMap({{"ms", Value(1000)}}))});
@@ -857,6 +892,8 @@ int main() {
   T_RUN(retry_inactiveDoesNotWrap);
 
   T_RUN(timeout_slowRequestTimesOut);
+  T_RUN(timeout_lateResponseTimesOutHoweverLateTheCallerLooks);
+  T_RUN(timeout_lateFailureTimesOut);
   T_RUN(timeout_fastRequestPasses);
   T_RUN(timeout_msZeroDisables);
   T_RUN(timeout_inactiveDoesNotWrap);

package/project/.sdk/tm/cpp/test/harness.hpp

@@ -142,7 +142,7 @@ struct FhOpResult {
 
 inline std::string fhDefaultMethod(const std::string& op) {
   if (op == "create") return "POST";
-  if (op == "update") return "PATCH";
+  if (op == "update" || op == "patch") return "PATCH";
   if (op == "remove") return "DELETE";
   return "GET";
 }

package/project/.sdk/tm/cpp/test/primary_utility_test.cpp

@@ -308,7 +308,10 @@ static void fetcherLive() {
     calls->push_back(vmap({{"url", url}, {"init", fetchdef}}));
     return vmap({{"status", Value(200)}, {"statusText", Value("OK")}});
   };
-  Value opts = fhMap({{"system", fhMap({{"fetch", Value(fetchFn)}})}});
+  // Concrete base: a live construction must satisfy any server variables a
+  // templated base URL declares; a literal base sidesteps the requirement.
+  Value opts = fhMap({{"base", Value("http://localhost:8080")},
+                      {"system", fhMap({{"fetch", Value(fetchFn)}})}});
   auto liveClient = std::make_shared<ProjectNameSDK>(opts);
   UtilityPtr liveUtility = liveClient->getUtility();
 
@@ -328,7 +331,8 @@ static void fetcherBlockedTestMode() {
   vs::Injector fetchFn = [](vs::Injection&, const Value&, const std::string&, const Value&) -> Value {
     return vmap();
   };
-  Value opts = fhMap({{"system", fhMap({{"fetch", Value(fetchFn)}})}});
+  Value opts = fhMap({{"base", Value("http://localhost:8080")},
+                      {"system", fhMap({{"fetch", Value(fetchFn)}})}});
   auto blockedClient = std::make_shared<ProjectNameSDK>(opts);
   blockedClient->mode = "test";
 

package/project/.sdk/tm/cpp/test/server_variable_test.cpp

@@ -0,0 +1,57 @@
+// ProjectName SDK - a templated base URL takes each {name} from the `server`
+// option. A missing or empty value fails construction; test mode fills in
+// test-<name>.
+
+#include "harness.hpp"
+
+using namespace sdk;
+
+// A variable no API declares, so the API's own server defaults cannot fill it.
+static const std::string BASE = "https://api.example.test/bot{zzvar}";
+
+static Value baseOf(const std::shared_ptr<ProjectNameSDK>& client) {
+  return getp(client->optionsMap(), "base");
+}
+
+static void a_missing_or_empty_value_fails_construction() {
+  for (const Value& server : {vmap(), vmap({{"zzvar", Value("")}})}) {
+    SdkErrorPtr err;
+    try {
+      std::make_shared<ProjectNameSDK>(vmap({{"base", Value(BASE)}, {"server", server}}));
+    } catch (const SdkErrorPtr& e) {
+      err = e;
+    }
+    ASSERT_TRUE((bool)err, "construction should fail without a value for zzvar");
+    if (err) {
+      ASSERT_EQ(err->code, std::string("server_var_required"), "the error carries its code");
+      ASSERT_TRUE(std::string::npos != err->msg.find("the server variable 'zzvar' is required"), err->msg);
+      ASSERT_TRUE(std::string::npos != err->msg.find(BASE), err->msg);
+    }
+  }
+}
+
+static void a_server_value_fills_the_base() {
+  auto client = std::make_shared<ProjectNameSDK>(vmap({
+    {"base", Value(BASE)}, {"server", vmap({{"zzvar", Value("T1")}})},
+  }));
+  ASSERT_EQ_VAL(baseOf(client), Value("https://api.example.test/botT1"), "a server value fills the base");
+}
+
+static void test_mode_fills_the_base() {
+  auto client = std::make_shared<ProjectNameSDK>(vmap({
+    {"base", Value(BASE)}, {"test", vmap({{"active", Value(true)}})},
+  }));
+  ASSERT_EQ_VAL(baseOf(client), Value("https://api.example.test/bottest-zzvar"),
+                "the test option fills test-<name>");
+
+  auto mock = ProjectNameSDK::testSDK(Value::undef(), vmap({{"base", Value(BASE)}}));
+  ASSERT_EQ_VAL(baseOf(mock), Value("https://api.example.test/bottest-zzvar"),
+                "the test feature fills test-<name>");
+}
+
+int main() {
+  T_RUN(a_missing_or_empty_value_fails_construction);
+  T_RUN(a_server_value_fills_the_base);
+  T_RUN(test_mode_fills_the_base);
+  return sdktest::summary("server_variable_test");
+}

package/project/.sdk/tm/cpp/utility/cookie.hpp

@@ -0,0 +1,36 @@
+// ProjectName SDK: the cookie header, read one way everywhere.
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace sdk {
+namespace util {
+
+// The caller's cookie pieces with the named cookies removed: a cookie is one
+// ;-delimited piece, whatever its value holds.
+inline std::vector<std::string> cookieKeep(const std::string& header, const std::vector<std::string>& names) {
+  auto trim = [](const std::string& s) {
+    size_t a = s.find_first_not_of(" \t");
+    size_t b = s.find_last_not_of(" \t");
+    return std::string::npos == a ? std::string() : s.substr(a, b - a + 1);
+  };
+  std::vector<std::string> kept;
+  size_t at = 0;
+  while (at <= header.size()) {
+    size_t end = header.find(';', at);
+    if (std::string::npos == end) end = header.size();
+    std::string cookie = trim(header.substr(at, end - at));
+    std::string name = trim(cookie.substr(0, cookie.find('=')));
+    bool owned = false;
+    for (const auto& n : names) {
+      if (n == name) owned = true;
+    }
+    if (!cookie.empty() && !owned) kept.push_back(cookie);
+    at = end + 1;
+  }
+  return kept;
+}
+
+}  // namespace util
+}  // namespace sdk