@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/tm/clojure/src/sdk/features.clj

@@ -112,6 +112,16 @@
 
 (declare test-build-args make-netsim)
 
+;; The key a list's response transform
+;; ["`$EACH`", "body", {"`$MERGE`": "`.<key>`"}] reads each item's record under.
+(defn- item-envelope-key [spec]
+  (when (and (vs/islist spec) (= 3 (count spec))
+             (= "`$EACH`" (first spec)) (= "body" (second spec))
+             (vs/ismap (nth spec 2)))
+    (let [merge (vs/getprop (nth spec 2) "`$MERGE`")]
+      (when (string? merge)
+        (second (re-matches #"`\.([^.`$]+)`" merge))))))
+
 (defn test-feature []
   (let [fa (new-feature "test" true "0.0.1")]
     (swap! fa assoc
@@ -136,16 +146,20 @@
                        ;; scope here, so the point is the one being served.
                        (let [envelope (fn [data]
                                         (let [tm (vs/getprop (core/oget fctx :point) "transform")
-                                              spec (vs/getprop tm "res")]
-                                          ;; Rebuild whatever nesting the transform unwraps;
-                                          ;; GraphQL ops unwrap `body.data.<field>`.
-                                          (if (and (some? data) (string? spec))
+                                              spec (vs/getprop tm "res")
+                                              ikey (item-envelope-key spec)]
+                                          (cond
+                                            (and (some? ikey) (vs/islist data))
+                                            (apply vs/jt (map (fn [item] (vs/jm ikey item)) data))
+                                            ;; Rebuild whatever nesting the transform unwraps;
+                                            ;; GraphQL ops unwrap `body.data.<field>`.
+                                            (and (some? data) (string? spec))
                                             (if-let [m (re-matches #"`body\.(.+)`" spec)]
                                               (reduce (fn [out seg] (vs/jm seg out))
                                                       data
                                                       (reverse (str/split (second m) #"\." -1)))
                                               data)
-                                            data)))
+                                            :else data)))
                              respond (fn [status data extra]
                                        (let [payload (envelope data)
                                              out (vs/jm "status" status "statusText" "OK"
@@ -177,7 +191,7 @@
                              (if (nil? found) (respond 404 nil (vs/jm "statusText" "Not found"))
                                  (do (when (vs/islist found) (doseq [item (vec found)] (vs/delprop item "$KEY")))
                                      (respond 200 (vs/clone found) nil))))
-                           (= opn "update")
+                           (or (= opn "update") (= opn "patch"))
                            (let [update-match (vs/jm)
                                  reqdata (core/oget fctx :reqdata)]
                              (when (vs/ismap reqdata)
@@ -194,7 +208,8 @@
                                ;; update miss: 404, never another record
                                (if (nil? ent) (respond 404 nil (vs/jm "statusText" "Not found"))
                                    (do (when (and (vs/ismap ent) (vs/ismap reqdata))
-                                         (vs/merge (vs/jt ent reqdata)))
+                                         ;; `$body` travels on the wire alone; the record is the rest.
+                                         (vs/merge (vs/jt ent (doto (vs/clone reqdata) (vs/delprop "$body")))))
                                        (vs/delprop ent "$KEY")
                                        (respond 200 (vs/clone ent) nil)))))
                            (= opn "remove")
@@ -209,7 +224,8 @@
                                             (format "%04x%04x%04x%04x" (rand-int 0x10000) (rand-int 0x10000) (rand-int 0x10000) (rand-int 0x10000)))
                                      ent (vs/clone (core/oget fctx :reqdata))]
                                  (if (vs/ismap ent)
-                                   (do (.put ^java.util.Map ent "id" id)
+                                   (do (vs/delprop ent "$body")
+                                       (.put ^java.util.Map ent "id" id)
                                        (when (string? id) (.put ^java.util.Map entmap (str id) ent))
                                        (vs/delprop ent "$KEY")
                                        (respond 200 (vs/clone ent) nil))
@@ -380,18 +396,24 @@
         (fn [ctx url fetchdef inner]
           (let [ms (opt fa "ms" 30000)]
             (if (<= ms 0) (inner ctx url fetchdef)
-                (let [now (opt fa "now")]
-                  (if (fn? now)
-                    (let [start (now) r (inner ctx url fetchdef)]
-                      (if (> (- (now) start) ms)
-                        (do (track! ms) [nil (core/ctx-error ctx "timeout" (str "Request exceeded timeout of " ms "ms"))])
-                        r))
-                    (let [fut (future (inner ctx url fetchdef))
-                          r (deref fut (long ms) ::timeout)]
-                      (if (= r ::timeout)
-                        (do (future-cancel fut) (track! ms)
-                            [nil (core/ctx-error ctx "timeout" (str "Request exceeded timeout of " ms "ms"))])
-                        r)))))))]
+                ;; The deadline runs from here, not from the deref below: a
+                ;; caller paused between the two would otherwise find a late
+                ;; response complete and take it. The future notes when it
+                ;; finished, so a response or a failure after the deadline is
+                ;; a timeout however late the caller looks.
+                (let [now (let [n (opt fa "now")] (if (fn? n) n #(System/currentTimeMillis)))
+                      start (now)
+                      arrived (atom Long/MAX_VALUE)
+                      fut (future (try (inner ctx url fetchdef) (finally (reset! arrived (now)))))
+                      remaining (max 0 (- ms (- (now) start)))
+                      late? (fn [] (< ms (- @arrived start)))
+                      r (try (deref fut (long remaining) ::timeout)
+                             (catch java.util.concurrent.ExecutionException e
+                               (if (late?) ::timeout (throw (or (.getCause e) e)))))]
+                  (if (or (= r ::timeout) (late?))
+                    (do (future-cancel fut) (track! ms)
+                        [nil (core/ctx-error ctx "timeout" (str "Request exceeded timeout of " ms "ms"))])
+                    r)))))]
     (swap! fa assoc
            "init" (fn [ctx options]
                     (swap! fa assoc :client (core/oget ctx :client)
@@ -1471,6 +1493,8 @@
                     ;; call would be rejected for the one key that made it
                     ;; reachable.
                     (.remove ^java.util.Map out "$action")
+                    ;; Nor is `$body`, the raw request body.
+                    (.remove ^java.util.Map out "$body")
                     out))]
     (swap! fa assoc :spec (vs/jm) :request true :response false :mode "throw")
     (swap! fa assoc

package/project/.sdk/tm/clojure/test/sdk/test/concurrency.clj

@@ -0,0 +1,136 @@
+;; ProjectName SDK concurrency tests - 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.
+(ns sdk.test.concurrency
+  (:require [sdk.core :as core]
+            [sdk.client :as client]
+            [sdk.testutil :as t]
+            [voxgig.struct :as vs])
+  (:import [java.util.concurrent ConcurrentLinkedQueue CountDownLatch CyclicBarrier]))
+
+(def ^:private rounds 200)
+(def ^:private width 8)
+(def ^:private ops 32)
+(def ^:private masked "a [redacted] b [redacted] c")
+
+;; Runs body on width threads released together, and returns what they threw.
+(defn- at-once [body]
+  (let [start (CyclicBarrier. width)
+        thrown (ConcurrentLinkedQueue.)
+        threads (mapv (fn [n]
+                        (doto (Thread. ^Runnable (fn []
+                                                   (try
+                                                     (.await start)
+                                                     (body n)
+                                                     (catch Throwable e (.add thrown e)))))
+                          (.start)))
+                      (range width))]
+    (doseq [^Thread thread threads] (.join thread))
+    (vec thrown)))
+
+(defn- resolve-op [root k]
+  (core/oget (core/make-context (vs/jm "opname" (str "op" k)) root) :op))
+
+(defn- resolutions-share-one-cached-operation []
+  (dotimes [round rounds]
+    (let [sdk (client/test-sdk nil nil)
+          root @(:root-ctx sdk)
+          got (vec (repeatedly width #(object-array ops)))
+          thrown (at-once (fn [n] (dotimes [k ops] (aset ^objects (got n) k (resolve-op root k)))))]
+      (t/is-true (empty? thrown) (str "round " round " threw: " (pr-str thrown)))
+      (dotimes [k ops]
+        (let [cached (resolve-op root k)]
+          (dotimes [n width]
+            (t/is-true (identical? cached (aget ^objects (got n) k))
+                       (str "round " round ": op" k " resolved to more than one Operation"))))))))
+
+;; A live client whose transport answers at once.
+(defn- live-sdk []
+  (client/make-sdk
+   (vs/jm "base" "http://concurrency.test/api"
+          "allow" (vs/jm "op" "direct")
+          "system" (vs/jm "fetch" (fn [_url _fetchdef]
+                                    [(vs/jm "status" 200 "statusText" "OK" "headers" (vs/jm)
+                                            "json" (fn [] (vs/jm "ok" true)))
+                                     nil])))))
+
+(defn- added-secret [round n k] (str "ADDED-SECRET-" round "-" n "-" k))
+
+;; Registers thread n's secrets, then counts the thread out of registering.
+(defn- register-secrets [clean-add ^CountDownLatch registering round n]
+  (try
+    (dotimes [k ops] (clean-add (added-secret round n k)))
+    (finally (.countDown registering))))
+
+(defn- every-secret-masked [clean round]
+  (dotimes [n (quot width 2)]
+    (dotimes [k ops]
+      (let [added (added-secret round n k)]
+        (t/is-eq (clean added) "[redacted]"
+                 (str "round " round ": " added " was registered but not masked"))))))
+
+;; 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.
+(defn- registration-keeps-every-secret-masked []
+  (dotimes [round (quot rounds 4)]
+    (let [sdk (client/test-sdk nil nil)
+          root @(:root-ctx sdk)
+          clean (fn [v] ((core/uget root :clean) root v))
+          clean-add (fn [v] ((core/uget root :clean-add) root v))
+          inner (str "INNER-SECRET-" round)
+          text (str "a " inner " b OUTER-" inner "-TAIL c")
+          _ (clean-add inner)
+          _ (clean-add (str "OUTER-" inner "-TAIL"))
+          _ (t/is-eq (clean text) masked (str "round " round))
+          registering (CountDownLatch. (quot width 2))
+          wrong (ConcurrentLinkedQueue.)
+          thrown (at-once
+                  (fn [n]
+                    (if (< n (quot width 2))
+                      (register-secrets clean-add registering round n)
+                      (loop []
+                        (when (pos? (.getCount registering))
+                          (let [got (clean text)]
+                            (if (= masked got) (recur) (.add wrong got))))))))]
+      (t/is-true (empty? thrown) (str "round " round " threw: " (pr-str thrown)))
+      (t/is-true (.isEmpty wrong) (str "round " round " cleaned to: " (pr-str (vec wrong))))
+      (every-secret-masked clean round))))
+
+;; Requests on one client while secrets register on it: each request copies
+;; the client's options, the registry among them.
+(defn- requests-survive-registration []
+  (dotimes [round (quot rounds 4)]
+    (let [sdk (live-sdk)
+          root @(:root-ctx sdk)
+          clean (fn [v] ((core/uget root :clean) root v))
+          clean-add (fn [v] ((core/uget root :clean-add) root v))
+          registering (CountDownLatch. (quot width 2))
+          failed (ConcurrentLinkedQueue.)
+          thrown (at-once
+                  (fn [n]
+                    (if (< n (quot width 2))
+                      (register-secrets clean-add registering round n)
+                      (loop []
+                        (when (pos? (.getCount registering))
+                          (let [res (client/direct sdk (vs/jm "path" (str "p" n)))]
+                            (if (true? (vs/getprop res "ok")) (recur) (.add failed res))))))))]
+      (t/is-true (empty? thrown) (str "round " round " threw: " (pr-str thrown)))
+      (t/is-true (.isEmpty failed) (str "round " round ", a request failed: " (pr-str (vec failed))))
+      (every-secret-masked clean round))))
+
+(defn run [rec]
+  (let [ran (atom 0)
+        failed (atom 0)
+        counting (fn [name ok? msg]
+                   (swap! ran inc)
+                   (when-not ok? (swap! failed inc))
+                   (rec name ok? msg))]
+    (t/run-check counting "concurrency-resolutions-share-one-cached-operation"
+                 resolutions-share-one-cached-operation)
+    (t/run-check counting "concurrency-registration-keeps-every-secret-masked"
+                 registration-keeps-every-secret-masked)
+    (t/run-check counting "concurrency-requests-survive-registration"
+                 requests-survive-registration)
+    (println (str "concurrency: " @ran " check(s), " @failed " failed"))))

package/project/.sdk/tm/clojure/test/sdk/test/feature.clj

@@ -21,7 +21,7 @@
 (defn fspec [name & kvs] {"name" name "options" (if (seq kvs) (apply vs/jm kvs) (vs/jm))})
 
 (defn default-method [opname]
-  (cond (= opname "create") "POST" (= opname "update") "PATCH" (= opname "remove") "DELETE" :else "GET"))
+  (cond (= opname "create") "POST" (or (= opname "update") (= opname "patch")) "PATCH" (= opname "remove") "DELETE" :else "GET"))
 
 (defn make-response [status data headers]
   (let [h (vs/jm)]
@@ -51,6 +51,11 @@
 (defn clock-sleeper [c] (fn [ms] (swap! c + (or ms 0))))
 (defn clock-advance [c ms] (swap! c + ms))
 
+;; A clock standing at 0 for the calling thread and at `later` for any other.
+(defn worker-clock [later]
+  (let [caller (Thread/currentThread)]
+    (fn [] (if (identical? (Thread/currentThread) caller) 0 later))))
+
 (defn fake-entity [name] {:get-name (fn [] name)})
 
 (defn- merge-headers [base extra]
@@ -265,6 +270,21 @@
            (fn [] (let [c (make-clock)
                         h (make-harness [(fspec "timeout" "ms" 1000 "now" (clock-now c))])]
                     (t/is-eq (get (h-op h) "ok") true "ok"))))
+    ;; The deadline runs from the request's start, not from the wait: the
+    ;; clock stands at the start for the caller and 300 ms later for the worker.
+    (check "timeout-late-response-however-late-the-caller-looks" "timeout"
+           (fn [] (let [h (make-harness [(fspec "timeout" "ms" 20 "now" (worker-clock 300))])
+                        res (h-op h)]
+                    (t/is-eq (rcode res) "timeout" "timeout")
+                    (t/is-eq (mget (h-track h "_timeout") "count") 1 "count"))))
+    ;; A transport failure after the deadline is a timeout too, not the failure.
+    (check "timeout-late-failure-times-out" "timeout"
+           (fn [] (let [failing (fn [fctx _url _fetchdef]
+                                  (core/sdk-throw (core/ctx-error fctx "socket_closed" "socket closed")))
+                        h (make-harness [(fspec "timeout" "ms" 20 "now" (worker-clock 300))] :server failing)
+                        res (h-op h)]
+                    (t/is-eq (rcode res) "timeout" "timeout")
+                    (t/is-eq (mget (h-track h "_timeout") "count") 1 "count"))))
     (check "timeout-ms-zero-disables" "timeout"
            (fn [] (let [h (make-harness [(fspec "timeout" "ms" 0)])]
                     (t/is-eq (get (h-op h) "ok") true "ok"))))

package/project/.sdk/tm/clojure/test/sdk/test_runner.clj

@@ -1,6 +1,6 @@
 ;; ProjectName SDK test runner (tools.deps main entry point).
 ;; Runs the vendored omni runner's smoke test, the API-agnostic suites
-;; (primary utility, pipeline, features, netsim), the generated API-specific
+;; (primary utility, pipeline, features, netsim, concurrency), the generated API-specific
 ;; suite, and the vendored struct corpus, then reports counts and exits
 ;; non-zero on any failure. `--sdk-only` skips the corpus steps (see -main).
 (ns sdk.test-runner
@@ -11,6 +11,7 @@
             [sdk.test.struct-corpus :as corpus]
             [sdk.test.omni-smoke :as omnismoke]
             [sdk.test.clean :as clean]
+            [sdk.test.concurrency :as concurrency]
             [sdk.gentest :as gentest]
             [clojure.java.io :as io]))
 
@@ -89,6 +90,14 @@
   (first (filter (fn [p] (.exists (java.io.File. ^String p)))
                  ["../.sdk/test/test.json" ".sdk/test/test.json" "../../.sdk/test/test.json" "test/test.json"])))
 
+;; The agent pool keeps the JVM alive for a minute after the last task, so a
+;; run that passes exits as one that fails does.
+(defn- all-green []
+  (println "ALL GREEN")
+  (flush)
+  (shutdown-agents)
+  (System/exit 0))
+
 ;; `--sdk-only` runs the SDK's OWN suites and skips the three steps that read
 ;; the shared corpus (.sdk/test/test.json): the omni smoke test, the primary
 ;; corpus and the struct corpus. create-sdkgen compiles that corpus into
@@ -111,6 +120,7 @@
     (feature/run rec)
     (run-feature-suites rec)
     (netsim/run rec)
+    (concurrency/run rec)
     (gentest/run rec)
     ;; The canary sweep (generated: sdk/test/clean.clj) prints its own
     ;; `clean: swept N surface(s), M leak(s)` line, which sdkgen's lane reads.
@@ -126,7 +136,7 @@
             (flush)
             (if (pos? nf)
               (System/exit 1)
-              (println "ALL GREEN")))
+              (all-green)))
         (let [cf (find-corpus-file)]
           (if (nil? cf)
             (do (println "STRUCT CORPUS: test.json not found on any candidate path") (flush) (System/exit 1))
@@ -136,4 +146,4 @@
               (flush)
               (if (or (pos? nf) (pos? cfail))
                 (System/exit 1)
-                (println "ALL GREEN")))))))))
+                (all-green)))))))))

