@voxgig/sdkgen 4.23.0 → 4.24.1

package/project/.sdk/tm/py/test/test_pipeline.py

@@ -13,6 +13,8 @@
 #   result_body utility (it has no parse guard), so that ts case is
 #   omitted.
 
+import re
+
 import pytest
 
 from projectname_sdk import ProjectNameSDK
@@ -495,6 +497,10 @@ class TestFeatureOrdering:
 
 class TestPrepareAuth:
 
+    # A cookie credential as prepare_auth writes it: `<scheme>=K` for the
+    # probe key, with no scheme prefix and nothing else in the bag.
+    COOKIE_PAIR = re.compile(r"^[^=;]+=K$")
+
     class _AuthClient:
         def __init__(self, options):
             self._options = options
@@ -503,57 +509,128 @@ class TestPrepareAuth:
             return self._options
 
     # Fake client so the exact options.auth / apikey shape is controlled.
-    def _auth_ctx(self, client, options, headers):
+    def _auth_ctx(self, client, options, spec):
         utility = client._utility
         ctx = utility.make_context({"opname": "load"}, client.get_root_ctx())
         ctx.client = self._AuthClient(options)
-        ctx.spec = None if headers is None else ProjectNameSpec(
-            {"headers": headers})
+        ctx.spec = spec
         return ctx
 
+    @staticmethod
+    def _bags():
+        return ProjectNameSpec({"headers": {}, "query": {}})
+
+    @staticmethod
+    def _bag(spec, where):
+        # A cookie credential rides the header bag, because a cookie IS a
+        # header.
+        return spec.query if "query" == where else spec.headers
+
+    @staticmethod
+    def _auth(prefix):
+        # `basic: false` is explicit: an HTTP Basic API's generated config
+        # carries `auth.basic: true`, and a client that merges it in takes a
+        # branch that needs a secret as well. With none supplied that branch
+        # deliberately writes nothing, which the probe reads as a public API.
+        return {"prefix": prefix, "basic": False}
+
+    # Run prepare_auth with both containers present and see which one the
+    # generated utility writes to, and under what name. None means this SDK
+    # places no credential at all - a public API - which is a legitimate
+    # shape, and the tests below assert exactly that instead. `pair` is the
+    # `<scheme>=` lead-in of a COOKIE credential, which rides the header bag
+    # under the key `cookie` instead of taking a header of its own.
+    def _probe(self, client, options):
+        ctx = self._auth_ctx(client, options, self._bags())
+        client._utility.prepare_auth(ctx)
+        for where in ("headers", "query"):
+            bag = self._bag(ctx.spec, where)
+            for name in bag:
+                value = bag[name]
+                pair = ""
+                if ("headers" == where and "cookie" == name
+                        and isinstance(value, str)
+                        and self.COOKIE_PAIR.match(value)):
+                    pair = value[:-1]
+                return {"where": where, "name": name, "value": value, "pair": pair}
+        return None
+
+    def _credential(self, client):
+        return self._probe(
+            client, {"apikey": "K", "auth": self._auth("Bearer")})
+
+    # Every credential this SDK could possibly place: both credentials and
+    # Basic switched on, so whichever branch the API has, something lands
+    # unless the API is public.
+    def _any_credential(self, client):
+        return self._probe(client, {
+            "apikey": "K", "secret": "S",
+            "auth": {"prefix": "Bearer", "basic": True}})
+
+    def _placed(self, client, options, seed=None):
+        cred = self._credential(client)
+        spec = self._bags()
+        if cred is not None and seed is not None:
+            self._bag(spec, cred["where"])[cred["name"]] = seed
+        ctx = self._auth_ctx(client, options, spec)
+        client._utility.prepare_auth(ctx)
+        if cred is None:
+            return None
+        return self._bag(ctx.spec, cred["where"]).get(cred["name"])
+
     def test_guards_a_missing_spec(self):
         client = _client()
         ctx = self._auth_ctx(client,
-                             {"auth": {"prefix": ""}, "apikey": "K"}, None)
+                             {"auth": self._auth(""), "apikey": "K"}, None)
         _, err = client._utility.prepare_auth(ctx)
         assert err.code == "auth_no_spec"
 
