@voxgig/sdkgen 4.34.0 → 4.34.1

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

@@ -1,6 +1,6 @@
 -- ProjectName SDK utility: make_fetch_def
 
-local vs = require("utility.struct.struct")
+local media = require("utility.media")
 
 local function make_fetch_def_util(ctx)
   local spec = ctx.spec
@@ -30,11 +30,7 @@ local function make_fetch_def_util(ctx)
   }
 
   if spec.body ~= nil then
-    if type(spec.body) == "table" then
-      fetchdef["body"] = vs.jsonify(spec.body)
-    else
-      fetchdef["body"] = spec.body
-    end
+    fetchdef["body"] = media.request_body(ctx.point, spec.body)
   end
 
   return fetchdef, nil

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

@@ -49,13 +49,13 @@ local function densify_lists(v, seen)
   return v
 end
 
-local function noentity(settings)
+local function plain(settings, name)
   if type(settings) ~= "table" then
     return settings
   end
   local out = {}
   for k, v in pairs(settings) do
-    if k ~= "entity" then
+    if k ~= "entity" and not (name == "rbac" and k == "rules") then
       out[k] = v
     end
   end
@@ -65,20 +65,23 @@ end
 -- The options to scan for secrets. The feature map is keyed by feature
 -- names, not field names, so it is scanned as a list: `secrets` must not
 -- make every setting of that feature a secret. Entity blocks hold entity
--- settings and seeded records, never a credential, so none is scanned. The
--- raw scan still sees the feature list form, whose entries each carry `name`.
+-- settings and seeded records, never a credential, so none is scanned, and
+-- nor are rbac's rules, keyed by entity and operation names. The raw scan
+-- still sees the feature list form, whose entries each carry `name`.
 local function secret_scan(opts, omit)
   local out = {}
   for k, v in pairs(opts) do
     if not omit[k] and k ~= "entity" then
       if k == "feature" and type(v) == "table" then
         local list = {}