package/project/.sdk/tm/cpp/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) $$const.year$$ Voxgig
+Copyright (c) $$const.year$$ PROJECTPUBLISHER
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/project/.sdk/tm/cpp/core/types.hpp

@@ -11,10 +11,15 @@
 #ifndef SDK_CORE_TYPES_HPP
 #define SDK_CORE_TYPES_HPP
 
+#include <algorithm>
+#include <atomic>
+#include <cctype>
 #include <functional>
 #include <map>
 #include <memory>
+#include <mutex>
 #include <ostream>
+#include <shared_mutex>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -49,7 +54,11 @@ using FeaturePtr = std::shared_ptr<Feature>;
 using UtilityPtr = std::shared_ptr<Utility>;
 using CtxPtr = std::shared_ptr<Context>;
 
-using OpMap = std::map<std::string, OperationPtr>;
+// Shared by every context of one client, so by requests on several threads.
+struct OpMap {
+  std::mutex lock;
+  std::map<std::string, OperationPtr> ops;
+};
 using OpMapPtr = std::shared_ptr<OpMap>;
 
 // Generated (core/config.hpp) — the embedded API config + feature factory.
@@ -70,6 +79,26 @@ inline long long toLong(const Value& v, long long def) {
 }
 inline Value toMapAny(const Value& v) { return v.is_map() ? v : Value::undef(); }
 
