@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/ocaml/ReadmeTopTest_ocaml.ts

@@ -6,12 +6,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlListMatch, ocamlOpField, ocamlVarName } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a field's canonical type.
 function ocamlLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -37,15 +38,11 @@ let () =
   if (exampleEntity && primaryOp) {
     const fn = ocamlVarName(exampleEntity.name)
     const idF = entityIdField(exampleEntity)
-    const field =
-      'load' === primaryOp ? 'e_load' :
-        'list' === primaryOp ? 'e_list' :
-          'create' === primaryOp ? 'e_create' :
-            'update' === primaryOp ? 'e_update' : 'e_remove'
+    const field = ocamlOpField(primaryOp)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'Noval'
     if ('list' === primaryOp) {
-      arg = '(empty_map ())'
+      arg = ocamlListMatch(exampleEntity)
     } else if (isMatchOp) {
       // Every REQUIRED match key (id first).
       const items = opRequestShape(exampleEntity, primaryOp).items
@@ -56,7 +53,7 @@ let () =
         ? `(jo [${items.map((it: any) =>
           `("${it.name}", ${it.name === idF ? '(Str "test01")' : ocamlLit(it.type)})`).join('; ')}])`
         : '(empty_map ())'
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)

package/project/.sdk/src/cmp/ocaml/TestClean_ocaml.ts

@@ -62,6 +62,7 @@ function candidates(entity: any[]): string {
         : 'load' === op ? `(ent.e_load m ctrl).e_data_get ()`
           : 'create' === op ? `(ent.e_create m ctrl).e_data_get ()`
             : 'update' === op ? `(ent.e_update m ctrl).e_data_get ()`
+            : 'patch' === op ? `(ent.e_patch m ctrl).e_data_get ()`
               : 'remove' === op ? `(ent.e_remove m ctrl).e_data_get ()`
                 : null
       if (null == run) continue
@@ -69,7 +70,9 @@ function candidates(entity: any[]): string {
         rank: OP_ORDER[op] ?? 2,
         text: `  { c_name = "${ocamlString(e.name + '.' + op)}";
     c_params = [${pointParams(e.op[op]).map((p) => '"' + ocamlString(p) + '"').join('; ')}];
-    c_run = (fun sdk m ctrl -> let ent = Sdk_client.${fn} sdk Noval in ${run});
+    c_run = (fun sdk m ctrl mtch ->
+        let ent = Sdk_client.${fn} sdk Noval in
+        Fun.protect ~finally:(fun () -> mtch := ent.e_match_get ()) (fun () -> ${run}));
     c_stream = (fun sdk m callopts ->
         let ent = Sdk_client.${fn} sdk Noval in List.of_seq (ent.e_stream "${op}" m callopts)) };`,
       })
@@ -182,7 +185,22 @@ let scenarios : scenario list = [
             ("body", Str "<html>");
             ("json", Func (fun _ _ _ _ -> failwith "Unexpected token < in JSON"))]) } ]
 
-let make_sdk ?(extra = []) (sc : scenario) (sinks : sinks) (cleanopts : (string * value) list) : sdk_client =
+(* Offline, as every generated suite is: the test OPTION resolves a required
+ * server variable to test-<name>, and installs no transport. *)
+let offline (opts : value) : value =
+  setp opts "test" (jo [("active", Bool true)]);
+  opts
+
+(* A client the sweep cannot build leaves nothing swept: a harness error, not
+ * a leak. *)
+let construct (opts : value) : sdk_client =
+  try Sdk_client.make (offline opts)
+  with e ->
+    failwith ("clean harness: the client could not be constructed, so nothing was swept: "
+              ^ Printexc.to_string e)
+
+let make_sdk ?(extra = []) ?(auth = Noval) (sc : scenario) (sinks : sinks)
+    (cleanopts : (string * value) list) : sdk_client =
   let capture name = vfunc1 (fun record -> value_forms sinks name record; Noval) in
   let feature = empty_map () in
   let on name kvs = if Harness.has_feature name then setp feature name (jo (("active", Bool true) :: kvs)) in