-        for _, fopts in pairs(v) do
-          list[#list + 1] = noentity(fopts)
+        for fname, fopts in pairs(v) do
+          local name = type(fname) == "string" and fname or
+            (type(fopts) == "table" and fopts.name or nil)
+          list[#list + 1] = plain(fopts, name)
         end
         v = list
       elseif k == "test" then
-        v = noentity(v)
+        v = plain(v, nil)
       end
       out[k] = v
     end

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

@@ -29,6 +29,43 @@ local function terminal_param(point)
 end
 
 
+-- The entity's own route among some points.
+local function own_point(points)
+  local best = points[1]
+  for i = 1, #points do
+    local cand = points[i]
+    local cand_term = terminal_param(cand)
+    local best_term = terminal_param(best)
+    if cand_term ~= best_term then
+      if cand_term then
+        best = cand
+      end
+    elseif parts_len(cand) < parts_len(best) then
+      best = cand
+    end
+  end
+  return best
+end
+
+
+-- The path parameters of a point that neither the call nor the entity gives
+-- a value for, looked up as param looks them up.
+local function unfilled(ctx, point)
+  local missing = {}
+  local parts = vs.getprop(point, "parts")
+  if type(parts) ~= "table" then
+    return missing
+  end
+  for _, part in ipairs(parts) do
+    local name = type(part) == "string" and part:match("^{([^{}/]+)}$") or nil
+    if name ~= nil and helpers.param_value(ctx, point, name) == nil then
+      missing[#missing + 1] = name
+    end
+  end
+  return missing
+end
+
+
 local function make_point_util(ctx)
   if ctx.out["point"] ~= nil then
     local preset = ctx.out["point"]
@@ -45,11 +82,11 @@ local function make_point_util(ctx)
   local op = ctx.op
   local options = ctx.options
 
-  local allow_op = vs.getpath(options, "allow.op") or ""
-  if type(allow_op) == "string" and not string.find(allow_op, op.name, 1, true) then
+  local allow_op = vs.getpath(options, "allow.op")
+  if not helpers.allowed(allow_op, op.name) then
     return nil, ctx:make_error("point_op_allow",
       'Operation "' .. op.name ..
-      '" not allowed by SDK option allow.op value: "' .. allow_op .. '"')
+      '" not allowed by SDK option allow.op value: "' .. tostring(allow_op or "") .. '"')
   end
 
   if #op.points == 0 then
@@ -125,19 +162,35 @@ local function make_point_util(ctx)
           '" action "' .. vs.stringify(unmatched_action) .. '" is not valid.')
       end
 
-      point = op.points[1]
+      -- A call without an action falls back to a point without one, as
+      -- generation does, and only to a route the call can fill.
+      local plain = {}
       for i = 1, #op.points do
         local cand = op.points[i]
-        local cand_term = terminal_param(cand)
-        local best_term = terminal_param(point)
-        if cand_term ~= best_term then
-          if cand_term then
-            point = cand
-          end
-        elseif parts_len(cand) < parts_len(point) then
-          point = cand
+        if vs.getprop(helpers.to_map(vs.getprop(cand, "select")), "$action") == nil then
+          plain[#plain + 1] = cand
         end
       end
+      if #plain == 0 then
+        return nil, ctx:make_error("point_action_required",
+          'Operation "' .. op.name ..
+          '" has only action endpoints; pass $action to choose one.')
+      end
+      local fillable = {}
+      for _, cand in ipairs(plain) do
+        if #unfilled(ctx, cand) == 0 then
+          fillable[#fillable + 1] = cand
+        end
+      end
+
+      if #fillable == 0 then
+        return nil, ctx:make_error("point_no_match",
+          'Operation "' .. op.name ..
+          '" has no endpoint whose path parameters are all given (missing: ' ..
+          table.concat(unfilled(ctx, own_point(plain)), ", ") .. ').')
+      end
+
+      point = own_point(fillable)
     end
 
     if reqselector ~= nil then

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

@@ -3,6 +3,7 @@
 local vs = require("utility.struct.struct")
 local graphql = require("utility.graphql")
 local Spec = require("core.spec")
+local helpers = require("core.helpers")
 
 local function make_spec_util(ctx)
   if ctx.out["spec"] ~= nil then
@@ -51,11 +52,11 @@ local function make_spec_util(ctx)
 
   ctx.spec.method = utility.prepare_method(ctx)
 
-  local allow_method = vs.getpath(options, "allow.method") or ""
-  if type(allow_method) == "string" and not string.find(allow_method, ctx.spec.method, 1, true) then
+  local allow_method = vs.getpath(options, "allow.method")
+  if not helpers.allowed(allow_method, ctx.spec.method) then
     return nil, ctx:make_error("spec_method_allow",
-      'Method "' .. ctx.spec.method ..
-      '" not allowed by SDK option allow.method value: "' .. allow_method .. '"')
+      'Method "' .. tostring(ctx.spec.method or "") ..
+      '" not allowed by SDK option allow.method value: "' .. tostring(allow_method or "") .. '"')
   end
 
   ctx.spec.params = utility.prepare_params(ctx)
@@ -83,11 +84,25 @@ local function make_spec_util(ctx)
     ctx.ctrl.explain["spec"] = ctx.spec
   end
 
+  -- Whatever prepare_auth sets in the query, under whichever name, is the
+  -- credential; a key it leaves as it was is the caller's.
+  local query = {}
+  for k, v in pairs(ctx.spec.query or {}) do
+    query[k] = v
+  end
+
   local spec, err = utility.prepare_auth(ctx)
   if err ~= nil then
     return nil, err
   end
 
+  spec.authquery = {}
+  for k, v in pairs(spec.query or {}) do
+    if query[k] ~= v then
+      table.insert(spec.authquery, k)
+    end
+  end
+
   ctx.spec = spec
   return spec, nil
 end

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

@@ -18,6 +18,12 @@ local function make_url_util(ctx)
   local url = vs.join({ spec.base, spec.prefix, spec.path, spec.suffix }, "/", true)
   local resmatch = {}
 
+  -- Sent with the request, never recorded as the entity's match.
+  local authquery = {}
+  for _, name in ipairs(spec.authquery or {}) do
+    authquery[name] = true
+  end
+
   -- A route the definition ends with a slash keeps it: a server such as a
   -- Django REST one redirects or refuses the route without it.
   local orig = ctx.point ~= nil and vs.getprop(ctx.point, "orig") or nil
@@ -46,6 +52,19 @@ local function make_url_util(ctx)
     end
   end
 
+  -- 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.
+  local base = type(spec.base) == "string" and (spec.base:gsub("/+$", "")) or ""
+  local route = url:sub(1, #base) == base and url:sub(#base + 1) or url
+  local unfilled = {}
+  for found in route:gmatch("{[^{}/]+}") do
+    unfilled[#unfilled + 1] = found
+  end
+  if #unfilled > 0 then
+    return "", ctx:make_error("url_param_missing",
+      "URL path has no value for " .. table.concat(unfilled, ", ") .. ".")
+  end
+
   -- Append query string from spec.query.
   local qsep = "?"
   local query_items = vs.items(spec.query)
@@ -57,7 +76,9 @@ local function make_url_util(ctx)
         local val_str = type(val) == "string" and val or tostring(val)
         url = url .. qsep .. vs.escurl(key) .. "=" .. vs.escurl(val_str)
         qsep = "&"
-        resmatch[key] = val
+        if not authquery[key] then
+          resmatch[key] = val
+        end
       end
     end
   end

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

@@ -0,0 +1,106 @@
+-- ProjectName SDK utility: media
+
+-- 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.
+
+local vs = require("utility.struct.struct")
+
+local M = {}
+
+-- The data key holding a raw request body. Like `$action`, it can never be a
+-- declared argument name.
+M.RAW_BODY = "$body"
+
+function M.is_json_media(media)
+  local m = string.lower((tostring(media or ""):match("^[^;]*")):match("^%s*(.-)%s*$"))
+  return m == "application/json" or m == "text/json" or m:sub(-5) == "+json"
+end
+
+-- The declared JSON type alone, else every declared type in the model's
+-- order; nil when no success response declares a body.
+function M.accept_of(point)
+  local res = vs.getprop(point, "response")
+  local media = vs.getprop(res, "media")
+  if type(media) ~= "string" or media == "" then
+    return nil
+  end
+  if vs.getprop(res, "kind") == "json" then
+    return media
+  end
+  local types = { media }
+  local alts = vs.getprop(res, "alternatives")
+  if type(alts) == "table" then
+    for _, alt in ipairs(alts) do
+      local m = vs.getprop(alt, "media")
+      if type(m) == "string" and m ~= "" then
+        types[#types + 1] = m
+      end
+    end
+  end
+  return table.concat(types, ", ")
+end
+
+function M.is_raw_request(point)
+  return vs.getpath(point, "body.kind") == "raw"
+end
+
+function M.is_json_request(point)
+  return vs.getpath(point, "body.kind") == "json"
+end
+
+-- A table is JSON, and so is a scalar on a point that declares a JSON body.
+-- Anything else goes as given.
+function M.request_body(point, body)
+  if type(body) == "table" or (type(body) ~= "userdata" and M.is_json_request(point)) then
+    return vs.jsonify(body)
+  end
+  return body
+end
+
+local function has_header(headers, name)
+  for key in pairs(headers) do
+    if type(key) == "string" and string.lower(key) == name then
+      return true
+    end
+  end
+  return false
+end
+
+-- A caller's accept wins. A declared request type replaces each JSON
+-- content-type, the SDK default, and leaves any other the caller set.
+function M.media_headers(point, headers)
+  local accept = M.accept_of(point)
+  if accept ~= nil and not has_header(headers, "accept") then
+    headers["accept"] = accept
+  end
+
+  local body = vs.getprop(point, "body")
+  local kind = vs.getprop(body, "kind")
+  local media = vs.getprop(body, "media")
+  if (kind == "raw" or kind == "json") and type(media) == "string" and media ~= "" then
+    local drop = {}
+    for key, val in pairs(headers) do
+      if type(key) == "string" and string.lower(key) == "content-type" and M.is_json_media(val) then
+        drop[#drop + 1] = key
+      end
+    end
+    for _, key in ipairs(drop) do
+      headers[key] = nil
+    end
+    if not has_header(headers, "content-type") then
+      headers["content-type"] = media
+    end
+  end
+
+  return headers
+end
+
+-- A string, of bytes or text, sent as it is.
+function M.raw_body(reqdata)
+  if type(reqdata) ~= "table" then
+    return nil
+  end
+  return reqdata[M.RAW_BODY]
+end
+
+return M

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

@@ -4,13 +4,6 @@ local vs = require("utility.struct.struct")
 local helpers = require("core.helpers")
 
 local function param_util(ctx, paramdef)
-  local point = ctx.point
-  local spec = ctx.spec
-  local match = ctx.match
-  local reqmatch = ctx.reqmatch
-  local data = ctx.data
-  local reqdata = ctx.reqdata
-
   local pt = vs.typify(paramdef)
   local key = ""
 
@@ -23,46 +16,13 @@ local function param_util(ctx, paramdef)
     end
   end
 
-  local akey = ""
-  if point ~= nil then
-    local alias = helpers.to_map(vs.getprop(point, "alias"))
-    if alias ~= nil then
-      local ak = vs.getprop(alias, key)
-      if type(ak) == "string" then
-        akey = ak
-      end
-    end
-  end
-
-  local val = vs.getprop(reqmatch, key)
-
-  if val == nil then
-    val = vs.getprop(match, key)
-  end
-
-  if val == nil and akey ~= "" then
-    if spec ~= nil then
-      spec.alias[akey] = key
-    end
-    val = vs.getprop(reqmatch, akey)
-  end
-
-  if val == nil then
-    val = vs.getprop(reqdata, key)
-  end
-
-  if val == nil then
-    val = vs.getprop(data, key)
-  end
-
-  if val == nil and akey ~= "" then
-    val = vs.getprop(reqdata, akey)
-    if val == nil then
-      val = vs.getprop(data, akey)
-    end
+  local akey = helpers.param_alias(ctx.point, key)
+  if ctx.spec ~= nil and akey ~= "" and
+    vs.getprop(ctx.reqmatch, key) == nil and vs.getprop(ctx.match, key) == nil then
+    ctx.spec.alias[akey] = key
   end
 
-  return val
+  return helpers.param_value(ctx, ctx.point, key)
 end
 
 return param_util

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

@@ -1,9 +1,14 @@
 -- ProjectName SDK utility: prepare_body
 
+local media = require("utility.media")
+
 local function prepare_body_util(ctx)
   local op = ctx.op
 
   if op.input == "data" then
+    if media.is_raw_request(ctx.point) then
+      return media.raw_body(ctx.reqdata)
+    end
     local body = ctx.utility.transform_request(ctx)
     return body
   end

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

@@ -1,6 +1,29 @@
 -- ProjectName SDK utility: prepare_headers
 
 local vs = require("utility.struct.struct")
+local helpers = require("core.helpers")
+local media = require("utility.media")
+
+-- The form style of a cookie parameter: a list repeats the name, a map sends
+-- its own keys, and every value is percent-encoded.
+local function cookie_pair(wire, val)
+  local function esc(v)
+    return vs.escurl(vs.stringify(v))
+  end
+  local pairs_ = {}
+  if vs.islist(val) then
+    for _, item in ipairs(val) do
+      pairs_[#pairs_ + 1] = wire .. "=" .. esc(item)
+    end
+  elseif vs.ismap(val) then
+    for _, key in ipairs(vs.keysof(val)) do
+      pairs_[#pairs_ + 1] = vs.escurl(key) .. "=" .. esc(val[key])
+    end
+  else
+    pairs_[#pairs_ + 1] = wire .. "=" .. esc(val)
+  end
+  return table.concat(pairs_, "; ")
+end
 
 local function prepare_headers_util(ctx)
   local options = ctx.client:options_map()
@@ -13,34 +36,61 @@ local function prepare_headers_util(ctx)
       out = cloned
     end
   end
+  out = media.media_headers(ctx.point, out)
 
-  -- A header parameter travels as a header, under the name the definition
-  -- gives it, and only from this call's own arguments. It replaces a default
-  -- of the same name, whatever its case.
-  local hl = ctx.point ~= nil and vs.getpath(ctx.point, "args.header") or nil
-  if type(hl) == "table" then
-    for _, hd in ipairs(hl) do
-      local name = vs.getprop(hd, "name")
-      if type(name) == "string" and name ~= "" then
-        local orig = vs.getprop(hd, "orig")
-        if type(orig) ~= "string" or orig == "" then
-          orig = name
+  -- A header argument replaces a default of the same name, whatever its case.
+  for _, arg in ipairs(helpers.call_args(ctx, "header")) do
+    if arg.val ~= nil then
+      local wire = string.lower(arg.wire)
+      for key in pairs(out) do
+        if type(key) == "string" and string.lower(key) == wire then
+          out[key] = nil
         end
-        local val = vs.getprop(ctx.reqmatch or {}, name)
-        if val == nil then
-          val = vs.getprop(ctx.reqdata or {}, name)
+      end
+      out[wire] = vs.stringify(arg.val)
+    end
+  end
+
+  -- A cookie argument travels in the cookie header, form serialized and
+  -- percent-encoded, replacing a cookie of the same name among those the
+  -- caller's headers already send.
+  local sent = {}
+  for _, arg in ipairs(helpers.call_args(ctx, "cookie")) do
+    if arg.val ~= nil then
+      sent[#sent + 1] = arg
+    end
+  end
+  if #sent > 0 then
+    local names = {}
+    for _, arg in ipairs(sent) do
+      if vs.ismap(arg.val) then
+        for _, key in ipairs(vs.keysof(arg.val)) do
+          names[vs.escurl(key)] = true
         end
-        if val ~= nil then
-          local wire = string.lower(orig)
-          for key in pairs(out) do
-            if type(key) == "string" and string.lower(key) == wire then
-              out[key] = nil
-            end
+      else
+        names[arg.wire] = true
+      end
+    end
+    local kept = {}
+    for key, given in pairs(out) do
+      if type(key) == "string" and string.lower(key) == "cookie" then
+        if type(given) == "string" then
+          for _, cookie in ipairs(helpers.cookie_keep(given, names)) do
+            kept[#kept + 1] = cookie
           end
-          out[wire] = vs.stringify(val)
         end
+        out[key] = nil
+      end
+    end
+    for _, arg in ipairs(sent) do
+      local pair = cookie_pair(arg.wire, arg.val)
+      if pair ~= "" then
+        kept[#kept + 1] = pair
       end
     end
+    if #kept > 0 then
+      out["cookie"] = table.concat(kept, "; ")
+    end
   end
 
   return out

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

@@ -1,6 +1,7 @@
 -- ProjectName SDK utility: prepare_query
 
 local vs = require("utility.struct.struct")
+local helpers = require("core.helpers")
 
 local function contains_param(params, s)
   for _, v in ipairs(params) do
@@ -34,13 +35,27 @@ local function prepare_query_util(ctx)
         end
       end
     end
-    -- A header parameter travels in the headers, which prepare_headers fills.
+    -- A header or cookie parameter travels in the headers, which prepare_headers
+    -- fills, unless a query parameter shares its name: then both are sent.
+    local declared = {}
+    local ql = vs.getpath(point, "args.query")
+    if type(ql) == "table" then
+      for _, qd in ipairs(ql) do
+        local qname = vs.getprop(qd, "name")
+        if type(qname) == "string" then
+          declared[qname] = true
+        end
+      end
+    end
     local hl = vs.getpath(point, "args.header")
-    if type(hl) == "table" then
-      for _, hd in ipairs(hl) do
-        local name = vs.getprop(hd, "name")
-        if type(name) == "string" then
-          table.insert(params, name)
+    local cl = vs.getpath(point, "args.cookie")
+    for _, located in ipairs({ hl or {}, cl or {} }) do
+      if type(located) == "table" then
+        for _, hd in ipairs(located) do
+          local name = vs.getprop(hd, "name")
+          if type(name) == "string" and not declared[name] then
+            table.insert(params, name)
+          end
         end
       end
     end
@@ -75,6 +90,13 @@ local function prepare_query_util(ctx)
     end
   end
 
+  -- A create or update passes its query arguments in its data.
+  for _, arg in ipairs(helpers.call_args(ctx, "query")) do
+    if arg.val ~= nil and not contains_param(params, arg.name) then
+      out[arg.wire] = arg.val
+    end
+  end
+
   return out
 end
 

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

@@ -1,5 +1,7 @@
 -- ProjectName SDK utility: result_body
 
+local unreadable_body = require("utility.unreadable_body")
+
 local function result_body_util(ctx)
   local response = ctx.response
   local result = ctx.result
@@ -9,6 +11,11 @@ local function result_body_util(ctx)
       local json_data = response.json_func()
       result.body = json_data
     end
+    if response ~= nil and response.unreadable then
+      local sent = ctx.spec ~= nil and ctx.spec.headers or nil
+      result.err = unreadable_body(ctx, result.status, result.headers, response.body,
+        sent, result.err)
+    end
   end
 
   return result