+// Whether a comma-separated allow option names the item: whole names, any case.
+inline bool allowed(const Value& names, const std::string& item) {
+  if (!names.is_string() || item.empty()) return false;
+  const std::string list = names.as_string();
+  size_t start = 0;
+  for (;;) {
+    size_t end = list.find(',', start);
+    size_t s = start;
+    size_t e = std::string::npos == end ? list.size() : end;
+    while (s < e && std::isspace((unsigned char)list[s])) s++;
+    while (e > s && std::isspace((unsigned char)list[e - 1])) e--;
+    if (e - s == item.size() && std::equal(item.begin(), item.end(), list.begin() + s,
+          [](char a, char b) { return std::toupper((unsigned char)a) == std::toupper((unsigned char)b); })) {
+      return true;
+    }
+    if (std::string::npos == end) return false;
+    start = end + 1;
+  }
+}
+
 SdkErrorPtr unsupportedOp(const std::string& opname, const std::string& entityname);
 
 } // namespace Helpers
@@ -146,6 +175,9 @@ public:
   Value body = Value::undef();
   std::string url = "";
   std::string path = "";
+  // The query parameters prepareAuth placed: the credential, which the
+  // request sends and the entity's match leaves out.
+  std::vector<std::string> authquery;
 
   Spec() {
     headers = vmap();
@@ -214,6 +246,8 @@ public:
   JsonFunc jsonFunc;
   Value body = Value::undef();
   SdkErrorPtr err;
+  // Set by a transport that could not read a non-blank body as JSON.
+  bool unreadable = false;
 
   Response() = default;
 
@@ -237,6 +271,8 @@ public:
       };
     }
     body = getp(m, "body");