-    def test_an_apikey_with_a_prefix_is_space_joined(self):
-        client = _client()
-        ctx = self._auth_ctx(client,
-                             {"apikey": "K", "auth": {"prefix": "Bearer"}}, {})
-        _, err = client._utility.prepare_auth(ctx)
-        assert err is None
-        assert ctx.spec.headers["authorization"] == "Bearer K"
+    # Without this the cases below cannot fail for an SDK whose credential the
+    # probe misses: every one of them takes the public-API path instead.
+    def test_the_probe_finds_the_credential_this_sdk_places(self):
+        client = _client()
+        assert (self._credential(client) is None) == (
+            self._any_credential(client) is None)
+
+    def test_the_apikey_is_placed_where_this_api_puts_it(self):
+        client = _client()
+        cred = self._credential(client)
+        if cred is None:
+            # A public API places nothing, and that is the whole assertion.
+            assert self._placed(
+                client, {"apikey": "K", "auth": self._auth("Bearer")}) is None
+            return
+        assert cred["where"] in ("headers", "query")
+        if "" != cred["pair"]:
+            # A cookie credential is a `<scheme>=<key>` pair, and the scheme
+            # name leaves no room for the option's prefix.
+            assert self.COOKIE_PAIR.match(cred["value"]), cred["value"]
+            return
+        # A header credential is prefix-joined; a query credential is the raw
+        # key, because a query parameter has nowhere to put a scheme name.
+        assert cred["value"] == ("K" if "query" == cred["where"] else "Bearer K")
 
     def test_a_raw_apikey_goes_in_as_is(self):
         client = _client()
-        ctx = self._auth_ctx(client,
-                             {"apikey": "K", "auth": {"prefix": ""}}, {})
-        client._utility.prepare_auth(ctx)
-        assert ctx.spec.headers["authorization"] == "K"
+        cred = self._credential(client)
+        expected = None if cred is None else cred["pair"] + "K"
+        assert self._placed(
+            client, {"apikey": "K", "auth": self._auth("")}) == expected
 
-    def test_an_empty_apikey_drops_the_header(self):
+    def test_an_empty_apikey_drops_the_credential(self):
         client = _client()
-        ctx = self._auth_ctx(client,
-                             {"apikey": "", "auth": {"prefix": "Bearer"}},
-                             {"authorization": "stale"})
-        client._utility.prepare_auth(ctx)
-        assert ctx.spec.headers.get("authorization") is None
+        assert self._placed(
+            client, {"apikey": "", "auth": self._auth("Bearer")},
+            "stale") is None
 
-    def test_a_public_api_with_no_auth_block_drops_the_header(self):
+    def test_a_public_api_with_no_auth_block_drops_the_credential(self):
         client = _client()
-        ctx = self._auth_ctx(client, {"apikey": "K"},
-                             {"authorization": "stale"})
-        client._utility.prepare_auth(ctx)
-        assert ctx.spec.headers.get("authorization") is None
+        assert self._placed(client, {"apikey": "K"}, "stale") is None
 
-    def test_a_missing_apikey_option_drops_the_header(self):
+    def test_a_missing_apikey_option_drops_the_credential(self):
         client = _client()
-        ctx = self._auth_ctx(client, {"auth": {"prefix": "Bearer"}},
-                             {"authorization": "stale"})
-        client._utility.prepare_auth(ctx)
-        assert ctx.spec.headers.get("authorization") is None
+        assert self._placed(
+            client, {"auth": self._auth("Bearer")}, "stale") is None
 
 
 class TestResultHelpers:

package/project/.sdk/tm/py/test/test_primary_utility.py

@@ -47,6 +47,63 @@ client = _run['client']['sdk']
 utility = client._utility
 
 
