@voxgig/sdkgen 4.30.3 → 4.31.1

package/project/.sdk/tm/js/test/definition-runner.js

@@ -0,0 +1,161 @@
+// Checks one operation against the API definition rather than the model the
+// SDK was generated from. A mock transport answers with the definition's own
+// response example, so nothing here depends on how the model reads it.
+
+const assert = require('node:assert/strict')
+
+
+
+
+const KEY = 'definition-test-key'
+const BASE = 'http://definition.test'
+
+
+async function runDefinitionPoint(SDK, point) {
+  const sent = []
+  const body = null == point.sample ? null : JSON.stringify(point.sample)
+
+  const client = new SDK({
+    apikey: KEY,
+    base: BASE,
+    feature: { test: { active: false } },
+    system: {
+      fetch: async (url, init) => {
+        sent.push({ url: new URL(String(url)), init: init || {} })
+        return new Response(204 === point.status ? null : body, {
+          status: point.status,
+          headers: { 'content-type': 'application/json' },
+        })
+      },
+    },
+  })
+
+  const input = { ...point.select }
+  for (const arg of point.args) input[arg.name] = arg.value
+  if (null != point.action) input.$action = point.action
+
+  let result
+  let error
+  try {
+    result = await client[point.accessor]()[point.op](input)
+  }
+  catch (err) {
+    error = err
+  }
+
+  assert.equal(sent.length, 1, 'expected one request, sent ' + sent.length +
+    (error ? ': ' + error.message : ''))
+  const { url, init } = sent[0]
+
+  assert.equal(String(init.method || 'GET').toUpperCase(), point.method, 'method')
+
+  const route = point.path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const arg = point.args.find((a) => a.wire === name)
+    return null == arg ? '{' + name + '}' : encodeURIComponent(String(arg.value))
+  })
+  assert.equal(url.pathname, route, 'route')
+
+  // Only what the definition declares, so never a path parameter again.
+  const credentialQuery = (point.auth || []).flat()
+    .filter((c) => 'query' === c.in).map((c) => c.name)
+  for (const key of url.searchParams.keys()) {
+    assert(point.query.includes(key) || credentialQuery.includes(key),
+      'query parameter not in the definition: ' + key)
+  }
+
+  // From the apikey alone, placed as the definition's security scheme says.
+  if (null != point.auth && 0 < point.auth.length) {
+    const headers = new Headers(init.headers)
+    assert(point.auth.some((set) => set.every((c) => placed(c, headers, url))),
+      'credential not sent as the definition declares it: ' + JSON.stringify(point.auth))
+  }
+
+  if (null != error) {
+    throw error
+  }
+
+  if (null == point.sample) {
+    return
+  }
+
+  if ('list' === point.op) {
+    const records = recordsOf(point.sample)
+    if (null != records) {
+      assert(Array.isArray(result), 'list did not return a list')
+      assert.equal(result.length, records.length,
+        'list read ' + result.length + ' records where the definition example holds ' +
+        records.length)
+    }
+  }
+  else if ('load' === point.op || 'create' === point.op || 'update' === point.op) {
+    const record = recordOf(point.sample, point.idField)
+    if (null != record) {
+      assert.equal(result?.data?.()?.[point.idField], record[point.idField],
+        'the entity does not hold the record the definition example returns')
+    }
+  }
+}
+
+
+function placed(cred, headers, url) {
+  if ('query' === cred.in) {
+    return KEY === url.searchParams.get(cred.name)
+  }
+
+  if ('cookie' === cred.in) {
+    return String(headers.get('cookie') || '').split(';')
+      .some((part) => cred.name + '=' + KEY === part.trim())
+  }
+
+  const value = headers.get(cred.name)
+  if (null == value) {
+    return false
+  }
+
+  const [kind, token] = value.split(' ')
+
+  // The client carries no secret, so the password must be empty.
+  if ('basic' === cred.scheme) {
+    return 'basic' === String(kind).toLowerCase() &&
+      Buffer.from(String(token), 'base64').toString('utf8') === KEY + ':'
+  }
+
+  if ('bearer' === cred.scheme) {
+    return 'bearer' === String(kind).toLowerCase() && KEY === token
+  }
+
+  return value.includes(KEY)
+}
+
+
+// The records a list response holds: the body itself, or its one property
+// that is a non-empty list of objects. Anything else proves nothing.
+function recordsOf(sample) {
+  if (Array.isArray(sample)) {
+    return sample
+  }
+  if (null == sample || 'object' !== typeof sample) {
+    return null
+  }
+  const lists = Object.values(sample).filter((v) => Array.isArray(v) && 0 < v.length &&
+    v.every((x) => null != x && 'object' === typeof x && !Array.isArray(x)))
+  return 1 === lists.length ? lists[0] : null
+}
+
+
+// The record a single-item response returns: the body, or its one property
+// holding an object with the identity field.
+function recordOf(sample, idField) {
+  if (null == sample || 'object' !== typeof sample || Array.isArray(sample)) {
+    return null
+  }
+  if (null != sample[idField]) {
+    return sample
+  }
+  const inner = Object.values(sample).filter((v) => null != v && 'object' === typeof v &&
+    !Array.isArray(v) && null != v[idField])
+  return 1 === inner.length ? inner[0] : null
+}
+
+
+module.exports = { runDefinitionPoint, recordsOf, recordOf }