+    Value ur = getp(m, "unreadable");
+    unreadable = ur.is_bool() && ur.as_bool();
   }
 };
 
@@ -594,6 +630,24 @@ public:
 
 // ---- SdkClient --------------------------------------------------------
 
+// A registration replaces the secret registry (options.__derived__.clean
+// .values) while requests copy the options: it holds this lock exclusively,
+// and every read of that slot holds it shared.
+inline std::shared_mutex& cleanRegistryLock() {
+  // winpthreads sets up a static rwlock on its first lock, failing threads
+  // that race it with EINVAL; that first lock runs in this static's
+  // initialization, which every other caller waits for.
+  struct Warmed {
+    std::shared_mutex lock;
+    Warmed() {
+      lock.lock();
+      lock.unlock();
+    }
+  };
+  static Warmed warmed;
+  return warmed.lock;
+}
+
 class SdkClient {
 public:
   std::string mode = "live";
@@ -650,6 +704,7 @@ public:
   virtual std::vector<SdkEntityPtr> list(const Value& reqmatch, const Value& ctrl) = 0;
   virtual SdkEntityPtr create(const Value& reqdata, const Value& ctrl) = 0;
   virtual SdkEntityPtr update(const Value& reqdata, const Value& ctrl) = 0;
+  virtual SdkEntityPtr patch(const Value& reqdata, const Value& ctrl) = 0;
   virtual SdkEntityPtr remove(const Value& reqmatch, const Value& ctrl) = 0;
 };
 
