@voxgig/sdkgen 4.33.0 → 4.34.1

package/project/.sdk/tm/java/test/FeatureCorpusTest.java

@@ -50,7 +50,7 @@ public class FeatureCorpusTest {
 
   // The standard operation names, in the order the runner prefers them.
   private static final List<String> FEATURE_CORPUS_OPS =
-      List.of("load", "list", "create", "update", "remove");
+      List.of("load", "list", "create", "update", "patch", "remove");
 
   /** One discovered operation: the client accessor plus the entity method. */
   private static final class Op {
@@ -349,6 +349,37 @@ public class FeatureCorpusTest {
     return null;
   }
 
+  /**
+   * The first feature a case composes that this SDK does not generate, probed
+   * as a section's own feature is. Such a case is skipped rather than failed.
+   */
+  private static String missingFeature(Object kaseRaw, Map<String, Boolean> have) {
+    Object spec = kaseRaw instanceof Map ? ((Map<String, Object>) kaseRaw).get("feature") : null;
+    List<String> names = new ArrayList<>();
+    if (spec instanceof List) {
+      for (Object f : (List<Object>) spec) {
+        if (f instanceof Map && ((Map<String, Object>) f).get("name") instanceof String) {
+          names.add((String) ((Map<String, Object>) f).get("name"));
+        }
+      }
+    }
+    else if (spec instanceof Map) {
+      names.addAll(new TreeMap<>((Map<String, Object>) spec).keySet());
+    }
+    for (String name : names) {
+      Boolean known = have.get(name);
+      if (null == known) {
+        known = null != record(buildClient(Map.of("feature",
+            List.of(Map.of("name", name, "active", true)))), name);
+        have.put(name, known);
+      }
+      if (!known) {
+        return name;
+      }
+    }
+    return null;
+  }
+
   @Test
   public void corpusCarriesAFeatureSection() {
     // A corpus with no `feature` section is a SKIP, not a failure. Each
@@ -385,6 +416,8 @@ public class FeatureCorpusTest {
         "this project's test.json has no `feature` section - recompile the "
             + "corpus (create-sdkgen .sdk/test/feature/) to run these cases");
 
+    List<String> failed = new ArrayList<>();
+    Map<String, Boolean> have = new LinkedHashMap<>();
     for (String name : new TreeMap<>(features).keySet()) {
       Object sectionRaw = features.get(name);
       if (!(sectionRaw instanceof Map)) {
@@ -419,8 +452,20 @@ public class FeatureCorpusTest {
 
       int ran = 0;
       for (Object rawCase : cases) {
+        String rawName = rawCase instanceof Map
+            ? String.valueOf(((Map<String, Object>) rawCase).get("name")) : "";
         int need = tokensUsed(rawCase);
         if (need > ops.size()) {
+          System.err.println(String.format(
+              "skip \"%s\": needs %d operations, this SDK offers %d", rawName, need, ops.size()));
+          continue;
+        }
+
+        String missing = missingFeature(rawCase, have);
+        if (null != missing) {
+          System.err.println(String.format(
+              "skip \"%s\": needs the %s feature, which this SDK does not generate",
+              rawName, missing));
           continue;
         }
 
@@ -429,54 +474,67 @@ public class FeatureCorpusTest {
           tokens.put("#OP" + (i + 1), ops.get(i).key);
         }
         Map<String, Object> kase = (Map<String, Object>) resolve(rawCase, tokens);
-
-        ProjectNameSDK client = buildClient(kase);
         String label = String.valueOf(kase.get("name"));
+        ran++;
 
-        List<Object> steps = kase.get("op") instanceof List
-            ? (List<Object>) kase.get("op") : List.of();
-        for (Object stepRaw : steps) {
-          Map<String, Object> step = (Map<String, Object>) stepRaw;
-          Op op = byKey.get(step.get("op"));
-          assertNotNull(op, label + ": no operation " + step.get("op"));
-          Map<String, Object> ctrl = step.get("ctrl") instanceof Map
-              ? new LinkedHashMap<>((Map<String, Object>) step.get("ctrl"))
-              : new LinkedHashMap<>();
-          Object wanterr = step.get("err");
-
-          try {
-            invoke(client, op, ctrl);
-            if (null != wanterr) {
-              fail(label + ": " + step.get("op") + " was expected to fail, and did not");
+        // Every failing case is reported, not only the first.
+        try {
+          ProjectNameSDK client = buildClient(kase);
+
+          List<Object> steps = kase.get("op") instanceof List
+              ? (List<Object>) kase.get("op") : List.of();
+          for (Object stepRaw : steps) {
+            Map<String, Object> step = (Map<String, Object>) stepRaw;
+            Op op = byKey.get(step.get("op"));
+            assertNotNull(op, label + ": no operation " + step.get("op"));
+            Map<String, Object> ctrl = step.get("ctrl") instanceof Map
+                ? new LinkedHashMap<>((Map<String, Object>) step.get("ctrl"))
+                : new LinkedHashMap<>();
+            Object wanterr = step.get("err");
+
+            try {
+              invoke(client, op, ctrl);
+              if (null != wanterr) {
+                fail(label + ": " + step.get("op") + " was expected to fail, and did not");
+              }
             }
-          }
-          catch (org.opentest4j.AssertionFailedError e) {
-            throw e;
-          }
-          catch (Exception err) {
-            assertNotNull(wanterr,
-                label + ": " + step.get("op") + " failed unexpectedly: " + err);
-            if (wanterr instanceof String) {
-              // The CODE, not the message: makeError prefixes and humanises
-              // the text, so matching it would pass on any error that
-              // happened to mention the word.
-              String code = err instanceof SdkError ? ((SdkError) err).code : null;
-              assertEquals(wanterr, code, label + ": wrong error code (" + err + ")");
+            catch (org.opentest4j.AssertionFailedError e) {
+              throw e;
+            }
+            catch (Exception err) {
+              assertNotNull(wanterr,
+                  label + ": " + step.get("op") + " failed unexpectedly: " + err);
+              if (wanterr instanceof String) {
+                // The CODE, not the message: makeError prefixes and humanises
+                // the text, so matching it would pass on any error that
+                // happened to mention the word.
+                String code = err instanceof SdkError ? ((SdkError) err).code : null;
+                assertEquals(wanterr, code, label + ": wrong error code (" + err + ")");
+              }
             }
           }
-        }
 
-        subset(record(client, name), kase.get("out"), label + ": _" + name);
-        ran++;
+          subset(record(client, name), kase.get("out"), label + ": _" + name);
+        }
+        catch (AssertionError | Exception e) {
+          String msg = String.valueOf(e.getMessage());
+          failed.add(msg.startsWith(label) ? msg : label + ": " + msg);
+        }
       }
 
-      assertTrue(0 < ran, "every feature." + name + " case was skipped");
       // Say how many ran. A partial run is legitimate (an SDK with one
       // operation skips the cases needing two) but it should be visible
       // rather than inferred from a green tick.
       System.err.println(String.format(
           "feature.%s: ran %d of %d case(s) against %d operation(s)",
           name, ran, cases.size(), ops.size()));
+      if (0 == ran) {
+        failed.add("every feature." + name + " case was skipped");
+      }
+    }
+
+    if (!failed.isEmpty()) {
+      fail(failed.size() + " feature corpus case(s) failed:\n  " + String.join("\n  ", failed));
     }
   }
 }

package/project/.sdk/tm/java/test/FeatureHarness.java

@@ -203,6 +203,7 @@ public final class FeatureHarness {
       case "create":
         return "POST";
       case "update":
+      case "patch":
         return "PATCH";
       case "remove":
         return "DELETE";

package/project/.sdk/tm/java/test/FeatureTest.java

@@ -297,6 +297,39 @@ public class FeatureTest {
     assertEquals(1, f.count, "expected 1 timeout");
   }
 
+  // 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, as a paused thread did on a loaded runner. The clock stands
+  // at the start for the caller and 300 ms later for the worker, so the
+  // response is instant in real time and late by the clock.
+  @Test
+  public void timeout_lateResponseTimesOutHoweverLateTheCallerLooks() {
+    assumeFeatures("timeout");
+    TimeoutFeature f = new TimeoutFeature();
+    FhHarness h = fhMake(null, fhF(f, fhMap("ms", 20, "now", workerClock(300L))));
+    FhOpResult res = h.op(fhOp("load"));
+    assertEquals("timeout", fhErrCode(res.err), "expected timeout error, got " + res.err);
+    assertEquals(1, f.count, "expected 1 timeout");
+  }
+
+  // A transport failure after the deadline is a timeout too, not the failure.
+  @Test
+  public void timeout_lateFailureTimesOut() {
+    assumeFeatures("timeout");
+    TimeoutFeature f = new TimeoutFeature();
+    FhHarness h = fhMake((ctx, url, fetchdef) -> { throw new IllegalStateException("socket closed"); },
+        fhF(f, fhMap("ms", 20, "now", workerClock(300L))));
+    FhOpResult res = h.op(fhOp("load"));
+    assertEquals("timeout", fhErrCode(res.err), "expected timeout error, got " + res.err);
+    assertEquals(1, f.count, "expected 1 timeout");
+  }
+
+  // A clock standing at 0 for the calling thread and at `later` for any other.
+  private static LongSupplier workerClock(long later) {
+    Thread caller = Thread.currentThread();
+    return () -> Thread.currentThread() == caller ? 0L : later;
+  }
+
   @Test
   public void timeout_fastRequestPasses() {
     assumeFeatures("timeout");

package/project/.sdk/tm/java/test/PipelineTest.java

@@ -611,7 +611,10 @@ public class PipelineTest {
     Context ctx = plCtx(client, utility, null);
     ctx.spec = authSpec();
     if (cred != null && seed != null) {
-      authBag(ctx.spec, cred.where()).put(cred.name(), seed);
+      // Seed what prepareAuth would have written: cred.pair() is the
+      // `<scheme>=` lead-in for a cookie and "" for a header or query, so an
+      // opaque seed is never mistaken for a stranger's cookie.
+      authBag(ctx.spec, cred.where()).put(cred.name(), cred.pair() + seed);
     }
     utility.prepareAuth.apply(ctx);
     if (cred == null) {

package/project/.sdk/tm/java/test/RunnerSupport.java

@@ -381,6 +381,103 @@ public final class RunnerSupport {
     return new SdkError(code, msg, null);
   }
 
+  // A live check that did not pass, as main.kit.test.live.strict decides:
+  // strict fails the test, lenient skips it with the same reason.
+  public static void liveMiss(boolean strict, String reason) {
+    if (strict) {
+      org.junit.jupiter.api.Assertions.fail(reason);
+    }
+    org.junit.jupiter.api.Assumptions.abort(reason);
+  }
+
+  // An account holding no record for the test to read skips either way.
+  public static void liveEmpty(String reason) {
+    org.junit.jupiter.api.Assumptions.abort(reason);
+  }
+
+  // A live list response's records: the body, or the first list an
+  // envelope holds.
+  public static List<Object> liveList(Object data) {
+    if (data instanceof List) {
+      return (List<Object>) data;
+    }
+    if (data instanceof Map) {
+      for (Object value : new TreeMap<>((Map<String, Object>) data).values()) {
+        if (value instanceof List) {
+          return (List<Object>) value;
+        }
+      }
+    }
+    return null;
+  }
+
+  // A live response for a message: the SDK's error, or else its status and
+  // content type, never its body.
+  public static String liveDescribe(Map<String, Object> result) {
+    if (result == null) {
+      return "no response";
+    }
+    Object err = result.get("err");
+    if (err instanceof Throwable) {
+      return ((Throwable) err).getMessage();
+    }
+    if (err != null) {
+      return String.valueOf(err);
+    }
+    String out = "HTTP " + result.get("status");
+    if (result.get("headers") instanceof Map) {
+      for (Map.Entry<String, Object> e : ((Map<String, Object>) result.get("headers")).entrySet()) {
+        if ("content-type".equalsIgnoreCase(e.getKey()) && e.getValue() != null) {
+          out += " " + String.valueOf(e.getValue()).split(";")[0].trim();
+        }
+      }
+    }
+    return out;
+  }
+
+  // The record a create-less flow reads live: the first its list returns,
+  // put where the flow reads the fixture's existing records.
+  public static void liveExisting(Map<String, Object> data, boolean strict, String name,
+      Supplier<Object> list) {
+    Object found = null;
+    try {
+      found = list.get();
+    }
+    catch (RuntimeException e) {
+      liveMiss(strict, "Live list discovery failed: " + e.getMessage());
+    }
+    if (!(found instanceof List)) {
+      liveMiss(strict, "Live list discovery returned no list");
+    }
+    List<Object> items = (List<Object>) found;
+    if (items.isEmpty()) {
+      liveEmpty("The account has no " + name + " record to load");
+    }
+    Object first = items.get(0);
+    Object record = first instanceof Entity ? ((Entity) first).data() : first;
+    Object existing = data.get("existing");
+    if (!(existing instanceof Map)) {
+      existing = new LinkedHashMap<String, Object>();
+      data.put("existing", existing);
+    }
+    Map<String, Object> holder = new LinkedHashMap<>();
+    holder.put("live01", record);
+    ((Map<String, Object>) existing).put(name, holder);
+  }
+
+  // In a lenient live run a failing check skips, observing the live API.
+  public static void liveObserve(Throwable err, boolean live, boolean strict) {
+    if (strict || !live || err instanceof org.opentest4j.TestAbortedException) {
+      RunnerSupport.<RuntimeException>rethrow(err);
+    }
+    org.junit.jupiter.api.Assumptions.abort(
+        "live run, main.kit.test.live.strict is false: " + err.getMessage());
+  }
+
+  private static <T extends Throwable> void rethrow(Throwable err) throws T {
+    throw (T) err;
+  }
+
   // entityListToData extracts data maps from a list of Entity objects.
   public static List<Object> entityListToData(List<Object> list) {
     List<Object> out = new ArrayList<>();

package/project/.sdk/tm/java/utility/Clean.java

@@ -219,7 +219,8 @@ final class Clean {
   // any shape: a credential mistyped as a map or a number is still one, and
   // a message can quote it. A key under `feature` names a feature, not a
   // field, so a feature called secrets does not make its settings secret.
-  // Entity blocks (entity settings, seeded records) hold no credential.
+  // Entity blocks (entity settings, seeded records) hold no credential, and
+  // nor do rbac's rules, keyed by entity and operation names.
   static void addSensitiveOptions(Map<String, Object> cfg, Map<String, Object> opts) {
     IdentityHashMap<Object, Boolean> seen = new IdentityHashMap<>();
     for (Map.Entry<String, Object> e : opts.entrySet()) {
@@ -229,24 +230,33 @@ final class Clean {
       if ("entity".equals(key)) {
         continue;
       }
-      if ("feature".equals(key) && (val instanceof Map || val instanceof List)) {
-        Collection<?> fsets = val instanceof Map ? ((Map<?, ?>) val).values() : (List<?>) val;
-        for (Object fopts : fsets) {
-          addSensitive(cfg, noEntity(fopts), under, 2, seen);
+      if ("feature".equals(key) && val instanceof Map) {
+        for (Map.Entry<?, ?> f : ((Map<?, ?>) val).entrySet()) {
+          addSensitive(cfg, plain(f.getValue(), String.valueOf(f.getKey())), under, 2, seen);
+        }
+      }
+      else if ("feature".equals(key) && val instanceof List) {
+        for (Object fopts : (List<?>) val) {
+          Object name = fopts instanceof Map ? ((Map<?, ?>) fopts).get("name") : null;
+          addSensitive(cfg, plain(fopts, name instanceof String ? (String) name : null),
+              under, 2, seen);
         }
       }
       else {
-        addSensitive(cfg, "test".equals(key) ? noEntity(val) : val, under, 1, seen);
+        addSensitive(cfg, "test".equals(key) ? plain(val, null) : val, under, 1, seen);
       }
     }
   }
 
-  private static Object noEntity(Object block) {
+  private static Object plain(Object block, String name) {
     if (!(block instanceof Map)) {
       return block;
     }
     Map<Object, Object> out = new LinkedHashMap<>((Map<?, ?>) block);
     out.remove("entity");
+    if ("rbac".equals(name)) {
+      out.remove("rules");
+    }
     return out;
   }
 

package/project/.sdk/tm/java/utility/Fetcher.java

@@ -1,5 +1,6 @@
 package JAVAPACKAGE.utility;
 
+import java.io.InputStream;
 import java.net.InetSocketAddress;
 import java.net.ProxySelector;
 import java.net.URI;
@@ -67,6 +68,13 @@ final class Fetcher {
     if (body instanceof String && !"".equals(body)) {
       bodyPublisher = HttpRequest.BodyPublishers.ofString((String) body);
     }
+    else if (body instanceof byte[]) {
+      bodyPublisher = HttpRequest.BodyPublishers.ofByteArray((byte[]) body);
+    }
+    else if (body instanceof InputStream) {
+      InputStream stream = (InputStream) body;
+      bodyPublisher = HttpRequest.BodyPublishers.ofInputStream(() -> stream);
+    }
 
     HttpRequest.Builder reqb;
     try {
@@ -89,9 +97,14 @@ final class Fetcher {
       }
     }
     // Default User-Agent — some CDNs block Java's default. Use a
-    // Mozilla-shaped UA unless the caller already set one.
+    // Mozilla-shaped UA unless the caller already set one, and record it with
+    // the headers the request sent.
     if (!hasUA) {
-      reqb.setHeader("User-Agent", "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)");
+      String agent = "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)";
+      reqb.setHeader("User-Agent", agent);
+      if (headersRaw instanceof Map) {
+        ((Map<String, Object>) headersRaw).put("user-agent", agent);
+      }
     }
 
     HttpResponse<String> resp;
@@ -114,7 +127,17 @@ final class Fetcher {
     }
 
     String bodyText = resp.body() == null ? "" : resp.body();
-    final Object jsonBody = bodyText.isEmpty() ? null : Json.parseOrNull(bodyText);
+    Object parsed = null;
+    boolean unreadable = false;
+    if (!bodyText.isBlank()) {
+      try {
+        parsed = Json.parse(bodyText);
+      }
+      catch (RuntimeException e) {
+        unreadable = true;
+      }
+    }
+    final Object jsonBody = parsed;
 
     Map<String, Object> out = new LinkedHashMap<>();
     out.put("status", resp.statusCode());
@@ -122,6 +145,7 @@ final class Fetcher {
     out.put("headers", headers);
     out.put("json", (Supplier<Object>) () -> jsonBody);
     out.put("body", bodyText);
+    out.put("unreadable", unreadable);
     return out;
   }
 

package/project/.sdk/tm/java/utility/MakeFetchDef.java

@@ -6,7 +6,6 @@ import java.util.Map;
 import JAVAPACKAGE.core.Context;
 import JAVAPACKAGE.core.Result;
 import JAVAPACKAGE.core.Spec;
-import JAVAPACKAGE.utility.struct.Struct;
 
 final class MakeFetchDef {
 
@@ -35,12 +34,7 @@ final class MakeFetchDef {
     fetchdef.put("headers", spec.headers);
 
     if (spec.body != null) {
-      if (spec.body instanceof Map) {
-        fetchdef.put("body", Struct.jsonify(spec.body));
-      }
-      else {
-        fetchdef.put("body", spec.body);
-      }
+      fetchdef.put("body", Media.requestBody(ctx.point, spec.body));
     }
 
     return fetchdef;

package/project/.sdk/tm/java/utility/MakePoint.java

@@ -39,6 +39,41 @@ final class MakePoint {
     return last instanceof String && ((String) last).startsWith("{");
   }
 
+  private static final java.util.regex.Pattern PATH_PARAM =
+      java.util.regex.Pattern.compile("\\{([^{}/]+)\\}");
+
+  // The path parameters of a point that neither the call nor the entity gives
+  // a value for, looked up as prepareParams looks them up.
+  private static List<String> unfilled(Context ctx, Map<String, Object> point) {
+    List<String> missing = new ArrayList<>();
+    Object parts = Struct.getprop(point, "parts");
+    if (parts instanceof List) {
+      for (Object part : (List<Object>) parts) {
+        java.util.regex.Matcher found = PATH_PARAM.matcher(String.valueOf(part));
+        if (found.matches() && Param.paramValue(ctx, point, found.group(1)) == null) {
+          missing.add(found.group(1));
+        }
+      }
+    }
+    return missing;
+  }
+
+  private static Map<String, Object> ownPoint(List<Map<String, Object>> points) {
+    Map<String, Object> best = points.get(0);
+    for (Map<String, Object> cand : points) {
+      boolean candTerm = terminalParam(cand);
+      boolean bestTerm = terminalParam(best);
+      if (candTerm != bestTerm) {
+        if (candTerm) {
+          best = cand;
+        }
+      } else if (partsLen(cand) < partsLen(best)) {
+        best = cand;
+      }
+    }
+    return best;
+  }
+
   static Map<String, Object> makePoint(Context ctx) {
     Object outPoint = ctx.out.get("point");
     if (outPoint != null) {
@@ -59,7 +94,7 @@ final class MakePoint {
 
     Object allowOpRaw = Struct.getpath(options, List.of("allow", "op"));
     String allowOp = allowOpRaw instanceof String ? (String) allowOpRaw : "";
-    if (!allowOp.contains(op.name)) {
+    if (!Helpers.allowed(allowOpRaw, op.name)) {
       throw ctx.makeError("point_op_allow",
           "Operation \"" + op.name
               + "\" not allowed by SDK option allow.op value: \"" + allowOp + "\"");
@@ -141,18 +176,35 @@ final class MakePoint {
                   + "\" action \"" + Struct.stringify(unmatchedAction) + "\" is not valid.");
         }
 
-        point = op.points.get(0);
+        // A call without an action falls back to a point without one, as
+        // generation does, and only to a route the call can fill.
+        List<Map<String, Object>> plain = new ArrayList<>();
         for (Map<String, Object> cand : op.points) {
-          boolean candTerm = terminalParam(cand);
-          boolean bestTerm = terminalParam(point);
-          if (candTerm != bestTerm) {
-            if (candTerm) {
-              point = cand;
-            }
-          } else if (partsLen(cand) < partsLen(point)) {
-            point = cand;
+          Map<String, Object> candSelect = Helpers.toMapAny(Struct.getprop(cand, "select"));
+          if (Struct.getprop(candSelect, "$action", null) == null) {
+            plain.add(cand);
+          }
+        }
+        if (plain.isEmpty()) {
+          throw ctx.makeError("point_action_required",
+              "Operation \"" + op.name
+                  + "\" has only action endpoints; pass $action to choose one.");
+        }
+        List<Map<String, Object>> fillable = new ArrayList<>();
+        for (Map<String, Object> cand : plain) {
+          if (unfilled(ctx, cand).isEmpty()) {
+            fillable.add(cand);
           }
         }
+
+        if (fillable.isEmpty()) {
+          throw ctx.makeError("point_no_match",
+              "Operation \"" + op.name
+                  + "\" has no endpoint whose path parameters are all given (missing: "
+                  + String.join(", ", unfilled(ctx, ownPoint(plain))) + ").");
+        }
+
+        point = ownPoint(fillable);
       }
 
       if (reqselector != null) {

package/project/.sdk/tm/java/utility/MakeSpec.java

@@ -1,10 +1,13 @@
 package JAVAPACKAGE.utility;
 
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 import JAVAPACKAGE.core.Context;
+import JAVAPACKAGE.core.Helpers;
 import JAVAPACKAGE.core.Spec;
 import JAVAPACKAGE.core.Utility;
 import JAVAPACKAGE.utility.struct.Struct;
@@ -16,6 +19,11 @@ final class MakeSpec {
 
   static Spec makeSpec(Context ctx) {
     Object outSpec = ctx.out.get("spec");
+    // A PreSpec hook (validate) rejects the operation by placing its error
+    // here; the pipeline raises it, and ctx.spec stays a request spec.
+    if (outSpec instanceof RuntimeException) {
+      throw (RuntimeException) outSpec;
+    }
     if (outSpec instanceof Spec) {
       ctx.spec = (Spec) outSpec;
       return ctx.spec;
@@ -47,7 +55,7 @@ final class MakeSpec {
     String allowMethod = allowMethodRaw instanceof String ? (String) allowMethodRaw : "";
     // null-safe: an op outside the convention resolves NO method (see
     // PrepareMethod), which the allow list can never contain.
-    if (null == ctx.spec.method || !allowMethod.contains(ctx.spec.method)) {
+    if (!Helpers.allowed(allowMethodRaw, ctx.spec.method)) {
       throw ctx.makeError("spec_method_allow",
           "Method \"" + ctx.spec.method
               + "\" not allowed by SDK option allow.method value: \"" + allowMethod + "\"");
@@ -78,8 +86,25 @@ final class MakeSpec {
       ctx.ctrl.explain.put("spec", ctx.spec);
     }
 
+    // Whatever prepareAuth sets in the query, under whichever name, is the
+    // credential; a key it leaves as it was is the caller's.
+    Map<String, Object> query = new LinkedHashMap<>();
+    if (ctx.spec.query != null) {
+      query.putAll(ctx.spec.query);
+    }
+
     Spec spec = utility.prepareAuth.apply(ctx);
 
+    if (spec != null && spec.query != null) {
+      spec.authquery = new ArrayList<>();
+      for (Map.Entry<String, Object> entry : spec.query.entrySet()) {
+        String key = entry.getKey();
+        if (!query.containsKey(key) || !Objects.equals(query.get(key), entry.getValue())) {
+          spec.authquery.add(key);
+        }
+      }
+    }
+
     ctx.spec = spec;
     return spec;
   }