@voxgig/sdkgen 4.33.0 → 4.34.1

package/project/.sdk/src/cmp/rb/TestEntity_rb.ts

@@ -1,4 +1,4 @@
-import { flowSteps } from '@voxgig/sdkgen'
+import { flowSteps, opReachable } from '@voxgig/sdkgen'
 
 import {
   flatten,
@@ -27,12 +27,49 @@ import {
   isAuthActive,
   entityDataIdField, envName, envToken,
   serverVarEnv,
-  serverVariables
+  serverVariables,
+  invalidRequest,
+  liveFlowNeeds, liveStrict, liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { formatRubyValue } from './utility_rb'
 
 
+// The live prologue of a flow built from offline fixtures: blocked without
+// the ids it binds, and a create-less load reading the first listed record.
+function liveFlowGate(entity: any, needs: any, entidEnv: string): string {
+  let out = ''
+  if (0 < needs.keys.length) {
+    out += `    if setup[:live]
+      [${needs.keys.map((k: string) => JSON.stringify(k)).join(', ')}].each do |_live_key|
+        if setup[:synthetic_only] || setup[:idmap][_live_key].nil?
+          Runner.live_miss(LIVE_STRICT, "Live entity test blocked: needs #{_live_key} via ${entidEnv}")
+        end
+      end
+    end
+`
+  }
+  if (null != needs.blocked) {
+    out += `    if setup[:live]
+      Runner.live_miss(LIVE_STRICT, "Live entity test blocked: " + ${JSON.stringify(needs.blocked)})
+    end
+`
+  }
+  out += '    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]
+      Runner.live_existing(setup, LIVE_STRICT, ${JSON.stringify(entity.name)}) do
+        client.${entity.Name}(nil).list({${match}}, nil)
+      end
+    end
+`
+  }
+  return out
+}
+
+
 // See TestEntity_ts.ts for the GenCtx/OpGen contract.
 type GenCtx = {
   model: Model
@@ -51,11 +88,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 +135,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
@@ -108,12 +149,33 @@ require_relative "../${model.const.Name}_sdk"
 require_relative "runner"
 
 class ${entity.Name}EntityTest < Minitest::Test
+${liveStrictNote(strict, '#', '  ')}
+  LIVE_STRICT = ${strict}
+
   def test_create_instance
     testsdk = ${model.const.Name}SDK.test(nil, nil)
     ent = testsdk.${entity.Name}(nil)
     assert !ent.nil?
   end
 ${hasList ? `
+  def test_list_entities
+    seed = {
+      "entity" => {
+        "${entity.name}" => {
+          "l1" => { "id" => "l1" },
+          "l2" => { "id" => "l2" },
+        },
+      },
+    }
+    items = ${model.const.Name}SDK.test(seed, nil).${entity.Name}(nil).list(nil, nil)
+    # list resolves to one entity per record; data_get reads the record.
+    assert_equal 2, items.length
+    items.each do |item|
+      assert item.respond_to?(:data_get)
+      assert item.data_get.is_a?(Hash)
+    end
+  end
+
   # Feature #4: the entity stream(action, ...) method runs the op pipeline and
   # returns an Enumerator over result items. With the streaming feature active
   # it yields the feature's incremental output; otherwise it falls back to the
@@ -149,7 +211,7 @@ ${hasList ? `
       assert_equal 3, got.length
     end
   end
-` : ''}
+${failureTests(model, entity)}` : ''}${validateTest(model, entity)}
   def test_basic_flow
     setup = ${entity.name}_basic_setup(nil)
     # Per-op sdk-test-control.json skip.
@@ -161,14 +223,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]
-      skip "live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live"
-      return
-    end
-    client = setup[:client]
-
+${liveFlowGate(entity, needs, entidEnv)}
 `)
 
     // Check if the flow has a create step
@@ -202,7 +257,11 @@ ${hasList ? `
       }
     })
 
-    Content(`  end
+    Content(`${strict ? '' : `  rescue Minitest::Skip
+    raise
+  rescue StandardError, Minitest::Assertion => e
+    Runner.live_observe(e, setup, LIVE_STRICT)
+`}  end
 end
 
 `)
@@ -212,7 +271,7 @@ end
   Runner.load_env_local
 
   entity_data_file = File.join(__dir__, "..", "..", ".sdk", "test", "entity", "${entity.name}", "${entity.Name}TestData.json")
-  entity_data_source = File.read(entity_data_file)
+  entity_data_source = File.read(entity_data_file, encoding: "UTF-8")
   entity_data = JSON.parse(entity_data_source)
 
   options = {}
@@ -236,9 +295,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.
   entid_env_raw = ENV["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"]
   idmap_overridden = !entid_env_raw.nil? && entid_env_raw.strip.start_with?("{")
 
@@ -588,6 +646,104 @@ const GENERATE_OP: Record<string, OpGen> = {
 }
 
 
+// A failed operation raises from a stream as it does from the operation: a
+// transport failure, and a hook that rejects the call. A raising hook fires
+// PreUnexpected, and under throw false the call returns nil. The caller's
+// ctrl stays its own.
+function failureTests(model: Model, entity: ModelEntity): string {
+  const Name = model.const.Name
+  const Entity = entity.Name
+  return `
+  class FailHook < ${Name}BaseFeature
+    attr_reader :unexpected
+
+    def initialize
+      super()
+      @name = "failhook"
+      @unexpected = 0
+    end
+
+    def PreSpec(ctx)
+      raise "${entity.name} hook failed"
+    end
+
+    def PreUnexpected(ctx)
+      @unexpected += 1
+    end
+  end
+
+  def test_stream_error
+    offline = { "net" => { "offline" => true } }
+    err = assert_raises(StandardError) do
+      ${Name}SDK.test(offline, nil).${Entity}(nil).stream("list", nil, nil).to_a
+    end
+    assert_match(/offline/, err.message)
+
+    ${Name}SDK.test(offline, nil).${Entity}(nil)
+      .stream("list", nil, { "ctrl" => { "throw" => false } }).to_a
+
+    cfg = ${Name}Config.shared_config
+    if cfg["feature"].is_a?(Hash) && cfg["feature"].key?("rbac")
+      denied = ${Name}SDK.test(nil, { "feature" => { "rbac" => { "active" => true, "deny" => true } } })
+      err = assert_raises(StandardError) do
+        denied.${Entity}(nil).stream("list", nil, nil).to_a
+      end
+      assert_equal "rbac_denied", err.code
+    end
+  end
+
+  def test_stream_ctrl
+    explain = {}
+    ctrl = { "explain" => explain }
+    ${Name}SDK.test(nil, nil).${Entity}(nil).stream("list", nil, { "ctrl" => ctrl }).to_a
+    assert_equal ["explain"], ctrl.keys
+    assert_same explain, ctrl["explain"]
+    refute_empty explain
+  end
+
+  def test_unexpected
+    hook = FailHook.new
+    client = ${Name}SDK.new({ "feature" => { "test" => { "active" => true } }, "extend" => [hook] })
+
+    err = assert_raises(StandardError) do
+      client.${Entity}(nil).list(nil, nil)
+    end
+    assert_match(/hook failed/, err.message)
+    assert_operator hook.unexpected, :>, 0
+
+    fired = hook.unexpected
+    assert_nil client.${Entity}(nil).list(nil, { "throw" => false })
+    assert_operator hook.unexpected, :>, fired
+  end
+`
+}
+
+
+// An invalid request fails with validate's own error, before it is sent.
+function validateTest(model: Model, entity: ModelEntity): string {
+  const bad = invalidRequest(entity)
+  if (null == bad) {
+    return ''
+  }
+  const Name = model.const.Name
+  const args = Object.entries(bad.args)
+    .map(([k, v]) => JSON.stringify(k) + ' => ' + formatRubyValue(v)).join(', ')
+  return `
+  def test_validate
+    cfg = ${Name}Config.shared_config
+    unless cfg["feature"].is_a?(Hash) && cfg["feature"].key?("validate")
+      skip("feature not present in this SDK: validate")
+    end
+    client = ${Name}SDK.test(nil, { "feature" => { "validate" => { "active" => true } } })
+    err = assert_raises(StandardError) do
+      client.${entity.Name}(nil).${bad.op}({ ${args} }, nil)
+    end
+    assert_equal "validate_failed", err.code
+  end
+`
+}
+
+
 export {
   TestEntity
 }

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

@@ -146,38 +146,12 @@ class EntyClass
       end
       begin
         catch(:stream_stop) do
-          utility.feature_hook.call(ctx, "PrePoint")
-          point, err = utility.make_point.call(ctx)
-          ctx.out["point"] = point
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreSpec")
-          spec, err = utility.make_spec.call(ctx)
-          ctx.out["spec"] = spec
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreRequest")
-          resp, err = utility.make_request.call(ctx)
-          ctx.out["request"] = resp
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreResponse")
-          resp2, err = utility.make_response.call(ctx)
-          ctx.out["response"] = resp2
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreResult")
-          result, err = utility.make_result.call(ctx)
-          ctx.out["result"] = result
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreDone")
-
+          failed = _stream_steps(ctx)
           result = ctx.result
 
           # Inbound: prefer the streaming feature's incremental Enumerator;
           # else fall back to the materialised items so stream always yields.
-          stream_enum = result ? result.stream : nil
+          stream_enum = failed.nil? && result ? result.stream : nil
           if stream_enum
             # done does not run on this path, so its record is cleaned here.
             utility.clean_explain.call(ctx)
@@ -186,7 +160,8 @@ class EntyClass
               give.call(item)
             end
           else
-            data = utility.done.call(ctx)
+            # A failed step leaves through make_error, as an operation's does.
+            data = failed.nil? ? utility.done.call(ctx) : utility.make_error.call(ctx, failed)
             items = data.is_a?(Array) ? data : (data.nil? ? [] : [data])
             items.each do |item|
               throw :stream_stop if aborted.call
@@ -197,12 +172,55 @@ class EntyClass
       rescue StandardError => operr
         raise if inblock
         ctx.ctrl.err = operr
+
+        # What a hook raises here must not escape the cleaning below.
+        begin
+          utility.feature_hook.call(ctx, "PreUnexpected")
+        rescue StandardError => hookerr
+          operr = hookerr
+          ctx.ctrl.err = operr
+        end
+
         e = _unexpected(ctx, operr)
         raise e, cause: nil unless e.nil?
       end
     end
   end
 
+  # The steps an operation runs, with their hooks; the first that fails hands
+  # back its error.
+  private def _stream_steps(ctx)
+    utility = @_utility
+
+    utility.feature_hook.call(ctx, "PrePoint")
+    point, err = utility.make_point.call(ctx)
+    ctx.out["point"] = point
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreSpec")
+    spec, err = utility.make_spec.call(ctx)
+    ctx.out["spec"] = spec
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreRequest")
+    resp, err = utility.make_request.call(ctx)
+    ctx.out["request"] = resp
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreResponse")
+    resp2, err = utility.make_response.call(ctx)
+    ctx.out["response"] = resp2
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreResult")
+    result, err = utility.make_result.call(ctx)
+    ctx.out["result"] = result
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreDone")
+    nil
+  end
+
   # #LoadOp
 
   # #ListOp
@@ -211,6 +229,8 @@ class EntyClass
 
   # #UpdateOp
 
+  # #PatchOp
+
   # #RemoveOp
 
   private

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

@@ -5,7 +5,8 @@
   # @param reqmatch [EntityNameListMatch, Hash, nil] match filter (any subset of
   #   EntityName fields); defaults to nil, treated as an empty match that lists all.
   # @param ctrl [Object, nil] optional per-call control
-  # @return [Array<EntityName>, Array] the matching EntityName items; raises ProjectNameError on failure
+  # @return [Array<EntityName>] the matching EntityName items, one entity per
+  #   record (data_get reads the record); raises ProjectNameError on failure
   def list(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({
@@ -22,16 +23,6 @@
       end
     end
 
-    # list yields the BARE Array of records — each an accessible Hash — so
-    # callers can index item["id"] directly, matching py/lua/go. make_result
-    # wraps each entry as an Entity instance for internal use; unwrap those
-    # back to their bare record Hashes here (load/create/etc. are unaffected).
-    if records.is_a?(Array)
-      records = records.map do |item|
-        item.respond_to?(:data_get) ? item.data_get : item
-      end
-    end
-
     records
   end
 

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

@@ -0,0 +1,31 @@
+require_relative '../utility/struct/voxgig_struct'
+require_relative '../core/helpers'
+
+# EJECT-START
+
+  # Change part of an existing EntityName: only the fields given are sent.
+  #
+  # @param reqdata [EntityNamePatchData, Hash, nil] body data
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntityName, Hash] the patched EntityName; raises ProjectNameError on failure
+  def patch(reqdata, ctrl = nil)
+    utility = @_utility
+    ctx = utility.make_context.call({
+      "opname" => "patch",
+      "ctrl" => ctrl,
+      "match" => @_match,
+      "data" => @_data,
+      "reqdata" => reqdata,
+    }, @_entctx)
+
+    _run_op(ctx) do
+      if ctx.result
+        @_match = ctx.result.resmatch if ctx.result.resmatch
+        if ctx.result.resdata
+          @_data = ProjectNameHelpers.to_map(VoxgigStruct.clone(ctx.result.resdata)) || {}
+        end
+      end
+    end
+  end
+
+# EJECT-END

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

@@ -121,7 +121,13 @@ class ProjectNameSDK
     path = VoxgigStruct.getprop(fetchargs, "path") || ""
     path = "" unless path.is_a?(String)
     method_val = VoxgigStruct.getprop(fetchargs, "method") || "GET"
-    method_val = "GET" unless method_val.is_a?(String)
+    method_val = "GET" unless method_val.is_a?(String) && "" != method_val
+    method_val = method_val.upcase
+    allow_method = VoxgigStruct.getpath(opts, "allow.method")
+    unless ProjectNameUtilities.allowed(allow_method, method_val)
+      raise ctx.make_error("spec_method_allow",
+        "Method \"#{method_val}\" not allowed by SDK option allow.method value: \"#{allow_method}\"")
+    end
     params = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "params")) || {}
     query = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "query")) || {}
     headers = utility.prepare_headers.call(ctx)
@@ -171,8 +177,7 @@ class ProjectNameSDK
 
   # Is this raw-access op permitted by the SDK's allow.op option?
   def op_allowed?(op)
-    allow_op = VoxgigStruct.getpath(@options, "allow.op")
-    allow_op.is_a?(String) && allow_op.include?(op)
+    ProjectNameUtilities.allowed(VoxgigStruct.getpath(@options, "allow.op"), op)
   end
 
   def op_denied(op)
@@ -232,6 +237,7 @@ class ProjectNameSDK
       no_body = status == 204 || status == 304 || content_length.to_s == "0"
 
       json_data = nil
+      body_err = nil
       unless no_body
         jf = VoxgigStruct.getprop(fetched, "json")
         if jf.is_a?(Proc)
@@ -242,14 +248,22 @@ class ProjectNameSDK
             json_data = nil
           end
         end
+        if true == VoxgigStruct.getprop(fetched, "unreadable")
+          failed = status >= 200 && status < 300 ? nil : ctx.make_error("request_status",
+            "request: #{status}: #{VoxgigStruct.getprop(fetched, 'statusText')}")
+          body_err = ProjectNameUtilities::UnreadableBody.call(ctx, status, headers,
+            VoxgigStruct.getprop(fetched, "body"), fetchdef["headers"], failed)
+        end
       end
 
-      return {
-        "ok" => status >= 200 && status < 300,
+      out = {
+        "ok" => body_err.nil? && status >= 200 && status < 300,
         "status" => status,
         "headers" => headers,
         "data" => json_data,
       }
+      out["err"] = utility.clean.call(ctx, body_err) unless body_err.nil?
+      return out
     end
 
     return {

package/project/.sdk/src/cmp/rust/EntityTypes_rust.ts

@@ -92,7 +92,7 @@ use crate::utility::voxgigstruct::Value;
         )
 
         const ops = ent.op || {}
-        ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        ;['load', 'list', 'create', 'update', 'patch', 'remove'].forEach((opname: string) => {
           if (null == ops[opname]) {
             return
           }

package/project/.sdk/src/cmp/rust/Entity_rust.ts

@@ -39,12 +39,12 @@ const Entity = cmp(function Entity(props: any) {
       const opnames = Object.keys(entity.op || {})
 
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['#' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ?
               ({ indent }: any) => {
-                const arg = ('create' === opname || 'update' === opname) ?
+                const arg = ('create' === opname || 'update' === opname || 'patch' === opname) ?
                   'reqdata' : 'reqmatch'
                 // The stub mirrors the real signature: ops resolve to the
                 // ENTITY (`list` to a vector of them), so an unsupported op

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -5,6 +5,7 @@ import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
   entityClassName,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
   TEST_CONTROL_EXCLUDE
@@ -56,11 +57,10 @@ const Main = cmp(async function Main(props: any) {
   // here exactly like the go target.
   Copy({
     from: 'tm/' + target.name,
-    // pluginExcludes: the generate-time plugin trim (an INACTIVE plugin
-    // group's declared files stay out of the tree - the model's `path`
-    // entries are target-root-relative, which is this Copy's root). The
-    // FEATURE-level trim for rust stays an add-time concern, as go's does.
-    exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
+    // The generate-time trim: a declared feature that is off, and an inactive
+    // plugin group, whose `path` entries are relative to this Copy's root.
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE,
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
       RUSTCRATE: rustcrate,
@@ -198,7 +198,7 @@ pub use crate::core::context::{Context, CtxSpec, OpMap};
 pub use crate::core::control::Control;
 pub use crate::core::error::${model.const.Name}Error;
 pub use crate::core::helpers::{
-    call_json, call_vfn, ja, jo, json_thunk, unsupported_op, vfn,
+    call_json, call_vfn, getp, ja, jo, json_thunk, to_map, unsupported_op, vfn,
 };
 pub use crate::core::operation::Operation;
 pub use crate::core::point::Point;
@@ -212,6 +212,7 @@ pub use crate::core::types::{
 pub use crate::core::utility_type::Utility;
 pub use crate::feature::base::BaseFeature;
 pub use crate::utility::jsonparse::json_parse;
+pub use crate::utility::media::bytes_value;
 pub use crate::utility::voxgigstruct::Value;
 
 // No-argument convenience constructors: \`${rustcrate}::new()\` /