@@ -714,7 +769,7 @@ inline SdkErrorPtr Helpers::unsupportedOp(const std::string& opname,
 
 // ---- Context ----
 inline Context::Context(const CtxSpec& cs, const CtxPtr& basectx) {
-  static long long counter = 10000000;
+  static std::atomic<long long> counter{10000000};
   id = "C" + std::to_string(++counter);
 
   // Client
@@ -796,8 +851,11 @@ inline OperationPtr Context::resolveOp(const std::string& opname) {
   if (entity) entname = entity->getName();
   std::string cacheKey = entname + ":" + opname;
 
-  auto it = opmap->find(cacheKey);
-  if (it != opmap->end()) return it->second;
+  {
+    std::lock_guard<std::mutex> guard(opmap->lock);
+    auto it = opmap->ops.find(cacheKey);
+    if (it != opmap->ops.end()) return it->second;
+  }
 
   if (opname.empty()) {
     return std::make_shared<Operation>(vmap());
@@ -806,7 +864,7 @@ inline OperationPtr Context::resolveOp(const std::string& opname) {
   Value opcfg = Struct::getpath(config, {"entity", entname, "op", opname});
 
   std::string input = "match";
-  if (opname == "update" || opname == "create") input = "data";
+  if (opname == "update" || opname == "create" || opname == "patch") input = "data";
 
   Value points = Value::undef();
   if (opcfg.is_map()) {
@@ -822,8 +880,9 @@ inline OperationPtr Context::resolveOp(const std::string& opname) {
   map_put(opdef, "points", points);
 
   auto op_ = std::make_shared<Operation>(opdef);
-  (*opmap)[cacheKey] = op_;
-  return op_;
+  // Every request racing to build this Operation gets the one stored first.
+  std::lock_guard<std::mutex> guard(opmap->lock);
+  return opmap->ops.emplace(cacheKey, op_).first->second;
 }
 
 inline SdkErrorPtr Context::makeError(const std::string& code, const std::string& msg) {
@@ -921,6 +980,7 @@ inline SdkClient::SdkClient(const Value& options_) {
 }
 
 inline Value SdkClient::optionsMap() {
+  std::shared_lock<std::shared_mutex> guard(cleanRegistryLock());
   Value out = Struct::clone(options);
   return out.is_map() ? out : vmap();
 }
@@ -954,6 +1014,14 @@ inline Value SdkClient::prepare(const Value& fetchargs_) {
   Value methodRaw = getp(fetchargs, "method");
   std::string method = methodRaw.is_string() ? methodRaw.as_string() : "";
   if (method.empty()) method = "GET";
+  for (auto& ch : method) ch = (char)std::toupper((unsigned char)ch);
+
+  Value allowMethod = Struct::getpath(opts, {"allow", "method"});
+  if (!Helpers::allowed(allowMethod, method)) {
+    throw ctx->makeError("spec_method_allow",
+        "Method \"" + method + "\" not allowed by SDK option allow.method value: \"" +
+        (allowMethod.is_string() ? allowMethod.as_string() : std::string()) + "\"");
+  }
 
   Value params = Helpers::toMapAny(getp(fetchargs, "params"));
   if (!params.is_map()) params = vmap();
@@ -993,9 +1061,7 @@ inline Value SdkClient::prepare(const Value& fetchargs_) {
 
 // Is this raw-access op permitted by the SDK's allow.op option?
 inline bool SdkClient::opAllowed(const std::string& op) {
-  Value allow = Struct::getpath(options, {"allow", "op"});
-  if (!allow.is_string()) return false;
-  return std::string::npos != allow.as_string().find(op);
+  return Helpers::allowed(Struct::getpath(options, {"allow", "op"}), op);
 }
 
 inline Value SdkClient::opDenied(const std::string& op) {
@@ -1061,6 +1127,74 @@ inline Value SdkClient::graphql(const std::string& query, const Value& variables
   return res;
 }
 
+// A body that is not JSON. An HTTP failure keeps its own error, with the
+// response described; otherwise the code tells a wrong content type from
+// malformed JSON.
+inline SdkErrorPtr unreadableBody(CtxPtr ctx, int status, const Value& headers, const Value& text,
+                                  const Value& sent, SdkErrorPtr failed) {
+  auto lower = [](std::string s) {
+    for (auto& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    return s;
+  };
+  auto headerValue = [&lower](const Value& h, const std::string& name) -> std::string {
+    if (!h.is_map()) return "";
+    for (const auto& kv : *h.as_map()) {
+      if (lower(kv.first) == name) {
+        return kv.second.is_string() ? kv.second.as_string() : Struct::stringify(kv.second);
+      }
+    }
+    return "";
+  };
+  auto clean = [&ctx](const std::string& s) -> std::string {
+    if (!ctx->utility || !ctx->utility->clean) return s;
+    Value v = ctx->utility->clean(ctx, Value(s));
+    return v.is_string() ? v.as_string() : s;
+  };
+
+  std::string type = headerValue(headers, "content-type");
+  std::string agent = clean(headerValue(sent, "user-agent"));
+  std::string detail = "HTTP " + std::to_string(status) + ", content-type " +
+    (type.empty() ? std::string("none") : type) + ", user-agent " +
+    (agent.empty() ? std::string("transport default") : agent);
+
+  if (!is_nullish(text)) {
+    // Cleaned whole: a secret the bound would split could leave its prefix.
+    std::string raw = text.is_string() ? text.as_string() : Struct::stringify(text);
+    std::string flat;
+    bool space = false;
+    for (unsigned char c : raw) {
+      if (std::isspace(c)) {
+        space = !flat.empty();
+        continue;
+      }
+      if (space) {
+        flat += ' ';
+        space = false;
+      }
+      flat += static_cast<char>(c);
+    }
+    flat = clean(flat);
+    size_t points = 0;
+    size_t end = 0;
+    for (; end < flat.size(); end++) {
+      if ((static_cast<unsigned char>(flat[end]) & 0xC0) == 0x80) continue;
+      if (160 == points) break;
+      points++;
+    }
+    detail += ", body: " + (end < flat.size() ? flat.substr(0, end) + "..." : flat);
+  }
+
+  if (failed) {
+    failed->msg += " (" + detail + ")";
+    return failed;
+  }
+  if (type.empty() || lower(type).find("json") != std::string::npos) {
+    return ctx->makeError("response_json_invalid", "response: body is not valid JSON (" + detail + ")");
+  }
+  return ctx->makeError("response_content_type",
+    "response: expected JSON, got " + type + " (" + detail + ")");
+}
+
 // Ungated request path shared by direct and graphql, each of which checks its
 // own allow.op token first. Private, rather than a flag on fetchargs: a
 // caller-supplied marker would let anyone opt straight back out of the gate
@@ -1125,10 +1259,24 @@ inline Value SdkClient::rawRequest(const Value& fetchargs_) {
       }
     }
 
-    map_put(out, "ok", Value(status >= 200 && status < 300));
+    SdkErrorPtr bodyErr;
+    Value ur = getp(fetched, "unreadable");
+    if (!noBody && ur.is_bool() && ur.as_bool()) {
+      SdkErrorPtr failed;
+      if (status < 200 || status >= 300) {
+        Value st = getp(fetched, "statusText");
+        failed = ctx->makeError("request_status", "request: " + std::to_string(status) + ": " +
+          (st.is_string() ? st.as_string() : std::string("")));
+      }
+      bodyErr = unreadableBody(ctx, status, headers, getp(fetched, "body"),
+        getp(fetchdef, "headers"), failed);
+    }
+
+    map_put(out, "ok", Value(!bodyErr && status >= 200 && status < 300));
     map_put(out, "status", Value(status));
     map_put(out, "headers", headers);
     map_put(out, "data", jsonData);
+    if (bodyErr) map_put(out, "err", vmap({{"message", u->clean(ctx, Value(bodyErr->msg))}}));
     return out;
   }
 
@@ -1233,8 +1381,14 @@ inline std::vector<Value> EntityBase::stream(const std::string& action,
 
   Value streamOpts = callopts.is_map() ? callopts : vmap();
 
-  Value ctrl = Helpers::toMapAny(getp(streamOpts, "ctrl"));
-  if (!ctrl.is_map()) ctrl = vmap();
+  // A copy: the caller's ctrl gains no key, and explain stays its own record.
+  Value ctrl = vmap();
+  Value given = Helpers::toMapAny(getp(streamOpts, "ctrl"));
+  if (given.is_map()) {
+    for (const auto& kv : *given.as_map()) {
+      map_put(ctrl, kv.first, kv.second);
+    }
+  }
   map_put(ctrl, "stream", streamOpts);
 
   CtxSpec cs;