+def _auth_bag(spec_obj, where):
+    # A cookie credential rides the header bag, because a cookie IS a header.
+    return spec_obj.query if "query" == where else spec_obj.headers
+
+
+class _AuthProbeClient:
+    """Minimal stand-in so the probe below controls the apikey: the suite's
+    own client carries whatever options a project configured, and an empty
+    apikey places no credential to find."""
+
+    def options_map(self):
+        # `basic: False`: a Basic API's config defaults it true, and the branch
+        # it selects needs a secret, so the probe would find nothing.
+        return {"apikey": "PROBE", "auth": {"prefix": "", "basic": False}}
+
+
+def _auth_credential():
+    """Which container the generated prepare_auth writes the credential
+    into, and under what name. The name is the API's OWN scheme name, so it
+    is discovered by running prepare_auth once rather than assumed."""
+    ctx = _make_test_ctx(client, utility)
+    ctx.client = _AuthProbeClient()
+    ctx.spec = ProjectNameSpec({"headers": {}, "query": {}})
+    try:
+        utility.prepare_auth(ctx)
+    except Exception:
+        return None
+    for where in ("headers", "query"):
+        bag = _auth_bag(ctx.spec, where)
+        for name in bag:
+            return {"where": where, "name": name}
+    return None
+
+
+def _retarget_auth(node, cred):
+    """Rename the corpus's `headers` bag to the real container, and the
+    `authorization` key inside it to the real credential name. Applied only
+    to the prepareAuth section, so real header assertions elsewhere are
+    untouched."""
+    if isinstance(node, list):
+        return [_retarget_auth(n, cred) for n in node]
+    if not isinstance(node, dict):
+        return node
+    out = {}
+    for key in node:
+        if "headers" == key:
+            bag = {}
+            inner = node[key] if isinstance(node[key], dict) else {}
+            for bagkey in inner:
+                name = cred["name"] if "authorization" == bagkey else bagkey
+                bag[name] = _retarget_auth(inner[bagkey], cred)
+            out[cred["where"]] = bag
+        else:
+            out[key] = _retarget_auth(node[key], cred)
+    return out
+
+
 # Sections deliberately left empty in the shared corpus
 # (.sdk/test/primary/<name>.aon carries a PENDING header). Everything else
 # MUST contribute cases.
@@ -538,7 +595,25 @@ class TestPrimaryUtility:
             ctx.client = auth_client
             return _unwrap(utility.prepare_auth(ctx))
 
-        runsection('prepareAuth', subject)
+        # The corpus writes the credential as `headers.authorization`: a
+        # PLACEHOLDER each runner points at the container and name this API
+        # actually uses.
+        cred = _auth_credential()
+        assert cred is not None, \
+            'prepare_auth placed no credential in headers or query'
+
+        # An absent section is runsection's report to make.
+        section = spec.get('prepareAuth') if isinstance(spec, dict) else None
+        swap = isinstance(section, dict) and (
+            'headers' != cred['where'] or 'authorization' != cred['name'])
+        original = section['basic'] if swap else None
+        if swap:
+            section['basic'] = _retarget_auth(original, cred)
+        try:
+            runsection('prepareAuth', subject)
+        finally:
+            if swap:
+                section['basic'] = original
 
     def test_prepare_body_basic(self):
         runsection('prepareBody', lambda ctx: utility.prepare_body(ctx))

package/project/.sdk/tm/rb/core/context.rb

@@ -30,7 +30,7 @@ class ProjectNameContext
       @ctrl.explain = ctrl_raw["explain"] if ctrl_raw["explain"].is_a?(Hash)
       @ctrl.actor = ctrl_raw["actor"] if ctrl_raw.key?("actor")
       @ctrl.paging = ctrl_raw["paging"] if ctrl_raw["paging"].is_a?(Hash)
-    elsif basectx&.ctrl
+    elsif basectx&.ctrl && ProjectNameHelpers.get_ctx_prop(ctxmap, "opname").nil?
       @ctrl = basectx.ctrl
     end
 

package/project/.sdk/tm/rb/feature/paging_feature.rb

@@ -4,8 +4,8 @@
 # stamps page/limit (or a cursor) into the request query; on the way back
 # (PreResult) it reads the server's pagination signals - a Link rel="next"
 # header, X-Page/X-Next-Page/X-Total-Count headers, or next/cursor/
