@voxgig/sdkgen 4.23.0 → 4.24.0

package/project/.sdk/tm/js/src/feature/test/TestFeature.js

@@ -148,6 +148,7 @@ class TestFeature extends BaseFeature {
         const found = select(entmap, args)
         const ent = getelem(found, 0)
         if (null == ent) {
+          // update miss: 404, never another record
           return respond(404, undefined, { statusText: S_NOT_FOUND })
         }
         else {
@@ -161,13 +162,12 @@ class TestFeature extends BaseFeature {
         const args = self.buildArgs(ctx, op, ctx.reqmatch)
         const found = select(entmap, args)
         const ent = getelem(found, 0)
-        if (null == ent) {
-          return respond(404, undefined, { statusText: S_NOT_FOUND })
-        }
-        else {
+        // Remove only the first matched entity. If nothing matches,
+        // succeed as a no-op rather than erroring.
+        if (null != ent) {
           delprop(entmap, getprop(ent, 'id'))
-          return respond(200)
         }
+        return respond(200)
       }
       else if ('create' === op.name) {
         const args = self.buildArgs(ctx, op, ctx.reqdata)
@@ -183,6 +183,8 @@ class TestFeature extends BaseFeature {
         const out = clone(ent)
         return respond(200, out)
       }
+
+      return respond(404, undefined, { statusText: 'Unknown operation' })
     }
 
     // Optional network behaviour simulation over the mock transport. Enable

package/project/.sdk/tm/js/src/utility/PrepareQueryUtility.js

@@ -13,7 +13,7 @@ function prepareQuery(ctx) {
 
   const out = {}
   for (let [key, val] of items(reqmatch)) {
-    if (null != val && !params.includes(key)) {
+    if (null != val && '$action' !== key && !params.includes(key)) {
       out[key] = val
     }
   }

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -254,6 +254,10 @@ describe('FeatureCorpus', () => {
 
       const probe = makeClient({})
       if (!probe._rootctx.config.hasFeature(name)) {
+        // The one line every runner prints for a section that names a
+        // feature this SDK does not generate, so an inert section is
+        // visible in the output rather than inferred from a green tick.
+        t.diagnostic(`feature.${name}: inert (this SDK does not generate the feature)`)
         return t.skip(`this SDK was generated without the ${name} feature`)
       }
 

package/project/.sdk/tm/kotlin/core/Context.kt

@@ -76,7 +76,7 @@ class Context(ctxmap: MutableMap<String, Any?>?, basectx: Context?) {
       } else if (cv is Control) {
         this.ctrl = cv
       }
-    } else if (basectx != null) {
+    } else if (basectx != null && Helpers.getCtxProp(ctxmap, "opname") == null) {
       this.ctrl = basectx.ctrl
     }
 

package/project/.sdk/tm/kotlin/feature/PagingFeature.kt

@@ -8,8 +8,9 @@ import KOTLINPACKAGE.utility.struct.Struct
 
 // Pagination support for list operations. On the way out (PreRequest) it
 // stamps page/limit (or a cursor) into the request query; on the way back
-// (PreResult) it reads the server's pagination signals and records them on
-// `ctx.result.paging`.
+// (PreResult) it reads the server's pagination signals (camelCase and
+// snake_case body forms) and records them on `ctx.result.paging` and the
+// caller's `ctrl.paging`.
 @Suppress("UNCHECKED_CAST")
 class PagingFeature : BaseFeature("paging", "0.0.1", true) {
 
@@ -53,7 +54,9 @@ class PagingFeature : BaseFeature("paging", "0.0.1", true) {
     if (cursor != null) {
       spec.query[cursorParam] = cursor
     } else if (spec.query[pageParam] == null) {
-      val page = 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.
+      val page = paging["nextPage"] ?: paging["page"]
       if (page != null) {
         spec.query[pageParam] = page
       } else {
@@ -166,18 +169,33 @@ class PagingFeature : BaseFeature("paging", "0.0.1", true) {
       }
     }
 
-    // Body-level cursors.
+    // Body-level signals; snake_case forms are read first so camelCase wins.
     if (body is MutableMap<*, *>) {
       val bm = body as MutableMap<String, Any?>
       if (bm["next"] != null && paging["next"] == null) {
         paging["next"] = bm["next"]
       }
+      if (bm["next_cursor"] != null) {
+        paging["cursor"] = bm["next_cursor"]
+      }
       if (bm["cursor"] != null) {
         paging["cursor"] = bm["cursor"]
       }
       if (bm["nextCursor"] != null) {
         paging["cursor"] = bm["nextCursor"]
       }
+      if (paging["nextPage"] == null) {
+        val np = bm["nextPage"] ?: bm["next_page"]
+        if (np is Number) {
+          paging["nextPage"] = np.toInt()
+        } else if (np is String) {
+          paging["nextPage"] = np
+        }
+      }
+      if (bm["has_more"] is Boolean) {
+        paging["hasMore"] = bm["has_more"]
+        explicitMore = true
+      }
       if (bm["hasMore"] is Boolean) {
         paging["hasMore"] = bm["hasMore"]
         explicitMore = true
@@ -197,6 +215,20 @@ class PagingFeature : BaseFeature("paging", "0.0.1", true) {
 
     result.paging = paging
     this.last = paging
+
+    // The Context shares the caller's paging map by reference, so refill it
+    // in place; an immutable map falls back to replacing the reference.
+    val shared = ctx.ctrl.paging
+    if (shared == null) {
+      ctx.ctrl.paging = paging
+    } else {
+      try {
+        shared.clear()
+        shared.putAll(paging)
+      } catch (e: UnsupportedOperationException) {
+        ctx.ctrl.paging = paging
+      }
+    }
   }
 
   private fun isList(ctx: Context): Boolean {

package/project/.sdk/tm/kotlin/feature/TestFeature.kt

@@ -160,20 +160,13 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
         }
         val args = buildArgs(ctx, op, updateMatch)
         val found = Struct.select(entmap, args)
-        var ent = Struct.getelem(found, 0, null)
-        if (ent == null) {
-          for (e in entmap.values) {
-            if (e is MutableMap<*, *>) {
-              ent = e
-              break
-            }
-          }
-        }
+        val ent = Struct.getelem(found, 0, null)
         if (ent == null) {
+          // update miss: 404, never another record
           return respond(ctx, 404, null, extra("statusText", "Not found"))
         }
         if (ent is MutableMap<*, *>) {
-          (ent as MutableMap<String, Any?>).putAll(reqdata)
+          Struct.merge(Struct.jt(ent, reqdata))
         }
         Struct.delprop(ent, "\$KEY")
         val out = Struct.clone(ent)
@@ -320,10 +313,14 @@ class TestFeature : BaseFeature("test", "0.0.1", true) {
       }
     }
 
-    // Get required params.
-    val paramsPath = Struct.getpath(point, listOf("args", "params"))
-    val reqdParams = Struct.select(paramsPath, Struct.jm("reqd", true))
-    val reqd = Struct.transform(reqdParams, Struct.jt("`\$EACH`", "", "`\$KEY.name`"))
+    // 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.
+    val reqdArgs = Struct.jt()
+    for (kind in listOf("params", "query")) {
+      val argsPath = Struct.getpath(point, listOf("args", kind))
+      reqdArgs.addAll(Struct.select(argsPath, Struct.jm("reqd", true)))
+    }
+    val reqd = Struct.transform(reqdArgs, Struct.jt("`\$EACH`", "", "`\$KEY.name`"))
 
     val qand = Struct.jt()
     val q = Struct.jm("`\$AND`", qand)

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

@@ -6,12 +6,44 @@ import java.net.URI
 import java.net.http.HttpClient
 import java.net.http.HttpRequest
 import java.net.http.HttpResponse
+import java.util.concurrent.ConcurrentHashMap
 import java.util.function.BiFunction
 import java.util.function.Supplier
 
 import KOTLINPACKAGE.core.Context
 import KOTLINPACKAGE.utility.struct.Struct
 
+// Clients keyed by redirect policy and proxy. Each HttpClient owns a
+// connection pool and a selector thread, so one per request reused
+// nothing; one per key pools across calls.
+private val clients = ConcurrentHashMap<String, HttpClient>()
+
+private fun clientFor(fetchdef: MutableMap<String, Any?>): HttpClient {
+  // "manual" (set by the station feature's middleware under a hosts
+  // policy) returns a 3xx like any other response: an automatic follow
+  // would carry injected credentials to a host no policy approved.
+  val redirectPolicy =
+    if ("manual" == fetchdef["redirect"]) HttpClient.Redirect.NEVER
+    else HttpClient.Redirect.NORMAL
+
+  val praw = fetchdef["proxy"]
+  val proxy = if (praw is String) praw else ""
+
+  return clients.computeIfAbsent("$redirectPolicy|$proxy") {
+    val clientb = HttpClient.newBuilder().followRedirects(redirectPolicy)
+    if ("" != proxy) {
+      try {
+        val proxyUri = URI.create(proxy)
+        val port = if (proxyUri.port < 0) 80 else proxyUri.port
+        clientb.proxy(ProxySelector.of(InetSocketAddress(proxyUri.host, port)))
+      } catch (e: RuntimeException) {
+        // Unparseable proxy target: direct connection, as the go transport.
+      }
+    }
+    clientb.build()
+  }
+}
+
 @Suppress("UNCHECKED_CAST")
 fun defaultHttpFetch(fullurl: String, fetchdef: MutableMap<String, Any?>): MutableMap<String, Any?> {
   var method = if (fetchdef["method"] is String) fetchdef["method"] as String else ""
@@ -50,32 +82,9 @@ fun defaultHttpFetch(fullurl: String, fetchdef: MutableMap<String, Any?>): Mutab
     reqb.setHeader("User-Agent", "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)")
   }
 
-  // Honour a redirect annotation on the fetch definition (set by the
-  // station feature's middleware under a hosts policy): "manual" returns
-  // a 3xx like any other response instead of following it — the ts
-  // donor's fetch honours the same key natively, and an automatic follow
-  // would carry injected credentials to a host no policy approved.
-  val redirectPolicy =
-    if ("manual" == fetchdef["redirect"]) HttpClient.Redirect.NEVER
-    else HttpClient.Redirect.NORMAL
-
-  // Honour a proxy annotation on the fetch definition (set by the proxy
-  // feature): route the request through a proxied HttpClient.
-  val clientb = HttpClient.newBuilder().followRedirects(redirectPolicy)
-  val proxy = fetchdef["proxy"]
-  if (proxy is String && "" != proxy) {
-    try {
-      val proxyUri = URI.create(proxy)
-      val port = if (proxyUri.port < 0) 80 else proxyUri.port
-      clientb.proxy(ProxySelector.of(InetSocketAddress(proxyUri.host, port)))
-    } catch (e: RuntimeException) {
-      // Unparseable proxy target: fall through to a direct connection.
-    }
-  }
-
   val resp: HttpResponse<String>
   try {
-    resp = clientb.build().send(reqb.build(), HttpResponse.BodyHandlers.ofString())
+    resp = clientFor(fetchdef).send(reqb.build(), HttpResponse.BodyHandlers.ofString())
   } catch (e: Exception) {
     throw RuntimeException("fetch: " + e.message, e)
   }

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

@@ -194,7 +194,7 @@ fun prepareQuery(ctx: Context): MutableMap<String, Any?> {
   for (item in Struct.items(reqmatch)) {
     val key = if (item[0] is String) item[0] as String else ""
     val v = item[1]
-    if (v != null && !containsStr(params, key)) {
+    if (v != null && "\$action" != key && !containsStr(params, key)) {
       out[key] = v
     }
   }

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

@@ -58,21 +58,36 @@ fun resultHeaders(ctx: Context): KOTLINPACKAGE.core.Result {
   return result!!
 }
 
+// `$action` selects the point (see makePoint); it is never an API field, so
+// the body is a copy without it. The caller's map is left untouched.
+private fun stripAction(reqdata: Any?): Any? {
+  if (reqdata !is Map<*, *> || !reqdata.containsKey("\$action")) {
+    return reqdata
+  }
+  val body = linkedMapOf<String, Any?>()
+  for ((k, v) in reqdata) {
+    if ("\$action" != k) {
+      body[k.toString()] = v
+    }
+  }
+  return body
+}
+
 fun transformRequest(ctx: Context): Any? {
   if (ctx.spec != null) {
     ctx.spec!!.step = "reqform"
   }
 
   val transform = Helpers.toMapAny(Struct.getprop(ctx.point, "transform"))
-    ?: return ctx.reqdata
+    ?: return stripAction(ctx.reqdata)
 
   val reqform = Struct.getprop(transform, "req", null)
-    ?: return ctx.reqdata
+    ?: return stripAction(ctx.reqdata)
 
   val data = linkedMapOf<String, Any?>()
   data["reqdata"] = ctx.reqdata
 
-  return Struct.transform(data, reqform)
+  return stripAction(Struct.transform(data, reqform))
 }
 
 fun transformResponse(ctx: Context): Any? {

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

@@ -49,7 +49,14 @@ function Context.new(ctxmap, basectx)
     if type(ctrl_raw.explain) == "table" then
       self.ctrl.explain = ctrl_raw.explain
     end
-  elseif basectx ~= nil and basectx.ctrl ~= nil then
+    if ctrl_raw.actor ~= nil then
+      self.ctrl.actor = ctrl_raw.actor
+    end
+    if type(ctrl_raw.paging) == "table" then
+      self.ctrl.paging = ctrl_raw.paging
+    end
+  elseif basectx ~= nil and basectx.ctrl ~= nil
+      and helpers.get_ctx_prop(ctxmap, "opname") == nil then
     self.ctrl = basectx.ctrl
   end
 

package/project/.sdk/tm/lua/core/control.lua

@@ -10,6 +10,9 @@ function Control.new(opts)
   self.throw_err = opts.throw_err
   self.err = nil
   self.explain = opts.explain
+  -- Per-call feature inputs (audit actor, paging cursor/page).
+  self.actor = opts.actor
+  self.paging = opts.paging
   return self
 end
 

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

@@ -5,8 +5,9 @@
 -- (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 `ctx.result.paging`. A
--- per-call `ctrl.paging` (cursor or page) wins over the option defaults,
+-- fields in the body (snake_case forms too) — and records them on
+-- `ctx.result.paging` and the caller's `ctrl.paging`. A per-call
+-- `ctrl.paging` (cursor or page) wins over the option defaults,
 -- so auto-iteration can advance the cursor/page and re-issue the list
 -- call until `hasMore` is false. Parameter names (`pageParam`,
 -- `limitParam`, `cursorParam`), `startPage` (default 1) and `limit` are
@@ -95,8 +96,14 @@ function PagingFeature:PreRequest(ctx)
   if paging["cursor"] ~= nil then
     spec.query[cursor_param] = paging["cursor"]
   elseif spec.query[page_param] == nil then
-    if paging["page"] ~= nil then
-      spec.query[page_param] = 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.
+    local page = paging["nextPage"]
+    if page == nil then
+      page = paging["page"]
+    end
+    if page ~= nil then
+      spec.query[page_param] = page
     else
       spec.query[page_param] = self.options["startPage"] or 1
     end
@@ -218,17 +225,33 @@ function PagingFeature:PreResult(ctx)
     end
   end
 
-  -- Body-level cursors.
+  -- Body-level signals; snake_case forms are read first so camelCase wins.
   if type(body) == "table" then
     if body["next"] ~= nil and paging.next == nil then
       paging.next = body["next"]
     end
+    if body["next_cursor"] ~= nil then
+      paging.cursor = body["next_cursor"]
+    end
     if body["cursor"] ~= nil then
       paging.cursor = body["cursor"]
     end
     if body["nextCursor"] ~= nil then
       paging.cursor = body["nextCursor"]
     end
+    if paging.nextPage == nil then
+      local np = body["nextPage"]
+      if np == nil then
+        np = body["next_page"]
+      end
+      if type(np) == "number" or type(np) == "string" then
+        paging.nextPage = np
+      end
+    end
+    if type(body["has_more"]) == "boolean" then
+      paging.hasMore = body["has_more"]
+      explicit_more = true
+    end
     if type(body["hasMore"]) == "boolean" then
       paging.hasMore = body["hasMore"]
       explicit_more = true
@@ -247,6 +270,22 @@ function PagingFeature:PreResult(ctx)
 
   result.paging = paging
 
+  if ctx.ctrl ~= nil then
+    -- The Context shares the caller's paging table by reference, so refill
+    -- it in place; a fresh table on ctrl never reaches the caller.
+    if type(ctx.ctrl.paging) == "table" then
+      local shared = ctx.ctrl.paging
+      for k in pairs(shared) do
+        shared[k] = nil
+      end
+      for k, v in pairs(paging) do
+        shared[k] = v
+      end
+    else
+      ctx.ctrl.paging = paging
+    end
+  end
+
   local client = self.client
   client._paging = { last = paging }
 end

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

@@ -167,21 +167,12 @@ function TestFeature:init(ctx, options)
       local args = test_self:build_args(fctx, op, update_match)
       local found = vs.select(entmap, args)
       local ent = vs.getelem(found, 0)
-      if ent == nil and type(entmap) == "table" then
-        for _, e in pairs(entmap) do
-          if type(e) == "table" then ent = e; break end
-        end
-      end
       if ent == nil then
+        -- update miss: 404, never another record
         return respond(404, nil, { statusText = "Not found" })
       end
-      if type(ent) == "table" then
-        local reqdata = fctx.reqdata
-        if reqdata ~= nil then
-          for k, v in pairs(reqdata) do
-            ent[k] = v
-          end
-        end
+      if type(ent) == "table" and type(fctx.reqdata) == "table" then
+        vs.merge({ ent, fctx.reqdata })
       end
       vs.delprop(ent, "$KEY")
       local out = vs.clone(ent)
@@ -312,12 +303,39 @@ function TestFeature:make_netsim(net, inner)
 end
 
 
+local function point_terminal(p)
+  local parts = vs.getprop(p, "parts")
+  if type(parts) ~= "table" or #parts == 0 then return false end
+  local last = parts[#parts]
+  return type(last) == "string" and last:sub(1, 1) == "{"
+end
+
+local function point_depth(p)
+  local parts = vs.getprop(p, "parts")
+  return type(parts) == "table" and #parts or 0
+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).
+local function pick_point(points)
+  if type(points) ~= "table" or #points == 0 then return nil end
+  local point = points[1]
+  for i = 2, #points do
+    local cand = points[i]
+    if point_terminal(cand) ~= point_terminal(point) then
+      if point_terminal(cand) then point = cand end
+    elseif point_depth(cand) < point_depth(point) then
+      point = cand
+    end
+  end
+  return point
+end
+
 function TestFeature:build_args(ctx, op, args)
   local opname = op.name
 
-  -- Get last point from config.
   local points = vs.getpath(ctx.config, "entity." .. ctx.entity:get_name() .. ".op." .. opname .. ".points")
-  local point = vs.getelem(points, -1)
+  local 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.

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

@@ -29,7 +29,8 @@ local function prepare_query_util(ctx)
     for _, item in ipairs(reqmatch_items) do
       local key = item[1]
       local val = item[2]
-      if val ~= nil and type(key) == "string" and not contains_param(params, key) then
+      if val ~= nil and type(key) == "string" and key ~= "$action"
+          and not contains_param(params, key) then
         out[key] = val
       end
     end

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

@@ -3,6 +3,22 @@
 local vs = require("utility.struct.struct")
 local helpers = require("core.helpers")
 
+-- `$action` selects the point (see make_point_util); it is never an API
+-- field, so the body is a copy without it. The caller's table is left
+-- untouched.
+local function strip_action(reqdata)
+  if not vs.ismap(reqdata) or reqdata["$action"] == nil then
+    return reqdata
+  end
+  local body = {}
+  for k, v in pairs(reqdata) do
+    if k ~= "$action" then
+      body[k] = v
+    end
+  end
+  return body
+end
+
 local function transform_request_util(ctx)
   local spec = ctx.spec
   local point = ctx.point
@@ -13,19 +29,19 @@ local function transform_request_util(ctx)
 
   local transform = helpers.to_map(vs.getprop(point, "transform"))
   if transform == nil then
-    return ctx.reqdata
+    return strip_action(ctx.reqdata)
   end
 
   local reqform = vs.getprop(transform, "req")
   if reqform == nil then
-    return ctx.reqdata
+    return strip_action(ctx.reqdata)
   end
 
   local reqdata = vs.transform({
     reqdata = ctx.reqdata,
   }, reqform)
 
-  return reqdata
+  return strip_action(reqdata)
 end
 
 return transform_request_util