@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/lua/TestEntity_lua.ts

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable } from '@voxgig/sdkgen'
 
 import {
   flatten,
@@ -27,7 +27,9 @@ import {
   isAuthActive,
   entityDataIdField, envName, envToken,
   serverVarEnv,
-  serverVariables
+  serverVariables,
+  invalidRequest,
+  liveFlowNeeds, liveStrict, liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { formatLuaValue } from './utility_lua'
@@ -44,6 +46,45 @@ type GenCtx = {
 type OpGen = (ctx: GenCtx, step: ModelEntityFlowStep, index: number) => void
 
 
+// The live prologue of a flow built from offline fixtures: blocked without
+// the ids it binds, a create-less load reading the first listed record, and
+// a lenient run observing its checks rather than failing on them.
+function liveFlowGate(entity: any, needs: any, entidEnv: string, strict: boolean): string {
+  let out = ''
+  if (0 < needs.keys.length) {
+    out += `    if setup.live then
+      for _, _live_key in ipairs({${needs.keys.map((k: string) => JSON.stringify(k)).join(', ')}}) do
+        if setup.synthetic_only or setup.idmap[_live_key] == nil then
+          runner.live_miss(pending, LIVE_STRICT, "Live entity test blocked: needs " .. _live_key .. " via ${entidEnv}")
+        end
+      end
+    end
+`
+  }
+  if (null != needs.blocked) {
+    out += `    if setup.live then
+      runner.live_miss(pending, LIVE_STRICT, "Live entity test blocked: " .. ${JSON.stringify(needs.blocked)})
+    end
+`
+  }
+  out += '    local client = setup.client\n'
+  if (null != needs.discover) {
+    const match = Object.entries(needs.discover)
+      .map(([k, v]: any) => `[${JSON.stringify(k)}] = setup.idmap[${JSON.stringify(v)}]`).join(', ')
+    out += `    if setup.live then
+      runner.live_existing(pending, setup, LIVE_STRICT, ${JSON.stringify(entity.name)}, function()
+        return client:${entity.Name}(nil):list({${match}}, nil)
+      end)
+    end
+`
+  }
+  if (!strict) {
+    out += '    local _live_ok, _live_err = pcall(function()\n'
+  }
+  return out
+}
+
+
 const TestEntity = cmp(function TestEntity(props: any) {
   const ctx$ = props.ctx$
   const model: Model = ctx$.model
@@ -51,11 +92,11 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
-  // The stream test streams the "list" op and asserts a 3-item collection, so
-  // it only applies to entities that declare a list op. Others (e.g. Batch =
-  // create/load) have no list endpoint — make_point errors and the stream
-  // yields nothing — so skip the stream test for them.
-  const hasList = !!(entity.op && (entity.op as any)?.list)
+  // The stream test streams the "list" op with no match and asserts a 3-item
+  // collection, so it only applies to an entity whose list a bare call can
+  // reach: not one without a list (e.g. Batch = create/load), not a nested
+  // list needing its parent's id, and not one whose routes all need an action.
+  const hasList = opReachable((entity.op as any)?.list, [])
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -98,6 +139,10 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const genCtx: GenCtx = { model, entity, flow: basicflow, PROJUPPER }
 
+  const strict = liveStrict(model, target.name)
+  const needs = liveFlowNeeds(entity, basicflow)
+  const entidEnv = PROJUPPER + '_TEST_' + envToken(entity.name) + '_ENTID'
+
   File({ name: entity.name + '_entity_test.' + target.ext }, () => {
 
     Content(`-- ${entity.Name} entity test
@@ -110,6 +155,10 @@ local runner = require("test.runner")
 
 local _test_dir = debug.getinfo(1, "S").source:match("^@(.+/)")  or "./"
 
+${liveStrictNote(strict, '--')}
+local LIVE_STRICT = ${strict}
+
+${hasList ? failHookClass(entity) : ''}
 describe("${entity.Name}Entity", function()
   it("should create instance", function()
     local testsdk = sdk.test(nil, nil)
@@ -157,7 +206,7 @@ ${hasList ? `
       assert.are.equal(3, #got)
     end
   end)
-` : ''}
+${failureTests(entity)}` : ''}${validateTest(entity)}
   it("should run basic flow", function()
     local setup = ${entity.name}_basic_setup(nil)
     -- Per-op sdk-test-control.json skip.
@@ -169,14 +218,7 @@ ${hasList ? `
         return
       end
     end
-    -- The basic flow consumes synthetic IDs from the fixture. In live mode
-    -- without an *_ENTID env override, those IDs hit the live API and 4xx.
-    if setup.synthetic_only then
-      pending("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live")
-      return
-    end
-    local client = setup.client
-
+${liveFlowGate(entity, needs, entidEnv, strict)}
 `)
 
     // Check if the flow has a create step
@@ -210,7 +252,11 @@ ${hasList ? `
       }
     })
 
-    Content(`  end)
+    Content(`${strict ? '' : `    end)
+    if not _live_ok then
+      runner.live_observe(pending, _live_err, setup, LIVE_STRICT)
+    end
+`}  end)
 end)
 
 `)
@@ -250,9 +296,8 @@ end)
 
 `)
 
-    Content(`  -- Detect ENTID env override before envOverride consumes it. When live
-  -- mode is on without a real override, the basic test runs against synthetic
-  -- IDs from the fixture and 4xx's. Surface this so the test can skip.
+    Content(`  -- Whether *_ENTID supplied the idmap, read before env_override consumes
+  -- it: without it, the ids a live flow binds are the fixture's synthetic ones.
   local entid_env_raw = os.getenv("${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID")
   local idmap_overridden = entid_env_raw ~= nil and entid_env_raw:match("^%s*{") ~= nil
 
@@ -608,6 +653,114 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A feature whose PreSpec hook raises, counting the PreUnexpected calls it sees.
+function failHookClass(entity: ModelEntity): string {
+  return `
+local BaseFeature = require("feature.base_feature")
+
+local FailHook = {}
+FailHook.__index = FailHook
+setmetatable(FailHook, { __index = BaseFeature })
+
+function FailHook.new()
+  local self = setmetatable(BaseFeature.new(), FailHook)
+  self.name = "failhook"
+  self.unexpected = 0
+  return self
+end
+
+function FailHook:init(_ctx, _options) end
+function FailHook:PreSpec(_ctx) error("${entity.name} hook failed") end
+function FailHook:PreUnexpected(_ctx) self.unexpected = self.unexpected + 1 end
+
+local function errtext(err)
+  if type(err) == "table" then
+    return tostring(err.msg or err.message or "")
+  end
+  return tostring(err)
+end
+`
+}
+
+
+// A failed operation raises from a stream as it fails the operation: a
+// transport failure, and a hook that rejects the call. A raising hook fires
+// PreUnexpected, and under throw false the call returns no error. The
+// caller's ctrl stays its own.
+function failureTests(entity: ModelEntity): string {
+  const Entity = entity.Name
+  return `
+  it("should report a failed stream", function()
+    local offline = { net = { offline = true } }
+    local ok, err = pcall(function()
+      for _ in sdk.test(offline, nil):${Entity}(nil):stream("list", nil, nil) do end
+    end)
+    assert.is_false(ok)
+    assert.truthy(string.find(errtext(err), "offline", 1, true))
+
+    for _ in sdk.test(offline, nil):${Entity}(nil):stream("list", nil, { ctrl = { throw = false } }) do end
+
+    local config = require("config_shared")()
+    if type(config.feature) == "table" and config.feature.rbac ~= nil then
+      local denied = sdk.test(nil, { feature = { rbac = { active = true, deny = true } } })
+      local dok, derr = pcall(function()
+        for _ in denied:${Entity}(nil):stream("list", nil, nil) do end
+      end)
+      assert.is_false(dok)
+      assert.are.equal("rbac_denied", type(derr) == "table" and derr.code or nil)
+    end
+  end)
+
+  it("should leave the caller's ctrl", function()
+    local explain = {}
+    local ctrl = { explain = explain }
+    for _ in sdk.test(nil, nil):${Entity}(nil):stream("list", nil, { ctrl = ctrl }) do end
+    assert.is_nil(ctrl.stream)
+    assert.are.equal(explain, ctrl.explain)
+    assert.is_not_nil(next(explain))
+  end)
+
+  it("should fire PreUnexpected", function()
+    local hook = FailHook.new()
+    local client = sdk.new({ feature = { test = { active = true } }, extend = { hook } })
+
+    local out, err = client:${Entity}(nil):list(nil, nil)
+    assert.is_nil(out)
+    assert.truthy(string.find(errtext(err), "hook failed", 1, true))
+    assert.is_true(hook.unexpected > 0)
+
+    local fired = hook.unexpected
+    out, err = client:${Entity}(nil):list(nil, { throw = false })
+    assert.is_nil(err)
+    assert.is_true(hook.unexpected > fired)
+  end)
+`
+}
+
+
+// An invalid request fails with validate's own error, before it is sent.
+function validateTest(entity: ModelEntity): string {
+  const bad = invalidRequest(entity)
+  if (null == bad) {
+    return ''
+  }
+  const args = Object.entries(bad.args)
+    .map(([k, v]) => '[' + JSON.stringify(k) + '] = ' + formatLuaValue(v)).join(', ')
+  return `
+  it("should refuse an invalid request", function()
+    local config = require("config_shared")()
+    if type(config.feature) ~= "table" or config.feature.validate == nil then
+      pending("feature not present in this SDK: validate")
+      return
+    end
+    local client = sdk.test(nil, { feature = { validate = { active = true } } })
+    local _, err = client:${entity.Name}(nil):${bad.op}({ ${args} }, nil)
+    assert.are.equal("validate_failed", type(err) == "table" and err.code or nil)
+  end)
+`
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/lua/fragment/Entity.fragment.lua

@@ -4,6 +4,7 @@ local json = require("dkjson")
 local vs = require("utility.struct.struct")
 local helpers = require("core.helpers")
 
+---@class EntyClass
 local EntyClass = {}
 EntyClass.__index = EntyClass
 
@@ -44,8 +45,7 @@ end
 
 
 -- The entity serialises and prints as its data, as ts does: the instance
--- also holds the client, the utility and a match that can carry a query
--- credential.
+-- also holds the client and the utility.
 function EntyClass:to_record()
   local rec = self._utility.clean(self._entctx, vs.clone(self._data or {}))
   rec["voxgig$entity"] = self._name
@@ -173,53 +173,13 @@ function EntyClass:stream(action, args, callopts)
   end
 
   local co = coroutine.create(function()
-    utility.feature_hook(ctx, "PrePoint")
-    local point, err = utility.make_point(ctx)
-    ctx.out["point"] = point
-    if err ~= nil then
-      return
-    end
-
-    utility.feature_hook(ctx, "PreSpec")
-    local spec
-    spec, err = utility.make_spec(ctx)
-    ctx.out["spec"] = spec
-    if err ~= nil then
-      return
-    end
-
-    utility.feature_hook(ctx, "PreRequest")
-    local resp
-    resp, err = utility.make_request(ctx)
-    ctx.out["request"] = resp
-    if err ~= nil then
-      return
-    end
-
-    utility.feature_hook(ctx, "PreResponse")
-    local resp2
-    resp2, err = utility.make_response(ctx)
-    ctx.out["response"] = resp2
-    if err ~= nil then
-      return
-    end
-
-    utility.feature_hook(ctx, "PreResult")
-    local result
-    result, err = utility.make_result(ctx)
-    ctx.out["result"] = result
-    if err ~= nil then
-      return
-    end
-
-    utility.feature_hook(ctx, "PreDone")
-
-    result = ctx.result
+    local failed = self:_stream_steps(ctx)
+    local result = ctx.result
 
     -- Inbound: prefer the streaming feature's incremental iterator; else fall
     -- back to the materialised items so stream always yields.
     local stream_fn = nil
-    if result ~= nil then
+    if failed == nil and result ~= nil then
       stream_fn = result.stream
     end
     if type(stream_fn) == "function" then
@@ -232,7 +192,17 @@ function EntyClass:stream(action, args, callopts)
         coroutine.yield(item)
       end
     else
-      local data = utility.done(ctx)
+      -- A failed step leaves through make_error, as an operation's does,
+      -- and its error is handed to the iterator to raise.
+      local data, err
+      if failed == nil then
+        data, err = utility.done(ctx)
+      else
+        data, err = utility.make_error(ctx, failed)
+      end
+      if err ~= nil then
+        return err
+      end
       local items
       if vs.islist(data) then
         items = data
@@ -251,8 +221,7 @@ function EntyClass:stream(action, args, callopts)
   end)
 
   -- An error raised while the caller iterates leaves through the same catch
-  -- path as an operation's. A step's error ends the stream silently, so the
-  -- record is cleaned whenever the stream ends.
+  -- path as an operation's, and the record is cleaned whenever the stream ends.
   return function()
     if coroutine.status(co) == "dead" then
       return nil
@@ -261,9 +230,18 @@ function EntyClass:stream(action, args, callopts)
     if ok then
       if coroutine.status(co) == "dead" then
         utility.clean_explain(ctx)
+        if item ~= nil then
+          error(item, 0)
+        end
       end
       return item
     end
+
+    -- What a hook raises here must not escape the cleaning below.
+    local hookok, hookerr = pcall(utility.feature_hook, ctx, "PreUnexpected")
+    if not hookok then
+      item = hookerr
+    end
     local err = self:_unexpected(ctx, item)
     if err ~= nil then
       error(err, 0)
@@ -273,6 +251,55 @@ function EntyClass:stream(action, args, callopts)
 end
 
 
+-- The steps an operation runs, with their hooks; the first that fails hands
+-- back its error.
+function EntyClass:_stream_steps(ctx)
+  local utility = self._utility
+
+  utility.feature_hook(ctx, "PrePoint")
+  local point, err = utility.make_point(ctx)
+  ctx.out["point"] = point
+  if err ~= nil then
+    return err
+  end
+
+  utility.feature_hook(ctx, "PreSpec")
+  local spec
+  spec, err = utility.make_spec(ctx)
+  ctx.out["spec"] = spec
+  if err ~= nil then
+    return err
+  end
+
+  utility.feature_hook(ctx, "PreRequest")
+  local resp
+  resp, err = utility.make_request(ctx)
+  ctx.out["request"] = resp
+  if err ~= nil then
+    return err
+  end
+
+  utility.feature_hook(ctx, "PreResponse")
+  local resp2
+  resp2, err = utility.make_response(ctx)
+  ctx.out["response"] = resp2
+  if err ~= nil then
+    return err
+  end
+
+  utility.feature_hook(ctx, "PreResult")
+  local result
+  result, err = utility.make_result(ctx)
+  ctx.out["result"] = result
+  if err ~= nil then
+    return err
+  end
+
+  utility.feature_hook(ctx, "PreDone")
+  return nil
+end
+
+
 -- #LoadOp
 
 -- #ListOp
@@ -281,16 +308,27 @@ end
 
 -- #UpdateOp
 
+-- #PatchOp
+
 -- #RemoveOp
 
 
 -- A hook, fetcher or parser that raises never reaches make_error: its error
 -- leaves cleaned, and so does the explain record it interrupted.
 function EntyClass:_run_op(ctx, post_done)
+  local utility = self._utility
   local ok, out, err = pcall(self._run_steps, self, ctx, post_done)
   if ok then
     return out, err
   end
+
+  -- What a hook raises here must not escape the cleaning below.
+  local hookok, hookerr = pcall(function()
+    -- #PreUnexpected-Hook
+  end)
+  if not hookok then
+    out = hookerr
+  end
   return nil, self:_unexpected(ctx, out)
 end
 

package/project/.sdk/src/cmp/lua/fragment/EntityCreateOp.fragment.lua

@@ -7,7 +7,7 @@ local entityCreateOp = {}
 
 ---@param reqdata EntityNameCreateData
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:create(reqdata, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/lua/fragment/EntityListOp.fragment.lua

@@ -4,7 +4,7 @@ local entityListOp = {}
 
 ---@param reqmatch EntityNameListMatch
 ---@param ctrl? table
----@return EntityName[]
+---@return EntyClass[]
 ---@return string? err
 function EntyClass:list(reqmatch, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/lua/fragment/EntityLoadOp.fragment.lua

@@ -7,7 +7,7 @@ local entityLoadOp = {}
 
 ---@param reqmatch EntityNameLoadMatch
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:load(reqmatch, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/lua/fragment/EntityPatchOp.fragment.lua

@@ -0,0 +1,34 @@
+local vs = require("utility.struct.struct")
+local helpers = require("core.helpers")
+
+local entityPatchOp = {}
+
+-- EJECT-START
+
+---@param reqdata EntityNamePatchData
+---@param ctrl? table
+---@return EntyClass
+---@return string? err
+function EntyClass:patch(reqdata, ctrl)
+  local utility = self._utility
+  local ctx = utility.make_context({
+    opname = "patch",
+    ctrl = ctrl,
+    match = self._match,
+    data = self._data,
+    reqdata = reqdata,
+  }, self._entctx)
+
+  return self:_run_op(ctx, function()
+    if ctx.result ~= nil then
+      if ctx.result.resmatch ~= nil then
+        self._match = ctx.result.resmatch
+      end
+      if ctx.result.resdata ~= nil then
+        self._data = helpers.to_map(vs.clone(ctx.result.resdata)) or {}
+      end
+    end
+  end)
+end
+
+-- EJECT-END

package/project/.sdk/src/cmp/lua/fragment/EntityRemoveOp.fragment.lua

@@ -7,7 +7,7 @@ local entityRemoveOp = {}
 
 ---@param reqmatch EntityNameRemoveMatch
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:remove(reqmatch, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/lua/fragment/EntityUpdateOp.fragment.lua

@@ -7,7 +7,7 @@ local entityUpdateOp = {}
 
 ---@param reqdata EntityNameUpdateData
 ---@param ctrl? table
----@return EntityName
+---@return EntyClass
 ---@return string? err
 function EntyClass:update(reqdata, ctrl)
   local utility = self._utility

package/project/.sdk/src/cmp/lua/fragment/Main.fragment.lua

@@ -5,6 +5,7 @@ local vs = require("utility.struct.struct")
 local Utility = require("core.utility_type")
 local Spec = require("core.spec")
 local helpers = require("core.helpers")
+local unreadable_body = require("utility.unreadable_body")
 
 -- Load utility registration (populates Utility._registrar)
 require("utility.register")
@@ -192,7 +193,15 @@ function ProjectNameSDK:prepare(fetchargs)
   if type(path) ~= "string" then path = "" end
 
   local method = vs.getprop(fetchargs, "method") or "GET"
-  if type(method) ~= "string" then method = "GET" end
+  if type(method) ~= "string" or method == "" then method = "GET" end
+  method = string.upper(method)
+
+  local allow_method = vs.getpath(options, "allow.method")
+  if not helpers.allowed(allow_method, method) then
+    return nil, ctx:make_error("spec_method_allow",
+      'Method "' .. method ..
+      '" not allowed by SDK option allow.method value: "' .. tostring(allow_method or "") .. '"')
+  end
 
   local params = helpers.to_map(vs.getprop(fetchargs, "params")) or {}
   local query = helpers.to_map(vs.getprop(fetchargs, "query")) or {}
@@ -250,8 +259,7 @@ end
 
 -- Is this raw-access op permitted by the SDK's allow.op option?
 function ProjectNameSDK:_op_allowed(op)
-  local allow = vs.getpath(self.options, "allow.op")
-  return type(allow) == "string" and allow:find(op, 1, true) ~= nil
+  return helpers.allowed(vs.getpath(self.options, "allow.op"), op)
 end
 
 
@@ -313,6 +321,7 @@ function ProjectNameSDK:_raw_request(fetchargs)
     local no_body = status == 204 or status == 304 or tostring(content_length) == "0"
 
     local json_data = nil
+    local body_err = nil
     if not no_body then
       local jf = vs.getprop(fetched, "json")
       if type(jf) == "function" then
@@ -322,14 +331,27 @@ function ProjectNameSDK:_raw_request(fetchargs)
         end
         -- Non-JSON body: json_data stays nil, status/headers preserved.
       end
+      if vs.getprop(fetched, "unreadable") == true then
+        local failed = nil
+        if status < 200 or status >= 300 then
+          failed = ctx:make_error("request_status",
+            "request: " .. tostring(status) .. ": " .. tostring(vs.getprop(fetched, "statusText")))
+        end
+        body_err = unreadable_body(ctx, status, headers, vs.getprop(fetched, "body"),
+          fetchdef["headers"], failed)
+      end
     end
 
-    return {
-      ok = status >= 200 and status < 300,
+    local out = {
+      ok = body_err == nil and status >= 200 and status < 300,
       status = status,
       headers = headers,
       data = json_data,
-    }, nil
+    }
+    if body_err ~= nil then
+      out.err = utility.clean(ctx, body_err)
+    end
+    return out, nil
   end
 
   return {

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

@@ -1,5 +1,5 @@
 
-import { ocamlString } from './utility_ocaml'
+import { ocamlOpField, ocamlString } from './utility_ocaml'
 
 
 // Emit the OCaml source for one entity CRUD operation, as an assignment to
@@ -8,11 +8,7 @@ import { ocamlString } from './utility_ocaml'
 // install a stub that errors at call time (so the entity_obj record is always
 // fully populated). Mirrors the rust/py Entity op fragments.
 function entityOp(opname: string, present: boolean, entityname: string): string {
-  const field =
-    'load' === opname ? 'e_load' :
-      'list' === opname ? 'e_list' :
-        'create' === opname ? 'e_create' :
-          'update' === opname ? 'e_update' : 'e_remove'
+  const field = ocamlOpField(opname)
 
   if (!present) {
     return `  ent.${field} <- (fun _ _ ->
@@ -21,13 +17,14 @@ function entityOp(opname: string, present: boolean, entityname: string): string
 `
   }
 
-  const inputField = ('create' === opname || 'update' === opname) ? 'cs_reqdata' : 'cs_reqmatch'
-  const arg = ('create' === opname || 'update' === opname) ? 'reqdata' : 'reqmatch'
+  const body = 'create' === opname || 'update' === opname || 'patch' === opname
+  const inputField = body ? 'cs_reqdata' : 'cs_reqmatch'
+  const arg = body ? 'reqdata' : 'reqmatch'
 
   // Writeback after a successful op (mirrors the py op fragments):
-  //   load/update/remove -> match + data ; list -> match ; create -> data
-  const writeMatch = ('list' === opname || 'load' === opname || 'update' === opname || 'remove' === opname)
-  const writeData = ('create' === opname || 'load' === opname || 'update' === opname || 'remove' === opname)
+  //   load/update/patch/remove -> match + data ; list -> match ; create -> data
+  const writeMatch = 'create' !== opname
+  const writeData = 'list' !== opname
 
   let post = ''
   if (writeMatch) {