-# nextCursor/hasMore fields in the body - and records them on
-# result.paging. A per-call ctrl paging value (page or cursor) takes
+# nextCursor/hasMore fields in the body (snake_case forms too) - and records
+# them on result.paging and the caller's ctrl paging. A per-call ctrl paging value (page or cursor) takes
 # priority. Parameter names ("pageParam", "limitParam", "cursorParam"),
 # "startPage" (default 1) and page size ("limit") are configurable.
 
@@ -56,8 +56,10 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
     if !paging["cursor"].nil?
       spec.query[cursor_param] = paging["cursor"]
     elsif spec.query[page_param].nil?
-      spec.query[page_param] =
-        paging["page"].nil? ? (@options["startPage"] || 1) : paging["page"]
+      # A record written back by PreResult holds the page just fetched as
+      # "page" and the one to fetch as "nextPage", so nextPage wins.
+      page = paging["nextPage"].nil? ? paging["page"] : paging["nextPage"]
+      spec.query[page_param] = page.nil? ? (@options["startPage"] || 1) : page
     end
 
     if !@options["limit"].nil? && spec.query[limit_param].nil?
@@ -158,11 +160,20 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
       paging["next"] = m[1] if m
     end
 
-    # Body-level cursors.
+    # Body-level signals; snake_case forms are read first so camelCase wins.
     if body.is_a?(Hash)
       paging["next"] = paging["next"] || body["next"] unless body["next"].nil?
+      paging["cursor"] = body["next_cursor"] unless body["next_cursor"].nil?
       paging["cursor"] = body["cursor"] unless body["cursor"].nil?
       paging["cursor"] = body["nextCursor"] unless body["nextCursor"].nil?
+      if paging["nextPage"].nil?
+        np = body["nextPage"].nil? ? body["next_page"] : body["nextPage"]
+        paging["nextPage"] = np if np.is_a?(Numeric) || np.is_a?(String)
+      end
+      if body["has_more"] == true || body["has_more"] == false
+        paging["hasMore"] = body["has_more"]
+        explicit_more = true
+      end
       if body["hasMore"] == true || body["hasMore"] == false
         paging["hasMore"] = body["hasMore"]
         explicit_more = true
@@ -181,6 +192,17 @@ class ProjectNamePagingFeature < ProjectNameBaseFeature
 
     result.paging = paging
 
+    if ctx.ctrl && ctx.ctrl.respond_to?(:paging=)
+      # The Context shares the caller's paging hash by reference, so refill
+      # it in place; a fresh hash on ctrl never reaches the caller.
+      if ctx.ctrl.paging.is_a?(Hash)
+        ctx.ctrl.paging.clear
+        ctx.ctrl.paging.merge!(paging)
+      else
+        ctx.ctrl.paging = paging
+      end
+    end
+
     @client.instance_variable_set(:@_paging, { "last" => paging })
   end
 

package/project/.sdk/tm/rb/feature/test_feature.rb

@@ -127,12 +127,10 @@ class ProjectNameTestFeature < ProjectNameBaseFeature
         args = test_self.build_args(fctx, op, update_match)
         found = VoxgigStruct.select(entmap, args)
         ent = VoxgigStruct.getelem(found, 0)
-        if ent.nil? && entmap.is_a?(Hash) && !entmap.empty?
-          ent = entmap.values.find { |e| e.is_a?(Hash) }
-        end
+        # update miss: 404, never another record
         return respond.call(404, nil, { "statusText" => "Not found" }) unless ent
-        if ent.is_a?(Hash) && fctx.reqdata
-          fctx.reqdata.each { |k, v| ent[k] = v }
+        if ent.is_a?(Hash) && fctx.reqdata.is_a?(Hash)
+          VoxgigStruct.merge([ent, fctx.reqdata])
         end
         VoxgigStruct.delprop(ent, "$KEY")
         out = VoxgigStruct.clone(ent)
@@ -237,14 +235,42 @@ class ProjectNameTestFeature < ProjectNameBaseFeature
     }
   end
 