@@ -198,11 +216,13 @@ let make_sdk ?(extra = []) (sc : scenario) (sinks : sinks) (cleanopts : (string
   let fetch = Func (fun _ args _ _ ->
       let url = match getelem args (Num 0.) with Str s -> s | _ -> "" in
       sc.s_respond url (getelem args (Num 1.))) in
-  let client = Sdk_client.make (jo [
+  let opts = jo [
       ("apikey", Str (canary_of "apikey")); ("secret", Str (canary_of "secret"));
       ("headers", jo [("X-Custom-Token", Str (canary_of "header"))]);
       ("clean", clean); ("feature", feature);
-      ("system", jo [("fetch", fetch)])]) in
+      ("system", jo [("fetch", fetch)])] in
+  (match auth with Map _ -> setp opts "auth" auth | _ -> ());
+  let client = construct opts in
   client.cl_features <- client.cl_features @ [capture_feature sinks] @ extra;
   client
 
@@ -280,7 +300,8 @@ let msg_of (e : exn option) : string =
 type candidate = {
   c_name : string;
   c_params : string list;
-  c_run : sdk_client -> value -> value -> value;
+  (* The operation's data; the ref receives the match its entity then holds. *)
+  c_run : sdk_client -> value -> value -> value ref -> value;
   c_stream : sdk_client -> value -> value -> value list;
 }
 
@@ -302,20 +323,23 @@ ${candidates(entity)}
 (* The first operation that completes against a plain 200: with no
  * arguments, else with every path parameter its points declare filled in. *)
 let usable_op () : target option =
-  let plain = Sdk_client.make (jo [
+  let plain = construct (jo [
       ("apikey", Str (canary_of "apikey"));
       ("system", jo [("fetch", Func (fun _ _ _ _ -> response 200 (jo [("id", Str "i1")])))])]) in
   first_some (fun c ->
       first_some (fun ps ->
-          try ignore (c.c_run plain (args ps) (empty_map ())); Some { t_cand = c; t_params = ps }
+          try ignore (c.c_run plain (args ps) (empty_map ()) (ref Noval)); Some { t_cand = c; t_params = ps }
           with _ -> None) [[]; c.c_params]) candidates
 
 let drive (sdk : sdk_client) (t : target) (ctrl : value) (sinks : sinks) : exn option =
   (* A caller may keep the record it passed rather than read ctrl.explain. *)
   let held = getp ctrl "explain" in
+  let mtch = ref Noval in
   let err =
-    try value_forms sinks "result" (t.t_cand.c_run sdk (args t.t_params) ctrl); None
+    try value_forms sinks "result" (t.t_cand.c_run sdk (args t.t_params) ctrl mtch); None
     with e -> error_forms sinks "error" e; Some e in
+  (* Raw, as a caller copying the match into another query reads it. *)
+  value_forms sinks "match" !mtch;
   (match getp ctrl "explain" with Map _ as ex -> value_forms sinks "explain" ex | _ -> ());
   (match held, getp ctrl "explain" with
    | Map h, Map now when h == now -> ()
@@ -347,13 +371,17 @@ let () =
               (match err with Some e -> errors := (key, e) :: !errors | None -> ());
               (match getp ctrl "explain" with Map _ as ex -> explains := (key, ex) :: !explains | _ -> ());
               value_forms sinks "sdk" (client_to_value sdk)) variants) scenarios;
+      (* A name given at run time replaces the declared one: the match
+       * leaves out whichever name prepare_auth placed. *)
+      ignore (drive (make_sdk ~auth:(jo [("name", Str "zzcred")]) (List.hd scenarios) sinks [])
+                target (empty_map ()) sinks);
       (* A credential mistyped as a map is rejected by validation, whose
        * message quotes the value it rejected. *)
       let rejected =
         try
-          ignore (Sdk_client.make (jo [
+          ignore (Sdk_client.make (offline (jo [
               ("apikey", jo [("value", Str (canary_of "apikey"))]);
-              ("clean", jo [("values", Str (canary_of "value"))])]));
+              ("clean", jo [("values", Str (canary_of "value"))])])));
           None
         with e -> Some e in
       (match rejected with
@@ -388,7 +416,7 @@ let () =
         [("stream", [stream_throw_feature ()]); ("stream-ok", [stream_ok_feature ()]);
          ("stream-plain", [])];
       (* A client given no clean block at all masks by the schema defaults. *)
-      let bare = Sdk_client.make (jo [
+      let bare = construct (jo [
           ("apikey", Str (canary_of "apikey")); ("secret", Str (canary_of "secret"));
           ("headers", jo [("X-Custom-Token", Str (canary_of "header"))]);
           ("system", jo [("fetch", Func (fun _ args _ _ ->
@@ -479,15 +507,18 @@ let () =
 (* A feature's name is not a field name: a feature called secrets does not
  * make its settings secret, though a sensitive field inside it still is. An
  * entity block, of per-entity settings or seeded records keyed by entity name
- * and id, is not read at all. *)
+ * and id, is not read at all, and nor are rbac's rules, keyed by entity and
+ * operation names. *)
 let () =
   test "clean.a_feature_name_is_read_as_a_name" (fun () ->
       let seeded = jo [("zztoken", jo [("ZZTOKEN01", jo [("note", Str "PLAINRECORD-t5r3e1w9")])])] in
-      let client = Sdk_client.make (jo [
+      let client = construct (jo [
           ("apikey", Str (canary_of "apikey"));
           ("feature", jo [
               ("secrets", jo [("active", Bool false); ("name", Str "ZZNAME-feat123");
                               ("token", Str "ZZTOKEN-feat456")]);
+              ("rbac", jo [("active", Bool false);
+                           ("rules", jo [("zztoken.load", Str "PLAINRULE-k7j5h3g1")])]);
               ("test", jo [("active", Bool false); ("entity", seeded)])]);
           ("entity", jo [("zztoken", jo [("alias", jo [("zzkey", Str "PLAINALIAS-m2n4b6v8")])])])]) in
       match client.cl_rootctx with
@@ -497,7 +528,9 @@ let () =
         check_vstr "a record seeded under an entity block is not registered"
           (clean_util ctx (Str "record PLAINRECORD-t5r3e1w9")) "record PLAINRECORD-t5r3e1w9";
         check_vstr "an entity's own settings are not registered"
-          (clean_util ctx (Str "alias PLAINALIAS-m2n4b6v8")) "alias PLAINALIAS-m2n4b6v8"
+          (clean_util ctx (Str "alias PLAINALIAS-m2n4b6v8")) "alias PLAINALIAS-m2n4b6v8";
+        check_vstr "an rbac rule keyed by entity and operation is not registered"
+          (clean_util ctx (Str "rule PLAINRULE-k7j5h3g1")) "rule PLAINRULE-k7j5h3g1"
       | None -> failwith "the client has no root context")
 
 let () =

package/project/.sdk/src/cmp/ocaml/TestEntity_ocaml.ts

@@ -3,6 +3,8 @@ import {
   Content,
   File,
   cmp,
+  invalidRequest,
+  opReachable,
 } from '@voxgig/sdkgen'
 
 import { ocamlString, ocamlVarName } from './utility_ocaml'
@@ -17,9 +19,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const { target, entity } = props
 
   const fn = ocamlVarName(entity.name)
-  const opnames = Object.keys(entity.op || {})
-  const hasList = opnames.includes('list')
-  const hasLoad = opnames.includes('load')
+  const hasList = opReachable(entity.op?.list, [])
+  const hasLoad = opReachable(entity.op?.load, ['id'])
   const hasId = null != entity.id
   const id = entity.name + '01'
 
@@ -118,11 +119,95 @@ let () =
           (List.length (List.of_seq (cent.e_stream "list" (empty_map ()) Noval))) 2
       end)
 `)
+
+      // Failure paths: the stream, the caller's ctrl, and a raising hook.
+      Content(`
+let () =
+  test "${ocamlString(entity.name)}.stream_error" (fun () ->
+      let offline = jo [("net", jo [("offline", Bool true)])] in
+      let ent = Sdk_client.${fn} (Sdk_client.test_with offline Noval) Noval in
+      let err = (try ignore (List.of_seq (ent.e_stream "list" (empty_map ()) Noval)); None
+                 with e -> Some e) in
+      check "the transport failure raises from the stream"
+        (match err with
+         | Some (Sdk_error_exc er) -> Sdk_runtime.substr_contains er.err_msg "offline"
+         | _ -> false);
+      let quiet = jo [("ctrl", jo [("throw", Bool false)])] in
+      let ent2 = Sdk_client.${fn} (Sdk_client.test_with offline Noval) Noval in
+      check_int "throw false ends the stream quietly"
+        (List.length (List.of_seq (ent2.e_stream "list" (empty_map ()) quiet))) 0;
+      if Harness.has_feature "rbac" then begin
+        let denied = Sdk_client.test_with Noval
+            (jo [("feature", jo [("rbac", jo [("active", Bool true); ("deny", Bool true)])])]) in
+        let dent = Sdk_client.${fn} denied Noval in
+        let derr = (try ignore (List.of_seq (dent.e_stream "list" (empty_map ()) Noval)); None
+                    with e -> Some e) in
+        check_str "the rbac denial raises from the stream"
+          (match derr with Some (Sdk_error_exc er) -> er.err_code | _ -> "<no SDK error>") "rbac_denied"
+      end)
+
+let () =
+  test "${ocamlString(entity.name)}.stream_ctrl" (fun () ->
+      let explain = empty_map () in
+      let ctrl = jo [("explain", explain)] in
+      let ent = Sdk_client.${fn} (Sdk_client.test ()) Noval in
+      ignore (List.of_seq (ent.e_stream "list" (empty_map ()) (jo [("ctrl", ctrl)])));
+      check "the stream left the caller's ctrl its own" (keysof ctrl = ["explain"]);
+      check "the caller's explain record is its own" (getp ctrl "explain" == explain);
+      check "the caller's explain record is filled" (List.length (keysof explain) > 0))
+
+let () =
+  test "${ocamlString(entity.name)}.unexpected" (fun () ->
+      let seen = ref 0 in
+      let hook : feature =
+        { f_name = "failhook"; f_version = "0.0.1"; f_active = true; f_options = Noval;
+          f_init = (fun _ _ -> ());
+          f_hook = (fun name _ ->
+              match name with
+              | "PreSpec" -> failwith "${ocamlString(entity.name)} hook failed"
+              | "PreUnexpected" -> incr seen
+              | _ -> ()) } in
+      let client = Sdk_client.test () in
+      client.cl_features <- client.cl_features @ [hook];
+      let ent = Sdk_client.${fn} client Noval in
+      let err = (try ignore (ent.e_list (empty_map ()) Noval); None with e -> Some e) in
+      check "the hook's failure is raised"
+        (match err with Some (Failure m) -> Sdk_runtime.substr_contains m "hook failed" | _ -> false);
+      check "PreUnexpected fired" (!seen > 0);
+      let fired = !seen in
+      check_int "throw false resolves to nothing"
+        (List.length (ent.e_list (empty_map ()) (jo [("throw", Bool false)]))) 0;
+      check "PreUnexpected fired under throw false" (!seen > fired))
+`)
+    }
+
+    const bad = invalidRequest(entity)
+    if (null != bad) {
+      const args = Object.entries(bad.args)
+        .map(([k, v]) => '("' + ocamlString(k) + '", ' + ocamlValue(v) + ')').join('; ')
+      Content(`
+let () =
+  test "${ocamlString(entity.name)}.validate" (fun () ->
+      if Harness.has_feature "validate" then begin
+        let client = Sdk_client.test_with Noval
+            (jo [("feature", jo [("validate", jo [("active", Bool true)])])]) in
+        let ent = Sdk_client.${fn} client Noval in
+        let err = (try ignore (ent.e_${bad.op} (jo [${args}]) Noval); None with e -> Some e) in
+        check_str "validate refuses an invalid request"
+          (match err with Some (Sdk_error_exc er) -> er.err_code | _ -> "<no SDK error>") "validate_failed"
+      end)
+`)
     }
   })
 })
 
 
+function ocamlValue(v: any): string {
+  return 'number' === typeof v ? 'Num ' + v + '.' :
+    'boolean' === typeof v ? 'Bool ' + v : 'Str "' + ocamlString(String(v)) + '"'
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/ocaml/fragment/RunOp.fragment.ml

@@ -1,17 +1,16 @@
 (* The catch path every entity call leaves through: an error that never
  * passed through make_error leaves cleaned, and so does the explain record
- * it interrupted. An SDK error fires PreUnexpected here, and whatever that
- * hook raises is cleaned in its place. *)
-let unexpected (ctx : ctx) (e : exn) : 'a =
-  let e = match e with
-    | Sdk_error_exc _ ->
-      (try
-         (* #PreUnexpected-Hook *)
-         e
-       with hookerr -> hookerr)
-    | _ -> e in
+ * it interrupted. PreUnexpected fires here, and whatever that hook raises is
+ * cleaned in its place. Noval when the caller switched throwing off. *)
+let unexpected (ctx : ctx) (e : exn) : value =
+  let e =
+    (try
+       (* #PreUnexpected-Hook *)
+       e
+     with hookerr -> hookerr) in
   clean_explain ctx;
-  raise (clean_exn ctx e)
+  if ctx.c_ctrl.ctrl_throw = Some false then Noval
+  else raise (clean_exn ctx e)
 
 (* Run the operation pipeline, firing feature hooks between stages via the
  * generated hook-marker lines. post_done runs after the PreDone stage, just

package/project/.sdk/src/cmp/ocaml/utility_ocaml.ts

@@ -4,7 +4,7 @@ import {
   walk,
 } from '@voxgig/struct'
 
-import { sdkName } from '@voxgig/sdkgen'
+import { sdkName, canonScalarKey, requiredItems } from '@voxgig/sdkgen'
 
 
 // OCaml keywords that are illegal as a lowercase identifier. sdkgen's shared
@@ -34,6 +34,12 @@ function entityModule(name: string): string {
 }
 
 
+// The entity_obj field holding an operation's closure.
+function ocamlOpField(opname: string): string {
+  return 'e_' + opname
+}
+
+
 // The opam / distribution package name, e.g. voxgig-solar-sdk (mirrors the go
 // module naming: org prefix from model.origin).
 function packageName(model: any): string {
@@ -145,10 +151,23 @@ function clean(o: any, dropDefaults?: boolean): any {
 }
 
 
+// A list's required route and query parameters, as the match it is called with.
+function ocamlListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'Null', INTEGER: '(Num 1.)', NUMBER: '(Num 1.)', BOOLEAN: '(Bool true)', ARRAY: '(empty_list ())', OBJECT: '(empty_map ())' }) as any)[canonScalarKey(type)] ?? '(Str "example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `(jo [${items.map((it: any) => `("${ocamlString(it.name)}", ${lit(it.type)})`).join('; ')}])`
+    : '(empty_map ())'
+}
+
+
 export {
   clean,
   entityModule,
   formatOcamlValue,
+  ocamlListMatch,
+  ocamlOpField,
   ocamlString,
   ocamlVarName,
   packageName,

package/project/.sdk/src/cmp/perl/Entity_perl.ts

@@ -40,7 +40,7 @@ const Entity = cmp(function Entity(props: any) {
       const opnames = Object.keys(entity.op || {})
 
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['# #' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ? '' : ({ indent }: any) => {

package/project/.sdk/src/cmp/perl/Main_perl.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names,
   File, Content, Copy, Folder, Fragment,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
   TEST_CONTROL_EXCLUDE
@@ -57,7 +58,8 @@ const Main = cmp(async function Main(props: any) {
   // Copy tm/perl files with replacements
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE,
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/perl/Package_perl.ts

@@ -5,7 +5,7 @@ import {
   cmp,
   collectDeps,
   pkgDescription,
-  targetFeatures,
+  authorInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -13,6 +13,8 @@ import type {
   Model,
 } from '@voxgig/apidef'
 
+import { minPerl, perlStringLiteral } from './utility_perl'
+
 
 // Perl package manifest: a minimal ExtUtils::MakeMaker Makefile.PL,
 // mirroring the struct perl port. The SDK is pure-Perl with zero non-core
@@ -28,8 +30,7 @@ const Package = cmp(async function Package(props: any) {
   // (e.g. "Voxgig::SDK::Solar" -> dist voxgig-sdk-solar).
   const Name = model.const.Name
 
-  const secrets = null != (targetFeatures(model, target) as any).secrets
-  const minperl = secrets ? '5.036' : '5.018'
+  const minperl = minPerl(model, target)
 
   const deps = collectDeps(model, target.name, target.deps, ctx$.log)
   const prereq = deps
@@ -53,7 +54,7 @@ WriteMakefile(
     NAME             => '${Name}SDK',
     VERSION_FROM     => 'lib/${Name}SDK.pm',
     ABSTRACT         => '${pkgDescription(model, target.name)}',
-    AUTHOR           => 'Voxgig',
+    AUTHOR           => ${perlStringLiteral(authorInfo(model, target.name).name)},
     LICENSE          => 'mit',
     MIN_PERL_VERSION => '${minperl}',
 ${prereq ? `    PREREQ_PM        => {\n${prereq}\n    },\n` : ''});

package/project/.sdk/src/cmp/perl/PrepareAuth_perl.ts

@@ -112,15 +112,23 @@ my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
 require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
 require(Cwd::abs_path("$__dir/../core/helpers.pm"));
-
+${'cookie' === spec.where ? 'require(Cwd::abs_path("$__dir/prepare_headers.pm"));\n' : ''}
 package ${spec.Name}Utilities;
 
 our %REGISTRY;
 
 ${placementNote(spec)}my $CRED_NAME = ${cred};
-my $OPTION_APIKEY = 'apikey';
+${'cookie' === spec.where ? `my $COOKIE_HEADER = 'cookie';
+` : ''}my $OPTION_APIKEY = 'apikey';
 ${secretConst}my $NOT_FOUND = '__NOTFOUND__';
 
+# The client's auth.name option, when set, replaces the name the API declares.
+my $auth_name = sub {
+  my ($options) = @_;
+  my $name = ${spec.Name}Helpers::gpath($options, 'auth.name');
+  return (defined $name && !ref $name && '' ne $name) ? ${'header' === spec.where ? 'lc($name)' : '$name'} : $CRED_NAME;
+};
+${cookieHelper(spec)}
 $REGISTRY{prepare_auth} = sub {
   my ($ctx) = @_;
   my $spec = $ctx->{spec};
@@ -130,10 +138,16 @@ $REGISTRY{prepare_auth} = sub {
 ${bag(spec)}  my $options = $ctx->{client}->options_map;
 
   # Public APIs that need no auth omit the options.auth block entirely.
-${noCredNote(spec)}  if (!defined ${spec.Name}Helpers::gp($options, 'auth')) {
-${clear(spec, '    ')}    return ($spec, undef);
+  if (!defined ${spec.Name}Helpers::gp($options, 'auth')) {
+${clear(spec, '$CRED_NAME', '    ')}    return ($spec, undef);
   }
 
+  my $name = $auth_name->($options);
+
+  # A credential left under the declared name would travel beside the renamed one.
+  if ($name ne $CRED_NAME) {
+${clear(spec, '$CRED_NAME', '    ')}  }
+
   my $apikey = Voxgig::Struct::getprop($options, $OPTION_APIKEY, $NOT_FOUND);
 ${basicBlock(spec, wantBasic)}${credBlock(spec)}
   return ($spec, undef);
@@ -154,32 +168,37 @@ const MISSING = `  if (!defined $apikey || Voxgig::Struct::is_none($apikey)
 
 
 function credBlock(spec: AuthSpec): string {
-  if ('cookie' === spec.where) {
-    return `
-${MISSING}
-    return ($spec, undef);
-  }
-
-${place(spec).replace(/^ {4}/gm, '  ')}`
-  }
-
   return `
 ${MISSING}
-${clear(spec, '    ')}  }
+${clear(spec, '$name', '    ')}  }
   else {
 ${place(spec)}  }
 `
 }
 
 
-function noCredNote(spec: AuthSpec): string {
+// The cookie header is shared with whatever cookies the caller set, so the
+// credential's pair is spliced in and out rather than appended.
+function cookieHelper(spec: AuthSpec): string {
   if ('cookie' !== spec.where) {
     return ''
   }
 
-  return `  # Nothing of OURS to remove either way: this SDK appends its pair to
-  # whatever cookie header the caller set and never stores one, and
-  # prepare_headers rebuilds that header from options on every request.
+  return `
+# Rewrite the cookie header with the named pair removed, then set to VALUE
+# when VALUE is defined; every other cookie is kept in order.
+my $set_cookie = sub {
+  my ($headers, $name, $value) = @_;
+  my $existing = $headers->{$COOKIE_HEADER};
+  my @kept = defined $existing && !ref $existing ? @{ cookie_keep($existing, { $name => 1 }) } : ();
+  push @kept, "$name=$value" if defined $value;
+  if (@kept) {
+    $headers->{$COOKIE_HEADER} = join('; ', @kept);
+  }
+  else {
+    delete $headers->{$COOKIE_HEADER};
+  }
+};
 `
 }
 
@@ -215,16 +234,16 @@ function bag(spec: AuthSpec): string {
 }
 
 
-function clear(spec: AuthSpec, ind: string): string {
+function clear(spec: AuthSpec, name: string, ind: string): string {
   if ('query' === spec.where) {
-    return `${ind}delete $query->{$CRED_NAME};\n`
+    return `${ind}delete $query->{${name}};\n`
   }
 
   if ('cookie' === spec.where) {
-    return ''
+    return `${ind}$set_cookie->($headers, ${name}, undef);\n`
   }
 
-  return `${ind}delete $headers->{$CRED_NAME};\n`
+  return `${ind}delete $headers->{${name}};\n`
 }
 
 
@@ -234,19 +253,15 @@ function place(spec: AuthSpec): string {
     # any API reads. The prefix is a header convention, and is dropped
     # here deliberately rather than silently concatenated. make_url
     # url-encodes both the name and the value.
-    $query->{$CRED_NAME} = (!ref $apikey) ? "$apikey" : '';
+    $query->{$name} = (!ref $apikey) ? "$apikey" : '';
 `
   }
 
   if ('cookie' === spec.where) {
     return `    my $apikey_val = (!ref $apikey) ? "$apikey" : '';
-    my $pair = "$CRED_NAME=$apikey_val";
-    # APPEND, never clobber: the caller's own cookie header may already
-    # carry a session or consent pair that the API needs alongside this
-    # credential.
-    my $cookie = $headers->{'cookie'};
-    $cookie = '' unless defined $cookie && !ref $cookie;
-    $headers->{'cookie'} = ('' eq $cookie) ? $pair : "$cookie; $pair";
+    # Spliced in, replacing an earlier pair of the same name, beside any
+    # session or consent pair the caller's own cookie header carries.
+    $set_cookie->($headers, $name, $apikey_val);
 `
   }
 
@@ -254,7 +269,7 @@ function place(spec: AuthSpec): string {
     $auth_prefix = '' unless defined $auth_prefix && !ref $auth_prefix;
     my $apikey_val = (!ref $apikey) ? "$apikey" : '';
     # Empty prefix (raw apiKey credential) must not add a leading space.
-    $headers->{$CRED_NAME} =
+    $headers->{$name} =
       ('' eq $auth_prefix) ? $apikey_val : "$auth_prefix $apikey_val";
 `
 }
@@ -282,7 +297,7 @@ function basicBlock(spec: AuthSpec, wantBasic: boolean): string {
       || (!ref $secret && ($secret eq $NOT_FOUND || $secret eq ''));
 
     if ($no_apikey) {
-      delete $headers->{$CRED_NAME};
+      delete $headers->{$name};
     }
     else {
       my $auth_prefix = ${spec.Name}Helpers::gpath($options, 'auth.prefix');
@@ -294,7 +309,7 @@ function basicBlock(spec: AuthSpec, wantBasic: boolean): string {
       # The joined, encoded pair is a wire form neither credential's own
       # registration covers.
       $ctx->{utility}{clean_add}->($ctx, $b64);
-      $headers->{$CRED_NAME} =
+      $headers->{$name} =
         ('' eq $auth_prefix) ? $b64 : "$auth_prefix $b64";
     }