package/project/.sdk/tm/js/test/pipeline.test.js

@@ -340,9 +340,9 @@ describe('pipeline:prepareAuth', () => {
   }
 
   // `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 below would read as a public API.
+  // `auth.basic: true`, and a client that merges it in takes the Basic
+  // branch, which base64-joins the key with a password rather than placing
+  // the key as it is.
   function auth(prefix) {
     return { prefix, basic: false }
   }
@@ -437,6 +437,46 @@ describe('pipeline:prepareAuth', () => {
   test('a missing apikey option drops the credential', () => {
     strictEqual(placed({ auth: auth('Bearer') }, 'stale'), undefined)
   })
+
+  // HTTP Basic joins the key with a password, which may be empty (RFC 7617):
+  // Lob documents its key as the user with a blank password. An SDK for an
+  // API that is not HTTP Basic has no such branch, and the first placement
+  // below tells the two apart.
+  test('HTTP Basic sends the key with a blank password', () => {
+    if (null == CRED || 'headers' !== CRED.where || '' !== CRED.pair) return
+    const basic = { prefix: 'Basic', basic: true }
+    const b64 = (s) => Buffer.from(s).toString('base64')
+    if (placed({ apikey: 'K', secret: 'S', auth: basic }) !== 'Basic ' + b64('K:S')) return
+    strictEqual(placed({ apikey: 'K', auth: basic }), 'Basic ' + b64('K:'))
+    strictEqual(placed({ apikey: 'K', secret: '', auth: basic }), 'Basic ' + b64('K:'))
+    strictEqual(placed({ apikey: '', secret: 'S', auth: basic }, 'stale'), undefined)
+  })
+})
+
+
+describe('pipeline:prepareQuery', () => {
+
+  // The generated config lists path parameters as args.params. A match field
+  // that fills the path must not be sent again as a query parameter, which a
+  // strict server rejects.
+  test('a path parameter stays out of the query', () => {
+    const point = { args: { params: [{ name: 'id', kind: 'param' }] } }
+    const ctx = base({ point, reqmatch: { id: 'i1', q: 'x' } })
+    deepStrictEqual(stdutil.prepareQuery(ctx), { q: 'x' })
+  })
+
+  test('an action is never a query parameter', () => {
+    const ctx = base({ point: { args: { params: [] } }, reqmatch: { $action: 'go', q: 'x' } })
+    deepStrictEqual(stdutil.prepareQuery(ctx), { q: 'x' })
+  })
+
+  // A query argument's orig is the name the API definition gives it, which
+  // the model may have renamed for the caller.
+  test('a query argument goes out under its orig', () => {
+    const point = { args: { query: [{ name: 'item_id', orig: 'itemIds', kind: 'query' }] } }
+    const ctx = base({ point, reqmatch: { item_id: ['i1'], q: 'x' } })
+    deepStrictEqual(stdutil.prepareQuery(ctx), { itemIds: ['i1'], q: 'x' })
+  })
 })
 
 

package/project/.sdk/tm/js/test/sdk-test-control.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "_doc": "Per-SDK test control. Lists tests/operations to skip in unit and live modes; tunes per-test pacing. Edit by hand. Loaded by js/test/utility.js.",
+  "_doc": "Per-SDK test control. Lists tests/operations to skip in unit, live and definition modes; tunes per-test pacing. Edit by hand. Loaded by js/test/utility.js.",
   "test": {
     "skip": {
       "live": {
@@ -10,6 +10,9 @@
       "unit": {
         "direct": [],
         "entityOp": []
+      },
+      "definition": {
+        "entityOp": []
       }
     },
     "live": {

package/project/.sdk/tm/kotlin/utility/Prepare.kt

@@ -179,15 +179,39 @@ fun prepareQuery(ctx: Context): MutableMap<String, Any?> {
   val point = ctx.point
   val reqmatch = ctx.reqmatch
 
-  var params: MutableList<Any?>? = null
+  val params: MutableList<Any?> = mutableListOf()
   if (point != null) {
     val p = Struct.getprop(point, "params")
     if (p is MutableList<*>) {
-      params = p as MutableList<Any?>
+      params.addAll(p as MutableList<Any?>)
+    }
+    // A path parameter travels in the path. The generated config lists them
+    // as args.params, which prepareParams reads; params is the older list.
+    val pl = Struct.getpath(point, listOf("args", "params"))
+    if (pl is List<*>) {
+      for (pd in pl) {
+        val name = Struct.getprop(pd, "name")
+        if (name is String) {
+          params.add(name)
+        }
+      }
     }
   }
-  if (params == null) {
-    params = mutableListOf()
+
+  // A query parameter travels under the name the definition gives it, its
+  // orig, which the model may have renamed for the caller.
+  val wire = mutableMapOf<String, String>()
+  if (point != null) {
+    val ql = Struct.getpath(point, listOf("args", "query"))
+    if (ql is List<*>) {
+      for (qd in ql) {
+        val name = Struct.getprop(qd, "name")
+        val orig = Struct.getprop(qd, "orig")
+        if (name is String && orig is String && orig.isNotEmpty()) {
+          wire[name] = orig
+        }
+      }
+    }
   }
 
   val out = linkedMapOf<String, Any?>()
@@ -195,7 +219,7 @@ fun prepareQuery(ctx: Context): MutableMap<String, Any?> {
     val key = if (item[0] is String) item[0] as String else ""
     val v = item[1]
     if (v != null && "\$action" != key && !containsStr(params, key)) {
-      out[key] = v
+      out[wire[key] ?: key] = v
     }
   }
 

package/project/.sdk/tm/lua/utility/prepare_query.lua

@@ -19,7 +19,36 @@ local function prepare_query_util(ctx)
   if point ~= nil then
     local p = vs.getprop(point, "params")
     if type(p) == "table" then
-      params = p
+      for _, v in ipairs(p) do
+        table.insert(params, v)
+      end
+    end
+    -- A path parameter travels in the path. The generated config lists them
+    -- as args.params, which prepare_params reads; params is the older list.
+    local pl = vs.getpath(point, "args.params")
+    if type(pl) == "table" then
+      for _, pd in ipairs(pl) do
+        local name = vs.getprop(pd, "name")
+        if type(name) == "string" then
+          table.insert(params, name)
+        end
+      end
+    end
+  end
+
+  -- A query parameter travels under the name the definition gives it, its
+  -- orig, which the model may have renamed for the caller.
+  local wire = {}
+  if point ~= nil then
+    local ql = vs.getpath(point, "args.query")
+    if type(ql) == "table" then
+      for _, qd in ipairs(ql) do
+        local name = vs.getprop(qd, "name")
+        local orig = vs.getprop(qd, "orig")
+        if type(name) == "string" and type(orig) == "string" and orig ~= "" then
+          wire[name] = orig
+        end
+      end
     end
   end
 
@@ -31,7 +60,7 @@ local function prepare_query_util(ctx)
       local val = item[2]
       if val ~= nil and type(key) == "string" and key ~= "$action"
           and not contains_param(params, key) then
-        out[key] = val
+        out[wire[key] or key] = val
       end
     end
   end

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -411,11 +411,32 @@ let prepare_query_util (ctx : ctx) : value =
   let params =
     match getp ctx.c_point "params" with List r -> !r | _ -> []
   in
+  (* A path parameter travels in the path. The generated config lists them as
+   * args.params, which prepare_params reads; params is the older list. *)
+  let arg_names =
+    match getp (getp ctx.c_point "args") "params" with
+    | List r -> List.map (fun pd -> getp pd "name") !r
+    | _ -> []
+  in
+  let params = params @ arg_names in
   let contains_param s = List.exists (fun v -> match v with Str x -> x = s | _ -> false) params in
+  (* A query parameter travels under the name the definition gives it, its
+   * orig, which the model may have renamed for the caller. *)
+  let wire =
+    match getp (getp ctx.c_point "args") "query" with
+    | List r ->
+      List.filter_map (fun qd ->
+          match getp qd "name", getp qd "orig" with
+          | Str n, Str o when o <> "" -> Some (n, o)
+          | _ -> None) !r
+    | _ -> []
+  in
+  let wire_name k = match List.assoc_opt k wire with Some o -> o | None -> k in
   let out = empty_map () in
   List.iter (fun k ->
       let v = getp reqmatch k in
-      if not (is_noval v) && k <> "$action" && not (contains_param k) then setp out k v)
+      if not (is_noval v) && k <> "$action" && not (contains_param k) then
+        setp out (wire_name k) v)
     (keysof reqmatch);
   out
 

package/project/.sdk/tm/perl/utility/prepare_query.pm

@@ -22,7 +22,30 @@ $REGISTRY{prepare_query} = sub {
   my $params = [];
   if ($point) {
     my $p = ProjectNameHelpers::gp($point, 'params');
-    $params = $p if Voxgig::Struct::islist($p);
+    $params = [@$p] if Voxgig::Struct::islist($p);
+    # A path parameter travels in the path. The generated config lists them
+    # as args.params, which prepare_params reads; params is the older list.
+    my $pl = ProjectNameHelpers::gpath($point, 'args.params');
+    if (Voxgig::Struct::islist($pl)) {
+      for my $pd (@$pl) {
+        my $name = ProjectNameHelpers::gp($pd, 'name');
+        push @$params, $name if defined $name && !ref $name;
+      }
+    }
+  }
+  # A query parameter travels under the name the definition gives it, its
+  # orig, which the model may have renamed for the caller.
+  my %wire;
+  if ($point) {
+    my $ql = ProjectNameHelpers::gpath($point, 'args.query');
+    if (Voxgig::Struct::islist($ql)) {
+      for my $qd (@$ql) {
+        my $name = ProjectNameHelpers::gp($qd, 'name');
+        my $orig = ProjectNameHelpers::gp($qd, 'orig');
+        $wire{$name} = $orig
+          if defined $name && !ref $name && defined $orig && !ref $orig && '' ne $orig;
+      }
+    }
   }
   my $out = {};
   my $items = Voxgig::Struct::items($reqmatch);
@@ -32,7 +55,7 @@ $REGISTRY{prepare_query} = sub {
       next unless ProjectNameHelpers::rb_truthy($val) && defined $key && !ref $key;
       next if '$action' eq $key;
       next if grep { defined $_ && !ref $_ && $_ eq $key } @$params;
-      $out->{$key} = $val;
+      $out->{exists $wire{$key} ? $wire{$key} : $key} = $val;
     }
   }
   return $out;

package/project/.sdk/tm/php/utility/PrepareQuery.php

@@ -15,6 +15,33 @@ class ProjectNamePrepareQuery
             if (is_array($p)) {
                 $params = $p;
             }
+            // A path parameter travels in the path. The generated config lists
+            // them as args.params, which prepareParams reads; params is the
+            // older list of names.
+            $pl = \Voxgig\Struct\Struct::getpath($point, 'args.params');
+            if (is_array($pl)) {
+                foreach ($pl as $pd) {
+                    $name = \Voxgig\Struct\Struct::getprop($pd, 'name');
+                    if (is_string($name)) {
+                        $params[] = $name;
+                    }
+                }
+            }
+        }
+        // A query parameter travels under the name the definition gives it,
+        // its orig, which the model may have renamed for the caller.
+        $wire = [];
+        if ($point) {
+            $ql = \Voxgig\Struct\Struct::getpath($point, 'args.query');
+            if (is_array($ql)) {
+                foreach ($ql as $qd) {
+                    $name = \Voxgig\Struct\Struct::getprop($qd, 'name');
+                    $orig = \Voxgig\Struct\Struct::getprop($qd, 'orig');
+                    if (is_string($name) && is_string($orig) && '' !== $orig) {
+                        $wire[$name] = $orig;
+                    }
+                }
+            }
         }
         $out = [];
         $items = \Voxgig\Struct\Struct::items($reqmatch);
@@ -23,7 +50,7 @@ class ProjectNamePrepareQuery
                 $key = $item[0];
                 $val = $item[1];
                 if ($val !== null && is_string($key) && '$action' !== $key && !in_array($key, $params, true)) {
-                    $out[$key] = $val;
+                    $out[$wire[$key] ?? $key] = $val;
                 }
             }
         }

package/project/.sdk/tm/py/pkg/utility/prepare_query.py

@@ -19,7 +19,28 @@ def prepare_query_util(ctx):
     if point is not None:
         p = vs.getprop(point, "params")
         if isinstance(p, list):
-            params = p
+            params = list(p)
+        # A path parameter travels in the path. The generated config lists
+        # them as args.params, which prepare_params reads; params is the
+        # older list of names.
+        pl = vs.getpath(point, "args.params")
+        if isinstance(pl, list):
+            for pd in pl:
+                name = vs.getprop(pd, "name")
+                if isinstance(name, str):
+                    params.append(name)
+
+    # A query parameter travels under the name the definition gives it, its
+    # orig, which the model may have renamed for the caller.
+    wire = {}
+    if point is not None:
+        ql = vs.getpath(point, "args.query")
+        if isinstance(ql, list):
+            for qd in ql:
+                name = vs.getprop(qd, "name")
+                orig = vs.getprop(qd, "orig")
+                if isinstance(name, str) and isinstance(orig, str) and orig != "":
+                    wire[name] = orig
 
     out = {}
     reqmatch_items = vs.items(reqmatch)
@@ -29,6 +50,6 @@ def prepare_query_util(ctx):
             val = item[1]
             if val is not None and isinstance(key, str) and key != "$action" \
                     and not _contains_param(params, key):
-                out[key] = val
+                out[wire.get(key, key)] = val
 
     return out

package/project/.sdk/tm/rb/utility/prepare_query.rb

@@ -7,14 +7,36 @@ module ProjectNameUtilities
     params = []
     if point
       p = VoxgigStruct.getprop(point, "params")
-      params = p if p.is_a?(Array)
+      params = p.dup if p.is_a?(Array)
+      # A path parameter travels in the path. The generated config lists them
+      # as args.params, which prepare_params reads; params is the older list.
+      pl = VoxgigStruct.getpath(point, "args.params")
+      if pl.is_a?(Array)
+        pl.each do |pd|
+          name = VoxgigStruct.getprop(pd, "name")
+          params << name if name.is_a?(String)
+        end
+      end
+    end
+    # A query parameter travels under the name the definition gives it, its
+    # orig, which the model may have renamed for the caller.
+    wire = {}
+    if point
+      ql = VoxgigStruct.getpath(point, "args.query")
+      if ql.is_a?(Array)
+        ql.each do |qd|
+          name = VoxgigStruct.getprop(qd, "name")
+          orig = VoxgigStruct.getprop(qd, "orig")
+          wire[name] = orig if name.is_a?(String) && orig.is_a?(String) && !orig.empty?
+        end
+      end
     end
     out = {}
     items = VoxgigStruct.items(reqmatch)
     if items
       items.each do |item|
         key, val = item[0], item[1]
-        out[key] = val if val && key.is_a?(String) && key != "$action" && !params.include?(key)
+        out[wire.fetch(key, key)] = val if val && key.is_a?(String) && key != "$action" && !params.include?(key)
       end
     end
     out

package/project/.sdk/tm/rust/utility/prepare_query.rs

@@ -29,6 +29,38 @@ pub fn prepare_query_util(ctx: &Rc<Context>) -> Value {
         false
     };
 
+    // A path parameter travels in the path. The generated config lists them as
+    // args.params, which prepare_params reads; params is the older list of names.
+    let aparams = getp(&getp(&point, "args"), "params");
+    let in_args = |key: &str| -> bool {
+        if let Value::List(pl) = &aparams {
+            for pd in pl.borrow().iter() {
+                if let Value::Str(s) = getp(pd, "name") {
+                    if s == key {
+                        return true;
+                    }
+                }
+            }
+        }
+        false
+    };
+
+    // A query parameter travels under the name the definition gives it, its
+    // orig, which the model may have renamed for the caller.
+    let aquery = getp(&getp(&point, "args"), "query");
+    let wire_name = |key: &str| -> String {
+        if let Value::List(ql) = &aquery {
+            for qd in ql.borrow().iter() {
+                if let (Value::Str(n), Value::Str(o)) = (getp(qd, "name"), getp(qd, "orig")) {
+                    if n == key && !o.is_empty() {
+                        return o;
+                    }
+                }
+            }
+        }
+        key.to_string()
+    };
+
     let out = Value::empty_map();
     if let Value::Map(rm) = &reqmatch {
         let entries: Vec<(String, Value)> = rm
@@ -37,8 +69,8 @@ pub fn prepare_query_util(ctx: &Rc<Context>) -> Value {
             .map(|(k, v)| (k.clone(), v.clone()))
             .collect();
         for (key, val) in entries {
-            if !val.is_noval() && !val.is_null() && "$action" != key && !contains(&key) {
-                setp(&out, &key, val);
+            if !val.is_noval() && !val.is_null() && "$action" != key && !contains(&key) && !in_args(&key) {
+                setp(&out, &wire_name(&key), val);
             }
         }
     }

package/project/.sdk/tm/scala/utility/Prepare.scala

@@ -67,11 +67,38 @@ object PrepareQuery {
     var reqmatch = ctx.reqmatch
     if (reqmatch == null) reqmatch = new LinkedHashMap[String, Object]()
 
-    var params: JList[Object] = null
+    val params: JList[Object] = new ArrayList[Object]()
     if (point != null) {
-      Struct.getprop(point, "params") match { case l: JList[_] => params = l.asInstanceOf[JList[Object]]; case _ => }
+      Struct.getprop(point, "params") match { case l: JList[_] => params.addAll(l.asInstanceOf[JList[Object]]); case _ => }
+      // A path parameter travels in the path. The generated config lists them
+      // as args.params, which prepareParams reads; params is the older list.
+      Struct.getpath(point, java.util.List.of("args", "params")) match {
+        case l: JList[_] =>
+          val pit = l.iterator()
+          while (pit.hasNext) {
+            Struct.getprop(pit.next(), "name") match { case s: String => params.add(s); case _ => }
+          }
+        case _ =>
+      }
+    }
+
+    // A query parameter travels under the name the definition gives it, its
+    // orig, which the model may have renamed for the caller.
+    val wire = new LinkedHashMap[String, String]()
+    if (point != null) {
+      Struct.getpath(point, java.util.List.of("args", "query")) match {
+        case l: JList[_] =>
+          val qit = l.iterator()
+          while (qit.hasNext) {
+            val qd = qit.next()
+            (Struct.getprop(qd, "name"), Struct.getprop(qd, "orig")) match {
+              case (n: String, o: String) if o.nonEmpty => wire.put(n, o)
+              case _ =>
+            }
+          }
+        case _ =>
+      }
     }
-    if (params == null) params = new ArrayList[Object]()
 
     val out = new LinkedHashMap[String, Object]()
     val it = Struct.items(reqmatch).iterator()
@@ -79,7 +106,7 @@ object PrepareQuery {
       val item = it.next()
       val key = item.get(0) match { case s: String => s; case _ => "" }
       val v = item.get(1)
-      if (v != null && "$action" != key && !containsStr(params, key)) out.put(key, v)
+      if (v != null && "$action" != key && !containsStr(params, key)) out.put(wire.getOrDefault(key, key), v)
     }
     out
   }