+  # The entity's own endpoint: a terminal `{param}` marks a record route,
+  # and among equals the shallower path wins (the same rule as make_point).
+  def pick_point(points)
+    return nil unless points.is_a?(Array) && !points.empty?
+    terminal = ->(p) {
+      parts = VoxgigStruct.getprop(p, "parts")
+      parts.is_a?(Array) && !parts.empty? && parts[-1].is_a?(String) && parts[-1].start_with?("{")
+    }
+    depth = ->(p) {
+      parts = VoxgigStruct.getprop(p, "parts")
+      parts.is_a?(Array) ? parts.length : 0
+    }
+    point = points[0]
+    points[1..].each do |cand|
+      if terminal.call(cand) != terminal.call(point)
+        point = cand if terminal.call(cand)
+      elsif depth.call(cand) < depth.call(point)
+        point = cand
+      end
+    end
+    point
+  end
+
   def build_args(ctx, op, args)
     opname = op.name
     points = VoxgigStruct.getpath(ctx.config, "entity.#{ctx.entity.get_name}.op.#{opname}.points")
-    point = VoxgigStruct.getelem(points, -1)
+    point = pick_point(points)
 
+    # Path AND query: a path-only read misses a query-addressed record
+    # (e.g. GET /result?trace_id=), which has no path param at all.
     params_path = VoxgigStruct.getpath(point, "args.params")
     reqd_params = VoxgigStruct.select(params_path, { "reqd" => true })
-    reqd = VoxgigStruct.transform(reqd_params, ["`$EACH`", "", "`$KEY.name`"])
+    query_path = VoxgigStruct.getpath(point, "args.query")
+    reqd_query = VoxgigStruct.select(query_path, { "reqd" => true })
+    reqd = (VoxgigStruct.transform(reqd_params, ["`$EACH`", "", "`$KEY.name`"]) || []) +
+      (VoxgigStruct.transform(reqd_query, ["`$EACH`", "", "`$KEY.name`"]) || [])
 
     qand = []
     q = { "`$AND`" => qand }

package/project/.sdk/tm/rb/test/feature_corpus_test.rb

@@ -200,6 +200,13 @@ class FeatureCorpusTest < Minitest::Test
     assert_equal expect, actual, path
   end
 
+  # Whether the SDK built the feature at all. The activity record is the
+  # wrong probe: most features create theirs on first use, so an idle
+  # client has none and every section but the eager ones read as inert.
+  def present?(client, name)
+    (client.features || []).any? { |f| f.respond_to?(:name) && f.name == name }
+  end
+
   def record(client, name)
     # A corpus key is any manifest item name, so it may carry characters
     # (foo-bar, foo.2) that cannot form a Ruby instance-variable name. The
@@ -246,7 +253,11 @@ class FeatureCorpusTest < Minitest::Test
       # Probed by ACTIVATING it: the feature defaults to inactive, so an idle
       # client never builds it and its absence says nothing.
       probe = build_client({ "feature" => [{ "name" => name, "active" => true }] })
-      next if record(probe, name).nil?
+      unless present?(probe, name)
+        # The one line every runner prints for an inert section.
+        puts "feature.#{name}: inert (this SDK does not generate the feature)"
+        next
+      end
 
       ops = usable_ops(2)
       by_key = ops.each_with_object({}) { |o, h| h[o["key"]] = o }

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

@@ -911,6 +911,44 @@ class FeatureTest < Minitest::Test
     assert_equal true, res["result"].paging["hasMore"]
   end
 
