@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/tm/kotlin/test/RunnerSupport.kt

@@ -287,6 +287,96 @@ object RunnerSupport {
     return 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.
+  fun liveMiss(strict: Boolean, reason: String) {
+    if (strict) {
+      org.junit.jupiter.api.Assertions.fail<Unit>(reason)
+    }
+    org.junit.jupiter.api.Assumptions.abort<Unit>(reason)
+  }
+
+  // An account holding no record for the test to read skips either way.
+  fun liveEmpty(reason: String) {
+    org.junit.jupiter.api.Assumptions.abort<Unit>(reason)
+  }
+
+  // A live list response's records: the body, or the first list an
+  // envelope holds.
+  fun liveList(data: Any?): List<Any?>? {
+    if (data is List<*>) {
+      return data as List<Any?>
+    }
+    if (data is Map<*, *>) {
+      for (value in TreeMap(data as Map<String, Any?>).values) {
+        if (value is List<*>) {
+          return value as List<Any?>
+        }
+      }
+    }
+    return null
+  }
+
+  // A live response for a message: the SDK's error, or else its status and
+  // content type, never its body.
+  fun liveDescribe(result: Map<String, Any?>?): String {
+    if (result == null) {
+      return "no response"
+    }
+    val err = result["err"]
+    if (err is Throwable) {
+      return err.message ?: err.toString()
+    }
+    if (err != null) {
+      return err.toString()
+    }
+    var out = "HTTP " + result["status"]
+    val headers = result["headers"]
+    if (headers is Map<*, *>) {
+      for ((k, v) in headers) {
+        if ("content-type".equals(k.toString(), ignoreCase = true) && v != null) {
+          out += " " + v.toString().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.
+  fun liveExisting(data: MutableMap<String, Any?>, strict: Boolean, name: String, list: () -> Any?) {
+    var found: Any? = null
+    try {
+      found = list()
+    } catch (e: RuntimeException) {
+      liveMiss(strict, "Live list discovery failed: " + e.message)
+    }
+    if (found !is List<*>) {
+      liveMiss(strict, "Live list discovery returned no list")
+    }
+    val items = found as List<Any?>
+    if (items.isEmpty()) {
+      liveEmpty("The account has no " + name + " record to load")
+    }
+    val first = items[0]
+    val record = if (first is Entity) first.data() else first
+    var existing = data["existing"]
+    if (existing !is MutableMap<*, *>) {
+      existing = linkedMapOf<String, Any?>()
+      data["existing"] = existing
+    }
+    (existing as MutableMap<String, Any?>)[name] = linkedMapOf<String, Any?>("live01" to record)
+  }
+
+  // In a lenient live run a failing check skips, observing the live API.
+  fun liveObserve(err: Throwable, live: Boolean, strict: Boolean) {
+    if (strict || !live || err is org.opentest4j.TestAbortedException) {
+      throw err
+    }
+    org.junit.jupiter.api.Assumptions.abort<Unit>(
+      "live run, main.kit.test.live.strict is false: " + err.message)
+  }
+
   // entityListToData extracts data maps from a list of Entity objects.
   fun entityListToData(list: List<Any?>?): MutableList<Any?> {
     val out = mutableListOf<Any?>()

package/project/.sdk/tm/kotlin/test/ServerVariableTest.kt

@@ -0,0 +1,50 @@
+package KOTLINPACKAGE.sdktest
+
+// A templated base URL takes each {name} from the `server` option. A missing or
+// empty value fails construction; test mode fills in test-<name>.
+
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Assertions.fail
+import org.junit.jupiter.api.Test
+
+import KOTLINPACKAGE.core.ProjectNameSDK
+import KOTLINPACKAGE.core.SdkError
+
+class ServerVariableTest {
+
+  // A variable no API declares, so the API's own server defaults cannot fill it.
+  private val base = "https://api.example.test/bot{zzvar}"
+
+  private fun build(vararg kv: Pair<String, Any?>): ProjectNameSDK =
+    ProjectNameSDK(linkedMapOf<String, Any?>("base" to base, *kv))
+
+  @Test
+  fun aMissingOrEmptyValueFailsConstruction() {
+    for (server in listOf(linkedMapOf<String, Any?>(), linkedMapOf<String, Any?>("zzvar" to ""))) {
+      try {
+        build("server" to server)
+        fail<Unit>("construction should fail without a value for zzvar: $server")
+      } catch (e: SdkError) {
+        assertEquals("server_var_required", e.code)
+        assertTrue(e.message.contains("the server variable 'zzvar' is required"), e.message)
+        assertTrue(e.message.contains(base), e.message)
+      }
+    }
+  }
+
+  @Test
+  fun aServerValueFillsTheBase() {
+    val client = build("server" to linkedMapOf<String, Any?>("zzvar" to "T1"))
+    assertEquals("https://api.example.test/botT1", client.optionsMap()["base"])
+  }
+
+  @Test
+  fun testModeFillsTheBase() {
+    val client = build("test" to linkedMapOf<String, Any?>("active" to true))
+    assertEquals("https://api.example.test/bottest-zzvar", client.optionsMap()["base"])
+
+    val mock = ProjectNameSDK.testSDK(null, linkedMapOf<String, Any?>("base" to base))
+    assertEquals("https://api.example.test/bottest-zzvar", mock.optionsMap()["base"])
+  }
+}

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

@@ -159,7 +159,8 @@ fun cleanAdd(ctx: Context, value: 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.
 internal fun registerSensitive(cfg: CleanConfig, opts: Map<String, Any?>) {
   val seen = mutableListOf<Any>()
   for ((k, v) in opts) {
@@ -168,19 +169,20 @@ internal fun registerSensitive(cfg: CleanConfig, opts: Map<String, Any?>) {
     }
     val under = sensitiveKey(cfg, k)
     when {
-      "feature" == k && v is Map<*, *> -> for (fopts in v.values) {
-        addSensitive(cfg, noEntity(fopts), under, 2, seen)
+      "feature" == k && v is Map<*, *> -> for ((name, fopts) in v) {
+        addSensitive(cfg, plainSettings(fopts, name?.toString()), under, 2, seen)
       }
       "feature" == k && v is List<*> -> for (fopts in v) {
-        addSensitive(cfg, noEntity(fopts), under, 2, seen)
+        addSensitive(cfg, plainSettings(fopts, (fopts as? Map<*, *>)?.get("name") as? String), under, 2, seen)
       }
-      else -> addSensitive(cfg, if ("test" == k) noEntity(v) else v, under, 1, seen)
+      else -> addSensitive(cfg, if ("test" == k) plainSettings(v, null) else v, under, 1, seen)
     }
   }
 }
 
-private fun noEntity(block: Any?): Any? =
-  if (block is Map<*, *>) block.filterKeys { it != "entity" } else block
+private fun plainSettings(block: Any?, name: String?): Any? =
+  if (block is Map<*, *>) block.filterKeys { it != "entity" && !("rbac" == name && it == "rules") }
+  else block
 
 private fun addSensitive(cfg: CleanConfig, v: Any?, under: Boolean, depth: Int, seen: MutableList<Any>) {
   if (v == null || MAXDEPTH <= depth) {

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

@@ -1,5 +1,6 @@
 package KOTLINPACKAGE.utility
 
+import java.io.InputStream
 import java.net.InetSocketAddress
 import java.net.ProxySelector
 import java.net.URI
@@ -55,6 +56,10 @@ fun defaultHttpFetch(fullurl: String, fetchdef: MutableMap<String, Any?>): Mutab
   val body = fetchdef["body"]
   if (body is String && "" != body) {
     bodyPublisher = HttpRequest.BodyPublishers.ofString(body)
+  } else if (body is ByteArray) {
+    bodyPublisher = HttpRequest.BodyPublishers.ofByteArray(body)
+  } else if (body is InputStream) {
+    bodyPublisher = HttpRequest.BodyPublishers.ofInputStream { body }
   }
 
   val reqb: HttpRequest.Builder
@@ -77,9 +82,14 @@ fun defaultHttpFetch(fullurl: String, fetchdef: MutableMap<String, Any?>): Mutab
       }
     }
   }
-  // Default User-Agent — some CDNs block Java's default.
+  // Default User-Agent — some CDNs block Java's default. It is recorded with
+  // the headers the request sent.
   if (!hasUA) {
-    reqb.setHeader("User-Agent", "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)")
+    val agent = "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)"
+    reqb.setHeader("User-Agent", agent)
+    if (headersRaw is MutableMap<*, *>) {
+      (headersRaw as MutableMap<String, Any?>)["user-agent"] = agent
+    }
   }
 
   val resp: HttpResponse<String>
@@ -99,14 +109,24 @@ fun defaultHttpFetch(fullurl: String, fetchdef: MutableMap<String, Any?>): Mutab
   }
 
   val bodyText = resp.body() ?: ""
-  val jsonBody: Any? = if (bodyText.isEmpty()) null else Json.parseOrNull(bodyText)
+  var jsonBody: Any? = null
+  var unreadable = false
+  if (bodyText.isNotBlank()) {
+    try {
+      jsonBody = Json.parse(bodyText)
+    } catch (e: RuntimeException) {
+      unreadable = true
+    }
+  }
+  val parsed = jsonBody
 
   val out = linkedMapOf<String, Any?>()
   out["status"] = resp.statusCode()
   out["statusText"] = statusText(resp.statusCode())
   out["headers"] = headers
-  out["json"] = Supplier<Any?> { jsonBody }
+  out["json"] = Supplier<Any?> { parsed }
   out["body"] = bodyText
+  out["unreadable"] = unreadable
   return out
 }
 

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

@@ -7,6 +7,9 @@ import KOTLINPACKAGE.core.SdkError
 import KOTLINPACKAGE.core.Utility
 import KOTLINPACKAGE.utility.struct.Struct
 
+// A {name} placeholder in a templated server URL (an OpenAPI server variable).
+private val SERVER_VAR = Regex("\\{([A-Za-z0-9_]+)\\}")
+
 @Suppress("UNCHECKED_CAST")
 fun makeOptions(ctx: Context): MutableMap<String, Any?> {
   var options = ctx.options
@@ -155,6 +158,29 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
     }
   }
 
+  // A templated base URL takes each {name} from options.server. An empty value
+  // cannot make a working URL, so it fails construction, except in test mode,
+  // where it becomes test-<name>.
+  val base = opts["base"]
+  if (base is String && base.contains('{')) {
+    val testmode = true == Struct.getpath(opts, listOf("test", "active")) ||
+      true == Struct.getpath(opts, listOf("feature", "test", "active"))
+    val server = Helpers.toMapAny(opts["server"])
+    val mainName = Struct.getpath(config, listOf("main", "name"))
+    val sdkname = if (mainName is String && "" != mainName) mainName else "SDK"
+    opts["base"] = SERVER_VAR.replace(base) { m ->
+      val name = m.groupValues[1]
+      val value = server?.get(name) as? String ?: ""
+      when {
+        "" != value -> value
+        testmode -> "test-$name"
+        else -> throw SdkError("server_var_required",
+          "$sdkname: the server variable '$name' is required: the API base URL is " +
+            "'$base' - pass \"server\" to mapOf(\"$name\" to \"...\") in the SDK options", ctx)
+      }
+    }
+  }
+
   // Resolve the feature add-order: an explicit list order (above) wins;
   // otherwise order the map test-first, then the remaining names sorted, so
   // the outcome is deterministic and `test` is always the base transport.

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

@@ -25,6 +25,38 @@ private fun terminalParam(point: Map<String, Any?>?): Boolean {
   return last is String && last.startsWith("{")
 }
 
+private val PATH_PARAM = Regex("\\{([^{}/]+)\\}")
+
+private fun ownPoint(points: List<MutableMap<String, Any?>>): MutableMap<String, Any?> {
+  var best = points[0]
+  for (cand in points) {
+    val candTerm = terminalParam(cand)
+    val bestTerm = terminalParam(best)
+    if (candTerm != bestTerm) {
+      if (candTerm) {
+        best = cand
+      }
+    } else if (partsLen(cand) < partsLen(best)) {
+      best = cand
+    }
+  }
+  return best
+}
+
+// The path parameters of a point that neither the call nor the entity gives
+// a value for, looked up as param looks them up.
+private fun unfilledParams(ctx: Context, point: Map<String, Any?>?): List<String> {
+  val parts = Struct.getprop(point, "parts") as? List<*> ?: return emptyList()
+  val missing = mutableListOf<String>()
+  for (part in parts) {
+    val found = PATH_PARAM.matchEntire(part as? String ?: "") ?: continue
+    if (paramValue(ctx, point, found.groupValues[1]) == null) {
+      missing.add(found.groupValues[1])
+    }
+  }
+  return missing
+}
+
 @Suppress("UNCHECKED_CAST")
 fun makePoint(ctx: Context): Map<String, Any?> {
   val outPoint = ctx.out["point"]
@@ -46,7 +78,7 @@ fun makePoint(ctx: Context): Map<String, Any?> {
 
   val allowOpRaw = Struct.getpath(options, listOf("allow", "op"))
   val allowOp = if (allowOpRaw is String) allowOpRaw else ""
-  if (!allowOp.contains(op.name)) {
+  if (!Helpers.allowed(allowOpRaw, op.name)) {
     throw ctx.makeError(
       "point_op_allow",
       "Operation \"" + op.name +
@@ -130,18 +162,31 @@ fun makePoint(ctx: Context): Map<String, Any?> {
         )
       }
 
-      point = op.points[0]
-      for (cand in op.points) {
-        val candTerm = terminalParam(cand)
-        val bestTerm = terminalParam(point)
-        if (candTerm != bestTerm) {
-          if (candTerm) {
-            point = cand
-          }
-        } else if (partsLen(cand) < partsLen(point)) {
-          point = cand
-        }
+      // A call without an action falls back to a point without one, as
+      // generation does, and only to a route the call can fill.
+      val plain = op.points.filter {
+        Struct.getprop(Helpers.toMapAny(Struct.getprop(it, "select")), "\$action", null) == null
       }
+      if (plain.isEmpty()) {
+        throw ctx.makeError(
+          "point_action_required",
+          "Operation \"" + op.name +
+            "\" has only action endpoints; pass \$action to choose one.",
+        )
+      }
+
+      val fillable = plain.filter { unfilledParams(ctx, it).isEmpty() }
+
+      if (fillable.isEmpty()) {
+        throw ctx.makeError(
+          "point_no_match",
+          "Operation \"" + op.name +
+            "\" has no endpoint whose path parameters are all given (missing: " +
+            unfilledParams(ctx, ownPoint(plain)).joinToString(", ") + ").",
+        )
+      }
+
+      point = ownPoint(fillable)
     }
 
     val reqAction = Struct.getprop(reqselector, "\$action", null)

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

@@ -1,6 +1,7 @@
 package KOTLINPACKAGE.utility
 
 import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
 import KOTLINPACKAGE.core.Result
 import KOTLINPACKAGE.core.Spec
 import KOTLINPACKAGE.utility.struct.Struct
@@ -46,7 +47,7 @@ fun makeSpec(ctx: Context): Spec {
 
   val allowMethodRaw = Struct.getpath(options, listOf("allow", "method"))
   val allowMethod = if (allowMethodRaw is String) allowMethodRaw else ""
-  if (method == null || "" == method || !allowMethod.contains(method)) {
+  if (method == null || !Helpers.allowed(allowMethodRaw, method)) {
     throw ctx.makeError(
       "spec_method_allow",
       "Method \"" + (method ?: "") +
@@ -80,8 +81,17 @@ fun makeSpec(ctx: Context): Spec {
     ctx.ctrl.explain!!["spec"] = spec
   }
 
+  // Whatever prepareAuth sets in the query, under whichever name, is the
+  // credential; a key it leaves as it was is the caller's.
+  val query = LinkedHashMap(spec.query)
+
   val authed = utility.prepareAuth(ctx)
 
+  authed.authquery = authed.query.entries
+    .filter { !query.containsKey(it.key) || query[it.key] != it.value }
+    .map { it.key }
+    .toMutableList()
+
   ctx.spec = authed
   return authed
 }
@@ -114,6 +124,9 @@ fun makeUrl(ctx: Context): String {
 
   val resmatch = linkedMapOf<String, Any?>()
 
+  // Sent with the request, never recorded as the entity's match.
+  val authquery = spec.authquery
+
   val params = spec.params
   for (item in Struct.items(params)) {
     val key = if (item[0] is String) item[0] as String else ""
@@ -125,6 +138,14 @@ fun makeUrl(ctx: Context): String {
     }
   }
 
+  // A placeholder left in the route would send the request to the wrong route.
+  // The base's own placeholders are server variables, resolved with the options.
+  val route = url.removePrefix(spec.base.trimEnd('/'))
+  val unfilled = Regex("\\{[^{}/]+\\}").findAll(route).map { it.value }.toList()
+  if (unfilled.isNotEmpty()) {
+    throw ctx.makeError("url_param_missing", "URL path has no value for " + unfilled.joinToString(", ") + ".")
+  }
+
   // Append query string from spec.query.
   var qsep = "?"
   for (item in Struct.items(spec.query)) {
@@ -133,7 +154,9 @@ fun makeUrl(ctx: Context): String {
     if (v != null) {
       url += qsep + Struct.escurl(key) + "=" + Struct.escurl(Struct.stringify(v))
       qsep = "&"
-      resmatch[key] = v
+      if (!authquery.contains(key)) {
+        resmatch[key] = v
+      }
     }
   }
 
@@ -163,11 +186,7 @@ fun makeFetchDef(ctx: Context): MutableMap<String, Any?> {
 
   val body = spec.body
   if (body != null) {
-    if (body is MutableMap<*, *>) {
-      fetchdef["body"] = Struct.jsonify(body)
-    } else {
-      fetchdef["body"] = body
-    }
+    fetchdef["body"] = Media.requestBody(ctx.point, body)
   }
 
   return fetchdef

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

@@ -0,0 +1,83 @@
+package KOTLINPACKAGE.utility
+
+import java.io.InputStream
+
+import KOTLINPACKAGE.utility.struct.Struct
+
+// The media types a point declares: `response` (the model's `rs`) for the
+// Accept header, and `body` (the model's `rb`) for the request body.
+object Media {
+
+  // The data key holding a raw request body. Like `$action`, it can never be
+  // a declared argument name.
+  const val RAW_BODY = "\$body"
+
+  fun isJsonMedia(media: Any?): Boolean {
+    val m = (media as? String ?: "").split(";", limit = 2)[0].trim().lowercase()
+    return "application/json" == m || "text/json" == m || m.endsWith("+json")
+  }
+
+  // The declared JSON type alone, else every declared type in the model's
+  // order; null when no success response declares a body.
+  fun acceptOf(point: Any?): String? {
+    val res = Struct.getprop(point, "response", null)
+    val media = Struct.getprop(res, "media", null) as? String
+    if (media.isNullOrEmpty()) return null
+    if ("json" == Struct.getprop(res, "kind", null)) return media
+    val types = mutableListOf(media)
+    val alts = Struct.getprop(res, "alternatives", null)
+    if (alts is List<*>) {
+      for (alt in alts) {
+        val m = Struct.getprop(alt, "media", null) as? String
+        if (!m.isNullOrEmpty()) types.add(m)
+      }
+    }
+    return types.joinToString(", ")
+  }
+
+  fun isRawRequest(point: Any?): Boolean =
+    "raw" == Struct.getprop(Struct.getprop(point, "body", null), "kind", null)
+
+  fun isJsonRequest(point: Any?): Boolean =
+    "json" == Struct.getprop(Struct.getprop(point, "body", null), "kind", null)
+
+  // Bytes or a stream go as given. A map or a list is JSON, and so is a scalar
+  // on a point that declares a JSON body.
+  fun requestBody(point: Any?, body: Any): Any = when {
+    body is ByteArray || body is InputStream -> body
+    Struct.isnode(body) || isJsonRequest(point) -> Struct.jsonify(body)
+    else -> body
+  }
+
+  private fun hasHeader(headers: Map<String, Any?>, name: String): Boolean =
+    headers.keys.any { it.lowercase() == name }
+
+  // A caller's accept wins. A declared request type replaces each JSON
+  // content-type, the SDK default, and leaves any other the caller set.
+  fun headers(point: Any?, headers: MutableMap<String, Any?>): MutableMap<String, Any?> {
+    val accept = acceptOf(point)
+    if (accept != null && !hasHeader(headers, "accept")) {
+      headers["accept"] = accept
+    }
+
+    val body = Struct.getprop(point, "body", null)
+    val kind = Struct.getprop(body, "kind", null)
+    val media = Struct.getprop(body, "media", null) as? String
+    if (("raw" == kind || "json" == kind) && !media.isNullOrEmpty()) {
+      headers.entries.removeIf { it.key.lowercase() == "content-type" && isJsonMedia(it.value) }
+      if (!hasHeader(headers, "content-type")) {
+        headers["content-type"] = media
+      }
+    }
+
+    return headers
+  }
+
+  // Bytes, an InputStream or a String, sent as they are. An InputStream can be
+  // read once, so it is read here, before the first attempt, and a retry sends
+  // the same bytes again.
+  fun rawBody(reqdata: Map<String, Any?>?): Any? {
+    val body = reqdata?.get(RAW_BODY)
+    return if (body is InputStream) body.readBytes() else body
+  }
+}