+  def test_paging_snake_case_signals_and_ctrl_write_back
+    skip_unless_feature("paging")
+    server, calls = H.recording_server { |n, _fd|
+      body = 1 == n ? { "has_more" => true, "next_cursor" => "c2" } : { "has_more" => false }
+      [H.make_response(200, body), nil]
+    }
+    h = harness([fspec("paging")], server: server)
+    pg = {}
+    ctrl = { "paging" => pg }
+    res = h.op(opname: "list", path: "/w", ctrl: ctrl)
+    assert_equal true, res["result"].paging["hasMore"]
+    assert_equal "c2", res["result"].paging["cursor"]
+    assert_equal "c2", pg["cursor"], "record written back into ctrl"
+    assert_equal true, pg["hasMore"]
+    h.op(opname: "list", path: "/w", ctrl: ctrl)
+    assert_match(/[?&]cursor=c2(&|\z)/, calls[1]["url"])
+    assert_equal false, pg["hasMore"]
+    assert_nil pg["cursor"]
+  end
+
+  def test_paging_continues_from_written_back_next_page
+    skip_unless_feature("paging")
+    server, calls = H.recording_server { |n, _fd|
+      body = 1 == n ? { "next_page" => 2 } : {}
+      [H.make_response(200, body, "x-page" => n.to_s), nil]
+    }
+    h = harness([fspec("paging")], server: server)
+    pg = {}
+    ctrl = { "paging" => pg }
+    h.op(opname: "list", path: "/w", ctrl: ctrl)
+    assert_equal 1, pg["page"]
+    assert_equal 2, pg["nextPage"]
+    assert_equal true, pg["hasMore"]
+    h.op(opname: "list", path: "/w", ctrl: ctrl)
+    assert_match(/[?&]page=2(&|\z)/, calls[1]["url"])
+    assert_equal false, pg["hasMore"]
+  end
+
   def test_paging_non_list_op_is_not_paged
     skip_unless_feature("paging")
     server, calls = H.recording_server

package/project/.sdk/tm/rb/test/pipeline_test.rb

@@ -513,52 +513,128 @@ class PipelineTest < Minitest::Test
 
   # === prepare_auth ===
 
-  def auth_ctx(options, headers)
+  # A cookie credential as prepare_auth writes it: `<scheme>=K` for the probe
+  # key, with no scheme prefix and nothing else in the bag.
+  COOKIE_PAIR = /\A[^=;]+=K\z/
+
+  def auth_ctx(options, spec)
     ctx = ProjectNameContext.new({
       "client" => OptClient.new(options),
       "utility" => @utility,
       "opname" => "load",
     }, nil)
-    ctx.spec = headers.nil? ? nil : ProjectNameSpec.new({ "headers" => headers, "step" => "s" })
+    ctx.spec = spec
     ctx
   end
 
+  def auth_bags
+    ProjectNameSpec.new({ "headers" => {}, "query" => {}, "step" => "s" })
+  end
+
+  # A cookie credential rides the header bag, because a cookie IS a header.
+  def auth_bag(spec, where)
+    "query" == where ? spec.query : spec.headers
+  end
+
+  # `basic: false` is explicit: an HTTP Basic API's generated config carries
+  # `auth.basic: true`, and a client that merges it in takes a branch that
+  # needs a secret as well. With none supplied that branch deliberately writes
+  # nothing, which the probe would read as a public API.
+  def auth_block(prefix)
+    { "prefix" => prefix, "basic" => false }
+  end
+
+  # Run prepare_auth with both containers present and see which one the
+  # generated utility writes to, and under what name. nil means this SDK
+  # places no credential at all - a public API - which is a legitimate shape,
+  # and the tests below assert exactly that instead. `pair` is the `<scheme>=`
+  # lead-in of a COOKIE credential, which rides the header bag under the key
+  # `cookie` instead of taking a header of its own.
+  def auth_probe(options)
+    ctx = auth_ctx(options, auth_bags)
+    @utility.prepare_auth.call(ctx)
+    ["headers", "query"].each do |where|
+      bag = auth_bag(ctx.spec, where)
+      bag.each do |name, value|
+        pair = ""
+        if "headers" == where && "cookie" == name && value.is_a?(String) &&
+           COOKIE_PAIR.match?(value)
+          pair = value[0..-2]
+        end
+        return { "where" => where, "name" => name, "value" => value, "pair" => pair }
+      end
+    end
+    nil
+  end
+
+  def auth_credential
+    auth_probe({ "apikey" => "K", "auth" => auth_block("Bearer") })
+  end
+
+  # Every credential this SDK could possibly place: both credentials and Basic
+  # switched on, so whichever branch the API has, something lands unless the
+  # API is public.
+  def auth_any_credential
+    auth_probe({ "apikey" => "K", "secret" => "S",
+                 "auth" => { "prefix" => "Bearer", "basic" => true } })
+  end
+
+  def auth_placed(options, seed = nil)
+    cred = auth_credential
+    spec = auth_bags
+    auth_bag(spec, cred["where"])[cred["name"]] = seed if !cred.nil? && !seed.nil?
+    ctx = auth_ctx(options, spec)
+    @utility.prepare_auth.call(ctx)
+    cred.nil? ? nil : auth_bag(ctx.spec, cred["where"])[cred["name"]]
+  end
+
   def test_prepare_auth_guards_a_missing_spec
-    ctx = auth_ctx({ "auth" => { "prefix" => "" }, "apikey" => "K" }, nil)
+    ctx = auth_ctx({ "auth" => auth_block(""), "apikey" => "K" }, nil)
     _, err = @utility.prepare_auth.call(ctx)
     assert_equal "auth_no_spec", err.code
   end
 
-  def test_prepare_auth_an_apikey_with_a_prefix_is_space_joined
-    ctx = auth_ctx({ "apikey" => "K", "auth" => { "prefix" => "Bearer" } }, {})
-    _, err = @utility.prepare_auth.call(ctx)
-    assert_nil err
-    assert_equal "Bearer K", ctx.spec.headers["authorization"]
+  # Without this the cases below cannot fail for an SDK whose credential the
+  # probe misses: every one of them takes the public-API path instead.
+  def test_prepare_auth_probe_finds_the_credential_this_sdk_places
+    assert_equal auth_credential.nil?, auth_any_credential.nil?
+  end
+
+  def test_prepare_auth_places_the_apikey_where_this_api_puts_it
+    cred = auth_credential
+    if cred.nil?
+      # A public API places nothing, and that is the whole assertion.
+      assert_nil auth_placed({ "apikey" => "K", "auth" => auth_block("Bearer") })
+      return
+    end
+    assert_includes ["headers", "query"], cred["where"]
+    if "" != cred["pair"]
+      # A cookie credential is a `<scheme>=<key>` pair, and the scheme name
+      # leaves no room for the option's prefix.
+      assert_match COOKIE_PAIR, cred["value"]
+      return
+    end
+    # A header credential is prefix-joined; a query credential is the raw
+    # key, because a query parameter has nowhere to put a scheme name.
+    assert_equal("query" == cred["where"] ? "K" : "Bearer K", cred["value"])
   end
 
   def test_prepare_auth_a_raw_apikey_goes_in_as_is
-    ctx = auth_ctx({ "apikey" => "K", "auth" => { "prefix" => "" } }, {})
-    @utility.prepare_auth.call(ctx)
-    assert_equal "K", ctx.spec.headers["authorization"]
+    cred = auth_credential
+    expected = cred.nil? ? nil : cred["pair"] + "K"
+    assert_equal expected, auth_placed({ "apikey" => "K", "auth" => auth_block("") })
   end
 
-  def test_prepare_auth_an_empty_apikey_drops_the_header
-    ctx = auth_ctx({ "apikey" => "", "auth" => { "prefix" => "Bearer" } },
-      { "authorization" => "stale" })
-    @utility.prepare_auth.call(ctx)
-    assert_nil ctx.spec.headers["authorization"]
+  def test_prepare_auth_an_empty_apikey_drops_the_credential
+    assert_nil auth_placed({ "apikey" => "", "auth" => auth_block("Bearer") }, "stale")
   end
 
-  def test_prepare_auth_a_public_api_drops_the_header
-    ctx = auth_ctx({ "apikey" => "K" }, { "authorization" => "stale" })
-    @utility.prepare_auth.call(ctx)
-    assert_nil ctx.spec.headers["authorization"]
+  def test_prepare_auth_a_public_api_drops_the_credential
+    assert_nil auth_placed({ "apikey" => "K" }, "stale")
   end
 
-  def test_prepare_auth_a_missing_apikey_option_drops_the_header
-    ctx = auth_ctx({ "auth" => { "prefix" => "Bearer" } }, { "authorization" => "stale" })
-    @utility.prepare_auth.call(ctx)
-    assert_nil ctx.spec.headers["authorization"]
+  def test_prepare_auth_a_missing_apikey_option_drops_the_credential
+    assert_nil auth_placed({ "auth" => auth_block("Bearer") }, "stale")
   end